# npm scripts

> Exact package.json commands: bootstrap, check, package, verify, smoke, publication:check, frontend:build, and test globs.

- Repository: sashimikun/grok-bot-0.18-reconstructed
- GitHub: https://github.com/sashimikun/grok-bot-0.18-reconstructed
- Human docs: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15
- Complete Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/llms-full.txt

## Source Files

- `package.json`
- `scripts/bootstrap-runtime.mjs`
- `scripts/build.mjs`
- `scripts/package-macos.mjs`
- `scripts/verify.mjs`
- `scripts/smoke.mjs`
- `scripts/verify-publication-tree.mjs`

---

---
title: "npm scripts"
description: "Exact package.json commands: bootstrap, check, package, verify, smoke, publication:check, frontend:build, and test globs."
---

`package.json` is the command surface for this reconstruction. The package is `grok-bot-0.18-reconstructed` at `0.18.0-reconstructed.1`, `"type": "module"`, `"private": true`, and `engines.node` `>=26.5.0 <27`. Every `npm run` entry is a Node ESM script, a `tsc` project, Vite, or a composition of those. `npm ci` also runs `postinstall`.

```json
{
  "bootstrap": "node scripts/bootstrap-runtime.mjs",
  "build": "node scripts/build.mjs",
  "check": "npm run typecheck && npm run source:typecheck && npm test",
  "frontend:build": "vite build --config frontend/vite.config.ts",
  "frontend:recover": "node scripts/recover-frontend.mjs",
  "native:patch": "node scripts/apply-third-party-patches.mjs",
  "native:build:electron": "node scripts/build-tree-sitter-electron.mjs",
  "package": "npm run check && node scripts/package-macos.mjs",
  "package:diagnostic": "npm run check && node scripts/package-fidelity-diagnostic.mjs",
  "publication:check": "node scripts/verify-publication-tree.mjs",
  "postinstall": "node scripts/apply-third-party-patches.mjs",
  "smoke": "node scripts/smoke.mjs",
  "test": "node --test tests/*.test.mjs",
  "typecheck": "tsc --project frontend/tsconfig.json",
  "source:typecheck": "tsc --project source/tsconfig.json",
  "verify": "node scripts/verify.mjs"
}
```

## Script graph

`check` is the shared gate. `package` and `package:diagnostic` always run it first. `bootstrap` is independent and must succeed before packaging can resolve the 0.18.0 Electron shell. `frontend:build` does not feed the default packaged renderer.

```mermaid
flowchart TB
  subgraph install["install"]
    PI["postinstall / native:patch"]
  end
  subgraph gate["npm run check"]
    TC["typecheck<br/>frontend/tsconfig.json"]
    STC["source:typecheck<br/>source/tsconfig.json"]
    TST["test<br/>tests/*.test.mjs"]
    TC --> STC --> TST
  end
  subgraph hydrate["bootstrap"]
    B["scripts/bootstrap-runtime.mjs"]
    SRC["ignored src/app/dist"]
    CACHE[".cache/runtime/Grok Bot.app"]
    B --> SRC
    B --> CACHE
  end
  PKG["package"] --> gate
  PKG --> PM["scripts/package-macos.mjs"]
  PM --> CACHE
  PM --> SRC
  PM --> DIST["dist/Grok Bot 0.18 Reconstructed.app"]
  BUILD["build"] --> ASAR[".build/fidelity/app.asar"]
  V["verify"] --> DIST
  SM["smoke"] --> DIST
  FB["frontend:build"] --> SHELL[".build/frontend-shell"]
  PUB["publication:check"] --> TREE["HEAD tree vs archive/init/add"]
```

## Catalog

