@navbook/cli 0.1.0

package/dist/cli/render/table.js

@@ -0,0 +1,58 @@
+/**
+ * Column-aligned listings for `nav issue list` / `nav pr list`.
+ */
+const GAP = "  ";
+/** Render a table, shrinking flexible columns to fit the terminal width. */
+export function renderTable(columns, rows, opts) {
+    if (rows.length === 0)
+        return "";
+    const widths = columns.map((column, index) => Math.max(column.header.length, ...rows.map((row) => displayWidth(row[index] ?? ""))));
+    const available = opts.width;
+    if (available !== undefined)
+        shrinkToFit(columns, widths, available);
+    const lines = [];
+    lines.push(opts.colors.dim(joinCells(columns.map((column, index) => pad(column.header.toUpperCase(), widths[index])))));
+    for (const row of rows) {
+        lines.push(joinCells(columns.map((_, index) => pad(truncate(row[index] ?? "", widths[index]), widths[index]))));
+    }
+    return lines.join("\n");
+}
+function shrinkToFit(columns, widths, available) {
+    const gaps = GAP.length * (columns.length - 1);
+    const flexible = columns
+        .map((column, index) => ({ column, index }))
+        .filter(({ column }) => column.flexible);
+    if (flexible.length === 0)
+        return;
+    let total = widths.reduce((sum, w) => sum + w, 0) + gaps;
+    for (const { column, index } of flexible) {
+        if (total <= available)
+            break;
+        const minWidth = column.minWidth ?? 8;
+        const current = widths[index];
+        const reduced = Math.max(minWidth, current - (total - available));
+        total -= current - reduced;
+        widths[index] = reduced;
+    }
+}
+function joinCells(cells) {
+    return cells.join(GAP).replace(/\s+$/, "");
+}
+function pad(text, width) {
+    const padding = width - displayWidth(text);
+    return padding > 0 ? text + " ".repeat(padding) : text;
+}
+/** Truncate to `width`, marking the cut with a single ellipsis character. */
+export function truncate(text, width) {
+    if (width <= 0)
+        return "";
+    if (displayWidth(text) <= width)
+        return text;
+    if (width === 1)
+        return "~";
+    return `${text.slice(0, width - 1)}~`;
+}
+function displayWidth(text) {
+    return [...text].length;
+}
+//# sourceMappingURL=table.js.map

package/dist/cli/render/table.js.map

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

package/dist/cli/resolve.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Turning what the user typed into the entity they meant — spec 02 §2.2
+ * (prefixes of at least four characters) and spec 04 §4.3 (a verb given an ID
+ * of the other kind points at the right noun).
+ */
+import { type EntityKind, type EntityRecord, type Repo } from "../core/tree.ts";
+/**
+ * Accept a whole entity directory name wherever an ID is expected.
+ *
+ * Shell completion offers `<id>-<slug>` names, and they are what a user copies
+ * out of a path or a forge URL; the ID is simply its first eight characters.
+ */
+export declare function asId(argument: string): string;
+/** Resolve an ID or unambiguous prefix to an entity of the expected kind. */
+export declare function resolveEntity(repo: Repo, prefix: string, kind: EntityKind): EntityRecord;
+/** Resolve a comment ID or prefix within one entity (used by `--reply-to`). */
+export declare function resolveComment(entity: EntityRecord, prefix: string): string;

package/dist/cli/resolve.js

