@jitsusama/agentic-harness.core 0.1.0

package/dist/thinking/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How hard pi may be asked to think.
+ *
+ * Its own module for the reason `exec` and `remote` are: both the
+ * review side and the subagent side need this vocabulary and neither
+ * owns it. It is pi's, and everything here does is write it down once.
+ *
+ * It had been written down four times, in two domains that share no
+ * module: the roster parser that validates one, the two tool schemas
+ * that offer one, and the runner type that receives one. Four copies
+ * of a list nothing compares is a list that will disagree with itself,
+ * and the failure is quiet: a level one copy accepts and pi does not
+ * reaches the CLI, and the reviewer runs at whatever pi makes of it.
+ */
+/** The levels pi's `--thinking` flag accepts, in order of effort. */
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh"];
+/** One of the levels pi's `--thinking` flag accepts. */
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** Whether some string is a level pi would accept. */
+export declare function isThinkingLevel(value: string): value is ThinkingLevel;

package/dist/thinking/index.js

@@ -0,0 +1,27 @@
+/**
+ * How hard pi may be asked to think.
+ *
+ * Its own module for the reason `exec` and `remote` are: both the
+ * review side and the subagent side need this vocabulary and neither
+ * owns it. It is pi's, and everything here does is write it down once.
+ *
+ * It had been written down four times, in two domains that share no
+ * module: the roster parser that validates one, the two tool schemas
+ * that offer one, and the runner type that receives one. Four copies
+ * of a list nothing compares is a list that will disagree with itself,
+ * and the failure is quiet: a level one copy accepts and pi does not
+ * reaches the CLI, and the reviewer runs at whatever pi makes of it.
+ */
+/** The levels pi's `--thinking` flag accepts, in order of effort. */
+export const THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+];
+/** Whether some string is a level pi would accept. */
+export function isThinkingLevel(value) {
+    return THINKING_LEVELS.some((level) => level === value);
+}

package/dist/title/block.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Turns detected title violations into a single skill-grounded
+ * instruction the guardian hands back to the author. It names the
+ * offending prefix and points at the format skill so the retry is
+ * a descriptive rewrite, not a guess.
+ */
+import type { TitleViolation } from "./detect.js";
+/** Format title violations into a block message, or "" if none. */
+export declare function formatTitleBlock(violations: TitleViolation[], entityLabel: string, skill: string): string;

package/dist/title/block.js

@@ -0,0 +1,32 @@
+/**
+ * Turns detected title violations into a single skill-grounded
+ * instruction the guardian hands back to the author. It names the
+ * offending prefix and points at the format skill so the retry is
+ * a descriptive rewrite, not a guess.
+ */
+/** Format title violations into a block message, or "" if none. */
+export function formatTitleBlock(violations, entityLabel, skill) {
+    if (violations.length === 0)
+        return "";
+    const lines = [
+        `This ${entityLabel} title breaks the ${skill} title convention.`,
+        "Fix it and try again.",
+        "",
+    ];
+    const prefixes = violations
+        .filter((v) => v.issue === "conventional-commit")
+        .map((v) => v.found);
+    if (prefixes.length > 0) {
+        lines.push(`Conventional commit format (${prefixes.join(", ")}) is forbidden`, "for titles. Use a descriptive Title Case title that names the", "value, not the implementation, and drop the type prefix. For", 'example "Add Token Refresh to Prevent Session Timeouts" rather', 'than "feat(auth): implement refresh token logic".', "");
+    }
+    const sentenceCase = violations.find((v) => v.issue === "sentence-case");
+    if (sentenceCase) {
+        lines.push("The title reads as a sentence, not Title Case. These major", `words are lowercase: ${sentenceCase.found}. Capitalize every`, "noun, verb, adjective, adverb and pronoun; leave only articles,", "short prepositions and coordinating conjunctions lowercase. A", "deliberately lowercase proper noun (gitstream, gsperf) can stay", "lowercase; it is the run of ordinary words that needs fixing.", "");
+    }
+    const tooLong = violations.find((v) => v.issue === "over-length");
+    if (tooLong) {
+        lines.push(`The title is ${tooLong.found.replace(" (limit ", ", over the limit of ").replace(")", "")}.`, "Trim it to a tight Title Case summary. The lower bound the skill", "suggests (50 characters) is guidance; the upper bound is", "enforced because longer titles truncate in GitHub views and read", "badly in logs.", "");
+    }
+    lines.push(`See the ${skill} and github-cli-convention skills for the title`, "rules (Title Case, length, the formula).");
+    return lines.join("\n");
+}

