@wei840222/qmd 2026.8.23

package/dist/trust.d.ts

@@ -0,0 +1,152 @@
+/**
+ * trust.ts — approval gate for project-local `.qmd` config.
+ *
+ * A project-local `.qmd/index.yml` arrives with a `git clone`, and
+ * `findLocalConfigPath` adopts it automatically for any command run inside the
+ * tree. Three fields in that file can reach outside the project:
+ *
+ * - `update:` — a shell command run by `qmd update` (#886)
+ * - `collections.*.path` — any directory the process can read (#889)
+ * - `models.embed` / `models.rerank` / `models.generate` — any `hf:` repo or
+ *   local GGUF path (#889)
+ *
+ * Global `~/.config/qmd` is never gated. In-project collection paths and the
+ * built-in default model URIs are also allowed without approval: those are
+ * what a local config is for. Approvals are per config file and per gated
+ * set, recorded in `<config dir>/trusted.json`. Editing a hook, pointing a
+ * collection outside the project, or changing a custom model URI changes the
+ * digest and re-arms the gate.
+ */
+/** A collection's pre-update hook, as it will be executed. */
+export type UpdateHook = {
+    collection: string;
+    command: string;
+};
+export type CollectionPath = {
+    collection: string;
+    path: string;
+};
+export type ModelSlot = "embed" | "rerank" | "generate";
+export type ModelsSnapshot = {
+    embed?: string;
+    rerank?: string;
+    generate?: string;
+};
+export type SensitiveSnapshot = {
+    hooks: UpdateHook[];
+    paths: CollectionPath[];
+    models: ModelsSnapshot;
+};
+export type GatedItems = {
+    hooks: UpdateHook[];
+    paths: CollectionPath[];
+    models: Array<{
+        slot: ModelSlot;
+        uri: string;
+    }>;
+};
+export type BuiltinModels = Required<ModelsSnapshot>;
+export type TrustRecord = {
+    /** Digest of the gated set that was approved. */
+    hooks: string;
+    /** ISO timestamp of the approval. */
+    trustedAt: string;
+};
+export type TrustStore = Record<string, TrustRecord>;
+/** Path of the trust database. Lives beside the global config. */
+export declare function getTrustFilePath(): string;
+/**
+ * Whether a config path is project-local — i.e. discovered by walking up from
+ * the working directory rather than written by the user in their config dir.
+ *
+ * `findLocalConfigPath` and `qmd init` both use `.qmd/index.y{a,}ml`, and the
+ * global config lives in a directory named `qmd`, so the parent directory name
+ * separates the two cases without extra bookkeeping.
+ */
+export declare function isLocalConfigPath(configPath: string): boolean;
+/** Directory that contains the `.qmd` folder for a project-local config. */
+export declare function projectRootFromConfig(configPath: string): string;
+/** Expand a leading `~` to the user home directory. */
+export declare function expandUserPath(raw: string): string;
+/**
+ * Resolve a collection `path` from a project-local config: `~` expansion,
+ * then relative paths against the project root (the directory that contains
+ * `.qmd`), not against the process cwd.
+ */
+export declare function resolveConfigCollectionPath(rawPath: string, configPath: string): string;
+/**
+ * True if `rawPath` from a project-local config stays inside that project
+ * (the directory containing `.qmd`), after `~` expansion, relative
+ * resolution, and symlink realpath.
+ */
+export declare function isCollectionPathInsideProject(configPath: string, rawPath: string): boolean;
+export declare function gatedModels(models: ModelsSnapshot, builtins: BuiltinModels): Array<{
+    slot: ModelSlot;
+    uri: string;
+}>;
+export declare function gatedItems(configPath: string, snapshot: SensitiveSnapshot, builtins: BuiltinModels): GatedItems;
+export declare function hasGatedItems(gated: GatedItems): boolean;
+/**
+ * Stable digest over a hook set. Order-independent so that reordering
+ * collections in the YAML does not invalidate an approval, while any change to
+ * a command — or a new collection gaining one — does.
+ */
+export declare function hookDigest(hooks: UpdateHook[]): string;
+/**
+ * Digest of the gated surface of a project-local config: hooks, resolved
+ * collection paths, and non-default model URIs. Missing model keys and the
+ * built-in default URIs are equivalent so that `qmd init` filling defaults
+ * into the YAML does not invalidate an approval.
+ */
+export declare function sensitiveDigest(snapshot: SensitiveSnapshot, configPath: string, builtins: BuiltinModels): string;
+export declare function loadTrustStore(): TrustStore;
+export declare function isTrusted(configPath: string, digest: string): boolean;
+export declare function recordTrust(configPath: string, digest: string): void;
+/** Drop the record for a config path. Returns false if there was none. */
+export declare function revokeTrust(configPath: string): boolean;
+export declare function listTrusted(): Array<{
+    path: string;
+} & TrustRecord>;
+export type HookGateDecision = {
+    action: "run";
+    digest: string;
+} | {
+    action: "prompt";
+    digest: string;
+} | {
+    action: "skip";
+    digest: string;
+};
+export type LocalConfigGateDecision = HookGateDecision;
+/** True when the process has opted in to trusting project-local config unattended. */
+export declare function isLocalConfigTrustOptedIn(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Decide what to do with a config's `update:` hooks.
+ *
+ * Non-interactive callers — agents, CI, the MCP server — get `skip` rather than
+ * a hard failure: indexing is what they asked for, and failing the whole
+ * command would only push people toward a blanket opt-out.
+ */
+export declare function decideHookGate(options: {
+    configPath: string;
+    hooks: UpdateHook[];
+    isInteractive: boolean;
+    env?: NodeJS.ProcessEnv;
+    trustedCheck?: (configPath: string, digest: string) => boolean;
+}): HookGateDecision;
+/**
+ * Decide whether a project-local config may use its gated fields (hooks,
+ * out-of-project collection paths, non-default model URIs).
+ *
+ * In-project paths and built-in default models do not need a decision.
+ * Non-interactive callers get `skip`: in-project indexing still proceeds,
+ * hooks/outside paths/custom models do not.
+ */
+export declare function decideLocalConfigGate(options: {
+    configPath: string;
+    snapshot: SensitiveSnapshot;
+    builtins: BuiltinModels;
+    isInteractive: boolean;
+    env?: NodeJS.ProcessEnv;
+    trustedCheck?: (configPath: string, digest: string) => boolean;
+}): LocalConfigGateDecision;

package/dist/trust.js

@@ -0,0 +1,249 @@
+/**
+ * trust.ts — approval gate for project-local `.qmd` config.
+ *
+ * A project-local `.qmd/index.yml` arrives with a `git clone`, and
+ * `findLocalConfigPath` adopts it automatically for any command run inside the
+ * tree. Three fields in that file can reach outside the project:
+ *
+ * - `update:` — a shell command run by `qmd update` (#886)
+ * - `collections.*.path` — any directory the process can read (#889)
+ * - `models.embed` / `models.rerank` / `models.generate` — any `hf:` repo or
+ *   local GGUF path (#889)
+ *
+ * Global `~/.config/qmd` is never gated. In-project collection paths and the
+ * built-in default model URIs are also allowed without approval: those are
+ * what a local config is for. Approvals are per config file and per gated
+ * set, recorded in `<config dir>/trusted.json`. Editing a hook, pointing a
+ * collection outside the project, or changing a custom model URI changes the
+ * digest and re-arms the gate.
+ */
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "path";
+import { getConfigDir } from "./collections.js";
+import { qmdHomedir } from "./paths.js";
+/** Path of the trust database. Lives beside the global config. */
+export function getTrustFilePath() {
+    return join(getConfigDir(), "trusted.json");
+}
+/**
+ * Whether a config path is project-local — i.e. discovered by walking up from
+ * the working directory rather than written by the user in their config dir.
+ *
+ * `findLocalConfigPath` and `qmd init` both use `.qmd/index.y{a,}ml`, and the
+ * global config lives in a directory named `qmd`, so the parent directory name
+ * separates the two cases without extra bookkeeping.
+ */
+export function isLocalConfigPath(configPath) {
+    if (!configPath || configPath === "<inline>")
+        return false;
+    return basename(dirname(resolve(configPath))) === ".qmd";
+}
+/** Directory that contains the `.qmd` folder for a project-local config. */
+export function projectRootFromConfig(configPath) {
+    return dirname(dirname(resolve(configPath)));
+}
+/** Expand a leading `~` to the user home directory. */
+export function expandUserPath(raw) {
+    if (raw === "~")
+        return qmdHomedir();
+    if (raw.startsWith("~/") || raw.startsWith("~\\")) {
+        return join(qmdHomedir(), raw.slice(2));
+    }
+    return raw;
+}
+/**
+ * Resolve a collection `path` from a project-local config: `~` expansion,
+ * then relative paths against the project root (the directory that contains
+ * `.qmd`), not against the process cwd.
+ */
+export function resolveConfigCollectionPath(rawPath, configPath) {
+    const expanded = expandUserPath(String(rawPath ?? "").trim());
+    if (!expanded)
+        return projectRootFromConfig(configPath);
+    if (isAbsolute(expanded))
+        return resolve(expanded);
+    return resolve(projectRootFromConfig(configPath), expanded);
+}
+function realOrResolve(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/**
+ * True if `rawPath` from a project-local config stays inside that project
+ * (the directory containing `.qmd`), after `~` expansion, relative
+ * resolution, and symlink realpath.
+ */
+export function isCollectionPathInsideProject(configPath, rawPath) {
+    const root = realOrResolve(projectRootFromConfig(configPath));
+    const target = realOrResolve(resolveConfigCollectionPath(rawPath, configPath));
+    const rel = relative(root, target);
+    if (rel === "")
+        return true;
+    if (isAbsolute(rel))
+        return false;
+    return !rel.split(/[/\\]/).includes("..");
+}
+export function gatedModels(models, builtins) {
+    const out = [];
+    for (const slot of ["embed", "rerank", "generate"]) {
+        const uri = models[slot];
+        if (!uri)
+            continue;
+        if (uri === builtins[slot])
+            continue;
+        out.push({ slot, uri });
+    }
+    return out;
+}
+export function gatedItems(configPath, snapshot, builtins) {
+    return {
+        hooks: snapshot.hooks,
+        paths: snapshot.paths.filter(p => !isCollectionPathInsideProject(configPath, p.path)),
+        models: gatedModels(snapshot.models, builtins),
+    };
+}
+export function hasGatedItems(gated) {
+    return gated.hooks.length > 0 || gated.paths.length > 0 || gated.models.length > 0;
+}
+function byFirst(a, b) {
+    const left = a[0] ?? "";
+    const right = b[0] ?? "";
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * Stable digest over a hook set. Order-independent so that reordering
+ * collections in the YAML does not invalidate an approval, while any change to
+ * a command — or a new collection gaining one — does.
+ */
+export function hookDigest(hooks) {
+    const canonical = JSON.stringify(hooks
+        .map(h => [h.collection, h.command])
+        .sort(byFirst));
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/**
+ * Digest of the gated surface of a project-local config: hooks, resolved
+ * collection paths, and non-default model URIs. Missing model keys and the
+ * built-in default URIs are equivalent so that `qmd init` filling defaults
+ * into the YAML does not invalidate an approval.
+ */
+export function sensitiveDigest(snapshot, configPath, builtins) {
+    const gated = gatedItems(configPath, snapshot, builtins);
+    const canonical = JSON.stringify({
+        hooks: gated.hooks.map(h => [h.collection, h.command]).sort(byFirst),
+        paths: gated.paths
+            .map(p => [p.collection, resolveConfigCollectionPath(p.path, configPath)])
+            .sort(byFirst),
+        models: gated.models
+            .map(m => [m.slot, m.uri])
+            .sort(byFirst),
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+export function loadTrustStore() {
+    const path = getTrustFilePath();
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        // A corrupt trust file must not be treated as "everything is trusted".
+        return {};
+    }
+}
+function saveTrustStore(store) {
+    const path = getTrustFilePath();
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, "utf-8");
+}
+/** Trust records are keyed on the resolved config path. */
+function trustKey(configPath) {
+    return resolve(configPath);
+}
+export function isTrusted(configPath, digest) {
+    const record = loadTrustStore()[trustKey(configPath)];
+    return record?.hooks === digest;
+}
+export function recordTrust(configPath, digest) {
+    const store = loadTrustStore();
+    store[trustKey(configPath)] = { hooks: digest, trustedAt: new Date().toISOString() };
+    saveTrustStore(store);
+}
+/** Drop the record for a config path. Returns false if there was none. */
+export function revokeTrust(configPath) {
+    const store = loadTrustStore();
+    const key = trustKey(configPath);
+    if (!(key in store))
+        return false;
+    delete store[key];
+    saveTrustStore(store);
+    return true;
+}
+export function listTrusted() {
+    return Object.entries(loadTrustStore()).map(([path, record]) => ({ path, ...record }));
+}
+function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    return !["0", "false", "off", "no", "none"].includes(value.trim().toLowerCase());
+}
+/** True when the process has opted in to trusting project-local config unattended. */
+export function isLocalConfigTrustOptedIn(env = process.env) {
+    return isTruthyEnv(env.QMD_TRUST_LOCAL_CONFIG) || isTruthyEnv(env.QMD_TRUST_UPDATE_HOOKS);
+}
+/**
+ * Decide what to do with a config's `update:` hooks.
+ *
+ * Non-interactive callers — agents, CI, the MCP server — get `skip` rather than
+ * a hard failure: indexing is what they asked for, and failing the whole
+ * command would only push people toward a blanket opt-out.
+ */
+export function decideHookGate(options) {
+    const env = options.env ?? process.env;
+    const digest = hookDigest(options.hooks);
+    if (options.hooks.length === 0)
+        return { action: "run", digest };
+    if (isTruthyEnv(env.QMD_TRUST_UPDATE_HOOKS) || isTruthyEnv(env.QMD_TRUST_LOCAL_CONFIG)) {
+        return { action: "run", digest };
+    }
+    if (!isLocalConfigPath(options.configPath))
+        return { action: "run", digest };
+    const trusted = options.trustedCheck ?? isTrusted;
+    if (trusted(options.configPath, digest))
+        return { action: "run", digest };
+    return { action: options.isInteractive ? "prompt" : "skip", digest };
+}
+/**
+ * Decide whether a project-local config may use its gated fields (hooks,
+ * out-of-project collection paths, non-default model URIs).
+ *
+ * In-project paths and built-in default models do not need a decision.
+ * Non-interactive callers get `skip`: in-project indexing still proceeds,
+ * hooks/outside paths/custom models do not.
+ */
+export function decideLocalConfigGate(options) {
+    const env = options.env ?? process.env;
+    const digest = sensitiveDigest(options.snapshot, options.configPath, options.builtins);
+    const gated = gatedItems(options.configPath, options.snapshot, options.builtins);
+    if (!hasGatedItems(gated))
+        return { action: "run", digest };
+    if (isLocalConfigTrustOptedIn(env))
+        return { action: "run", digest };
+    if (!isLocalConfigPath(options.configPath))
+        return { action: "run", digest };
+    const trusted = options.trustedCheck ?? isTrusted;
+    if (trusted(options.configPath, digest))
+        return { action: "run", digest };
+    return { action: options.isInteractive ? "prompt" : "skip", digest };
+}

package/package.json

@@ -0,0 +1,139 @@
+{
+  "name": "@wei840222/qmd",
+  "version": "2026.8.23",
+  "packageManager": "pnpm@11.15.1",
+  "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "qmd": "bin/qmd"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "skills/",
+    "scripts/build.mjs",
+    "scripts/check-package-grammars.mjs",
+    "scripts/package-smoke.mjs",
+    "scripts/sync-zh-dict.mjs",
+    "scripts/test-all.mjs",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepare": "node scripts/install-hooks.mjs && node scripts/build.mjs",
+    "build": "node scripts/build.mjs",
+    "lint": "oxlint",
+    "test": "node scripts/test-all.mjs",
+    "test:types": "node ./node_modules/typescript/bin/tsc -p tsconfig.build.json --noEmit",
+    "test:node": "bun scripts/test-runtime.mjs node",
+    "test:bun": "bun scripts/test-runtime.mjs bun",
+    "test:models:node": "bun scripts/test-runtime.mjs node --models-only",
+    "test:models:bun": "bun scripts/test-runtime.mjs bun --models-only",
+    "test:unit": "CI=true node ./node_modules/vitest/vitest.mjs run --reporter=verbose --testTimeout 60000 test/ && CI=true bun test --timeout 60000 --preload ./src/test-preload.ts test/",
+    "test:quality": "node ./node_modules/vitest/vitest.mjs run --reporter=verbose test/eval-cjk.test.ts",
+    "test:package": "node scripts/package-smoke.mjs",
+    "smoke:package-grammars": "node scripts/check-package-grammars.mjs",
+    "dict:sync": "node scripts/sync-zh-dict.mjs",
+    "measure:cjk": "bun scripts/measure-cjk.ts",
+    "inspector": "bunx @modelcontextprotocol/inspector tsx src/cli/qmd.ts mcp",
+    "release": "./scripts/release.sh",
+    "qmd": "tsx src/cli/qmd.ts",
+    "index": "tsx src/cli/qmd.ts index",
+    "vector": "tsx src/cli/qmd.ts vector",
+    "search": "tsx src/cli/qmd.ts search",
+    "vsearch": "tsx src/cli/qmd.ts vsearch",
+    "rerank": "tsx src/cli/qmd.ts rerank",
+    "bench": "bun src/cli/qmd.ts bench"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wei840222/qmd.git"
+  },
+  "homepage": "https://github.com/wei840222/qmd#readme",
+  "bugs": {
+    "url": "https://github.com/wei840222/qmd/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "@node-rs/jieba": "2.0.1",
+    "better-sqlite3": "^13.0.3",
+    "fast-glob": "3.3.3",
+    "node-llama-cpp": "3.20.0",
+    "picomatch": "4.0.5",
+    "sqlite-vec": "0.1.9",
+    "tree-sitter-go": "0.25.0",
+    "tree-sitter-python": "0.25.0",
+    "tree-sitter-rust": "0.24.0",
+    "tree-sitter-typescript": "0.23.2",
+    "web-tree-sitter": "0.26.12",
+    "yaml": "2.9.0",
+    "zod": "4.2.1"
+  },
+  "optionalDependencies": {
+    "sqlite-vec-darwin-arm64": "0.1.9",
+    "sqlite-vec-darwin-x64": "0.1.9",
+    "sqlite-vec-linux-arm64": "0.1.9",
+    "sqlite-vec-linux-x64": "0.1.9",
+    "sqlite-vec-windows-x64": "0.1.9"
+  },
+  "devDependencies": {
+    "@oxlint/plugins": "1.78.0",
+    "@types/better-sqlite3": "7.6.13",
+    "oxlint": "1.78.0",
+    "tsx": "4.23.12",
+    "vitest": "3.2.7"
+  },
+  "overrides": {
+    "@hono/node-server": "2.0.10",
+    "ajv": "8.18.0",
+    "esbuild": "0.28.1",
+    "fast-uri": "3.1.5",
+    "hono": "4.12.34",
+    "ip-address": "10.3.1",
+    "nanoid": "3.3.18",
+    "path-to-regexp": "8.4.0",
+    "postcss": "8.5.23",
+    "qs": "6.15.3",
+    "rollup": "4.59.0",
+    "simple-git": "3.36.0",
+    "tar": "7.5.21",
+    "vite": "7.3.5"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "markdown",
+    "search",
+    "fts",
+    "full-text-search",
+    "vector",
+    "semantic-search",
+    "sqlite",
+    "bm25",
+    "embeddings",
+    "rag",
+    "mcp",
+    "reranking",
+    "knowledge-base",
+    "local-ai",
+    "llm"
+  ],
+  "author": "Tobi Lutke <tobi@lutke.com>",
+  "license": "MIT"
+}

package/scripts/build.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { chmodSync, copyFileSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(fileURLToPath(new URL("..", import.meta.url)));
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    stdio: "inherit",
+    // Never shell:true — on Windows, cmd.exe splits unquoted process.execPath
+    // at spaces (C:\Program Files\nodejs\node.exe) and the build can exit 0
+    // with no dist/. spawnSync can spawn the binary + args array directly. (#681)
+    shell: false,
+    ...options,
+  });
+  if (result.error || result.status !== 0) {
+    if (result.error) {
+      console.error(`build: failed to spawn ${command}: ${result.error.message}`);
+    }
+    process.exit(result.status ?? 1);
+  }
+}
+
+run(process.execPath, [join(root, "node_modules", "typescript", "bin", "tsc"), "-p", "tsconfig.build.json"]);
+copyFileSync(
+  join(root, "src", "search", "zh-dict.txt"),
+  join(root, "dist", "search", "zh-dict.txt"),
+);
+for (const path of [
+  "zh-tw-dictionary.txt",
+  "zh-tw-tech-dictionary.js",
+  "zh-tw-tech-dictionary.d.ts",
+]) {
+  rmSync(join(root, "dist", "search", path), { force: true });
+}
+
+const cliPath = join(root, "dist", "cli", "qmd.js");
+const tmpPath = `${cliPath}.tmp`;
+const built = readFileSync(cliPath, "utf8");
+const withoutExistingShebang = built.startsWith("#!") ? built.slice(built.indexOf("\n") + 1) : built;
+writeFileSync(tmpPath, `#!/usr/bin/env node\n${withoutExistingShebang}`);
+renameSync(tmpPath, cliPath);
+chmodSync(cliPath, 0o755);
+
+// Stamp the commit this build came from, for `qmd --version`.
+//
+// It has to happen here: a published tarball has no git history of its own, so
+// discovering the commit at runtime finds whatever repository the install
+// happens to sit inside (a global install under /opt/homebrew reported
+// Homebrew's HEAD as qmd's). See src/cli/version.ts.
+//
+// Uses spawnSync directly rather than run() above, because run() exits the
+// build on a non-zero status: no git, no repo, or a source tarball must all
+// degrade to an unstamped build, not a failed one.
+function git(args) {
+  const result = spawnSync("git", args, { cwd: root, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+  if (result.status !== 0 || typeof result.stdout !== "string") return null;
+  return result.stdout.trim();
+}
+
+function buildCommit() {
+  const top = git(["rev-parse", "--show-toplevel"]);
+  // Only trust a repository that *is* this package — same rule the runtime
+  // fallback applies, so building from inside an unrelated checkout can't
+  // stamp that checkout's commit.
+  if (top === null || realpathSync(top) !== realpathSync(root)) return "";
+
+  const commit = git(["rev-parse", "--short", "HEAD"]);
+  if (!commit) return "";
+
+  // A build from a dirty tree is not the commit it claims to be; say so, so
+  // "did my install actually take?" has an answer.
+  const status = git(["status", "--porcelain"]);
+  return status ? `${commit}-dirty` : commit;
+}
+
+writeFileSync(
+  join(root, "dist", "cli", "build-info.json"),
+  `${JSON.stringify({ commit: buildCommit(), builtAt: new Date().toISOString() }, null, 2)}\n`,
+);

package/scripts/check-package-grammars.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+const grammars = [
+  "tree-sitter-typescript/tree-sitter-typescript.wasm",
+  "tree-sitter-typescript/tree-sitter-tsx.wasm",
+  "tree-sitter-python/tree-sitter-python.wasm",
+  "tree-sitter-go/tree-sitter-go.wasm",
+  "tree-sitter-rust/tree-sitter-rust.wasm",
+];
+
+let ok = true;
+for (const grammar of grammars) {
+  try {
+    const resolved = require.resolve(grammar);
+    console.log(`ok ${grammar} -> ${resolved}`);
+  } catch (err) {
+    ok = false;
+    console.error(`missing ${grammar}`);
+    console.error(err instanceof Error ? err.message : String(err));
+  }
+}
+
+if (!ok) {
+  console.error("\nAST grammar package smoke check failed. Run `bun install` locally or repair a broken global install with the matching `bun add tree-sitter-...@<version>` command shown by `qmd status`.");
+  process.exit(1);
+}