| Script | Command | Role |
| --- | --- | --- |
| `bootstrap` | `node scripts/bootstrap-runtime.mjs` | Pin, cache, and hydrate the 0.18.0 runtime |
| `check` | `typecheck && source:typecheck && test` | Sequential typecheck + unit tests |
| `package` | `check` then `scripts/package-macos.mjs` | Darwin app bundle, ad-hoc sign, package audit |
| `verify` | `node scripts/verify.mjs` | Inspect an existing `.app` ASAR and identity |
| `smoke` | `node scripts/smoke.mjs` | Native e2e launch, 12s timeout |
| `publication:check` | `node scripts/verify-publication-tree.mjs` | Prove `git archive` export is lossless |
| `frontend:build` | `vite build --config frontend/vite.config.ts` | Design-workspace renderer to `.build/frontend-shell` |
| `test` | `node --test tests/*.test.mjs` | One-level glob under `tests/` |
| `typecheck` | `tsc --project frontend/tsconfig.json` | Renderer TS, `noEmit` |
| `source:typecheck` | `tsc --project source/tsconfig.json` | Runtime TS, `noEmit` |
| `build` | `node scripts/build.mjs` | Fidelity hybrid ASAR only (no `.app`) |
| `package:diagnostic` | `check` then `scripts/package-fidelity-diagnostic.mjs` | Isolated fidelity diagnostic bundle |
| `frontend:recover` | `node scripts/recover-frontend.mjs` | Ignored formatted copy under `recovered/frontend` |
| `native:patch` | `node scripts/apply-third-party-patches.mjs` | Same as `postinstall` |
| `native:build:electron` | `node scripts/build-tree-sitter-electron.mjs` | Rebuild tree-sitter for Electron ABI |

## `npm run bootstrap`

Resolves a Grok Bot **0.18.0** app, verifies `app.asar` SHA-256 `6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58`, and extracts `dist/` into ignored `src/app/dist`.

Resolution order:

1. `GROK_BOT_018_APP` — copy that app into `.cache/runtime/Grok Bot.app` after `CFBundleShortVersionString` is `0.18.0`.
2. Cached app at `.cache/runtime/Grok Bot.app`.
3. Git LFS DMG `research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg` (SHA-256 `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb`), copied to `.cache/downloads/Grok_Bot_0.18.0.dmg`.
4. Public URL `https://downloads.cursor.com/grokbot/stable/darwin-arm64/0.18.0/Grok_Bot_0.18.0.dmg`.

DMG extract uses `hdiutil attach` on `Grok Bot.app`. Hydration requires `dist/electron-main/main.cjs`, `dist/host/host-main.cjs`, and `dist/renderer/index.html`.

<RequestExample>
```bash
npm run bootstrap
```
</RequestExample>

<ResponseExample>
```text
Runtime ready: <repo>/.cache/runtime/Grok Bot.app
Checksum-pinned source payload ready: <repo>/src/app/dist (<sha256>)
The checksum-pinned app supplies only the Electron shell, ABI-matched native dependencies, and explicitly documented build fallbacks.
```
</ResponseExample>

<ParamField body="GROK_BOT_018_APP" type="string">
Absolute path to an existing 0.18.0 `Grok Bot.app`. Version mismatch fails before hydration.
</ParamField>

Failure cases: LFS pointer-sized archive, DMG checksum mismatch (`Run git lfs pull before bootstrapping.`), HTTP download failure, missing required `app.asar` files, `Expected Grok Bot 0.18.0`. Later packaging without a cache throws `Missing 0.18.0 runtime. Run npm run bootstrap first.`

## `npm run check`

Runs **in order** and stops on the first non-zero exit:

1. `typecheck` — `tsc --project frontend/tsconfig.json` (`include`: `src`, `vite.config.ts`; `noEmit: true`).
2. `source:typecheck` — `tsc --project source/tsconfig.json` (`include`: `**/*.ts`; `noEmit: true`).
3. `test` — `node --test tests/*.test.mjs`.

This is the required local gate in `CONTRIBUTING.md` together with `frontend:build`. `package` embeds `check`; running `check` alone does not compile runtimes or write `dist/`.

## `npm test` glob

Exact script: `node --test tests/*.test.mjs`. The glob is one directory deep. Nested files under `tests/` are not collected.

| File | What it pins |
| --- | --- |
| `tests/backend-mcp-exec-json.test.mjs` | MCP exec JSON |
| `tests/codex-direct-responses.test.mjs` | Codex Responses client |
| `tests/inference-router-transcript.test.mjs` | Router transcript store |
| `tests/publication-bootstrap.test.mjs` | Binding paths into `source/`; hydration checksum |
| `tests/publication-packaging.test.mjs` | Verify authority is the `.app`; default fidelity renderer; ignore rules |
| `tests/reconstructed-updater-guard.test.mjs` | `SAND_DISABLE_*` packaging guard |
| `tests/research-archives.test.mjs` | LFS installer inventory `artifacts.json` schemaVersion 1 |
| `tests/router-settings.test.mjs` | Settings Router wiring |