@@ -0,0 +1,68 @@
+/**
+ * Turning what the user typed into the entity they meant — spec 02 §2.2
+ * (prefixes of at least four characters) and spec 04 §4.3 (a verb given an ID
+ * of the other kind points at the right noun).
+ */
+import { MIN_PREFIX_LENGTH, resolvePrefix } from "../core/id.js";
+import { allEntities } from "../core/tree.js";
+import { fail } from "./errors.js";
+const NOUN = { issue: "issue", pr: "pull request" };
+const COMMAND = { issue: "nav issue", pr: "nav pr" };
+/**
+ * Accept a whole entity directory name wherever an ID is expected.
+ *
+ * Shell completion offers `<id>-<slug>` names, and they are what a user copies
+ * out of a path or a forge URL; the ID is simply its first eight characters.
+ */
+export function asId(argument) {
+    const match = /^([a-z][a-z0-9]{7})-[a-z0-9-]+$/.exec(argument.toLowerCase());
+    return match ? match[1] : argument;
+}
+/** Resolve an ID or unambiguous prefix to an entity of the expected kind. */
+export function resolveEntity(repo, prefix, kind) {
+    const entities = allEntities(repo);
+    const resolution = resolvePrefix(asId(prefix), entities.map((e) => e.id));
+    if (!resolution.ok) {
+        switch (resolution.reason) {
+            case "too-short":
+                fail(`'${prefix}' is too short; ID prefixes must be at least ${MIN_PREFIX_LENGTH} characters`);
+                break;
+            case "not-found":
+                fail(`no ${NOUN[kind]} matches '${prefix}'`);
+                break;
+            default:
+                fail(`'${prefix}' is ambiguous; ${resolution.matches.length} entities match`, resolution.matches.map((id) => describe(entities.find((e) => e.id === id))));
+        }
+    }
+    const matches = entities.filter((e) => e.id === resolution.id);
+    const wanted = matches.find((e) => e.kind === kind);
+    if (wanted)
+        return wanted;
+    const other = matches[0];
+    fail(`#${other.id} is ${other.kind === "pr" ? "a pull request" : "an issue"} — use '${COMMAND[other.kind]} ${verbHint()}'`);
+}
+function verbHint() {
+    return "show";
+}
+function describe(entity) {
+    if (!entity)
+        return "";
+    return `#${entity.id}  ${entity.kind === "pr" ? "pr   " : "issue"}  ${entity.title}`;
+}
+/** Resolve a comment ID or prefix within one entity (used by `--reply-to`). */
+export function resolveComment(entity, prefix) {
+    const resolution = resolvePrefix(prefix, entity.comments.map((c) => c.id));
+    if (resolution.ok)
+        return resolution.id;
+    switch (resolution.reason) {
+        case "too-short":
+            fail(`'${prefix}' is too short; ID prefixes must be at least ${MIN_PREFIX_LENGTH} characters`);
+            break;
+        case "not-found":
+            fail(`no comment of #${entity.id} matches '${prefix}'`);
+            break;
+        default:
+            fail(`'${prefix}' is ambiguous within #${entity.id}`, resolution.matches.map((id) => `#${id}`));
+    }
+}
+//# sourceMappingURL=resolve.js.map

package/dist/cli/resolve.js.map

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

