@navbook/cli 0.1.0

package/dist/cli/context.js

@@ -0,0 +1,93 @@
+/**
+ * Per-invocation context: where the repository is, what time it is, where IDs
+ * come from, and how output is styled.
+ *
+ * This is the one place the conformance hooks `NAV_NOW` and `NAV_IDS` are
+ * honored (see `doc/spec/fixtures/README.md`). Keeping them here means `core`
+ * has no notion of testing and every command is deterministic under fixtures.
+ */
+import { webcrypto } from "node:crypto";
+import { mintId as coreMintId, isId } from "../core/id.js";
+import { toIsoSeconds } from "../core/time.js";
+import { findRepo, userIdentity } from "../git/repo.js";
+import { NavError } from "./errors.js";
+import { makeColors } from "./render/colors.js";
+export const NAV_NOW_ENV = "NAV_NOW";
+export const NAV_IDS_ENV = "NAV_IDS";
+const defaultRandomBytes = (n) => webcrypto.getRandomValues(new Uint8Array(n));
+export function makeContext(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const env = opts.env ?? process.env;
+    const stdout = opts.stdout ?? process.stdout;
+    const stderr = opts.stderr ?? process.stderr;
+    let paths;
+    try {
+        paths = findRepo(cwd);
+    }
+    catch (error) {
+        if (opts.requireRepo === false) {
+            paths = { repoRoot: cwd, navRoot: "", hasNavbook: false };
+        }
+        else {
+            throw new NavError(error instanceof Error ? error.message : String(error));
+        }
+    }
+    const fixedNow = parseFixedNow(env[NAV_NOW_ENV]);
+    const scriptedIds = parseScriptedIds(env[NAV_IDS_ENV]);
+    let idCursor = 0;
+    return {
+        cwd,
+        env,
+        repoRoot: paths.repoRoot,
+        navRoot: paths.navRoot,
+        hasNavbook: paths.hasNavbook,
+        colors: makeColors(stdout, env),
+        stdout,
+        stderr,
+        now: () => (fixedNow ? new Date(fixedNow) : new Date()),
+        mintId(taken) {
+            if (scriptedIds) {
+                const next = scriptedIds[idCursor++];
+                if (next === undefined) {
+                    throw new NavError(`${NAV_IDS_ENV} is exhausted after ${scriptedIds.length} id(s)`);
+                }
+                return next;
+            }
+            for (let attempt = 0; attempt < 100; attempt++) {
+                const id = coreMintId(defaultRandomBytes);
+                if (!taken?.has(id))
+                    return id;
+            }
+            /* c8 ignore next */
+            throw new NavError("could not mint a collision-free id");
+        },
+        identity: () => userIdentity(paths.repoRoot),
+    };
+}
+function parseFixedNow(value) {
+    if (!value)
+        return null;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new NavError(`${NAV_NOW_ENV} is not a valid timestamp: ${value}`);
+    }
+    return date;
+}
+function parseScriptedIds(value) {
+    if (value === undefined)
+        return null;
+    const ids = value
+        .split(",")
+        .map((id) => id.trim())
+        .filter((id) => id !== "");
+    for (const id of ids) {
+        if (!isId(id))
+            throw new NavError(`${NAV_IDS_ENV} contains an invalid id: ${id}`);
+    }
+    return ids;
+}
+/** The current instant as an ISO 8601 string with second precision. */
+export function nowIso(ctx) {
+    return toIsoSeconds(ctx.now());
+}
+//# sourceMappingURL=context.js.map

package/dist/cli/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/cli/context.ts"],"names":[],"mappings":"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"}

package/dist/cli/editor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `$EDITOR` integration for the `--edit` flows.
+ *
+ * The editor is always opened on the real Navbook file, exactly as spec 04 §4.3
+ * describes, so nothing has to be parsed back out of a scratch buffer.
+ */
+import type { Ctx } from "./context.ts";
+/** Single-quote a path for a POSIX shell, escaping any embedded quotes. */
+export declare function shellQuote(value: string): string;
+/** The editor command to use, or null when none can be determined. */
+export declare function editorCommand(env: NodeJS.ProcessEnv): string | null;
+/** Open `absolutePath` in the user's editor, failing if it exits non-zero. */
+export declare function openInEditor(ctx: Ctx, absolutePath: string): void;
+/**
+ * Edit a Navbook file before it exists.
+ *
+ * The buffer is a real `.md` file (so editors highlight it) held next to
+ * `COMMIT_EDITMSG` in the git directory, and it is prefilled with the exact
+ * frontmatter the file will carry — the author can adjust the title, labels and
+ * body in one pass. Nothing is created in `.navbook/` until the text is valid,
+ * so an abort leaves no partial entity behind.
+ */
+export declare function editBuffer(ctx: Ctx, name: string, initial: string): string;

