feat(#630): make @altinity/clickhouse-http standalone-buildable, retire client-web vendor spike (phase 8)

.github/workflows/ci.yml

@@ -84,13 +84,14 @@ jobs:
               - 'src/**'
               - 'schemas/**'
               - 'tests/e2e/**'
-              # #630 Phase 1: tests/e2e/clickhouse-http-transport.spec.js now
-              # imports this ONE shared spike fixture server directly — a
+              # #630 Phase 1 named the shared fixture server
+              # (tests/spike/clickhouse-client/fault-server.mjs) here
+              # explicitly, since the root e2e suite imports it directly — a
               # real cross-tree dependency the PR path filter didn't know
-              # about before. Deliberately narrow (not `tests/spike/**`):
-              # the rest of that historical spike suite is not a dependency
-              # of the root e2e suite and stays out of ordinary PR CI.
-              - 'tests/spike/clickhouse-client/fault-server.mjs'
+              # about otherwise. #630 Phase 8 moved that fixture to
+              # packages/clickhouse-http/test/browser/fault-server.mjs,
+              # already covered by the blanket 'packages/**' entry below, so
+              # no dedicated entry is needed here anymore.
               - 'playwright.config.js'
               - 'build/**'
               - 'package.json'
@@ -150,6 +151,8 @@ jobs:
       - run: npm ci --no-audit --no-fund
       - name: Test (vitest + coverage gate)
         run: npm test
+      - name: '@altinity/clickhouse-http isolated-package proof (npm pack, install outside the workspace, ESM + TS resolution)'
+        run: npm run test:clickhouse-http:pack
       - name: Build single-file SPA
         run: npm run build
       - uses: actions/upload-artifact@v7
@@ -253,7 +256,10 @@ jobs:
       - name: Lint the installer (shellcheck)
         run: |
           sudo apt-get update -qq && sudo apt-get install -y -qq shellcheck
-          shellcheck install.sh build/bundle.sh
+          # #630 Phase 8 modifies both build wrappers (each now composes the
+          # package build explicitly) — lint both alongside the existing root
+          # installer shell script.
+          shellcheck install.sh build/bundle.sh deploy/install.sh
 
   # Exercise the published runtime shape, including Caddy's static
   # Content-Encoding negotiation. Node decodes each selected sidecar, so the
@@ -363,7 +369,8 @@ jobs:
       (github.event_name == 'pull_request' && needs.changes.outputs.e2e == 'true')
     runs-on: ubuntu-latest
     env:
-      # One engine on PRs, all three everywhere else.
+      # Root SQL Browser e2e: one engine on PRs, all three everywhere else
+      # (unchanged cost policy — #630 Phase 8 does not widen this).
       PR_ONLY_CHROMIUM: ${{ github.event_name == 'pull_request' }}
     steps:
       - uses: actions/checkout@v7
@@ -372,10 +379,15 @@ jobs:
           node-version: '22'
           cache: npm
       - run: npm ci --no-audit --no-fund
+      # #630 Phase 8: the @altinity/clickhouse-http package's own Chromium/
+      # WebKit regression suite runs on every applicable CI event alongside
+      # the root suite (issue #630's own required acceptance engines for the
+      # package), so WebKit is installed on PRs too now, not just Chromium —
+      # widened from Chromium-only specifically for this package suite.
       - name: Install Playwright browsers
         run: |
           if [ "$PR_ONLY_CHROMIUM" = "true" ]; then
-            npx playwright install --with-deps chromium
+            npx playwright install --with-deps chromium webkit
           else
             npx playwright install --with-deps chromium firefox webkit
           fi
@@ -386,6 +398,8 @@ jobs:
           else
             npm run test:e2e
           fi
+      - name: '@altinity/clickhouse-http Chromium+WebKit regression suite'
+        run: npm run test:clickhouse-http:browser -- --project=chromium --project=webkit
       - uses: actions/upload-artifact@v7
         if: ${{ failure() }}
         with:

.wiki/Architecture.md

@@ -80,7 +80,20 @@ module mocking.
 
 `build/build.mjs` bundles `src/main.js` with esbuild, minifies it, and inlines JS
 and `src/styles.css` into `build/template.html`. Output is `dist/sql.html`, with
-no third-party runtime requests.
+no third-party runtime requests. `packages/clickhouse-http` (#630 Phase 2's
+first npm workspace) has its own independent build/type/test boundary since
+Phase 8 — package-local esbuild/tsc produce `dist/**` (unbundled ESM +
+declarations), and its manifest resolves there, never to source; root
+`npm run build`/`build/bundle.sh`/`deploy/install.sh` all explicitly build
+the package first so root esbuild's bare `@altinity/clickhouse-http` import
+resolves to that built output through the workspace `node_modules` symlink.
+Phase 8 also closes issue #630: the migration-only `ch-client.js`
+forwarding aliases are gone, `@clickhouse/client-web` and its executable
+vendor-spike wiring (`tests/spike/clickhouse-client/**`) are removed, and
+the package's own Chromium+WebKit regression suite
+(`packages/clickhouse-http/test/browser/**`) proves the built artifact
+directly. See [`docs/clickhouse-http-repository-extraction.md`](../docs/clickhouse-http-repository-extraction.md)
+for the #639 handoff.
 
 Canonical source: [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md) and
 [`CLAUDE.md`](../CLAUDE.md).

.wiki/Decisions-and-Roadmap.md

@@ -369,6 +369,71 @@ Two roadmap tracks are current:
   (`build/lib/check-legacy-owners.mjs`) rather than a specifier-text regex,
   since a regex cannot tell which names a named import binds.
 
+  **Phase 8** (final phase, merged) claims **A17**/**A18**, completing issue
+  #630. `packages/clickhouse-http` becomes independently buildable/packable:
+  package-local `esbuild` (unbundled browser-first ESM, `bundle: false`) and
+  `tsc` (declaration-only emit) produce `dist/**`; the manifest's `main`/
+  `types`/`exports["."]` all point at that built output, never source;
+  `npm run build`/`build/bundle.sh`/`deploy/install.sh` all explicitly build
+  the package first (`npm run build:clickhouse-http`) before the root
+  application builder, so root esbuild's metafile resolves the workspace
+  symlink to `packages/clickhouse-http/dist/*.js` — attributed to the
+  `project` ownership bucket, never `external` — with no `packages/
+  clickhouse-http/src/*.ts` input anywhere. Root `tsconfig.json`/Vitest
+  coverage drop package source entirely; package-local `tsconfig.json`/
+  `vitest.config.ts` (100/95/90/100 per file) own it instead, exercising the
+  built public barrel via a relative import to `src/index.ts` (coverage
+  attribution reasons — the isolated-package proof below is the real
+  built-artifact proof). A new `test/isolated-package.mjs` (`npm run
+  test:pack`) builds the package, runs a REAL `npm pack`, installs the
+  tarball into a fixture OUTSIDE the repository, imports it as ESM, and
+  compiles a TypeScript consumer against its declarations — proving neither
+  runtime nor type resolution ever falls back into this repository's source.
+  A new package-owned Chromium/WebKit regression suite
+  (`packages/clickhouse-http/test/browser/**`) serves the package's own
+  generated `dist/**` directly (`harness.html` imports `/dist/index.js`, no
+  import map); its former root-suite home
+  (`tests/e2e/clickhouse-http-transport.{html,spec.js}`) splits into that
+  package suite plus a narrower root `tests/e2e/authenticated-clickhouse-
+  request.{html,spec.js}` for SQL Browser's own authentication-policy
+  variants (the package-owned `fault-server.mjs` fixture, moved from the
+  spike, stays importable from both). The migration-only `ch-client.ts`
+  forwarding aliases (`chUrl`/`parseExceptionText`/`findExceptionFrame`) are
+  removed now that every spike consumer is gone; `export-service.ts` imports
+  `findExceptionFrame` directly from the package under one narrow, named
+  Rule-D exception (`PHASE8_NARROW_RULE_D_EXCEPTIONS`) rather than through
+  that retired gateway. Five new/extended architecture guards
+  (`build/check-boundaries.mjs`/`build/lib/check-legacy-owners.mjs`, all
+  real-parser-backed, never a hand-rolled regex scanner): package
+  containment broadens to the package's own `test/**`/`build.mjs`/
+  `vitest.config.ts` (Guard 1); the relative-deep-import ban on the package
+  widens from `src/**` to the whole package directory, catching a
+  `dist/**` escape a source-only ban would have missed (Guard 2); root-wide
+  (not just former-owner-scoped) declaration/re-export ownership for the
+  historical `chUrl`/`createHttpTransport`/`ClickHouseTransport`/
+  `TransportDeps`/`TransportRequest` transport surface, with an exemption for
+  the sanctioned package import itself (Guard 3); the same root-wide
+  ownership rule for the moved progress-stream/exception-parsing primitives
+  (Guard 4); and the `@clickhouse/client-web` ban's former "future official
+  transport file" allowlist is deleted outright, its scan widened to
+  `src/**`/`packages/clickhouse-http/**` (excluding generated `dist/**`)/
+  `tests/**`/`build/**`, plus structural manifest/lock/script/directory
+  checks (Guard 5). The whole `@clickhouse/client-web` devDependency, its
+  npm scripts, and the executable `tests/spike/clickhouse-client/**`
+  directory (33 files by the plan's own count) are deleted per an exact
+  file-by-file disposition table — most outright, `fault-server.mjs` moved
+  (above), a handful ported into first-party regressions then deleted; the
+  candidate-build-only `additionalNotices`/`--notices` plumbing in
+  `build/build.mjs`/`build/size-report.mjs` goes with them.
+  `docs/evidence/585/**` and ADR-0005's Rejected decision/historical content
+  are untouched — only a narrow current-state addendum documents the
+  executable retirement (`tests/unit/client-web-retirement-policy.test.js`
+  replaces the former `client-web-spike-policy.test.js`, whose assertions
+  described the now-retired opposite state). #639 begins with external
+  repository creation/release and the SQL Browser consumer cutover, per the
+  tested mechanical extraction handoff this phase adds,
+  [`docs/clickhouse-http-repository-extraction.md`](../docs/clickhouse-http-repository-extraction.md).
+
 Re-read GitHub before acting because issue state can change; a MERGED PR is
 not proof its code is on `main` (see the reset above).