package/dist/cli/workspace.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Reading and mutating the `.navbook/` working tree.
+ *
+ * Core plans; this module executes. Every write goes through {@link applyOps}
+ * so the set of touched paths is known exactly — which is what makes the
+ * `--commit` guard of spec 04 §4.2 precise rather than approximate.
+ */
+import type { FileOp } from "../core/ops.ts";
+import { type Query } from "../core/query.ts";
+import { type NavTree, type Repo } from "../core/tree.ts";
+import type { Ctx } from "./context.ts";
+export interface ReadTreeOptions {
+    /** Skip `comments/` directories when the command cannot need them. */
+    includeComments?: boolean;
+}
+/** Read `.navbook/` into a flat path→content map. */
+export declare function readNavTree(navRoot: string, opts?: ReadTreeOptions): NavTree;
+/** Load the repository model from the working tree. */
+export declare function loadRepo(ctx: Ctx, opts?: ReadTreeOptions): Repo;
+/** Load the repository, reading comment bodies only when the query needs them. */
+export declare function loadRepoForQuery(ctx: Ctx, query: Query): Repo;
+/** Fail with a helpful message when the repository has no `.navbook/` yet. */
+export declare function requireNavbook(ctx: Ctx): void;
+/** Convert a path relative to `.navbook/` into a repository-relative path. */
+export declare function repoPath(navRelative: string): string;
+/** Absolute filesystem path for a path relative to `.navbook/`. */
+export declare function absPath(ctx: Ctx, navRelative: string): string;
+export interface ApplyResult {
+    /** Repository-relative paths the operation created, rewrote or moved. */
+    touched: string[];
+}
+/**
+ * Execute file operations in order, then stage exactly the paths involved.
+ *
+ * Renames are performed as a filesystem move followed by `git add`, which
+ * produces the same index state as `git mv` while also working on entities that
+ * have not been committed yet.
+ */
+export declare function applyOps(ctx: Ctx, ops: readonly FileOp[]): ApplyResult;
+/** Stage paths, tolerating those that no longer exist and were never tracked. */
+export declare function stage(ctx: Ctx, paths: readonly string[]): void;
+/**
+ * Every ID in the repository, read from names alone.
+ *
+ * Entity IDs are in directory names and comment IDs are in filenames (§2.2,
+ * §2.6), so uniqueness can be checked without opening a single file — which
+ * keeps `open` fast while still honouring "unique across all entity and
+ * comment IDs".
+ */
+export declare function scanAllIds(navRoot: string): Set<string>;
+/** Repository-relative path of an absolute path, in POSIX form. */
+export declare function toRepoRelative(ctx: Ctx, absolute: string): string;

package/dist/cli/workspace.js