package/dist/cli/editor.js

@@ -0,0 +1,67 @@
+/**
+ * `$EDITOR` integration for the `--edit` flows.
+ *
+ * The editor is always opened on the real Navbook file, exactly as spec 04 §4.3
+ * describes, so nothing has to be parsed back out of a scratch buffer.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gitDir } from "../git/repo.js";
+import { fail } from "./errors.js";
+/** Single-quote a path for a POSIX shell, escaping any embedded quotes. */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** The editor command to use, or null when none can be determined. */
+export function editorCommand(env) {
+    for (const key of ["VISUAL", "EDITOR"]) {
+        const value = env[key];
+        if (value && value.trim() !== "")
+            return value.trim();
+    }
+    return null;
+}
+/** Open `absolutePath` in the user's editor, failing if it exits non-zero. */
+export function openInEditor(ctx, absolutePath) {
+    const editor = editorCommand(ctx.env);
+    if (!editor) {
+        fail("no editor configured", [
+            "set $VISUAL or $EDITOR, or pass -m/--message to supply the text directly",
+        ]);
+    }
+    // $EDITOR may carry its own flags ("code -w"), so it is interpreted by a
+    // shell; the path is quoted rather than passed as an argument, because a
+    // shell command string has no argv to bind positional parameters from.
+    const result = spawnSync(`${editor} ${shellQuote(absolutePath)}`, {
+        stdio: "inherit",
+        shell: true,
+        cwd: ctx.repoRoot,
+        env: ctx.env,
+    });
+    if (result.error)
+        fail(`could not start editor '${editor}': ${result.error.message}`);
+    if ((result.status ?? 1) !== 0)
+        fail(`editor '${editor}' exited with status ${result.status}`);
+}
+/**
+ * Edit a Navbook file before it exists.
+ *
+ * The buffer is a real `.md` file (so editors highlight it) held next to
+ * `COMMIT_EDITMSG` in the git directory, and it is prefilled with the exact
+ * frontmatter the file will carry — the author can adjust the title, labels and
+ * body in one pass. Nothing is created in `.navbook/` until the text is valid,
+ * so an abort leaves no partial entity behind.
+ */
+export function editBuffer(ctx, name, initial) {
+    const path = join(gitDir(ctx.repoRoot), name);
+    writeFileSync(path, initial, "utf8");
+    try {
+        openInEditor(ctx, path);
+        return readFileSync(path, "utf8");
+    }
+    finally {
+        rmSync(path, { force: true });
+    }
+}
+//# sourceMappingURL=editor.js.map

package/dist/cli/editor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor.js","sourceRoot":"","sources":["../../src/cli/editor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC,2EAA2E;AAC3E,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC;AAC/C,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,aAAa,CAAC,GAAsB;IAClD,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,YAAY,CAAC,GAAQ,EAAE,YAAoB;IACzD,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,IAAI,CAAC,sBAAsB,EAAE;YAC3B,0EAA0E;SAC3E,CAAC,CAAC;IACL,CAAC;IACD,yEAAyE;IACzE,yEAAyE;IACzE,uEAAuE;IACvE,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,EAAE;QAChE,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,IAAI;QACX,GAAG,EAAE,GAAG,CAAC,QAAQ;QACjB,GAAG,EAAE,GAAG,CAAC,GAAG;KACb,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,KAAK;QAAE,IAAI,CAAC,2BAA2B,MAAM,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACtF,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC;QAAE,IAAI,CAAC,WAAW,MAAM,wBAAwB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AACjG,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,GAAQ,EAAE,IAAY,EAAE,OAAe;IAChE,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACrC,IAAI,CAAC;QACH,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACxB,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAChC,CAAC;AACH,CAAC"}