## `npm run package`

Darwin only. Non-macOS throws `The reconstructed macOS application can only be packaged on macOS.`

After `check`, `scripts/package-macos.mjs`:

1. Compiles the fidelity hybrid ASAR (`buildFidelityReconstructedAsar`): clean `source/` runtimes where activated, checksum-pinned shipped renderer, then `applyOriginalRendererRouterPatch`.
2. Audits the official cached app as **reference only**.
3. `ditto` of the runtime into `dist/`, then `xattr -cr` to drop quarantine.
4. Replaces `Contents/Resources/app.asar` and `.unpacked`.
5. Sets `CFBundleIdentifier` `com.anysphere.sand.reconstructed`, `CFBundleDisplayName` `Grok Bot 0.18 Reconstructed`, URL scheme `sand` only; removes `ElectronAsarIntegrity`.
6. Ad-hoc `codesign` (one retry on nested-framework failure), then `codesign --verify --deep --strict`.
7. `verifyReconstructedMacPackage`.

Default output: `dist/Grok Bot 0.18 Reconstructed.app`. Default packaging keeps the checksum-pinned renderer (publication test: `default packaging keeps the polished checksum-pinned renderer`).

<ParamField body="GROK_BOT_OUTPUT_APP_NAME" type="string">
Basename of the output `.app` under `dist/`. Default `Grok Bot 0.18 Reconstructed.app`.
</ParamField>

<ParamField body="GROK_BOT_RENDERER_SOURCE" type="string">
Directory containing `index.html` copied into staged `dist/renderer` during ASAR staging. Default `npm run package` still uses the fidelity (checksum-pinned) renderer composition unless this override is set. `frontend:build` output is not selected automatically.
</ParamField>

<ParamField body="GROK_BOT_HOST_BINDINGS_MANIFEST" type="string">
Optional host production-binding manifest path.
</ParamField>

<ParamField body="GROK_BOT_ELECTRON_MAIN_BINDINGS_MANIFEST" type="string">
Optional Electron-main binding manifest. Default `manifests/reconstruction/electron-main-production-bindings-manifest.json` when that file exists.
</ParamField>

## `npm run verify`

Validates a packaged `.app` (default `dist/Grok Bot 0.18 Reconstructed.app`), not `.build/app.asar`.

Usage: `node scripts/verify.mjs [--app /absolute/path/to/App.app]`. Invalid argv throws `Usage: node scripts/verify.mjs [--app /absolute/path/to/App.app]`.

Hard checks include:

- At least **1,000** surviving `// src/` evidence markers in hydrated `electron-main` + `host` mains.
- Required ASAR entries: `dist/electron-main/main.cjs`, preloads, `node-agent-coordinator`, `host-main.cjs`, workers, `local-exec-daemon`, `dist/renderer/index.html`, `dist/reconstruction-build.json`, `dist/runtime-composition-audit.json`, `package.json`.
- Unpacked natives: `better_sqlite3.node`, `sand-webauthn-signer`, tree-sitter Node bindings.
- No renderer `.map` files in the ASAR.
- Packaged app icon matches `frontend/manifests/renderer-runtime-assets.json`.
- Bundle id `com.anysphere.sand.reconstructed`, display name `Grok Bot 0.18 Reconstructed`, `sand` URL scheme, no leftover `ElectronAsarIntegrity`.
- `codesign --verify --deep --strict`.

Renderer mode must be `checksum-pinned-artifact-runtime` or `clean-source`; anything else throws `Unsupported packaged renderer mode`.

## `npm run smoke`

`scripts/smoke.mjs` calls `runNativeE2E` on the default output app with `timeoutMs: 12_000` and `structuralOnly: false`. Launch env forces `SAND_DISABLE_UPDATES`, `SAND_DISABLE_TELEMETRY`, and `SAND_DISABLE_ANALYTICS` to `"1"`.

