# npm scripts reference

> package.json scripts: start, lint, make, setup-qmd, verify:auto-router:* suite, and when to use ./scripts/dev.sh vs npm run start directly.

- Repository: Parcha-ai/build
- GitHub: https://github.com/Parcha-ai/build
- Human docs: https://grok-wiki.com/public/docs/parcha-ai-build-bea5702b371b
- Complete Markdown: https://grok-wiki.com/public/docs/parcha-ai-build-bea5702b371b/llms-full.txt

## Source Files

- `package.json`
- `scripts/dev.sh`
- `scripts/build.sh`
- `scripts/setup-qmd.ts`
- `CLAUDE.md`
- `.claude/commands/dev.md`

---

---
title: "npm scripts reference"
description: "package.json scripts: start, lint, make, setup-qmd, verify:auto-router:* suite, and when to use ./scripts/dev.sh vs npm run start directly."
---

Build’s `package.json` defines Electron Forge entry points (`start`, `package`, `make`), housekeeping (`clean:build`, `lint`), QMD bundling (`setup-qmd`), and fifteen `verify:auto-router:*` regression scripts under `scripts/`. Day-to-day development should use `./scripts/dev.sh`, which sets dev-only environment variables and runs `npm run setup-qmd` before delegating to `npm run start`.

## Script inventory

| Script | Command | Purpose |
|--------|---------|---------|
| `start` | `electron-forge start` | Webpack dev server + Electron app (raw Forge entry) |
| `package` | `electron-forge package` | Pack app without full distributable makers |
| `clean:build` | Node one-liner | Deletes `.webpack` and `out/v{version}` |
| `make` | `clean:build` then `electron-forge make` | Production distributable (DMG/ZIP/etc.) |
| `publish` | `electron-forge publish` | Forge publish flow (not used in local README workflow) |
| `lint` | `eslint --ext .ts,.tsx .` | Full-repo TypeScript/TSX lint |
| `setup-qmd` | `npx ts-node scripts/setup-qmd.ts` | Bundle Bun + QMD for **current** OS/arch |
| `setup-qmd:all` | `npx ts-node scripts/setup-qmd.ts all` | Bundle QMD for all supported platforms |
| `verify:auto-router:*` | `npx ts-node scripts/verify-auto-router-*.ts` | Auto Build routing regression checks (see below) |

Current package version (used in `clean:build` and `outDir`): **0.5.27** (`package.json`).

## Development: `./scripts/dev.sh` vs `npm run start`

<Warning>
Use `./scripts/dev.sh` for normal development. Running `npm run start` alone skips QMD setup, dev instance naming, port cleanup, isolated `userData`, and production-settings sync.
</Warning>

### What `./scripts/dev.sh` does

```text
scripts/dev.sh
  ├─ DEV_INSTANCE_NAME  (random adjective-noun, e.g. snappy-koala)
  ├─ npm run setup-qmd
  ├─ kill dev Electron (node_modules/electron only; not out/ production)
  ├─ DEV_WEBPACK_PORT=9001  (+ free port 9001)
  ├─ GREP_DEV_USER_DATA=/tmp/grep-build-dev
  │    └─ one-time copy settings/MCP from prod; copy sessions when present
  └─ npm run start  →  electron-forge start
```

| Variable / path | Set by `dev.sh` | Effect |
|---------------|-----------------|--------|
| `DEV_INSTANCE_NAME` | Random name | Shown in terminal banner and status bar (`[{name}]`) via preload |
| `DEV_WEBPACK_PORT` | `9001` | Webpack dev server port in `forge.config.ts` (default otherwise `3000`) |
| `GREP_DEV_USER_DATA` | `/tmp/grep-build-dev` | `app.setPath('userData', …)` in main process; DevTools auto-open |
| Prod sync | `~/Library/Application Support/Build`, `G-Build`, or `Grep Build` | Copies `claudette-settings.json` / `claudette-mcp-servers.json` only if missing in dev; always attempts `claudette-sessions.json` |

Main process behavior tied to dev env (`src/main/index.ts`):

- **No** `main.log` file logging when `DEV_INSTANCE_NAME` is set (production writes to `userData/main.log`).
- CDP defaults to port **9223** in dev vs **9222** in production (overridable with `ELECTRON_CDP_PORT`).

<Info>
`forge.config.ts` also reads `DEV_WEBPACK_LOGGER_PORT` (default **9000**) for the Forge logger port. `dev.sh` frees **9001** (webpack), not 9000.
</Info>

### When `npm run start` alone is acceptable

