|
| 1 | +# Original Prompt |
| 2 | + |
| 3 | +> Let's fix the cloudflare. |
| 4 | +> |
| 5 | +> I also want to completely refactor this repo to TypeScript without breaking CI. |
| 6 | +> |
| 7 | +> Do we have a full e2e test for App Scanning? |
| 8 | +
|
| 9 | +# Goal |
| 10 | + |
| 11 | +Move the repo from a mostly JavaScript codebase to a TypeScript-first codebase without breaking CI, production deploys, or the existing app-scanning behavior, while keeping each migration slice small enough to review and roll back. |
| 12 | + |
| 13 | +# Non-Goals |
| 14 | + |
| 15 | +- Rewrite the whole repo to TypeScript in one commit. |
| 16 | +- Change scanner or site behavior just to satisfy typing. |
| 17 | +- Replace Astro, Vue, pnpm, or Netlify/Cloudflare as part of the migration itself. |
| 18 | +- Force every legacy worker/helper package onto modern tooling before the type migration proves out. |
| 19 | + |
| 20 | +# Repo Findings |
| 21 | + |
| 22 | +- The repo is still overwhelmingly JavaScript-led: |
| 23 | +- 195 code files across `.ts`, `.js`, `.mjs`, `.vue`, and `.astro` |
| 24 | +- 12 TypeScript files, about 6.2% of code files |
| 25 | +- 1,802 TypeScript lines out of 20,721 total code lines, about 8.7% by line count |
| 26 | +- The scanner/app-test surface is now the strongest typed foothold in the repo: |
| 27 | +- `helpers/scanner/client.ts` |
| 28 | +- `helpers/scanner/scan.ts` |
| 29 | +- `helpers/scanner/worker.ts` |
| 30 | +- `test/scanner/client.test.ts` |
| 31 | +- The browser harness is already typed and now protects the main app-scanning flow: |
| 32 | +- `test/playwright/apple-silicon-app-test.playwright.ts` |
| 33 | +- `test/playwright/pagefind-native-filter.playwright.ts` |
| 34 | +- App-scanning coverage is strong for the happy path, but not exhaustive: |
| 35 | +- There is a real browser upload E2E for both the legacy scanner and the worker scanner via `?version=2`. |
| 36 | +- That test stubs the result-store POST, so it is not a full database/backend integration test. |
| 37 | +- There is a direct worker-scanner test using a generated `.app.zip` fixture. |
| 38 | +- Negative fixtures and heavier archive cases like DMG/PKG are still missing. |
| 39 | +- The page layer still uses JavaScript/Vue options API in `pages/apple-silicon-app-test.vue`, even though the scanner internals beneath it are now typed. |
| 40 | +- The repo has mixed runtime shapes: |
| 41 | +- old `.js` helper modules |
| 42 | +- some `.mjs` server/build modules |
| 43 | +- `.vue` and `.astro` files with little or no embedded TypeScript |
| 44 | +- Cloudflare worker subprojects under `doesitarm-default/` and `workers/analytics/` still use old JavaScript toolchains and should be treated as separate migration surfaces. |
| 45 | + |
| 46 | +# Decision |
| 47 | + |
| 48 | +Do the migration as a staged refactor with explicit CI gates after each slice. Keep the scanner/app-test lane as the proving ground, then expand outward to helper/build modules, then UI/runtime surfaces, then worker subprojects. Prefer converting boundary-stable modules first and avoid cross-repo churn until tests and deploys stay green. |
| 49 | + |
| 50 | +# Rollout Plan |
| 51 | + |
| 52 | +1. Lock the migration baseline and CI contract. |
| 53 | +- Treat `pnpm run typecheck`, `pnpm run test`, and `pnpm run test:browser` as the minimum green gate for repo-level migration slices. |
| 54 | +- Keep production smoke checks for app scanning and Pagefind in the validation ladder when changes touch scanner, app-test, or search. |
| 55 | +- Do not merge large TypeScript batches without passing the same gates that currently protect production deploys. |
| 56 | + |
| 57 | +2. Finish the scanner-adjacent TypeScript lane before broadening scope. |
| 58 | +- Convert the remaining scanner internals and helper modules that sit directly below the typed worker surface: |
| 59 | +- `helpers/scanner/parsers/macho.js` |
| 60 | +- `helpers/scanner/parsers/plist.js` |
| 61 | +- `helpers/scanner/file-api.js` |
| 62 | +- Add negative scanner fixtures alongside the existing happy-path test: |
| 63 | +- decompression failure |
| 64 | +- missing `Info.plist` |
| 65 | +- missing Mach-O |
| 66 | +- non-native architecture result |
| 67 | +- Keep the app-test browser E2E green for both the default path and `?version=2`. |
| 68 | + |
| 69 | +3. Make the worker scanner the default path, then delete the legacy scanner. |
| 70 | +- Switch the app-test page to use the typed worker scanner path by default. |
| 71 | +- Keep the browser test protecting the route while that cutover happens. |
| 72 | +- Once the default path is stable, remove the old `helpers/app-files-scanner.js` legacy implementation rather than maintaining two divergent scanner stacks. |
| 73 | +- This is the biggest simplification available before broader TypeScript conversion. |
| 74 | + |
| 75 | +4. Convert runtime config, URL, and shared helper modules. |
| 76 | +- Migrate shared helper modules that are reused by pages and builds but have relatively stable behavior: |
| 77 | +- `helpers/public-runtime-config.mjs` |
| 78 | +- `helpers/url.js` |
| 79 | +- `helpers/check-types.js` |
| 80 | +- `helpers/environment.js` |
| 81 | +- `helpers/config-node.js` |
| 82 | +- Prefer module-by-module conversion with targeted regression coverage instead of umbrella “helpers” commits. |
| 83 | + |
| 84 | +5. Convert build and list-generation modules in bounded slices. |
| 85 | +- Move the build pipeline from mixed `.js`/`.mjs` to typed modules in sequence: |
| 86 | +- list builders (`helpers/build-*.js`) |
| 87 | +- API/static builders |
| 88 | +- scripts under `scripts/` |
| 89 | +- `build-lists.js` |
| 90 | +- Keep `pnpm netlify-build` as the main verification gate for this stage, because these modules affect the deploy artifact more than the browser UI. |
| 91 | + |
| 92 | +6. Convert Vue and Astro surfaces after their underlying helpers are typed. |
| 93 | +- Start with high-risk pages that already have browser tests: |
| 94 | +- `pages/apple-silicon-app-test.vue` |
| 95 | +- search surfaces touched by the Pagefind regression |
| 96 | +- Then move into other Vue components and Astro pages incrementally. |
| 97 | +- Avoid converting large groups of Vue components in one pass unless they share the same typed props/state model. |
| 98 | + |
| 99 | +7. Migrate the Cloudflare worker subprojects as a separate workstream. |
| 100 | +- Treat `doesitarm-default/` and `workers/analytics/` as isolated packages with their own runtime/toolchain constraints. |
| 101 | +- Convert them after the main site/scanner path is stable. |
| 102 | +- Keep their CI/deploy workflow green independently of the main Astro site migration. |
| 103 | + |
| 104 | +# Validation Gates |
| 105 | + |
| 106 | +- For scanner/app-test changes: |
| 107 | +- `pnpm run typecheck` |
| 108 | +- `pnpm exec vitest run test/scanner/client.test.ts` |
| 109 | +- `pnpm run test:browser` |
| 110 | +- production smoke on `https://doesitarm.com/apple-silicon-app-test/` |
| 111 | + |
| 112 | +- For helper/build changes: |
| 113 | +- `pnpm run typecheck` |
| 114 | +- `pnpm run test` |
| 115 | +- `pnpm netlify-build` |
| 116 | + |
| 117 | +- For search-related changes: |
| 118 | +- `pnpm run typecheck` |
| 119 | +- `PLAYWRIGHT_BASE_URL=https://doesitarm.com pnpm run test:browser:pagefind` |
| 120 | + |
| 121 | +- For worker-subproject changes: |
| 122 | +- the relevant worker install/build path still succeeds |
| 123 | +- the Cloudflare deploy workflow remains green |
| 124 | + |
| 125 | +# Deliverables |
| 126 | + |
| 127 | +- A staged TypeScript migration plan in `docs/plans/repo-typescript-migration.md` |
| 128 | +- A bounded migration order that preserves CI and production safety |
| 129 | +- A rule for when it is safe to remove the legacy scanner path |
| 130 | +- Expanded scanner fixture coverage beyond the current native happy path |
| 131 | +- A clear split between main-site migration work and Cloudflare worker migration work |
| 132 | + |
| 133 | +# Risks And Open Questions |
| 134 | + |
| 135 | +- The fastest way to “convert everything” would create too much churn and likely destabilize CI; the staged path is slower but safer. |
| 136 | +- Browser-safe archive support may continue to diverge from Node/Bun-safe archive support for formats like DMG and PKG. |
| 137 | +- Legacy helper modules may hide runtime assumptions that only show up in the full Netlify build path. |
| 138 | +- Vue options-API files can become noisy when typed mechanically; they should be migrated only after props/state boundaries are clear. |
| 139 | +- The Cloudflare subprojects use older JS tooling and may need their own migration plan if they resist the main repo conventions. |
| 140 | +- “100% TypeScript” may not be worth pursuing literally for generated glue or tiny legacy worker entrypoints if the last few files cost more risk than value. |
| 141 | + |
| 142 | +# Sources |
| 143 | + |
| 144 | +- `docs/plans/app-test-typescript-refactor.md` |
| 145 | +- `docs/plans/app-discovery-d1-automation.md` |
| 146 | +- `test/playwright/apple-silicon-app-test.playwright.ts` |
| 147 | +- `test/scanner/client.test.ts` |
| 148 | +- `helpers/scanner/client.ts` |
| 149 | +- `helpers/scanner/scan.ts` |
| 150 | +- `helpers/scanner/worker.ts` |
| 151 | +- `pages/apple-silicon-app-test.vue` |
0 commit comments