fix: audit remediation - code quality and documentation improvements

Resolves #178

Code fixes:
- builder.ts: Add type guard for error handling (e instanceof Error)
- engine.prepare-options-helpers.ts: Use else-if for token injection clarity
- ng-add.spec.ts: Replace lazy .toBeTruthy() with proper builder assertion
- engine.spec.ts: Replace lazy .toBeDefined() with actual behavior test

Documentation fixes:
- README.md: Clarify Cloudflare Pages requires --no-notfound for SPA mode
- schema.json: Update noNotfound description for Cloudflare Pages
- CLAUDE.md: Add 404.html platform behavior, remove fragile line numbers

Author: JohannesHoppe

CLAUDE.md

@@ -139,8 +139,8 @@ actions.ts (deploy function)
 **Note:** `browserTarget` is deliberately HIDDEN from user-facing documentation per deprecation policy, even though it still works internally for backward compatibility.
 
 **Implementation details:**
-- Static build target: `browserTarget || buildTarget || default` (see `src/deploy/builder.ts:23-26`)
-- Final target: `prerenderTarget || staticBuildTarget` (see `src/deploy/builder.ts:45-50`)
+- Static build target: `browserTarget || buildTarget || default` (see `src/deploy/builder.ts`)
+- Final target: `prerenderTarget || staticBuildTarget` (see `src/deploy/builder.ts`)
 
 Output directory resolution:
 - Checks `angular.json` for `outputPath`
@@ -177,7 +177,10 @@ The engine appends CI metadata to commit messages when running on:
 
 1. **No Server-Side Rendering**: GitHub Pages only supports static files. SSR/Universal build targets are not supported.
 
-2. **404.html Handling**: By default creates `404.html` as copy of `index.html` to handle SPA routing on GitHub Pages. For Cloudflare Pages, disable with `--no-notfound`.
+2. **404.html Handling**:
+   - **GitHub Pages**: Requires `404.html` workaround (only way to get SPA routing, but returns HTTP 404 status)
+   - **Cloudflare Pages**: MUST NOT have `404.html` - its presence disables native SPA mode
+   - **Future**: Consider changing default or auto-detecting deployment target
 
 3. **Jekyll Bypass**: Creates `.nojekyll` to prevent GitHub Pages from processing files through Jekyll (which would break files starting with `_` or `.txt` in assets).
 

README.md

@@ -359,9 +359,12 @@ With `--no-dotfiles` files starting with `.` are ignored.
   - `ng deploy` – A `404.html` file is created by default.
   - `ng deploy --no-notfound` – No `404.html` file is created.
 
-By default, a `404.html` file is created, because this is the only known workaround to avoid 404 error messages on GitHub Pages.
-For Cloudflare Pages we highly recommend to disable the `404.html` file by setting this switch to true! 
-See [#178](https://github.com/angular-schule/angular-cli-ghpages/issues/178)
+By default, a `404.html` file is created, because this is the only known workaround for SPA routing on GitHub Pages (note: GitHub still returns HTTP 404 status, which may affect Brave browser and social previews).
+
+> [!IMPORTANT]
+> **Cloudflare Pages users:** You **must** use `--no-notfound` to enable native SPA routing. Cloudflare Pages only activates SPA mode when no `404.html` file exists. See [#178](https://github.com/angular-schule/angular-cli-ghpages/issues/178)
+>
+> We plan to change the default behavior in a future release to better support Cloudflare Pages.
 
 #### --no-nojekyll <a name="no-nojekyll"></a>
 

src/deploy/builder.ts

@@ -50,7 +50,8 @@ export default createBuilder(
       await deploy(engine, context, finalBuildTarget, options);
     } catch (e) {
       context.logger.error('❌ An error occurred when trying to deploy:');
-      context.logger.error(e.message);
+      const message = e instanceof Error ? e.message : String(e);
+      context.logger.error(message);
       return { success: false };
     }
 

src/deploy/schema.json

@@ -65,7 +65,7 @@
     },
     "noNotfound": {
       "type": "boolean",
-      "description": "By default a 404.html file is created, because this is the only known workaround to avoid 404 error messages on GitHub Pages. For Cloudflare Pages we highly recommend to disable the 404.html file by setting this switch to true!",
+      "description": "By default a 404.html file is created for SPA routing on GitHub Pages. For Cloudflare Pages, you must use --no-notfound to enable native SPA routing.",
       "default": false
     },
     "noNojekyll": {

src/engine/engine.prepare-options-helpers.ts

@@ -173,22 +173,19 @@ export async function injectTokenIntoRepoUrl(options: PreparedOptions): Promise<
     options.repo = options.repo.replace('GH_TOKEN', process.env.GH_TOKEN);
   }
   // preferred way: token is replaced from plain URL
+  // Note: Only the first available token is used (GH_TOKEN > PERSONAL_TOKEN > GITHUB_TOKEN)
   else if (options.repo && !options.repo.includes('x-access-token:')) {
     if (process.env.GH_TOKEN) {
       options.repo = options.repo.replace(
         'https://github.com/',
         `https://x-access-token:${process.env.GH_TOKEN}@github.com/`
       );
-    }
-
-    if (process.env.PERSONAL_TOKEN) {
+    } else if (process.env.PERSONAL_TOKEN) {
       options.repo = options.repo.replace(
         'https://github.com/',
         `https://x-access-token:${process.env.PERSONAL_TOKEN}@github.com/`
       );
-    }
-
-    if (process.env.GITHUB_TOKEN) {
+    } else if (process.env.GITHUB_TOKEN) {
       options.repo = options.repo.replace(
         'https://github.com/',
         `https://x-access-token:${process.env.GITHUB_TOKEN}@github.com/`

src/engine/engine.spec.ts

@@ -415,7 +415,7 @@ describe('engine', () => {
     });
 
     it('should monkeypatch util.debuglog before requiring gh-pages', async () => {
-      // This test verifies the critical ordering requirement documented in engine.ts:22-27
+      // This test verifies the critical ordering requirement:
       // The monkeypatch MUST occur before requiring gh-pages, otherwise gh-pages caches
       // the original util.debuglog and our interception won't work.
 
@@ -429,12 +429,13 @@ describe('engine', () => {
       await engine.prepareOptions({}, testLogger);
 
       // Now require gh-pages for the first time (after monkeypatch)
-      const ghpages = require('gh-pages');
+      require('gh-pages');
 
-      // gh-pages should now use our patched util.debuglog
-      // We can't directly test gh-pages internal calls, but we verified
-      // that util.debuglog('gh-pages') forwards to our logger
-      expect(infoSpy).toBeDefined();
+      // Verify our patched debuglog('gh-pages') forwards to the logger
+      const util = require('util');
+      const ghPagesLogger = util.debuglog('gh-pages');
+      ghPagesLogger('test message');
+      expect(infoSpy).toHaveBeenCalledWith('test message');
     });
   });
 });

src/ng-add.spec.ts

@@ -53,9 +53,8 @@ describe('ng-add', () => {
       );
 
       const resultConfig = readJSONFromTree(resultTree, 'angular.json');
-      expect(
-        resultConfig.projects[OTHER_PROJECT_NAME].architect.deploy
-      ).toBeTruthy();
+      const deployTarget = resultConfig.projects[OTHER_PROJECT_NAME].architect.deploy;
+      expect(deployTarget.builder).toBe('angular-cli-ghpages:deploy');
     });
   });