package/dist/title/detect.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Title convention detection: finds the mechanically certain
+ * violations of the PR and issue title convention so a guardian
+ * can block and point the author at the skill. Detection never
+ * rewrites; it names what is wrong and leaves the descriptive
+ * rephrasing to the author.
+ */
+import type { Violation } from "../gate/index.js";
+/** A single title convention violation. */
+export interface TitleViolation extends Violation {
+    readonly kind: "title";
+    /**
+     * conventional-commit: the title uses `type(scope): ...` form.
+     * over-length: the title exceeds the upper-bound character limit.
+     * sentence-case: the title reads as a sentence, not Title Case.
+     */
+    readonly issue: "conventional-commit" | "over-length" | "sentence-case";
+    /**
+     * The offending prefix (conventional-commit) or a description of
+     * the length and the limit (over-length).
+     */
+    readonly found: string;
+}
+/** Find the mechanically certain title convention violations. */
+export declare function detectTitleViolations(title: string): TitleViolation[];

package/dist/title/detect.js

@@ -0,0 +1,154 @@
+/**
+ * Title convention detection: finds the mechanically certain
+ * violations of the PR and issue title convention so a guardian
+ * can block and point the author at the skill. Detection never
+ * rewrites; it names what is wrong and leaves the descriptive
+ * rephrasing to the author.
+ */
+/**
+ * The upper bound the gate enforces on title length. The skills
+ * state a 50 to 72 range; the gate enforces the upper bound only
+ * because the lower bound is guidance (short descriptive titles
+ * like "Add Dark Mode Toggle" are fine, and the cli convention's
+ * own good example is 40 characters). 72 is the hard cap: past it
+ * the title truncates in GitHub views and reads badly in logs.
+ */
+const MAX_TITLE_LENGTH = 72;
+// The conventional-commit type words. A title that opens with one
+// of these followed by an optional `(scope)`, an optional `!` and
+// a colon is conventional-commit format, which the title
+// convention forbids. Anchoring on the known type list keeps the
+// match precise: a descriptive title with a non-type colon prefix
+// (`Gitstream: ...`) never matches, because the word before the
+// colon is not a type.
+const CONVENTIONAL_COMMIT_TYPES = [
+    "feat",
+    "fix",
+    "chore",
+    "docs",
+    "refactor",
+    "perf",
+    "test",
+    "build",
+    "ci",
+    "style",
+    "revert",
+    "wip",
+    "merge",
+    "release",
+    "bump",
+    "deps",
+    "hotfix",
+];
+// `type` then optional `(scope)`, optional `!`, then `:`. Matched
+// case-insensitively so `Fix:` and `FEAT:` are caught too.
+const CONVENTIONAL_COMMIT = new RegExp(`^(?:${CONVENTIONAL_COMMIT_TYPES.join("|")})(?:\\([^)]*\\))?!?:`, "i");
+// The minor words Title Case leaves lowercase unless they open or
+// close the title: articles, the short prepositions and the
+// coordinating conjunctions the markdown-standard skill names.
+// They are neither a capitalized nor a lowercase major word, so
+// they sit out the sentence-case count entirely.
+const MINOR_WORDS = new Set([
+    "a",
+    "an",
+    "the",
+    "of",
+    "in",
+    "on",
+    "at",
+    "to",
+    "for",
+    "with",
+    "by",
+    "from",
+    "as",
+    "and",
+    "or",
+    "but",
+    "nor",
+    "so",
+    "yet",
+]);
+// True when a word carries a backtick, dot or slash. Those mark
+// the tokens the convention keeps verbatim: backticked code and
+// dotted or slashed identifiers (vantage.Prepare, site/host).
+// This inspects punctuation only. Mixed-case tokens (iOS,
+// CamelCase, V1) are handled by the case loop below, which reads
+// their inner capital and leaves them out of the lowercase count.
+function isVerbatimToken(word) {
+    return /[`./]/.test(word);
+}
+/** Find the mechanically certain title convention violations. */
+export function detectTitleViolations(title) {
+    const trimmed = title.trim();
+    const violations = [];
+    const match = trimmed.match(CONVENTIONAL_COMMIT);
+    if (match) {
+        violations.push({
+            kind: "title",
+            issue: "conventional-commit",
+            found: match[0],
+        });
+    }
+    if (trimmed.length > MAX_TITLE_LENGTH) {
+        violations.push({
+            kind: "title",
+            issue: "over-length",
+            found: `${trimmed.length} characters (limit ${MAX_TITLE_LENGTH})`,
+        });
+    }
+    const sentenceCase = detectSentenceCase(trimmed);
+    if (sentenceCase)
+        violations.push(sentenceCase);
+    return violations;
+}
+/**
+ * Flag a title that reads as a sentence rather than Title Case.
+ *
+ * Detection is precision-over-recall: it counts the major words
+ * (everything that is not a minor word or a verbatim token) and
+ * splits them into capitalized and lowercase. A title is only
+ * flagged when its lowercase major words number at least two and
+ * outnumber the capitalized ones, the unambiguous signal of
+ * sentence case. A mostly-Title-Case title that carries one or
+ * two deliberately lowercase proper nouns (gitstream, gsperf)
+ * never trips, because those never outnumber the capitalized
+ * words around them.
+ */
+function detectSentenceCase(title) {
+    let capitalized = 0;
+    const lowercase = [];
+    for (const raw of title.split(/\s+/)) {
+        // Strip surrounding punctuation (quotes, parens, a trailing
+        // colon) but keep internal dots, slashes and hyphens.
+        const word = raw.replace(/^[^\p{L}\p{N}`]+|[^\p{L}\p{N}`]+$/gu, "");
+        if (!word)
+            continue;
+        if (!/\p{L}/u.test(word))
+            continue; // pure number or symbol
+        if (MINOR_WORDS.has(word.toLowerCase()))
+            continue;
+        if (isVerbatimToken(word))
+            continue;
+        const firstLetter = word.match(/\p{L}/u)?.[0] ?? "";
+        const startsUpper = firstLetter === firstLetter.toUpperCase();
+        const hasUpper = /\p{Lu}/u.test(word);
+        if (startsUpper) {
+            capitalized++;
+        }
+        else if (!hasUpper) {
+            // Lowercase first letter and no inner capital: a plain
+            // lowercase word. A mixed-case token (iOS) has an inner
+            // capital and is left verbatim.
+            lowercase.push(word);
+        }
+    }
+    if (lowercase.length >= 2 && lowercase.length > capitalized) {
+        return {
+            kind: "title",
+            issue: "sentence-case",
+            found: lowercase.join(", "),
+        };
+    }
+    return undefined;
+}

package/dist/title/gate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The title gate: a thin adapter over the shared loop breaker in
+ * the gate module. It supplies the title-specific detection, block
+ * formatting and relent wording; the block-first,
+ * relent-on-repeat mechanism lives in decideGate so titles share
+ * one behaviour with prose, sections and Slack.
+ */
+import { type GateDecision } from "../gate/index.js";
+/** What the gate needs to know about the artifact under review. */
+export interface TitleGateConfig {
+    /** "PR" or "issue", for the block message. */
+    readonly entityLabel: string;
+    /** The format skill that owns the title rules, for the message. */
+    readonly skill: string;
+}
+/** The gate's verdict on one title. */
+export type TitleGateDecision = GateDecision;
+/** Decide whether to block, relent or allow given prior block signatures. */
+export declare function titleGateDecision(title: string, priorSignatures: string[], config: TitleGateConfig): TitleGateDecision;

package/dist/title/gate.js

@@ -0,0 +1,21 @@
+/**
+ * The title gate: a thin adapter over the shared loop breaker in
+ * the gate module. It supplies the title-specific detection, block
+ * formatting and relent wording; the block-first,
+ * relent-on-repeat mechanism lives in decideGate so titles share
+ * one behaviour with prose, sections and Slack.
+ */
+import { decideGate } from "../gate/index.js";
+import { formatTitleBlock } from "./block.js";
+import { detectTitleViolations } from "./detect.js";
+/** Decide whether to block, relent or allow given prior block signatures. */
+export function titleGateDecision(title, priorSignatures, config) {
+    const violations = detectTitleViolations(title);
+    const relentPrefix = [
+        `This ${config.entityLabel} title still breaks the ${config.skill}`,
+        "title convention after a previous attempt, so it is being let",
+        "through rather than blocked again. Review it yourself:",
+        "",
+    ].join("\n");
+    return decideGate(violations, priorSignatures, (v) => formatTitleBlock(v, config.entityLabel, config.skill), relentPrefix, title);
+}

package/dist/title/index.d.ts

@@ -0,0 +1,3 @@
+export { formatTitleBlock } from "./block.js";
+export { detectTitleViolations, type TitleViolation } from "./detect.js";
+export { type TitleGateConfig, type TitleGateDecision, titleGateDecision, } from "./gate.js";

package/dist/title/index.js

@@ -0,0 +1,3 @@
+export { formatTitleBlock } from "./block.js";
+export { detectTitleViolations } from "./detect.js";
+export { titleGateDecision, } from "./gate.js";

package/dist/tree/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Public surface of the tree library.
+ *
+ * Pluggable working-directory providers. The harness ships
+ * a `git-worktree` provider that lives at
+ * `<repo>/.worktrees/<name>/`; downstream packages
+ * register their own at lower priority numbers to take
+ * over for specific repos.
+ *
+ * Typical use: `quest-workflow` calls
+ * `resolveTreeProvider(repoRoot)` to pick a provider, then
+ * dispatches `create` or `prune` against it. Consumers
+ * outside this package register their own providers via
+ * `registerTreeProvider`.
+ */
+export { clearTreeProviders, registerBuiltinTreeProviders, registerTreeProvider, unregisterTreeProvider, } from "./register.js";
+export { getTreeProvider, listTreeProviders, resolveTreeProvider, } from "./resolve.js";
+export type { CreateTreeInput, PruneTreeInput, TreeHandle, TreeProvider, } from "./types.js";

package/dist/tree/index.js

@@ -0,0 +1,17 @@
+/**
+ * Public surface of the tree library.
+ *
+ * Pluggable working-directory providers. The harness ships
+ * a `git-worktree` provider that lives at
+ * `<repo>/.worktrees/<name>/`; downstream packages
+ * register their own at lower priority numbers to take
+ * over for specific repos.
+ *
+ * Typical use: `quest-workflow` calls
+ * `resolveTreeProvider(repoRoot)` to pick a provider, then
+ * dispatches `create` or `prune` against it. Consumers
+ * outside this package register their own providers via
+ * `registerTreeProvider`.
+ */
+export { clearTreeProviders, registerBuiltinTreeProviders, registerTreeProvider, unregisterTreeProvider, } from "./register.js";
+export { getTreeProvider, listTreeProviders, resolveTreeProvider, } from "./resolve.js";

package/dist/tree/register.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Tree provider registration. Mirrors the refs and terminal
+ * libraries: explicit registration for built-ins, free
+ * functions for ad-hoc providers, an opt-out clear for
+ * tests.
+ */
+import type { TreeProvider } from "./types.js";
+/**
+ * Register a tree provider. Overwrites any previously
+ * registered provider with the same id.
+ */
+export declare function registerTreeProvider(provider: TreeProvider): void;
+/** Remove a provider from the registry. Idempotent. */
+export declare function unregisterTreeProvider(id: string): void;
+/**
+ * Seed the registry with the built-in providers. Currently
+ * one entry: `git-worktree` at priority 100. Idempotent.
+ */
+export declare function registerBuiltinTreeProviders(): void;
+/** Empty the registry. Intended for tests. */
+export declare function clearTreeProviders(): void;

package/dist/tree/register.js

@@ -0,0 +1,31 @@
+/**
+ * Tree provider registration. Mirrors the refs and terminal
+ * libraries: explicit registration for built-ins, free
+ * functions for ad-hoc providers, an opt-out clear for
+ * tests.
+ */
+import { BUILTIN_TREE_PROVIDERS } from "../internal/tree/builtins.js";
+import { clear, register, unregister } from "../internal/tree/registry.js";
+/**
+ * Register a tree provider. Overwrites any previously
+ * registered provider with the same id.
+ */
+export function registerTreeProvider(provider) {
+    register(provider);
+}
+/** Remove a provider from the registry. Idempotent. */
+export function unregisterTreeProvider(id) {
+    unregister(id);
+}
+/**
+ * Seed the registry with the built-in providers. Currently
+ * one entry: `git-worktree` at priority 100. Idempotent.
+ */
+export function registerBuiltinTreeProviders() {
+    for (const provider of BUILTIN_TREE_PROVIDERS)
+        register(provider);
+}
+/** Empty the registry. Intended for tests. */
+export function clearTreeProviders() {
+    clear();
+}

package/dist/tree/resolve.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Provider resolution: pick the active tree provider for a
+ * given repo root.
+ *
+ * Resolution order: every registered provider, sorted by
+ * `priority` ascending (smaller numbers first); the first
+ * whose `appliesTo(repoRoot)` returns true wins. Built-ins
+ * live at 100; downstream packages use lower numbers to
+ * take over.
+ */
+import type { TreeProvider } from "./types.js";
+/** Look up a provider by id, or `undefined`. */
+export declare function getTreeProvider(id: string): TreeProvider | undefined;
+/** Snapshot of every registered provider. */
+export declare function listTreeProviders(): TreeProvider[];
+/**
+ * Resolve the tree provider for a repo root. Returns
+ * `undefined` when no registered provider applies.
+ */
+export declare function resolveTreeProvider(repoRoot: string): TreeProvider | undefined;

package/dist/tree/resolve.js

@@ -0,0 +1,31 @@
+/**
+ * Provider resolution: pick the active tree provider for a
+ * given repo root.
+ *
+ * Resolution order: every registered provider, sorted by
+ * `priority` ascending (smaller numbers first); the first
+ * whose `appliesTo(repoRoot)` returns true wins. Built-ins
+ * live at 100; downstream packages use lower numbers to
+ * take over.
+ */
+import { get, list } from "../internal/tree/registry.js";
+/** Look up a provider by id, or `undefined`. */
+export function getTreeProvider(id) {
+    return get(id);
+}
+/** Snapshot of every registered provider. */
+export function listTreeProviders() {
+    return list();
+}
+/**
+ * Resolve the tree provider for a repo root. Returns
+ * `undefined` when no registered provider applies.
+ */
+export function resolveTreeProvider(repoRoot) {
+    const ranked = [...list()].sort((a, b) => a.priority - b.priority);
+    for (const provider of ranked) {
+        if (provider.appliesTo(repoRoot))
+            return provider;
+    }
+    return undefined;
+}

package/dist/tree/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Public types for the tree library.
+ *
+ * A `TreeProvider` knows how to create and prune a working
+ * directory for a stream of code-bearing work. Pluggable
+ * per repo root: the built-in `git-worktree` provider
+ * handles ordinary git repos at
+ * `<repo>/.worktrees/<name>/`; downstream packages
+ * register higher-priority providers for the repos they
+ * specialise in.
+ */
+/** Where the tree lives on disk and what's checked out. */
+export interface TreeHandle {
+    /** Absolute path to the tree's working directory. */
+    path: string;
+    /** Branch name checked out at `path`, when known. */
+    branch?: string;
+    /** Origin repo's root, when the provider knows it. */
+    repoRoot?: string;
+    /**
+     * Id of the provider that created the tree. Lets the
+     * prune side pick the right provider back up even if
+     * the active provider changed between create and
+     * prune.
+     */
+    providerId: string;
+}
+/** Input for `TreeProvider.create`. */
+export interface CreateTreeInput {
+    /** Suggested branch/tree name (slug-like). */
+    name: string;
+    /** Repo root the tree should branch off. */
+    repoRoot: string;
+    /**
+     * Base branch to branch from. Defaults to the repo's
+     * default branch when omitted.
+     */
+    baseBranch?: string;
+}
+/** Input for `TreeProvider.prune`. */
+export interface PruneTreeInput {
+    /** Absolute path to the tree to prune. */
+    path: string;
+    /**
+     * When true, ignore safety checks (dirty working
+     * directory, unmerged branch) and delete anyway. A
+     * higher-level safety gate forwards the caller's
+     * resolution answer through this flag.
+     */
+    force?: boolean;
+}
+/** A pluggable working-directory provider. */
+export interface TreeProvider {
+    /** Stable identifier (e.g. "git-worktree", "dev-tree"). */
+    id: string;
+    /**
+     * Resolution priority. Lower numbers run first; the
+     * first provider whose `appliesTo(repoRoot)` returns
+     * true wins. Built-ins live at 100; downstream
+     * specialisations use smaller numbers to take over.
+     */
+    priority: number;
+    /**
+     * Returns true when this provider handles the given
+     * repo root. Cheap and synchronous; do filesystem
+     * checks only when they're trivial.
+     */
+    appliesTo(repoRoot: string): boolean;
+    /** Create a tree. Returns the handle to persist. */
+    create(input: CreateTreeInput): Promise<TreeHandle>;
+    /**
+     * Prune a tree. Providers throw on safety conflicts
+     * (dirty state, unmerged branch) unless `force` is
+     * true.
+     */
+    prune(input: PruneTreeInput): Promise<void>;
+    /**
+     * Optional: list trees the provider knows about under
+     * a given repo root. Helpful for reconciling
+     * frontmatter against on-disk state.
+     */
+    list?(repoRoot: string): Promise<TreeHandle[]>;
+}

package/dist/tree/types.js

@@ -0,0 +1,12 @@
+/**
+ * Public types for the tree library.
+ *
+ * A `TreeProvider` knows how to create and prune a working
+ * directory for a stream of code-bearing work. Pluggable
+ * per repo root: the built-in `git-worktree` provider
+ * handles ordinary git repos at
+ * `<repo>/.worktrees/<name>/`; downstream packages
+ * register higher-priority providers for the repos they
+ * specialise in.
+ */
+export {};

package/dist/ui/count.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Writing a count the way a person would say it.
+ *
+ * The alternative writes itself and reads badly: `${n} tree(s)` is correct for every
+ * n and natural for none, and the single-item case is the common one, so the tell
+ * shows constantly. One surface here had a private helper for this and the other two
+ * spelled `(s)` inline in fifty places, which meant a session could show `1 branch`
+ * and `1 tree(s)` a line apart.
+ */
+/**
+ * A number and its noun, pluralized.
+ *
+ * Pass `plural` for a noun that does not simply take an s: `count(2, "entry",
+ * "entries")`. Zero takes the plural, as English does: nought trees, not nought tree.
+ */
+export declare function count(n: number, singular: string, plural?: string): string;
+/**
+ * Just the noun, for a sentence that has already said the number or does not want
+ * to. `${found.length} in ${noun(found.length, "tree")}` reads oddly; `Found 3, in 2
+ * trees` does not.
+ */
+export declare function noun(n: number, singular: string, plural?: string): string;
+/**
+ * The verb to agree with a count: `is` for one, `are` otherwise.
+ *
+ * Here because a sentence built around a count usually needs it, and a caller
+ * reaching for a ternary at the call site is how `1 trees are` happens.
+ */
+export declare function verb(n: number, singular: string, plural: string): string;

package/dist/ui/count.js

@@ -0,0 +1,35 @@
+/**
+ * Writing a count the way a person would say it.
+ *
+ * The alternative writes itself and reads badly: `${n} tree(s)` is correct for every
+ * n and natural for none, and the single-item case is the common one, so the tell
+ * shows constantly. One surface here had a private helper for this and the other two
+ * spelled `(s)` inline in fifty places, which meant a session could show `1 branch`
+ * and `1 tree(s)` a line apart.
+ */
+/**
+ * A number and its noun, pluralized.
+ *
+ * Pass `plural` for a noun that does not simply take an s: `count(2, "entry",
+ * "entries")`. Zero takes the plural, as English does: nought trees, not nought tree.
+ */
+export function count(n, singular, plural) {
+    return `${n} ${noun(n, singular, plural)}`;
+}
+/**
+ * Just the noun, for a sentence that has already said the number or does not want
+ * to. `${found.length} in ${noun(found.length, "tree")}` reads oddly; `Found 3, in 2
+ * trees` does not.
+ */
+export function noun(n, singular, plural) {
+    return n === 1 ? singular : (plural ?? `${singular}s`);
+}
+/**
+ * The verb to agree with a count: `is` for one, `are` otherwise.
+ *
+ * Here because a sentence built around a count usually needs it, and a caller
+ * reaching for a ternary at the call site is how `1 trees are` happens.
+ */
+export function verb(n, singular, plural) {
+    return n === 1 ? singular : plural;
+}

package/dist/ui/path.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Writing a path the way a person would say it.
+ *
+ * Absolute paths under a home directory carry a prefix that is the same on every
+ * line and tells the reader nothing. A tree listing is the worst case: two lines
+ * where the interesting halves are a key and a provider, and the widest thing on
+ * screen is a directory nobody has to type.
+ */
+/**
+ * A path with the home directory written as `~`.
+ *
+ * **For display only.** The result is not a path any tool can open: `~` is a
+ * shell courtesy, not a filesystem entry, and expanding it is the shell's job.
+ * So this belongs in the text a person reads and never in the `details` of a
+ * tool answer, where a caller may reasonably feed a path straight back into
+ * another call. When both are wanted, abbreviate the view and keep the absolute
+ * path in the details.
+ *
+ * Rewrites a leading home prefix and nothing else. A relative path is returned
+ * as it came, which is what makes this safe to apply to a list that mixes the
+ * two: a repo-relative `lib/work/tree.ts` has no prefix to lose. A path that
+ * merely mentions the home directory somewhere in the middle is also left alone,
+ * since only the prefix is a home directory rather than a coincidence.
+ */
+export declare function displayPath(path: string, home?: string): string;