package/dist/cli/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Exit codes — spec 04 §4.2: 0 success, 1 operational error, 2 format violation.
+ */
+export type ExitCode = 0 | 1 | 2;
+export declare class NavError extends Error {
+    readonly exitCode: ExitCode;
+    /** Extra lines printed under the message, e.g. candidate IDs. */
+    readonly details: string[];
+    constructor(message: string, opts?: {
+        exitCode?: ExitCode;
+        details?: string[];
+    });
+}
+/** An operational error: not found, ambiguous, malformed input (exit 1). */
+export declare function fail(message: string, details?: string[]): never;
+/** A format violation detected by `doctor` (exit 2). */
+export declare function failFormat(message: string, details?: string[]): never;

package/dist/cli/errors.js

@@ -0,0 +1,23 @@
+/**
+ * Exit codes — spec 04 §4.2: 0 success, 1 operational error, 2 format violation.
+ */
+export class NavError extends Error {
+    exitCode;
+    /** Extra lines printed under the message, e.g. candidate IDs. */
+    details;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "NavError";
+        this.exitCode = opts.exitCode ?? 1;
+        this.details = opts.details ?? [];
+    }
+}
+/** An operational error: not found, ambiguous, malformed input (exit 1). */
+export function fail(message, details = []) {
+    throw new NavError(message, { exitCode: 1, details });
+}
+/** A format violation detected by `doctor` (exit 2). */
+export function failFormat(message, details = []) {
+    throw new NavError(message, { exitCode: 2, details });
+}
+//# sourceMappingURL=errors.js.map

package/dist/cli/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/cli/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,QAAQ,CAAW;IAC5B,iEAAiE;IACxD,OAAO,CAAW;IAE3B,YAAY,OAAe,EAAE,OAAoD,EAAE;QACjF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IACpC,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,UAAU,IAAI,CAAC,OAAe,EAAE,UAAoB,EAAE;IAC1D,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;AACxD,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,UAAoB,EAAE;IAChE,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;AACxD,CAAC"}

package/dist/cli/history-checks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The doctor checks that need git archaeology — spec 04 §4.3, D7, D9 and D10.
+ *
+ * Their decision logic lives in `core/validate.ts`; this module supplies the
+ * history those pure functions judge. Every check degrades to silence when the
+ * history is unavailable (a shallow clone, an unfetched commit), because an
+ * absent object is not evidence of a fault.
+ */
+import { type Repo } from "../core/tree.ts";
+import { type Diagnostic } from "../core/validate.ts";
+import type { Ctx } from "./context.ts";
+/**
+ * How far a frontmatter timestamp may sit from the commit that introduced it
+ * before D10 calls it inconsistent.
+ *
+ * The specification says "wildly inconsistent" without a number. Two days
+ * absorbs offline work, a delayed push and any timezone confusion, while still
+ * catching a timestamp that was copied or typed from the wrong year.
+ */
+export declare const TIMESTAMP_SKEW_HOURS = 48;
+export declare function runHistoryChecks(ctx: Ctx, repo: Repo): Diagnostic[];

package/dist/cli/history-checks.js