- Debugging Electron Forge/webpack without dev isolation.
- CI or tooling that sets `DEV_INSTANCE_NAME`, `GREP_DEV_USER_DATA`, and runs `setup-qmd` itself.

Expect production `userData` paths, no status-bar dev instance label, and missing `resources/qmd` unless you ran `npm run setup-qmd` first.

### Hot reload vs full restart

| Layer | Change type | Action |
|-------|-------------|--------|
| Renderer | React, stores, styles | Hot reload (dev server) |
| Main | Services, IPC, `preload.ts` | Kill dev instance and re-run `./scripts/dev.sh` |

<Note>
Only one dev Electron from `node_modules/electron` should run at a time; `dev.sh` kills orphaned dev processes before launch. Do not kill production apps under `out/`.
</Note>

## Electron Forge scripts

### `npm run start`

Runs `electron-forge start` with the Webpack plugin (`forge.config.ts`): bundles main + renderer, serves renderer on `DEV_WEBPACK_PORT` (or 3000).

### `npm run package`

Packages the app without running all platform makers—useful for a faster pack smoke test.

### `npm run make`

```bash
npm run clean:build && electron-forge make
```

`clean:build` removes:

- `.webpack` (Forge webpack output)
- `out/v{npm_package_version}` (versioned distributable tree)

Forge `outDir` is `./out/v{version}`; macOS app bundle name is **Build** (`Build.app`, executable `build`). Typical arm64 path after build:

```text
out/v0.5.27/Build-darwin-arm64/Build.app
```

`postPackage` copies bundled QMD from `resources/qmd/{platform}-{arch}` into the app Resources folder; warns if missing. Optional signing/notarization when `APPLE_ID`, `APPLE_PASSWORD`, and `APPLE_TEAM_ID` are set.

### `npm run publish`

Standard Electron Forge publish—local release workflow in this repo centers on `make`, version bump, and git tags (see build-and-release page).

### Convenience wrapper: `./scripts/build.sh`

Not an npm script; shell wrapper that:

1. Reads version from `package.json`
2. `pkill` Build / electron-forge (aggressive—differs from `/build` guidance to avoid pkill before `make`)
3. `npm run make`
4. `git tag -f v{version}`
5. `open ./out/v{version}/Build-darwin-arm64/Build.app`

Prefer `npm run make` directly when other Electron instances must stay running.

## Lint

```bash
npm run lint
```

Runs ESLint on all `.ts` and `.tsx` files from the repo root. The Auto Build **meta-harness** gate also runs focused ESLint on routing-related paths (see below).

## QMD setup scripts

Semantic search bundles **Bun** (v1.1.38) and **QMD** (from `https://github.com/tobi/qmd`) into `resources/qmd/{platform}-{arch}/`.

| Script | Behavior |
|--------|----------|
| `npm run setup-qmd` | Current platform only (`darwin-arm64`, `darwin-x64`, `linux-x64`, `win32-x64`) |
| `npm run setup-qmd:all` | All platforms in `PLATFORMS` |

Outputs per platform:

- `bun/` — Bun runtime binary
- `qmd-package/` — QMD npm install via Bun
- `qmd` or `qmd.cmd` — wrapper invoking `bun … src/qmd.ts`

`dev.sh` runs `setup-qmd` on every dev start so local QMD matches the packaged layout. Before `make`, ensure the target platform slice exists or packaging logs a QMD warning.

## `verify:auto-router:*` regression suite

All scripts use `npx ts-node` and exit non-zero on assertion failure. They validate **Auto Build** routing (`auto-router.service`, Flue meta-router, Claude service integration)—not general app E2E.

### Orchestrator vs focused scripts

| Script | Role |
|--------|------|
| `verify:auto-router:meta-harness` | **Quality gate**: runs meta-eval, indistinguishable, flue-sandbox, workflow-metadata, controller-confidence, no-legacy-llm, flue-fallback, flue-auth-cooldown, flue-timeout, fixed-settings, goal-orchestration, handoff-context (script only—no separate npm entry), attachments, plan-mode, plus harness/transcript verifiers, focused ESLint, and `git diff --check` |
| Individual `verify:auto-router:*` | Run one concern in isolation for faster iteration |

### Per-script summary