@@ -0,0 +1,178 @@
+/**
+ * Reading and mutating the `.navbook/` working tree.
+ *
+ * Core plans; this module executes. Every write goes through {@link applyOps}
+ * so the set of touched paths is known exactly — which is what makes the
+ * `--commit` guard of spec 04 §4.2 precise rather than approximate.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, writeFileSync, } from "node:fs";
+import { dirname, join, posix, relative, sep } from "node:path";
+import { parseCommentFileName } from "../core/comments.js";
+import { NAVBOOK_ROOT } from "../core/json.js";
+import { needsComments } from "../core/query.js";
+import { parseDirName } from "../core/slug.js";
+import { parseTree } from "../core/tree.js";
+import { gitMaybe } from "../git/exec.js";
+import { add } from "../git/index-ops.js";
+import { fail } from "./errors.js";
+/** Read `.navbook/` into a flat path→content map. */
+export function readNavTree(navRoot, opts = {}) {
+    const includeComments = opts.includeComments !== false;
+    const files = new Map();
+    if (!existsSync(navRoot))
+        return files;
+    walk(navRoot, "", files, includeComments);
+    return files;
+}
+function walk(absolute, rel, files, includeComments) {
+    let entries;
+    try {
+        entries = readdirSync(absolute, { withFileTypes: true, encoding: "utf8" });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const childRel = rel === "" ? entry.name : `${rel}/${entry.name}`;
+        const childAbs = join(absolute, entry.name);
+        if (entry.isDirectory()) {
+            if (!includeComments && entry.name === "comments")
+                continue;
+            walk(childAbs, childRel, files, includeComments);
+        }
+        else if (entry.isFile()) {
+            files.set(childRel, readFileSync(childAbs, "utf8"));
+        }
+    }
+}
+/** Load the repository model from the working tree. */
+export function loadRepo(ctx, opts = {}) {
+    requireNavbook(ctx);
+    const includeComments = opts.includeComments !== false;
+    const files = readNavTree(ctx.navRoot, { includeComments });
+    return parseTree(files, { commentsLoaded: includeComments });
+}
+/** Load the repository, reading comment bodies only when the query needs them. */
+export function loadRepoForQuery(ctx, query) {
+    return loadRepo(ctx, { includeComments: needsComments(query) });
+}
+/** Fail with a helpful message when the repository has no `.navbook/` yet. */
+export function requireNavbook(ctx) {
+    if (!ctx.hasNavbook) {
+        fail(`not a Navbook repository: no ${NAVBOOK_ROOT}/ at the repository root`, [
+            "run 'nav init' to create it",
+        ]);
+    }
+}
+/** Convert a path relative to `.navbook/` into a repository-relative path. */
+export function repoPath(navRelative) {
+    return posix.join(NAVBOOK_ROOT, navRelative);
+}
+/** Absolute filesystem path for a path relative to `.navbook/`. */
+export function absPath(ctx, navRelative) {
+    return join(ctx.navRoot, ...navRelative.split("/"));
+}
+/**
+ * Execute file operations in order, then stage exactly the paths involved.
+ *
+ * Renames are performed as a filesystem move followed by `git add`, which
+ * produces the same index state as `git mv` while also working on entities that
+ * have not been committed yet.
+ */
+export function applyOps(ctx, ops) {
+    const touched = new Set();
+    for (const op of ops) {
+        if (op.op === "write") {
+            const target = absPath(ctx, op.path);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, op.content, "utf8");
+            touched.add(repoPath(op.path));
+            continue;
+        }
+        const from = absPath(ctx, op.from);
+        const to = absPath(ctx, op.to);
+        if (!existsSync(from))
+            fail(`cannot move ${repoPath(op.from)}: it does not exist`);
+        if (existsSync(to))
+            fail(`cannot move ${repoPath(op.from)}: ${repoPath(op.to)} already exists`);
+        mkdirSync(dirname(to), { recursive: true });
+        renameSync(from, to);
+        pruneEmptyParents(ctx, dirname(from));
+        touched.add(repoPath(op.from));
+        touched.add(repoPath(op.to));
+    }
+    stage(ctx, [...touched]);
+    return { touched: [...touched].sort() };
+}
+/**
+ * Remove directories left empty by a move, up to (but never including) the
+ * `.navbook/` root. Git does not track empty directories, so leaving them
+ * behind would make the working tree disagree with a fresh clone.
+ */
+function pruneEmptyParents(ctx, startDir) {
+    let current = startDir;
+    while (current.startsWith(ctx.navRoot) && current !== ctx.navRoot) {
+        try {
+            if (readdirSync(current).length > 0)
+                return;
+            rmdirSync(current);
+        }
+        catch {
+            return;
+        }
+        current = dirname(current);
+    }
+}
+/** Stage paths, tolerating those that no longer exist and were never tracked. */
+export function stage(ctx, paths) {
+    const stageable = paths.filter((path) => {
+        if (existsSync(join(ctx.repoRoot, ...path.split("/"))))
+            return true;
+        const tracked = gitMaybe(["ls-files", "--", path], { cwd: ctx.repoRoot });
+        return tracked !== null && tracked !== "";
+    });
+    add(ctx.repoRoot, stageable);
+}
+/**
+ * Every ID in the repository, read from names alone.
+ *
+ * Entity IDs are in directory names and comment IDs are in filenames (§2.2,
+ * §2.6), so uniqueness can be checked without opening a single file — which
+ * keeps `open` fast while still honouring "unique across all entity and
+ * comment IDs".
+ */
+export function scanAllIds(navRoot) {
+    const ids = new Set();
+    if (!existsSync(navRoot))
+        return ids;
+    const walk = (dir, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true, encoding: "utf8" });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const parsed = parseDirName(entry.name);
+                if (parsed)
+                    ids.add(parsed.id);
+                if (depth < 6)
+                    walk(join(dir, entry.name), depth + 1);
+            }
+            else if (entry.isFile()) {
+                const comment = parseCommentFileName(entry.name);
+                if (comment)
+                    ids.add(comment.id);
+            }
+        }
+    };
+    walk(navRoot, 0);
+    return ids;
+}
+/** Repository-relative path of an absolute path, in POSIX form. */
+export function toRepoRelative(ctx, absolute) {
+    return relative(ctx.repoRoot, absolute).split(sep).join("/");
+}
+//# sourceMappingURL=workspace.js.map

package/dist/cli/workspace.js.map

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

