chore(tooling): align CLI tooling and verify packed consumers

.bun-version

@@ -1 +1 @@
-1.4.2
+1.4.3

.github/workflows/verify.yml

@@ -43,17 +43,24 @@ jobs:
         with:
           bun-version-file: .bun-version
 
+      - name: Install Node.js
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version-file: .node-version
+
       - name: Install completion shells
         run: sudo apt-get update && sudo apt-get install --yes fish zsh
 
+      - name: Install dependencies
+        run: bun run setup
+
       - name: Install data app browser
         working-directory: data-app/tests
         run: |
-          bun install --frozen-lockfile
           bunx playwright install --with-deps chromium
 
       - name: Verify repository and integration paths
-        run: ./scripts/verify.sh --integration
+        run: bun run check --integration
 
       - name: Upload coverage report
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2

AGENTS.md

@@ -22,11 +22,13 @@ For data app starter, distribution, and browser work, follow [data-app/AGENTS.md
 
 ## Start here
 
+Install dependencies separately with `bun run setup` from the repository root before verification.
+
 ```bash
 git submodule update --init --recursive   # first checkout only
-./scripts/verify.sh --quick               # focused CLI changes, including coverage
-./scripts/verify.sh                         # full gate before PR (mirrors CI minus native compile)
-./scripts/verify.sh --integration         # lakehouse HTTP paths (mock at :15000)
+bun run check --quick               # focused CLI changes, including coverage
+bun run check                         # full gate before PR (mirrors CI minus native compile)
+bun run check --integration         # lakehouse HTTP paths (mock at :15000)
 ```
 
 For data app changes, run the focused checks first from the repository root:
@@ -38,8 +40,8 @@ bun run --cwd cli data-app:test:browser
 
 The starter build requires its published package dependencies; see [data-app/README.md](data-app/README.md)
 for setup and browser prerequisites. Run `bun run --cwd cli data-app:check` to check all
-three data app projects together. Use `./scripts/verify.sh --quick` after focused checks,
-then default `./scripts/verify.sh` before opening a PR.
+three data app projects together. Use `bun run check --quick` after focused checks,
+then default `bun run check` before opening a PR.
 
 ## Deep guides
 

CONTRIBUTING.md

@@ -6,7 +6,7 @@ The CLI is a TypeScript/Bun project in `cli/`. The entrypoint `bin/altertable` i
 
 1. Fork and clone the repository
 2. Initialize submodules: `git submodule update --init --recursive`
-3. Install dependencies: `cd cli && bun install`
+3. Install dependencies: `bun run setup` (from the repository root)
 4. Install the [Oxc VS Code extension](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) (works in Cursor) for format-on-save and lint diagnostics
 
 See [DEVELOPMENT.md](DEVELOPMENT.md) for build, compile, and release details.
@@ -15,8 +15,8 @@ See [DEVELOPMENT.md](DEVELOPMENT.md) for build, compile, and release details.
 
 1. Create a branch from `main`
 2. Edit `cli/src/**`
-3. Run checks: `./scripts/verify.sh` (use `--quick` for iterative CLI-only work; full verify before opening PR)
-4. Run integration tests when touching lakehouse HTTP paths: `./scripts/verify.sh --integration` (mock at `:15000`)
+3. Run checks: `bun run check` (use `bun run check --quick` for iterative work; full gate before opening PR)
+4. Run integration tests when touching lakehouse HTTP paths: `bun run check --integration` (mock at `:15000`)
 5. Commit using [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, etc.)
 6. Update `CHANGELOG.md` under `[Unreleased]` when the change is user-facing
 7. Open a pull request

DEVELOPMENT.md

@@ -6,6 +6,55 @@ The Bun runtime used by contributors, CI, and release builds is pinned in [`.bun
 
 GitHub Actions use the Node.js LTS version pinned in [`.node-version`](.node-version).
 
+From the repository root:
+
+```fish
+bun run setup                 # frozen installs for CLI and isolated consumers
+bun run dev -- --help         # same as bin/altertable
+bun run build                 # npm bundle in cli/dist/cli.js
+bun run typecheck
+bun run lint
+bun run lint:fix
+bun run format
+bun run format:check
+bun run test                  # Bun CLI unit tests, no watch
+bun run test:watch
+bun run knip                  # unused code, exports, and dependencies
+bun run knip:production       # production reachability
+bun run check                 # full canonical gate, including consumers and packages
+bun run check --quick         # focused gate without browser/package smoke tests
+bun run check:package         # focused build, pack, and extracted-consumer smoke
+```
+
+The root is a private command entry point, not a workspace: `cli/bun.lock` and the
+starter and browser-test lockfiles remain independent. Individual commands above
+operate on the CLI; the canonical check also covers top-level tests and the data app
+consumers. Install dependencies explicitly with `bun run setup` before checking;
+verification does not install development dependencies. Artifact smoke tests still
+install generated apps to exercise the real consumer path.
+
+CLI tests intentionally use `bun test` because they exercise Bun APIs and the CLI's
+runtime. The Bun build plugin embeds the offline starter in both npm and native
+artifacts; retaining it avoids introducing another build tool and plugin adapter.
+Formatting uses single quotes, ES5 trailing commas, unparenthesized single arrow
+parameters, an 80-column print width, and LF line endings. Import sorting is enabled while
+package JSON key order is preserved (`sortPackageJson: false` in Oxfmt 0.71).
+Generated API files stay
+under their generators' control.
+
+Typechecking uses TypeScript 7.0.2. The CLI installs that compiler under the explicit
+`typescript-checker` alias because `openapi-typescript` still needs the TypeScript
+6.0.3 JavaScript compiler API to generate identical API types. Its `typescript`
+dependency stays at 6.0.3 for generation only; both CLI and top-level test checks
+invoke the version 7 compiler explicitly. Knip excludes this alias from unused
+dependency detection because it is executed by its installed file path.
+
+`check:package` builds once, packs and extracts the CLI, and runs the full generated-app
+consumer smoke against the extracted executable. It does not run repository unit tests,
+Playwright tests, or lakehouse integration. The full `check` invokes it once.
+
+Additional commands from `cli/`:
+
 ```bash
 cd cli
 bun install
@@ -23,7 +72,7 @@ bun run generate:commands      # regenerate Markdown, JSON, and JSON Schema comm
 bun run generate:check         # non-mutating generated-artifact drift check
 bun run spec:refresh           # fetch hosted OpenAPI spec (see specs/rest/SPEC.md) + generate
 bun run build                  # bundle to cli/dist/cli.js
-bun run pack:check             # build + dry-run pack (verify publish contents)
+bun run pack:check             # build, pack, extract, and smoke-test the npm artifact
 ```
 
 The CLI reference wire contract is rendered from the command-reference module into
@@ -46,7 +95,7 @@ The JS bundle is the npm `bin` entry and a GitHub Release asset:
 cd cli
 bun run build                  # writes cli/dist/cli.js
 bun run scripts/smoke-npm-bundle.ts
-bun run pack:check             # ensures dist/ is the only packed file
+bun run pack:check             # smoke-test the actual packed executable and offline scaffold
 ```
 
 ## Compile native binaries
@@ -106,7 +155,7 @@ On push to `main`, `.github/workflows/release-please.yml`:
    The completed GitHub Release becomes public only after npm publication succeeds.
 
 Both `.github/workflows/test.yml` and the release workflow call `.github/workflows/verify.yml`, which
-runs the repository and integration gates and executes the npm bundle on the minimum supported Bun
+runs `bun run check --integration` and executes the npm bundle on the minimum supported Bun
 runtime. Branch CI then loads its native compile matrix from the typed release manifest and
 smoke-tests every Linux and macOS release target. Main-branch verification is never cancelled by a
 newer push. Workflows use explicit permissions, pinned runners/actions, concurrency controls, and job
@@ -177,12 +226,12 @@ The stored profile records only the URLs, not the flag, so subsequent commands a
 
 ## Verify (agents and contributors)
 
-From repo root, one script mirrors CI (minus native binary compile):
+From the repository root, the canonical command mirrors CI (minus native binary compile):
 
-```bash
-./scripts/verify.sh --quick        # typecheck, lint, format, knip, coverage, generated-artifact drift
-./scripts/verify.sh                # + build, pack:check, top-level black-box tests
-./scripts/verify.sh --integration  # + tests/integration.e2e.ts (requires mock at :15000)
+```fish
+bun run check --quick        # typecheck, lint, format, knip, coverage, drift, black-box tests
+bun run check                # + browser tests, package build, and consumer smoke
+bun run check --integration  # + tests/integration.e2e.ts (requires mock at :15000)
 ```
 
 See [AGENTS.md](AGENTS.md) and [cli/AGENTS.md](cli/AGENTS.md) for agent-oriented docs.

cli/.oxfmtrc.json

@@ -1,4 +1,11 @@
 {
   "$schema": "./node_modules/oxfmt/configuration_schema.json",
-  "ignorePatterns": ["dist/**", "src/generated/**", "bun.lock"]
+  "ignorePatterns": ["dist/**", "src/generated/**", "bun.lock"],
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "arrowParens": "avoid",
+  "printWidth": 80,
+  "endOfLine": "lf",
+  "sortImports": true,
+  "sortPackageJson": false
 }

cli/AGENTS.md

@@ -1,6 +1,6 @@
 # Agent guide — `cli/`
 
-Repo-level router: [../AGENTS.md](../AGENTS.md). Run `./scripts/verify.sh` from repo root.
+Repo-level router: [../AGENTS.md](../AGENTS.md). Run `bun run check` from repo root.
 
 Executor-oriented notes for working in the TypeScript CLI subtree.
 
@@ -14,10 +14,12 @@ Executor-oriented notes for working in the TypeScript CLI subtree.
 
 Preferred — from repo root:
 
+Install dependencies separately with `bun run setup` from the repository root before verification.
+
 ```bash
-./scripts/verify.sh --quick    # CLI checks only (typecheck, lint, format, knip, coverage, openapi drift)
-./scripts/verify.sh            # full gate (mirrors CI minus native compile)
-./scripts/verify.sh --integration   # + tests/integration.e2e.ts (mock at :15000)
+bun run check --quick    # CLI checks only (typecheck, lint, format, knip, coverage, openapi drift)
+bun run check            # full gate (mirrors CI minus native compile)
+bun run check --integration   # + tests/integration.e2e.ts (mock at :15000)
 ```
 
 Manual equivalents from `cli/`:
@@ -167,13 +169,17 @@ metadata; do not inspect or rewrite raw argv in parent handlers.
 Minimal pattern (management HTTP command):
 
 ```typescript
-import { defineCommand } from "@/lib/command.ts";
-import { sendHttp } from "@/lib/http-request.ts";
+import { defineCommand } from '@/lib/command.ts';
+import { sendHttp } from '@/lib/http-request.ts';
 
 export const myfeatureCommand = defineCommand({
-  meta: { name: "myfeature", description: "…" },
+  meta: { name: 'myfeature', description: '…' },
   async run({ execution, sink }) {
-    const request = { plane: "management", method: "GET", endpoint: "/path" } as const;
+    const request = {
+      plane: 'management',
+      method: 'GET',
+      endpoint: '/path',
+    } as const;
     const response = await sendHttp(request, execution);
     sink.writeJson(JSON.parse(response));
   },
@@ -206,7 +212,7 @@ Bump the OpenAPI spec and extend `openapi-http-conformance.test.ts` placeholder
 | lib pure function    | `cd cli && bun test path/to.test.ts`             |
 | command validation   | colocated `src/commands/<family>/<name>.test.ts` |
 | HTTP behavior        | mock file via `ALTERTABLE_MOCK_HTTP_FILE`        |
-| end-to-end lakehouse | `./scripts/verify.sh --integration`              |
+| end-to-end lakehouse | `bun run check --integration`                    |
 | completion structure | `cd cli && bun test src/commands/completion`     |
 
 Test env vars: `ALTERTABLE_CONFIG_HOME`, `ALTERTABLE_SECRET_BACKEND=file`, `ALTERTABLE_MOCK_HTTP_FILE`, `ALTERTABLE_HTTP_LOG`.