@navbook/cli 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Navbook contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+# Navbook
+
+_A lightweight software project manager that lives inside your git repo._
+
+Navbook stores every issue and pull request as plaintext files inside the
+repository, on the same branch and history as the code they describe. There is
+no server, no database, and no hidden ref namespace. If you can clone the
+repository, you have the whole tracker.
+
+This is meant to replace your code forge's issues with a portable,
+decentralised, offline-first solution. Is GitHub down? No big deal — you'll push
+your comment to `origin` whenever it's available again.
+
+```console
+$ nav issue open "Login times out on slow connections" --label bug -m "Aborts after 5 s on 3G."
+Created .navbook/issues/open/bqlybac0-login-timeout/  (#bqlybac0)
+
+$ nav issue list
+ID         STATUS  TITLE                                LABELS
+#bqlybac0  open    Login times out on slow connections  bug
+
+$ nav issue close bqly --resolution fixed --commit
+Closed #bqlybac0  .navbook/issues/closed/bqlybac0-login-timeout/
+Committed docs(issue): close #bqlybac0
+```
+
+That last command moved a directory and made a commit. On the branch that fixes
+the bug, the fix and the close travel together — merging the branch merges both.
+
+## Install
+
+Requires Node 24 or newer and a working `git`.
+
+```sh
+npm install -g @navbook/cli     # or: npx @navbook/cli <command>
+cd your-repo
+nav init
+nav install                # git alias, merge config, pre-commit hook, completions
+```
+
+`nav install` prints every change it is about to make and asks before making
+it, `apt`-style. `-y` skips the question; `nav uninstall` removes exactly what
+it added.
+
+The one setting worth knowing about is `merge.directoryRenames=true`, which
+`nav install` offers. Without it, the most common concurrent pair in Navbook — a
+comment racing a close — is placed correctly by git but still reported as a
+conflict to confirm. With it, that merge is clean.
+
+## What it looks like on disk
+
+```
+.navbook/
+├── issues/
+│   ├── open/
+│   │   └── bqlybac0-login-timeout/
+│   │       ├── issue.md
+│   │       └── comments/
+│   │           └── 2026-08-03T141207Z-t5kr1gq6.md
+│   └── closed/
+└── prs/
+    ├── open/
+    ├── merged/
+    └── closed/
+```
+
+An issue is a Markdown file with YAML frontmatter. Its status is which directory
+it sits in. A comment is one file, which is why two people commenting at once
+can never conflict. Every forge file browser, every editor, `ls` and `cat` are
+complete Navbook clients for reading.
+
+**The files are the product.** The `nav` CLI mints IDs, renders listings and
+validates the tree, but nothing requires it: creating, commenting on, closing
+and reviewing with a text editor and `git` is a first-class, supported workflow.
+No operation exists that only the tool can perform correctly.
+
+## Commands
+
+Everything is noun-verb, with one verb vocabulary shared by both entity kinds.
+
+```
+nav {issue|pr} {open|list|show|edit|comment|close|reopen}
+nav pr {update|review|merge}
+nav {init|id|doctor|install|uninstall}
+```
+
+IDs accept any unambiguous prefix of four characters or more, so `bqly` is
+usually enough. A full directory name works too.
+
+| Command | What it does |
+|---|---|
+| `nav issue open <title>` | File an issue. `-m TEXT`, or `$EDITOR` opens on the new file. |
+| `nav issue list [query]` | Filtered table; `--json` for one JSON object per line. |
+| `nav issue close <id> [--resolution R]` | Move it to `closed/`. |
+| `nav pr open [--target BRANCH]` | Open a PR from the current branch, pinning the exact head and merge base under review. |
+| `nav pr review <id> --approve` | Record a verdict bound to a specific revision. |
+| `nav pr list --all-refs` | Find PRs on branches you have fetched but not checked out. |
+| `nav pr merge <id>` | Merge into the checked-out target, archiving the discussion into its history. |
+| `nav doctor [--fix]` | Check the tree against the specification. |
+
+`--commit` on any mutating command wraps the change in a well-formed
+Conventional Commits `docs` commit (`docs(issue): close #bqlybac0`,
+`docs(pr): merge #dk3mp2x9`). Without it, changes are left staged for your own
+commit.
+
+### Query syntax
+
+```sh
+nav issue list status:closed label:bug assignee:example.com "timeout"
+```
+
+`status:`, `label:`, `assignee:`, `author:`, `milestone:`, and bare words that
+match the title, description or any comment body. Terms AND together; the
+default query is `status:open`.
+
+## Why the design is what it is
+
+Three properties drive everything else:
+
+- **Browsable.** The tracker renders on any forge with no plugin, because it is
+  just Markdown in human-named directories.
+- **Same history as the code.** `git log`, `git blame` and `git bisect` work on
+  tracker state exactly as they do on code. A release tag captures what the
+  tracker said at that moment.
+- **No coordination.** IDs are 8 random characters, not sequential numbers —
+  the single most repeated mistake in this problem space. Two people can file
+  issues offline, on different branches, and never collide.
+
+Pull requests live on the branch they propose to merge, so opening one needs no
+server and works offline. Merging carries the whole discussion into the target
+branch's permanent history. Approvals are bound to the exact revision they
+judged, so a force-push can never inherit a stale approval.
+
+## Platforms
+
+Developed and tested on Linux and macOS. Windows is not guaranteed; use
+[Git Bash](https://gitforwindows.org/) or WSL, where Navbook works because both
+provide the POSIX shell the hooks and completions expect.
+
+## Documentation
+
+The [specification](doc/spec/README.md) is the normative definition of the file
+format and the reference for anyone writing another implementation. Start with
+[01-functionality.md](doc/spec/01-functionality.md) for what Navbook does, or
+[02-data-model.md](doc/spec/02-data-model.md) for the exact file format.
+
+## Contributing
+
+Navbook tracks its own development in `.navbook/` — run `nav issue list` in a
+clone to see what is open.
+
+```sh
+npm install
+npm test           # unit, CLI and conformance suites
+npm run check      # lint and type-check
+npm run bench      # the performance budget, on its own machine
+```
+
+The [conformance fixtures](doc/spec/fixtures/README.md) are golden repositories
+that any implementation must pass; they run against `$NAV_BIN`, so the same
+suite validates the planned Rust rewrite.
+
+## License
+
+MIT.

package/dist/cli/commands/complete.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `nav __complete` — the completion backend the shell scripts call.
+ *
+ * Given the words typed so far (without the leading `nav`), it prints one
+ * candidate per line. Keeping the logic here rather than in three shell
+ * dialects is what makes ID and slug completion possible at all.
+ */
+import type { Ctx } from "../context.ts";
+export declare function cmdComplete(ctx: Ctx, words: string[]): void;

package/dist/cli/commands/complete.js

@@ -0,0 +1,72 @@
+/**
+ * `nav __complete` — the completion backend the shell scripts call.
+ *
+ * Given the words typed so far (without the leading `nav`), it prints one
+ * candidate per line. Keeping the logic here rather than in three shell
+ * dialects is what makes ID and slug completion possible at all.
+ */
+import { allEntities } from "../../core/tree.js";
+import { loadRepo } from "../workspace.js";
+const ROOT_COMMANDS = ["issue", "pr", "init", "id", "doctor", "install", "uninstall", "help"];
+const SHARED_VERBS = ["open", "list", "show", "edit", "comment", "close", "reopen"];
+const PR_VERBS = [...SHARED_VERBS, "update", "review", "merge"];
+const QUERY_KEYS = ["status:", "label:", "assignee:", "author:", "milestone:"];
+export function cmdComplete(ctx, words) {
+    for (const candidate of completionsFor(ctx, words))
+        ctx.stdout.write(`${candidate}\n`);
+}
+function completionsFor(ctx, words) {
+    const [noun, verb] = words;
+    if (noun === undefined)
+        return ROOT_COMMANDS;
+    if (noun !== "issue" && noun !== "pr") {
+        return words.length === 1 ? ROOT_COMMANDS : [];
+    }
+    const kind = noun === "issue" ? "issue" : "pr";
+    const verbs = kind === "issue" ? SHARED_VERBS : PR_VERBS;
+    if (verb === undefined)
+        return verbs;
+    if (!verbs.includes(verb))
+        return [];
+    if (verb === "list")
+        return [...QUERY_KEYS, ...labels(ctx)];
+    if (verb === "open")
+        return [];
+    // Every other verb takes an ID as its first argument.
+    return words.length === 2 ? entityCandidates(ctx, kind) : [];
+}
+/**
+ * Bare IDs and full directory names, so a user can complete either the short
+ * form they would type or the readable name they would recognize.
+ */
+function entityCandidates(ctx, kind) {
+    try {
+        const repo = loadRepo(ctx, { includeComments: false });
+        return allEntities(repo)
+            .filter((entity) => entity.kind === kind)
+            .flatMap((entity) => [entity.id, entity.dirName])
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function labels(ctx) {
+    try {
+        const repo = loadRepo(ctx, { includeComments: false });
+        const found = new Set();
+        for (const entity of allEntities(repo)) {
+            const values = entity.fm.labels;
+            if (!Array.isArray(values))
+                continue;
+            for (const value of values)
+                if (typeof value === "string")
+                    found.add(`label:${value}`);
+        }
+        return [...found].sort();
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=complete.js.map

package/dist/cli/commands/complete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete.js","sourceRoot":"","sources":["../../../src/cli/commands/complete.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AAElE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;AAC9F,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AACpF,MAAM,QAAQ,GAAG,CAAC,GAAG,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAChE,MAAM,UAAU,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;AAE/E,MAAM,UAAU,WAAW,CAAC,GAAQ,EAAE,KAAe;IACnD,KAAK,MAAM,SAAS,IAAI,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC;QAAE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,SAAS,IAAI,CAAC,CAAC;AACzF,CAAC;AAED,SAAS,cAAc,CAAC,GAAQ,EAAE,KAAe;IAC/C,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC;IAC3B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IAC7C,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;IACjD,CAAC;IAED,MAAM,IAAI,GAAe,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3D,MAAM,KAAK,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC;IACzD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAErC,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,CAAC,GAAG,UAAU,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5D,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,CAAC;IAC/B,sDAAsD;IACtD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,GAAQ,EAAE,IAAgB;IAClD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC;QACvD,OAAO,WAAW,CAAC,IAAI,CAAC;aACrB,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC;aACxC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;aAChD,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CAAC,GAAQ;IACtB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC;QACvD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;QAChC,KAAK,MAAM,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC;YAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBAAE,SAAS;YACrC,KAAK,MAAM,KAAK,IAAI,MAAM;gBAAE,IAAI,OAAO,KAAK,KAAK,QAAQ;oBAAE,KAAK,CAAC,GAAG,CAAC,SAAS,KAAK,EAAE,CAAC,CAAC;QACzF,CAAC;QACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/cli/commands/compose.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Producing the text of a new Navbook file, from `-m` or from `$EDITOR`.
+ *
+ * Both paths end in the same place: a complete file that has been parsed and
+ * validated before anything is written into `.navbook/`. The editor buffer is
+ * the whole file — frontmatter included — so an author can set the title,
+ * labels and body in one pass, and an abort leaves nothing behind.
+ */
+import { type ParsedFile, type Problem } from "../../core/files.ts";
+import type { Ctx } from "../context.ts";
+export interface ComposeOptions {
+    /** Text supplied with `-m`; when absent the editor is opened. */
+    message?: string;
+    /** Name of the scratch buffer inside the git directory. */
+    bufferName: string;
+    /** Render the complete file from a body. */
+    render: (body: string) => string;
+    /** Schema check applied to the finished file. */
+    validate: (parsed: ParsedFile) => Problem[];
+    /** Noun used in error messages, e.g. "issue" or "comment". */
+    noun: string;
+}
+export interface Composed {
+    content: string;
+    parsed: ParsedFile;
+}
+export declare function composeFile(ctx: Ctx, opts: ComposeOptions): Composed;

package/dist/cli/commands/compose.js

@@ -0,0 +1,44 @@
+/**
+ * Producing the text of a new Navbook file, from `-m` or from `$EDITOR`.
+ *
+ * Both paths end in the same place: a complete file that has been parsed and
+ * validated before anything is written into `.navbook/`. The editor buffer is
+ * the whole file — frontmatter included — so an author can set the title,
+ * labels and body in one pass, and an abort leaves nothing behind.
+ */
+import { parseFile } from "../../core/files.js";
+import { editBuffer } from "../editor.js";
+import { fail } from "../errors.js";
+export function composeFile(ctx, opts) {
+    if (opts.message !== undefined) {
+        if (opts.message.trim() === "")
+            fail(`empty ${opts.noun} text; aborting`);
+        return check(opts, opts.render(opts.message));
+    }
+    const edited = editBuffer(ctx, opts.bufferName, opts.render(""));
+    let parsed;
+    try {
+        parsed = parseFile(edited);
+    }
+    catch (error) {
+        fail(`aborting: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (parsed.body.trim() === "")
+        fail(`aborting ${opts.noun} due to empty body`);
+    return check(opts, edited);
+}
+function check(opts, content) {
+    let parsed;
+    try {
+        parsed = parseFile(content);
+    }
+    catch (error) {
+        fail(`aborting: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const problems = opts.validate(parsed);
+    if (problems.length > 0) {
+        fail(`the ${opts.noun} is not valid and was not created`, problems.map((problem) => `  ${problem.message}`));
+    }
+    return { content, parsed };
+}
+//# sourceMappingURL=compose.js.map

package/dist/cli/commands/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../../src/cli/commands/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAiC,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAoBpC,MAAM,UAAU,WAAW,CAAC,GAAQ,EAAE,IAAoB;IACxD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,iBAAiB,CAAC,CAAC;QAC1E,OAAO,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACjE,IAAI,MAAkB,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,aAAa,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,YAAY,IAAI,CAAC,IAAI,oBAAoB,CAAC,CAAC;IAC/E,OAAO,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,KAAK,CAAC,IAAoB,EAAE,OAAe;IAClD,IAAI,MAAkB,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,aAAa,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,IAAI,CACF,OAAO,IAAI,CAAC,IAAI,mCAAmC,EACnD,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAClD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC"}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `nav doctor` — spec 04 §4.3.
+ *
+ * Doctor enforces the specification, not a house style: hand edits that are
+ * unusual but valid must pass. Errors (exit 2) are format violations; warnings
+ * (exit 0) are things worth a look that may be perfectly deliberate.
+ */
+import type { Ctx } from "../context.ts";
+export interface DoctorOptions {
+    staged?: boolean;
+    fix?: boolean;
+    json?: boolean;
+}
+export declare function cmdDoctor(ctx: Ctx, opts: DoctorOptions): void;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,127 @@
+/**
+ * `nav doctor` — spec 04 §4.3.
+ *
+ * Doctor enforces the specification, not a house style: hand edits that are
+ * unusual but valid must pass. Errors (exit 2) are format violations; warnings
+ * (exit 0) are things worth a look that may be perfectly deliberate.
+ */
+import { NAVBOOK_ROOT } from "../../core/json.js";
+import { parseTree } from "../../core/tree.js";
+import { hasErrors, sortDiagnostics, validateRepo } from "../../core/validate.js";
+import { git, gitMaybe, splitNul } from "../../git/exec.js";
+import { stagedContent, stagedPaths } from "../../git/index-ops.js";
+import { NavError } from "../errors.js";
+import { runHistoryChecks } from "../history-checks.js";
+import { applyOps, loadRepo, repoPath, requireNavbook } from "../workspace.js";
+export function cmdDoctor(ctx, opts) {
+    requireNavbook(ctx);
+    const repo = opts.staged ? stagedRepo(ctx) : loadRepo(ctx);
+    const diagnostics = sortDiagnostics([
+        ...validateRepo(repo, { commitMessages: recentCommitMessages(ctx, opts) }),
+        // History-dependent checks are skipped for --staged: the commit being made
+        // does not exist yet, so there is nothing for them to read.
+        ...(opts.staged ? [] : runHistoryChecks(ctx, repo)),
+    ]);
+    const applied = opts.fix ? applyFixes(ctx, diagnostics) : [];
+    const remaining = opts.fix ? diagnostics.filter((d) => !d.fix) : diagnostics;
+    if (opts.json) {
+        for (const diagnostic of remaining) {
+            ctx.stdout.write(`${JSON.stringify(toJson(diagnostic))}\n`);
+        }
+    }
+    else {
+        report(ctx, remaining, applied);
+    }
+    if (hasErrors(remaining)) {
+        throw new NavError(`${countErrors(remaining)} format violation(s) found`, { exitCode: 2 });
+    }
+}
+function toJson(diagnostic) {
+    return {
+        check: diagnostic.check,
+        level: diagnostic.level,
+        path: diagnostic.path === "" ? "" : `${NAVBOOK_ROOT}/${diagnostic.path}`,
+        message: diagnostic.message,
+    };
+}
+function report(ctx, diagnostics, applied) {
+    const c = ctx.colors;
+    for (const line of applied)
+        ctx.stdout.write(`${c.green("fixed")}  ${line}\n`);
+    for (const diagnostic of diagnostics) {
+        const level = diagnostic.level === "error" ? c.red("error") : c.yellow("warning");
+        const where = diagnostic.path === "" ? "" : `${NAVBOOK_ROOT}/${diagnostic.path}: `;
+        ctx.stdout.write(`${level}  ${c.dim(diagnostic.check)}  ${where}${diagnostic.message}\n`);
+    }
+    const errors = countErrors(diagnostics);
+    const warnings = diagnostics.length - errors;
+    if (errors === 0 && warnings === 0) {
+        ctx.stdout.write(applied.length > 0 ? "No problems remain.\n" : "No problems found.\n");
+        return;
+    }
+    ctx.stdout.write(`${plural(errors, "error")}, ${plural(warnings, "warning")}\n`);
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function countErrors(diagnostics) {
+    return diagnostics.filter((d) => d.level === "error").length;
+}
+/** Apply every mechanical repair a diagnostic offers, reporting each one. */
+function applyFixes(ctx, diagnostics) {
+    const applied = [];
+    for (const diagnostic of diagnostics) {
+        if (!diagnostic.fix || diagnostic.fix.length === 0)
+            continue;
+        applyOps(ctx, diagnostic.fix);
+        for (const op of diagnostic.fix)
+            applied.push(describeFix(op));
+    }
+    return applied;
+}
+function describeFix(op) {
+    return op.op === "move"
+        ? `moved ${repoPath(op.from)} to ${repoPath(op.to)}`
+        : `wrote ${repoPath(op.path)}`;
+}
+/** Build the repository model from what is staged rather than the working tree. */
+function stagedRepo(ctx) {
+    const prefix = `${NAVBOOK_ROOT}/`;
+    const paths = allIndexedNavPaths(ctx).filter((path) => path.startsWith(prefix));
+    const files = new Map();
+    for (const path of paths) {
+        const content = stagedContent(ctx.repoRoot, path);
+        if (content !== null)
+            files.set(path.slice(prefix.length), content);
+    }
+    return parseTree(files);
+}
+/**
+ * Every `.navbook/` path in the index. The pre-commit hook needs the whole
+ * indexed tree, not only the changed paths: checks like ID uniqueness and
+ * reply-to resolution are properties of the tree the commit will create.
+ */
+function allIndexedNavPaths(ctx) {
+    const listed = splitNul(git(["ls-files", "--cached", "-z", "--", NAVBOOK_ROOT], { cwd: ctx.repoRoot }));
+    return listed.length > 0 ? listed : stagedPaths(ctx.repoRoot);
+}
+/**
+ * Commit messages scanned for dangling trailers (check D8).
+ *
+ * Bounded to recent history: a trailer naming an entity that is not in this
+ * tree is worth knowing about while the work is current, but the whole history
+ * of a long-lived repository would produce standing noise for entities that
+ * were legitimately archived or that live on a branch nobody has fetched.
+ */
+const TRAILER_SCAN_DEPTH = 100;
+function recentCommitMessages(ctx, opts) {
+    if (opts.staged)
+        return [];
+    const output = gitMaybe(["log", "--format=%B%x00", "-n", String(TRAILER_SCAN_DEPTH)], {
+        cwd: ctx.repoRoot,
+    });
+    if (output === null)
+        return [];
+    return output.split("\0").filter((message) => message.trim() !== "");
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/commands/doctor.js.map

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

package/dist/cli/commands/entity.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The verbs issues and pull requests share — spec 04 §4.3.
+ *
+ * One implementation serves both nouns; the entity kind only selects which
+ * collection is searched, which file name is edited, and which words appear in
+ * the report.
+ */
+import { type NewCommentInput } from "../../core/files.ts";
+import { type CloseInput, type Plan } from "../../core/ops.ts";
+import { type Query } from "../../core/query.ts";
+import type { EntityKind, EntityRecord, Repo } from "../../core/tree.ts";
+import type { Ctx } from "../context.ts";
+export interface GlobalFlags {
+    json?: boolean;
+    commit?: boolean;
+}
+/** Author string for the current git identity. */
+export declare function currentAuthor(ctx: Ctx): string;
+/** Entities of one kind from a parsed repository. */
+export declare function selectEntities(repo: Repo, kind: EntityKind): EntityRecord[];
+/** Newest first, with a stable tie-break on ID. */
+export declare function sortEntities(entities: readonly EntityRecord[]): EntityRecord[];
+export interface ExtraColumn {
+    header: string;
+    value: (entity: EntityRecord) => string;
+}
+export interface ListOptions extends GlobalFlags {
+    /** Columns appended by PR-specific listings. */
+    extraColumns?: ExtraColumn[];
+    /** Pre-collected entities, used by `nav pr list --all-refs`. */
+    entities?: EntityRecord[];
+    /** Extra JSON keys per entity, keyed by entity identity. */
+    jsonExtra?: (entity: EntityRecord) => Record<string, unknown>;
+}
+export declare function cmdList(ctx: Ctx, kind: EntityKind, terms: string[], opts: ListOptions): void;
+/** The query a listing will run, for callers that need it before loading. */
+export declare function parseListQuery(terms: string[], kind: EntityKind): Query;
+export declare function cmdShow(ctx: Ctx, kind: EntityKind, prefix: string, opts: GlobalFlags): void;
+export declare function cmdEdit(ctx: Ctx, kind: EntityKind, prefix: string, opts: GlobalFlags): void;
+export interface CommentOptions extends GlobalFlags {
+    message?: string;
+    replyTo?: string;
+    /** Review fields, supplied by `nav pr review`. */
+    review?: Pick<NewCommentInput, "verdict" | "revision" | "file" | "line">;
+}
+export declare function cmdComment(ctx: Ctx, kind: EntityKind, prefix: string, opts: CommentOptions): void;
+export interface CloseOptions extends GlobalFlags, CloseInput {
+}
+export declare function cmdClose(ctx: Ctx, kind: EntityKind, prefix: string, opts: CloseOptions): void;
+export declare function cmdReopen(ctx: Ctx, kind: EntityKind, prefix: string, opts: GlobalFlags): void;
+/**
+ * Build a plan that rewrites an entity file, turning a malformed-frontmatter
+ * failure into an operational error that names the file and the way out.
+ */
+export declare function rewritePlan(entity: EntityRecord, build: () => Plan): Plan;