package/dist/core/comments.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Comment files — spec 02 §2.6. One file per comment, named with a colon-free
+ * UTC timestamp plus the comment's own ID, so listings sort chronologically and
+ * concurrent comments can never collide.
+ */
+export declare const COMMENT_NAME_PATTERN: RegExp;
+export interface CommentName {
+    stamp: string;
+    date: Date;
+    id: string;
+}
+/** Build the filename for a comment created at `date` with identifier `id`. */
+export declare function commentFileName(date: Date, id: string): string;
+/** Parse a comment filename, or return null when it violates the grammar. */
+export declare function parseCommentFileName(name: string): CommentName | null;
+export interface ThreadItem<T> {
+    comment: T;
+    depth: number;
+}
+/**
+ * Order comments for display: chronologically by filename, with replies placed
+ * directly under the comment they answer and indented by one level.
+ *
+ * Replies to unknown comments, and reply cycles, degrade to top level rather
+ * than disappearing.
+ */
+export declare function threadOrder<T extends {
+    id: string;
+    replyTo?: string;
+    fileName: string;
+}>(comments: readonly T[]): ThreadItem<T>[];

package/dist/core/comments.js

@@ -0,0 +1,80 @@
+/**
+ * Comment files — spec 02 §2.6. One file per comment, named with a colon-free
+ * UTC timestamp plus the comment's own ID, so listings sort chronologically and
+ * concurrent comments can never collide.
+ */
+import { isId } from "./id.js";
+import { fromCompactStamp, toCompactStamp } from "./time.js";
+export const COMMENT_NAME_PATTERN = /^(\d{4}-\d{2}-\d{2}T\d{6}Z)-([a-z][a-z0-9]{7})\.md$/;
+/** Build the filename for a comment created at `date` with identifier `id`. */
+export function commentFileName(date, id) {
+    return `${toCompactStamp(date)}-${id}.md`;
+}
+/** Parse a comment filename, or return null when it violates the grammar. */
+export function parseCommentFileName(name) {
+    const match = COMMENT_NAME_PATTERN.exec(name);
+    if (!match)
+        return null;
+    const stamp = match[1];
+    const id = match[2];
+    if (!isId(id))
+        return null;
+    const date = fromCompactStamp(stamp);
+    if (!date)
+        return null;
+    return { stamp, date, id };
+}
+/**
+ * Order comments for display: chronologically by filename, with replies placed
+ * directly under the comment they answer and indented by one level.
+ *
+ * Replies to unknown comments, and reply cycles, degrade to top level rather
+ * than disappearing.
+ */
+export function threadOrder(comments) {
+    const sorted = [...comments].sort((a, b) => a.fileName < b.fileName ? -1 : a.fileName > b.fileName ? 1 : 0);
+    const byId = new Map(sorted.map((c) => [c.id, c]));
+    const children = new Map();
+    const roots = [];
+    for (const comment of sorted) {
+        const parent = comment.replyTo ? byId.get(comment.replyTo) : undefined;
+        if (!parent || parent.id === comment.id || createsCycle(comment, byId)) {
+            roots.push(comment);
+            continue;
+        }
+        const bucket = children.get(parent.id);
+        if (bucket)
+            bucket.push(comment);
+        else
+            children.set(parent.id, [comment]);
+    }
+    const out = [];
+    // Guard on identity, not id: duplicate ids are a doctor error (D3), and
+    // until they are fixed the thread must still show each file exactly once.
+    const emitted = new Set();
+    const walk = (comment, depth) => {
+        if (emitted.has(comment))
+            return;
+        emitted.add(comment);
+        out.push({ comment, depth });
+        for (const child of children.get(comment.id) ?? [])
+            walk(child, depth + 1);
+    };
+    for (const root of roots)
+        walk(root, 0);
+    for (const comment of sorted)
+        walk(comment, 0);
+    return out;
+}
+function createsCycle(start, byId) {
+    const seen = new Set([start.id]);
+    let current = start.replyTo ? byId.get(start.replyTo) : undefined;
+    while (current) {
+        if (seen.has(current.id))
+            return true;
+        seen.add(current.id);
+        current = current.replyTo ? byId.get(current.replyTo) : undefined;
+    }
+    return false;
+}
+//# sourceMappingURL=comments.js.map