@@ -0,0 +1,134 @@
+/**
+ * The doctor checks that need git archaeology — spec 04 §4.3, D7, D9 and D10.
+ *
+ * Their decision logic lives in `core/validate.ts`; this module supplies the
+ * history those pure functions judge. Every check degrades to silence when the
+ * history is unavailable (a shallow clone, an unfetched commit), because an
+ * absent object is not evidence of a fault.
+ */
+import { parseFile, readRevisions } from "../core/files.js";
+import { parseIso } from "../core/time.js";
+import { allEntities } from "../core/tree.js";
+import { checkRevisionsAppendOnly, checkTimestampSkew, planD9Fix, } from "../core/validate.js";
+import { addedAt, blobAt, fileVersions, isAncestor, objectExists } from "../git/history.js";
+import { currentBranch, resolveSha } from "../git/repo.js";
+import { repoPath } from "./workspace.js";
+/**
+ * How far a frontmatter timestamp may sit from the commit that introduced it
+ * before D10 calls it inconsistent.
+ *
+ * The specification says "wildly inconsistent" without a number. Two days
+ * absorbs offline work, a delayed push and any timezone confusion, while still
+ * catching a timestamp that was copied or typed from the wrong year.
+ */
+export const TIMESTAMP_SKEW_HOURS = 48;
+export function runHistoryChecks(ctx, repo) {
+    return [
+        ...checkAppendOnly(ctx, repo),
+        ...checkMergedButOpen(ctx, repo),
+        ...checkTimestamps(ctx, repo),
+    ];
+}
+/* ------------------------------------------- D7: revisions are append-only */
+function checkAppendOnly(ctx, repo) {
+    const out = [];
+    for (const pr of repo.prs) {
+        const versions = fileVersions(ctx.repoRoot, repoPath(pr.filePath));
+        if (versions.length < 2)
+            continue;
+        const lists = [];
+        for (const version of versions) {
+            const text = blobAt(ctx.repoRoot, version.sha, version.path);
+            if (text === null)
+                continue;
+            try {
+                lists.push(readRevisions(parseFile(text).fm));
+            }
+            catch {
+                // A malformed historical version is D2's business, not D7's.
+            }
+        }
+        const result = checkRevisionsAppendOnly(lists);
+        if (result.ok)
+            continue;
+        out.push({
+            check: "D7",
+            level: "error",
+            path: pr.filePath,
+            message: `revisions must only be appended to (§2.7): ${result.message}`,
+        });
+    }
+    return out;
+}
+/* ------------------------------------ D9: merged but not archived (03 §3.5) */
+function checkMergedButOpen(ctx, repo) {
+    const head = resolveSha(ctx.repoRoot, "HEAD");
+    if (!head)
+        return [];
+    // "Merged" only means anything on the branch the PR asked to merge into. On
+    // its own source branch the head is trivially an ancestor of HEAD, and on an
+    // unrelated branch containing it the fact is not actionable.
+    const branch = currentBranch(ctx.repoRoot);
+    if (!branch)
+        return [];
+    const out = [];
+    for (const pr of repo.prs) {
+        if (pr.status !== "open")
+            continue;
+        if (pr.fm.target !== branch)
+            continue;
+        const revisions = readRevisions(pr.fm);
+        const latest = revisions[revisions.length - 1];
+        // An unfetched head is not evidence of anything.
+        if (!latest || !objectExists(ctx.repoRoot, latest.head))
+            continue;
+        if (!isAncestor(ctx.repoRoot, latest.head, head))
+            continue;
+        out.push({
+            check: "D9",
+            level: "warning",
+            path: pr.dirPath,
+            message: `#${pr.id} is merged into this branch but still filed under prs/open/; move it to prs/merged/`,
+            fix: planD9Fix(pr),
+        });
+    }
+    return out;
+}
+/* --------------------------------- D10: timestamps versus the commit record */
+function checkTimestamps(ctx, repo) {
+    const out = [];
+    for (const entity of allEntities(repo)) {
+        // An entity whose timestamps legitimately predate the commit that carries
+        // them: bulk-imported from a forge (§2.4), or archived from an era the
+        // visible history may no longer reach (03 §3.6).
+        if (entity.archived || entity.fm["imported-from"] !== undefined)
+            continue;
+        const created = typeof entity.fm.created === "string" ? parseIso(entity.fm.created) : null;
+        if (created) {
+            const added = addedAt(ctx.repoRoot, repoPath(entity.filePath));
+            if (added && !checkTimestampSkew(created, added.authored, TIMESTAMP_SKEW_HOURS)) {
+                out.push({
+                    check: "D10",
+                    level: "warning",
+                    path: entity.filePath,
+                    message: `'created: ${entity.fm.created}' is more than ${TIMESTAMP_SKEW_HOURS}h from the commit that added it (${added.authored.toISOString().slice(0, 10)})`,
+                });
+            }
+        }
+        for (const comment of entity.comments) {
+            const added = addedAt(ctx.repoRoot, repoPath(comment.path));
+            if (!added)
+                continue;
+            if (checkTimestampSkew(comment.date, added.authored, TIMESTAMP_SKEW_HOURS))
+                continue;
+            out.push({
+                check: "D10",
+                level: "warning",
+                path: comment.path,
+                message: `the filename timestamp is more than ${TIMESTAMP_SKEW_HOURS}h from the commit that added it (${added.authored.toISOString().slice(0, 10)})`,
+            });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=history-checks.js.map

package/dist/cli/history-checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-checks.js","sourceRoot":"","sources":["../../src/cli/history-checks.ts"],"names":[],"mappings":"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"}

package/dist/cli/install/completions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shell completions.
+ *
+ * The scripts stay deliberately thin: anything that needs to know about the
+ * repository calls back into `nav __complete`, so completion behavior lives in
+ * one implementation rather than three shell dialects.
+ */
+export declare const SHELLS: readonly ["bash", "zsh", "fish"];
+export type Shell = (typeof SHELLS)[number];
+export declare function isShell(value: string): value is Shell;
+/** Guess the user's shell from `$SHELL`, defaulting to bash. */
+export declare function detectShell(env: NodeJS.ProcessEnv): Shell;
+/** Where a shell looks for per-user completion scripts. */
+export declare function completionPath(shell: Shell, env: NodeJS.ProcessEnv): string;
+/** Extra advice printed after installing, where a shell needs configuration. */
+export declare function completionNote(shell: Shell, path: string): string | null;
+export declare function completionScript(shell: Shell): string;
+export declare function installCompletions(shell: Shell, env: NodeJS.ProcessEnv): string;
+export declare function uninstallCompletions(shell: Shell, env: NodeJS.ProcessEnv): string | null;

package/dist/cli/install/completions.js

@@ -0,0 +1,94 @@
+/**
+ * Shell completions.
+ *
+ * The scripts stay deliberately thin: anything that needs to know about the
+ * repository calls back into `nav __complete`, so completion behavior lives in
+ * one implementation rather than three shell dialects.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+export const SHELLS = ["bash", "zsh", "fish"];
+export function isShell(value) {
+    return SHELLS.includes(value);
+}
+/** Guess the user's shell from `$SHELL`, defaulting to bash. */
+export function detectShell(env) {
+    const name = basename(env.SHELL ?? "");
+    return isShell(name) ? name : "bash";
+}
+/** Where a shell looks for per-user completion scripts. */
+export function completionPath(shell, env) {
+    const home = env.HOME ?? homedir();
+    const dataHome = env.XDG_DATA_HOME ?? join(home, ".local", "share");
+    const configHome = env.XDG_CONFIG_HOME ?? join(home, ".config");
+    switch (shell) {
+        case "bash":
+            return join(dataHome, "bash-completion", "completions", "nav");
+        case "zsh":
+            return join(dataHome, "zsh", "site-functions", "_nav");
+        default:
+            return join(configHome, "fish", "completions", "nav.fish");
+    }
+}
+/** Extra advice printed after installing, where a shell needs configuration. */
+export function completionNote(shell, path) {
+    if (shell !== "zsh")
+        return null;
+    return `zsh needs ${dirname(path)} on its fpath; add this to ~/.zshrc if it is not:\n  fpath=(${dirname(path)} $fpath)`;
+}
+export function completionScript(shell) {
+    switch (shell) {
+        case "bash":
+            return BASH;
+        case "zsh":
+            return ZSH;
+        default:
+            return FISH;
+    }
+}
+export function installCompletions(shell, env) {
+    const path = completionPath(shell, env);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, completionScript(shell), "utf8");
+    return path;
+}
+export function uninstallCompletions(shell, env) {
+    const path = completionPath(shell, env);
+    if (!existsSync(path))
+        return null;
+    // Only remove a file this tool wrote.
+    if (!readFileSync(path, "utf8").includes("nav __complete"))
+        return null;
+    rmSync(path, { force: true });
+    return path;
+}
+const BASH = `# bash completion for nav (navbook). Generated by 'nav install --completions'.
+_nav_complete() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  local reply
+  reply="$(nav __complete "\${COMP_WORDS[@]:1:COMP_CWORD-1}" 2>/dev/null)"
+  COMPREPLY=($(compgen -W "\${reply}" -- "\${cur}"))
+  return 0
+}
+complete -F _nav_complete nav
+`;
+const ZSH = `#compdef nav
+# zsh completion for nav (navbook). Generated by 'nav install --completions'.
+_nav() {
+  local -a candidates
+  candidates=(\${(f)"$(nav __complete \${words[2,CURRENT-1]} 2>/dev/null)"})
+  _describe 'nav' candidates
+}
+compdef _nav nav
+`;
+const FISH = `# fish completion for nav (navbook). Generated by 'nav install --completions'.
+function __nav_complete
+  set -l tokens (commandline -opc)
+  nav __complete $tokens[2..-1] 2>/dev/null
+end
+complete -c nav -f -a '(__nav_complete)'
+`;
+//# sourceMappingURL=completions.js.map

package/dist/cli/install/completions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completions.js","sourceRoot":"","sources":["../../../src/cli/install/completions.ts"],"names":[],"mappings":"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"}

package/dist/cli/install/hook.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The `pre-commit` hook — spec 04 §4.5.
+ *
+ * The hook is a thin shell script that calls the binary, so `--no-verify` and
+ * manual hook removal behave exactly as users expect. It is written as a marked
+ * block appended to any existing hook, and `nav uninstall --hooks` removes
+ * precisely that block and nothing else.
+ */
+export declare const MARKER_BEGIN = "# >>> navbook >>>";
+export declare const MARKER_END = "# <<< navbook <<<";
+export declare const HOOK_NAME = "pre-commit";
+export declare function hookPath(repoRoot: string): string;
+export declare function isInstalled(repoRoot: string): boolean;
+/** Append the marked block, creating the hook file if there is none. */
+export declare function installHook(repoRoot: string): void;
+/**
+ * Remove exactly the marked block. A hook that contained nothing else is
+ * deleted; a hook the user also wrote by hand keeps everything they wrote.
+ */
+export declare function uninstallHook(repoRoot: string): void;

package/dist/cli/install/hook.js

@@ -0,0 +1,78 @@
+/**
+ * The `pre-commit` hook — spec 04 §4.5.
+ *
+ * The hook is a thin shell script that calls the binary, so `--no-verify` and
+ * manual hook removal behave exactly as users expect. It is written as a marked
+ * block appended to any existing hook, and `nav uninstall --hooks` removes
+ * precisely that block and nothing else.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { hooksDir } from "../../git/repo.js";
+export const MARKER_BEGIN = "# >>> navbook >>>";
+export const MARKER_END = "# <<< navbook <<<";
+export const HOOK_NAME = "pre-commit";
+const SHEBANG = "#!/bin/sh";
+const BODY = `${MARKER_BEGIN}
+# Validate staged Navbook files. Only a format violation (exit 2) blocks the
+# commit; warnings never do, and a clone without nav installed is unaffected.
+# Commit with --no-verify, or delete this block, to skip the check.
+if command -v nav >/dev/null 2>&1; then
+  nav doctor --staged
+  if [ $? -eq 2 ]; then
+    exit 1
+  fi
+fi
+${MARKER_END}`;
+export function hookPath(repoRoot) {
+    return join(hooksDir(repoRoot), HOOK_NAME);
+}
+export function isInstalled(repoRoot) {
+    const path = hookPath(repoRoot);
+    return existsSync(path) && readFileSync(path, "utf8").includes(MARKER_BEGIN);
+}
+/** Append the marked block, creating the hook file if there is none. */
+export function installHook(repoRoot) {
+    const path = hookPath(repoRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (existing.includes(MARKER_BEGIN))
+        return;
+    const content = existing.trim() === ""
+        ? `${SHEBANG}\n${BODY}\n`
+        : `${existing.replace(/\n*$/, "\n")}\n${BODY}\n`;
+    writeFileSync(path, content, "utf8");
+    chmodSync(path, 0o755);
+}
+/**
+ * Remove exactly the marked block. A hook that contained nothing else is
+ * deleted; a hook the user also wrote by hand keeps everything they wrote.
+ */
+export function uninstallHook(repoRoot) {
+    const path = hookPath(repoRoot);
+    if (!existsSync(path))
+        return;
+    const existing = readFileSync(path, "utf8");
+    if (!existing.includes(MARKER_BEGIN))
+        return;
+    const stripped = existing
+        .split("\n")
+        .reduce((state, line) => {
+        if (line.trim() === MARKER_BEGIN)
+            return { lines: state.lines, inside: true };
+        if (line.trim() === MARKER_END)
+            return { lines: state.lines, inside: false };
+        if (!state.inside)
+            state.lines.push(line);
+        return state;
+    }, { lines: [], inside: false })
+        .lines.join("\n");
+    const remainder = stripped.replace(SHEBANG, "").trim();
+    if (remainder === "") {
+        rmSync(path, { force: true });
+        return;
+    }
+    writeFileSync(path, `${stripped.replace(/\n{3,}/g, "\n\n").replace(/\n*$/, "\n")}`, "utf8");
+    chmodSync(path, statSync(path).mode | 0o111);
+}
+//# sourceMappingURL=hook.js.map

package/dist/cli/install/hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.js","sourceRoot":"","sources":["../../../src/cli/install/hook.ts"],"names":[],"mappings":"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"}

package/dist/cli/main.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * `nav` entry point.
+ */
+import { type ExitCode } from "./errors.ts";
+export interface RunOptions {
+    argv?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    stdout?: NodeJS.WriteStream;
+    stderr?: NodeJS.WriteStream;
+}
+/** Run the CLI and return its exit code. Never throws for expected failures. */
+export declare function run(opts?: RunOptions): ExitCode;