| npm script | Verifier file | Check focus |
|------------|---------------|-------------|
| `verify:auto-router:attachments` | `verify-auto-router-attachments.ts` | Tier/model routing with DOM/image attachments (mocked store) |
| `verify:auto-router:controller-confidence` | `verify-auto-router-controller-confidence.ts` | Flue controller confidence / routing path |
| `verify:auto-router:flue-auth-cooldown` | `verify-auto-router-flue-auth-cooldown.ts` | Auth failure cooldown behavior |
| `verify:auto-router:flue-fallback` | `verify-auto-router-flue-fallback.ts` | Fallback when Flue controller fails |
| `verify:auto-router:flue-sandbox` | `verify-auto-router-flue-sandbox.ts` | Flue sandbox tool restrictions |
| `verify:auto-router:flue-timeout` | `verify-auto-router-flue-timeout.ts` | Flue timeout handling |
| `verify:auto-router:fixed-settings` | `verify-auto-router-fixed-settings.ts` | Legacy categories vs fixed `planModel`/`buildModel`/… settings |
| `verify:auto-router:goal-orchestration` | `verify-auto-router-goal-orchestration.ts` | `/goal` slash command → Auto routing (static source assertions) |
| `verify:auto-router:indistinguishable` | `verify-auto-router-indistinguishable.ts` | No leaked “Auto Build” branding in streamed UI text (static) |
| `verify:auto-router:meta-eval` | `verify-auto-router-meta-eval.ts` | Broad routing eval cases (mocked; optional live Flue paths) |
| `verify:auto-router:meta-eval:live` | same + `--live --require-live` | Requires live Flue runtime (`FLUE_RUNTIME_NODE_MODULES`, etc.) |
| `verify:auto-router:no-legacy-llm-after-controller` | `verify-auto-router-no-legacy-llm-after-controller.ts` | Legacy direct LLM classifier must not run after controller |
| `verify:auto-router:plan-mode` | `verify-auto-router-plan-mode.ts` | Plan-tier forces `plan` permission mode on lead harness (static) |
| `verify:auto-router:workflow-metadata` | `verify-auto-router-workflow-metadata.ts` | Workflow metadata in routing context (mocked messages) |

<Steps>
<Step title="Run full Auto Build gate">
```bash
npm run verify:auto-router:meta-harness
```
</Step>
<Step title="Run a single failing area">
```bash
npm run verify:auto-router:flue-timeout
```
</Step>
<Step title="Optional live Flue eval">
```bash
npm run verify:auto-router:meta-eval:live
```
Requires local Flue runtime; fails if `--require-live` cannot connect.
</Step>
</Steps>

There is **no** umbrella `verify:auto-router:all` npm script; use `meta-harness` for the bundled gate or run scripts individually.

## Optional Forge / build environment variables

| Variable | Used in | Purpose |
|----------|---------|---------|
| `DEV_WEBPACK_PORT` | `forge.config.ts`, `dev.sh` | Renderer webpack port |
| `DEV_WEBPACK_LOGGER_PORT` | `forge.config.ts` | Forge logger port (default 9000) |
| `DEV_INSTANCE_NAME` | `dev.sh`, main, preload, status bar | Dev build identifier |
| `GREP_DEV_USER_DATA` | `dev.sh`, `index.ts` | Isolated electron-store path |
| `ELECTRON_CDP_PORT` | `index.ts` | Override remote debugging port |
| `GREP_ELECTRON_ZIP_DIR` | `forge.config.ts` | Offline Electron zip for packaging |
| `GREP_ELECTRON_CACHE_ROOT` | `forge.config.ts` | Electron download cache root |
| `GREP_SKIP_ELECTRON_CHECKSUMS` | `forge.config.ts` | Set `1` to skip checksum verify |

## Recommended workflows

```text
Daily dev          →  ./scripts/dev.sh
Pre-commit         →  npm run lint
Auto Build change  →  npm run verify:auto-router:meta-harness
QMD / packaging    →  npm run setup-qmd  (or setup-qmd:all before release)
Ship binary        →  bump version → npm run make → git tag v{version}
```

<Check>
After `./scripts/dev.sh`, confirm the printed **DEV INSTANCE** name matches the status bar suffix (e.g. `[snappy-koala]`).
</Check>

## Related pages

<CardGroup>
<Card title="Build and release" href="/build-and-release">
Version bumping, `make` output layout, git tags, and release artifacts.
</Card>
<Card title="Semantic search (QMD)" href="/semantic-search-qmd">
Runtime QMD usage, IPC search, and how bundled `resources/qmd` is consumed.
</Card>
<Card title="Auto Build configuration" href="/auto-build-configuration">
`AutoRouterConfig` fields exercised by the verify scripts.
</Card>
<Card title="Auto Build routing" href="/auto-build-routing">
Plan/build/verify/refine tiers and controller routing behavior under test.
</Card>
<Card title="Installation" href="/installation">
Clone, `npm install`, and prerequisites before running scripts.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Port conflicts, dev instance locks, and packaged PATH issues.
</Card>
</CardGroup>