package/dist/core/comments.js.map

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

package/dist/core/files.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The three Navbook file kinds — spec 02 §2.5 (`issue.md`), §2.6 (comments and
+ * reviews) and §2.7 (`pr.md`): parsing, validation, and construction.
+ *
+ * Parsing never throws on schema problems; it collects them so `nav doctor` can
+ * report every fault in a file at once.
+ *
+ * Frontmatter is normalized once, at parse time: keys whose spec type is a
+ * string (or a list/map of strings) are read from the scalar's source text, so
+ * a hand-written all-digit commit SHA — which YAML would resolve to a lossy
+ * number — still round-trips as the forty characters the author typed.
+ */
+import { type NavDoc } from "./frontmatter.ts";
+export declare const SHA_PATTERN: RegExp;
+export declare const VERDICTS: readonly ["approve", "request-changes"];
+export type Verdict = (typeof VERDICTS)[number];
+export interface Problem {
+    key?: string;
+    message: string;
+}
+export interface ParsedFile {
+    nav: NavDoc;
+    /** Frontmatter with spec-typed keys normalized; unknown keys passed through. */
+    fm: Record<string, unknown>;
+    /** Frontmatter exactly as the YAML parser resolved it. */
+    raw: Record<string, unknown>;
+    body: string;
+    problems: Problem[];
+}
+export interface Revision {
+    head: string;
+    base: string;
+    date: string;
+}
+/** Parse any Navbook file; frontmatter faults surface as problems, not throws. */
+export declare function parseFile(text: string): ParsedFile;
+/** Coerce spec-typed frontmatter keys; leave unknown keys exactly as parsed. */
+export declare function normalizeFrontmatter(nav: NavDoc, parsed?: Record<string, unknown>): Record<string, unknown>;
+/** Read `labels` defensively, ignoring malformed entries. */
+export declare function readLabels(fm: Record<string, unknown>): string[];
+/** Read `assignee` (scalar or list) defensively. */
+export declare function readAssignees(fm: Record<string, unknown>): string[];
+/** Read `revisions` defensively, keeping only well-formed entries. */
+export declare function readRevisions(fm: Record<string, unknown>): Revision[];
+/** Read the `merged:` block defensively. */
+export declare function readMerged(fm: Record<string, unknown>): Record<string, unknown> | null;
+/** Validate an `issue.md` (§2.5). */
+export declare function validateIssue(parsed: ParsedFile): Problem[];
+/** Validate a `pr.md` (§2.7). */
+export declare function validatePr(parsed: ParsedFile): Problem[];
+/** Validate a comment file (§2.6), including the optional review fields. */
+export declare function validateComment(parsed: ParsedFile, opts: {
+    onPr: boolean;
+}): Problem[];
+export interface NewIssueInput {
+    title: string;
+    author: string;
+    created: string;
+    body: string;
+    labels?: string[];
+    assignee?: string[];
+    milestone?: string;
+}
+/** Render a new `issue.md`. */
+export declare function newIssueFile(input: NewIssueInput): string;
+export interface NewPrInput extends NewIssueInput {
+    target: string;
+    source: string;
+    revisions: Revision[];
+    draft?: boolean;
+}
+/** Render a new `pr.md`. */
+export declare function newPrFile(input: NewPrInput): string;
+export interface NewCommentInput {
+    author: string;
+    body: string;
+    replyTo?: string;
+    verdict?: Verdict;
+    revision?: string;
+    file?: string;
+    line?: string;
+}
+/** Render a new comment or review file. */
+export declare function newCommentFile(input: NewCommentInput): string;
+/** Trim trailing whitespace and guarantee exactly one closing newline. */
+export declare function normalizeBody(body: string): string;
+/** Format a person for frontmatter, falling back to the bare address. */
+export declare function formatAuthor(name: string | undefined, email: string): string;