<ResponseField name="process.exitCode" type="number">
`0` when `report.status === "pass"`, `2` when `"prerequisite"`, `1` otherwise. Lines look like `PASS check: detail` then `Smoke verification: PASS`.
</ResponseField>

## `npm run publication:check`

On the committed tree: `git archive HEAD` → extract → `git init` → `git add --all` → compare `rev-parse HEAD^{tree}` with `write-tree`. Mismatch reports omitted and unexpected paths (first 20 each). Also requires exported `frontend/src/recovered/ui/sand-form-primitives.css` to be non-empty so ignore rules did not drop tracked frontend source.

Success: `Publication export preserves <N> files and tree <oid>.`

## `npm run frontend:build`

`vite build --config frontend/vite.config.ts`: `base: "./"`, `outDir` `.build/frontend-shell`, `emptyOutDir: true`, `sourcemap: true`. Required by contributing, independent of `package`. The packaged UI stays the patched shipped renderer unless `GROK_BOT_RENDERER_SOURCE` points at a built tree.

`frontend:recover` writes an ignored formatted inspection copy under `recovered/frontend` from bootstrapped `src/app/dist/renderer`.

## Other scripts

### `build`

Same fidelity ASAR as packaging (`buildFidelityReconstructedAsar`) without copying into a `.app`. Logs `Reconstructed ASAR: …` and `Renderer mode: checksum-pinned upstream 0.18.0 payload`.

### `package:diagnostic`

Darwin only. Refuses if `.build/fidelity/e2e-candidate.json` or `release-candidate.json` exists. Stages under `.build/diagnostic-fidelity`.

### `postinstall` / `native:patch`

SHA-gated edits to `@connectrpc/connect` transports and `node_modules/tree-sitter/binding.gyp`. Unexpected input hashes throw `Refusing to patch unexpected …`. Idempotent when already at the patched digest.

### `native:build:electron`

Requires `ELECTRON_HEADERS_DIR` matching Electron `42.1.0` (`NODE_MODULE_VERSION` 146, Node 24.15.0 headers). Rebuilds `tree-sitter` and `tree-sitter-bash` for the packaged Electron ABI.

## Typical sequence

<Steps>
<Step title="Install and patch">
`npm ci` (Node 26.5.x). `postinstall` applies third-party patches.
</Step>
<Step title="Hydrate the pinned runtime">
`git lfs pull` then `npm run bootstrap`. Confirm `src/app/dist` and `.cache/runtime/Grok Bot.app`.
</Step>
<Step title="Gate">
`npm run check` and `npm run frontend:build`.
</Step>
<Step title="Package and prove">
On macOS: `npm run package`, then `npm run verify` and optionally `npm run smoke`. Before a public remote: `npm run publication:check`.
</Step>
</Steps>

<Warning>
Do not weaken checksum, bundle identity, codesign, or `publication:check` gates to force a green run. Generated trees (`.cache`, `.build`, `dist`, `src/app/dist`, `recovered`) stay untracked.
</Warning>

## Related pages

<CardGroup>
<Card title="Bootstrap the pinned runtime" href="/bootstrap-pinned-runtime">
`GROK_BOT_018_APP`, cache, LFS DMG, public URL, and `src/app/dist` hydration.
</Card>
<Card title="Package the macOS app" href="/package-macos-app">
ASAR replace, reconstructed identity, ad-hoc sign, and package audit.
</Card>
<Card title="Verify and smoke" href="/verify-and-smoke">
Required ASAR paths, evidence markers, 12s native e2e, updater guards.
</Card>
<Card title="Publication export" href="/publication-export">
`publication:check` tree equality, LFS push, NOTICE review.
</Card>
<Card title="Work on the frontend reconstruction" href="/edit-frontend-workspace">
Vite workspace vs checksum-pinned packaged renderer.
</Card>
<Card title="Environment variables" href="/environment-variables">
`GROK_BOT_018_APP`, `GROK_BOT_OUTPUT_APP_NAME`, `GROK_BOT_RENDERER_SOURCE`, `SAND_DISABLE_*`.
</Card>
<Card title="Contributing" href="/contributing">
Required `check` / `package` commands and what not to commit.
</Card>
</CardGroup>