grounder 0.4.0 → 0.6.0

package/dist/commands/overview.js

@@ -0,0 +1,150 @@
+import { withHomeDir } from "../connector/home.js";
+import { resolveLogsDir, resolveNotesDir, resolvePlansDir } from "../connector/vault.js";
+import { helpExitCode } from "../help.js";
+import { flagBool, parseArgs } from "../util/parse-args.js";
+import { toFileUri, vaultRelativePath } from "../util/path.js";
+import { listHandoffsDetailed } from "../vault/list-handoffs.js";
+import { listNotesDetailed } from "../vault/list-notes.js";
+import { listPlansDetailed } from "../vault/list-plans.js";
+import { writeSection, writeVaultItemListEntries } from "./output.js";
+import { requireLinkedProject } from "./require-linked.js";
+const DEFAULT_LIMIT = 3;
+const USAGE = "Usage: grounder overview [--limit <n>] [--markdown] [--json]\n";
+function usageError() {
+    process.stderr.write(USAGE);
+    return 1;
+}
+/**
+ * CLI entry for `grounder overview [--limit <n>] [--markdown] [--json]`.
+ * `--limit` must be a positive integer when provided.
+ * @returns Exit code (`0` on success, `1` on usage or config errors).
+ */
+export async function runOverview(argv) {
+    const helpCode = helpExitCode(argv, "overview");
+    if (helpCode !== null) {
+        return helpCode;
+    }
+    const { positional, flags } = parseArgs(argv);
+    if (positional.length > 0) {
+        return usageError();
+    }
+    for (const key of flags.keys()) {
+        if (key !== "limit" && key !== "markdown" && key !== "json") {
+            return usageError();
+        }
+    }
+    const markdown = flagBool(flags, "markdown");
+    const json = flagBool(flags, "json");
+    if (markdown && json) {
+        process.stderr.write("Use only one of --markdown or --json.\n");
+        return 1;
+    }
+    const limitRaw = flags.get("limit");
+    let limit = DEFAULT_LIMIT;
+    if (limitRaw !== undefined) {
+        if (typeof limitRaw !== "string") {
+            return usageError();
+        }
+        const trimmed = limitRaw.trim();
+        const parsed = Number.parseInt(trimmed, 10);
+        if (!/^\d+$/.test(trimmed) || Number.isNaN(parsed) || parsed < 1) {
+            return usageError();
+        }
+        limit = parsed;
+    }
+    return runOverviewWithOptions({ limit, markdown, json });
+}
+/**
+ * Lists a bucket uncapped (each lister already builds this full sorted array
+ * internally before slicing, so this costs no extra traversal) and slices
+ * locally — giving `--json` an honest `total` instead of reporting the
+ * shown-count twice under different names.
+ */
+async function gatherBucket(dir, noun, title, limit, lister) {
+    const all = await lister(dir);
+    return { dir, noun, title, all, shown: all.slice(0, limit) };
+}
+function jsonBucket(bucket) {
+    return {
+        total: bucket.all.length,
+        count: bucket.shown.length,
+        truncated: bucket.all.length > bucket.shown.length,
+        items: bucket.shown.map((entry) => ({
+            path: entry.path,
+            relativePath: vaultRelativePath(bucket.dir, entry.path),
+            fileUri: toFileUri(entry.path),
+            mtimeMs: entry.mtimeMs,
+        })),
+    };
+}
+/**
+ * Header line for one bucket's text/markdown section. Unlike the shared
+ * `note`/`handoff`/`plan list` header (`writeVaultItemList`'s
+ * `count === limit` → "there may be more" guess), overview already has the
+ * true total for free (see {@link gatherBucket}), so it reports an exact
+ * "N of M" instead of a maybe — the `--markdown` skill path relays this
+ * straight to the agent, where an honest count matters more than terseness.
+ */
+function bucketHeader(bucket) {
+    const total = bucket.all.length;
+    const shown = bucket.shown.length;
+    if (total === 0) {
+        return `No ${bucket.noun.plural}.\n`;
+    }
+    if (shown === total) {
+        const label = total === 1 ? bucket.noun.singular : bucket.noun.plural;
+        return `All ${total} ${label}:\n\n`;
+    }
+    return `Most recent ${shown} of ${total} ${bucket.noun.plural}:\n\n`;
+}
+function writeTextOutput(buckets, markdown) {
+    buckets.forEach((bucket, index) => {
+        if (index > 0) {
+            process.stdout.write("\n");
+        }
+        writeSection(bucket.title);
+        process.stdout.write(bucketHeader(bucket));
+        writeVaultItemListEntries(bucket.shown.map((entry) => entry.path), { markdown, titleRootDir: bucket.dir });
+    });
+}
+function writeJsonOutput(buckets) {
+    const payload = {};
+    for (const bucket of buckets) {
+        payload[bucket.noun.plural] = jsonBucket(bucket);
+    }
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+/**
+ * Resolves the linked project, gathers a per-bucket count + capped recent
+ * titles across `notes/`, `logs/` (handoffs), and `plans/` — the same
+ * newest-first listings `note/handoff/plan list` use, in one call. `--json`
+ * items also include `mtimeMs` (the same on-disk mtime each lister already
+ * fetches to rank entries; see `listNotesDetailed` / `listHandoffsDetailed` /
+ * `listPlansDetailed`). Text and markdown stay title + path only.
+ * @returns Exit code (`0` on success, `1` when vault/link is missing).
+ */
+export async function runOverviewWithOptions(options = {}) {
+    return withHomeDir(options.homeDir, async () => {
+        const linked = await requireLinkedProject(options.cwd ?? process.cwd());
+        if (!linked) {
+            return 1;
+        }
+        const limit = options.limit ?? DEFAULT_LIMIT;
+        const notesDir = resolveNotesDir(linked.home, linked.repo);
+        const logsDir = resolveLogsDir(linked.home, linked.repo);
+        const plansDir = resolvePlansDir(linked.home, linked.repo);
+        const buckets = await Promise.all([
+            gatherBucket(notesDir, { singular: "note", plural: "notes" }, "Notes", limit, listNotesDetailed),
+            gatherBucket(logsDir, { singular: "handoff", plural: "handoffs" }, "Handoffs", limit, listHandoffsDetailed),
+            gatherBucket(plansDir, { singular: "plan", plural: "plans" }, "Plans", limit, listPlansDetailed),
+        ]);
+        if (options.json) {
+            writeJsonOutput(buckets);
+        }
+        else {
+            writeTextOutput(buckets, options.markdown === true);
+        }
+        return 0;
+    });
+}
+//# sourceMappingURL=overview.js.map

package/dist/commands/overview.js.map

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

package/dist/commands/plan/list.d.ts

@@ -4,27 +4,35 @@ export interface PlanListOptions {
     cwd?: string;
     /** Max plans to print, newest first (default: 5). */
     limit?: number;
+    /**
+     * Agent relay: `[bucketRelativePath](fileUri)` on the title line (default:
+     * plain bucket-relative stem path). Absolute path stays indented beneath
+     * either way.
+     */
+    markdown?: boolean;
     /** Override home dir / `GROUNDER_HOME` (tests). */
     homeDir?: string;
 }
 /**
- * CLI entry for `grounder plan list [--limit <n>]`.
+ * CLI entry for `grounder plan list [--limit <n>] [--markdown]`.
  * `--limit` must be a positive integer when provided.
  * @returns Exit code (`0` on success, `1` on usage or config errors).
  */
 export declare function runPlanList(argv: string[]): Promise<number>;
 /**
- * Resolves the linked project, lists recent plans under `plans/` (newest first).
- * Prints a count header (blank line after when non-empty), then each plan as a
- * numbered two-line block — `N. ` + filename stem (title), then the indented
- * absolute path — separated by a blank line. The title line ends with two
- * trailing spaces (a Markdown hard line break) so agents can relay stdout
- * into chat and keep title and path on separate rendered lines. When `plans/`
- * is empty, prints `No plans.` only. The number is positional within this
- * listing only (not a stable identifier — a later `plan list` call may
- * renumber if plans change) and exists purely so a human or agent can refer
- * to "plan 2" in the same conversation without retyping the path. Same
- * vault/link prerequisites as `grounder plan`.
+ * Resolves the linked project, lists recent plans under `plans/` recursively
+ * (newest first). Prints a count header (blank line after when non-empty), then
+ * each plan as a numbered two-line block — `N. ` + bucket-relative stem path
+ * (nested files include subfolders), then the indented absolute path —
+ * separated by a blank line. With `markdown: true`, the title line is
+ * `[bucketRelativePath](fileUri)` under `plans/` (`.md` kept; no `plans/`
+ * prefix). The title line ends with two trailing spaces (a Markdown hard line
+ * break) so agents can relay stdout into chat and keep title and path on
+ * separate rendered lines. When `plans/` is empty, prints `No plans.` only. The
+ * number is positional within this listing only (not a stable identifier — a
+ * later `plan list` call may renumber if plans change) and exists purely so a
+ * human or agent can refer to "plan 2" in the same conversation without
+ * retyping the path. Same vault/link prerequisites as `grounder plan`.
  * @returns Exit code (`0` on success, `1` when vault/link is missing).
  */
 export declare function runPlanListWithOptions(options?: PlanListOptions): Promise<number>;

package/dist/commands/plan/list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/plan/list.ts"],"names":[],"mappings":"AAUA,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgCjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAa3F"}
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/plan/list.ts"],"names":[],"mappings":"AAUA,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgCjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB3F"}

package/dist/commands/plan/list.js

@@ -1,18 +1,18 @@
 import { withHomeDir } from "../../connector/home.js";
 import { resolvePlansDir } from "../../connector/vault.js";
 import { helpExitCode } from "../../help.js";
-import { parseArgs } from "../../util/parse-args.js";
+import { flagBool, parseArgs } from "../../util/parse-args.js";
 import { listPlans } from "../../vault/list-plans.js";
 import { writeVaultItemList } from "../output.js";
 import { requireLinkedProject } from "../require-linked.js";
 const DEFAULT_LIMIT = 5;
-const USAGE = "Usage: grounder plan list [--limit <n>]\n";
+const USAGE = "Usage: grounder plan list [--limit <n>] [--markdown]\n";
 function usageError() {
     process.stderr.write(USAGE);
     return 1;
 }
 /**
- * CLI entry for `grounder plan list [--limit <n>]`.
+ * CLI entry for `grounder plan list [--limit <n>] [--markdown]`.
  * `--limit` must be a positive integer when provided.
  * @returns Exit code (`0` on success, `1` on usage or config errors).
  */
@@ -26,7 +26,7 @@ export async function runPlanList(argv) {
         return usageError();
     }
     for (const key of flags.keys()) {
-        if (key !== "limit") {
+        if (key !== "limit" && key !== "markdown") {
             return usageError();
         }
     }
@@ -43,20 +43,22 @@ export async function runPlanList(argv) {
         }
         limit = parsed;
     }
-    return runPlanListWithOptions({ limit });
+    return runPlanListWithOptions({ limit, markdown: flagBool(flags, "markdown") });
 }
 /**
- * Resolves the linked project, lists recent plans under `plans/` (newest first).
- * Prints a count header (blank line after when non-empty), then each plan as a
- * numbered two-line block — `N. ` + filename stem (title), then the indented
- * absolute path — separated by a blank line. The title line ends with two
- * trailing spaces (a Markdown hard line break) so agents can relay stdout
- * into chat and keep title and path on separate rendered lines. When `plans/`
- * is empty, prints `No plans.` only. The number is positional within this
- * listing only (not a stable identifier — a later `plan list` call may
- * renumber if plans change) and exists purely so a human or agent can refer
- * to "plan 2" in the same conversation without retyping the path. Same
- * vault/link prerequisites as `grounder plan`.
+ * Resolves the linked project, lists recent plans under `plans/` recursively
+ * (newest first). Prints a count header (blank line after when non-empty), then
+ * each plan as a numbered two-line block — `N. ` + bucket-relative stem path
+ * (nested files include subfolders), then the indented absolute path —
+ * separated by a blank line. With `markdown: true`, the title line is
+ * `[bucketRelativePath](fileUri)` under `plans/` (`.md` kept; no `plans/`
+ * prefix). The title line ends with two trailing spaces (a Markdown hard line
+ * break) so agents can relay stdout into chat and keep title and path on
+ * separate rendered lines. When `plans/` is empty, prints `No plans.` only. The
+ * number is positional within this listing only (not a stable identifier — a
+ * later `plan list` call may renumber if plans change) and exists purely so a
+ * human or agent can refer to "plan 2" in the same conversation without
+ * retyping the path. Same vault/link prerequisites as `grounder plan`.
  * @returns Exit code (`0` on success, `1` when vault/link is missing).
  */
 export async function runPlanListWithOptions(options = {}) {
@@ -68,7 +70,10 @@ export async function runPlanListWithOptions(options = {}) {
         const limit = options.limit ?? DEFAULT_LIMIT;
         const plansDir = resolvePlansDir(linked.home, linked.repo);
         const paths = await listPlans(plansDir, { limit });
-        writeVaultItemList(paths, limit, { singular: "plan", plural: "plans" });
+        writeVaultItemList(paths, limit, { singular: "plan", plural: "plans" }, {
+            markdown: options.markdown === true,
+            titleRootDir: plansDir,
+        });
         return 0;
     });
 }

package/dist/commands/plan/list.js.map

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

package/dist/commands/plan.d.ts

@@ -13,6 +13,8 @@ export interface PlanOptions {
     planPath?: string;
     /** When true, overwrite an existing plan (preserving original `created`). */
     force?: boolean;
+    /** Topic keywords for search (`--topics "auth,jwt,middleware"`). */
+    topics?: string[];
     /** Override home dir / `GROUNDER_HOME` (tests). */
     homeDir?: string;
     /** Fixed clock for deterministic `created` / `updated` (tests). */

package/dist/commands/plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/commands/plan.ts"],"names":[],"mappings":"AAeA,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAoB7D;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CA4C9E"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/commands/plan.ts"],"names":[],"mappings":"AAeA,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B7D;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CA4C9E"}

package/dist/commands/plan.js

@@ -8,8 +8,8 @@ import { isPathInside, isRealPathInside, resolveUserPath } from "../util/path.js
 import { sanitizePlanName } from "../util/plan-name.js";
 import { updatePlanAtPath, writePlan } from "../vault/write-plan.js";
 import { requireLinkedProject } from "./require-linked.js";
-const USAGE = "Usage: grounder plan <text> --title <name> [--force]\n" +
-    "   or: grounder plan <text> --path <file>";
+const USAGE = "Usage: grounder plan <text> --title <name> [--force] [--topics <list>]\n" +
+    "   or: grounder plan <text> --path <file> [--topics <list>]";
 /**
  * CLI entry for `grounder plan <text> (--title <name> [--force] | --path <file>)`.
  * @returns Exit code (`0` on success, `1` on usage or config errors).
@@ -25,11 +25,19 @@ export async function runPlan(argv) {
         process.stderr.write(`${USAGE}\n`);
         return 1;
     }
+    const topicsRaw = flagString(flags, "topics");
+    const topics = topicsRaw
+        ? topicsRaw
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean)
+        : undefined;
     return runPlanWithOptions({
         text,
         title: flagString(flags, "title"),
         planPath: flagString(flags, "path"),
         force: flagBool(flags, "force"),
+        topics,
     });
 }
 /**
@@ -79,6 +87,7 @@ async function writeByTitle(plansDir, projectId, name, options) {
     const result = await writePlan(plansDir, name, options.text, {
         projectId,
         force: options.force,
+        topics: options.topics,
         now: options.now,
     });
     if (result.status === "exists") {
@@ -113,6 +122,7 @@ async function updateByPath(plansDir, projectId, options) {
     }
     const result = await updatePlanAtPath(filePath, options.text, {
         projectId,
+        topics: options.topics,
         now: options.now,
     });
     process.stdout.write(`Updated ${result.path}\n`);

package/dist/commands/plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/commands/plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/commands/plan.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,KAAK,GACT,0EAA0E;IAC1E,6DAA6D,CAAC;AAyBhE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAc;IAC1C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5C,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;QACnC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,SAAS;QACtB,CAAC,CAAC,SAAS;aACN,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,OAAO,CAAC;QACpB,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO,kBAAkB,CAAC;QACxB,IAAI;QACJ,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;QACjC,QAAQ,EAAE,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC;QACnC,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAC/B,MAAM;KACP,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAoB;IAC3D,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC;IAE/C,IAAI,QAAQ,IAAI,OAAO,EAAE,CAAC;QACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAClE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;QAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;QACnC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,OAAO,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oEAAoE,CAAC,CAAC;QAC3F,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,cAAc,GAAG,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACpF,IAAI,QAAQ,IAAI,CAAC,cAAc,EAAE,CAAC;QAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;QACnC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAE3D,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAChE,CAAC;QAED,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;YACnC,OAAO,CAAC,CAAC;QACX,CAAC;QAED,OAAO,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,QAAgB,EAChB,SAAiB,EACjB,IAAY,EACZ,OAAoB;IAEpB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;QAC3D,SAAS;QACT,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,MAAM,CAAC,IAAI,+BAA+B,CAAC,CAAC;QACzF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;IACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,QAAgB,EAChB,SAAiB,EACjB,OAAoB;IAEpB,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAE3C,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,QAAQ,IAAI,CAAC,CAAC;QACjF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3F,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,oEAAoE,QAAQ,UAAU,QAAQ,IAAI,CACnG,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,QAAQ,IAAI,CAAC,CAAC;QACtD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,mFAAmF;IACnF,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9D,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,oEAAoE,QAAQ,UAAU,QAAQ,IAAI,CACnG,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE;QAC5D,SAAS;QACT,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAC;IAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/commands/render-artifact-table.d.ts

@@ -0,0 +1,85 @@
+import type { ArtifactStatus } from "../agents/types.js";
+import type { GrounderState } from "../connector/state.js";
+import type { PlanAction, PlanEntry } from "../reconcile/core.js";
+import type { ApplyAgentInstallsResult } from "./apply.js";
+/** A row's plan status, independent of tense — "current" never changes wording; the
+ * others are rendered as an infinitive in a dry run and past tense in a real one. */
+export type RowStatus = "current" | "create" | "update" | "delete" | "forget" | "modified";
+export interface Row {
+    status: RowStatus;
+    target: string;
+    path: string;
+    /** Only meaningful when `status === "modified"` — what `--force` would do to this path. */
+    forceAction?: "overwrite" | "delete";
+}
+/** For hook/runtime rows, still reported via the old imperative `ArtifactStatus` shape. */
+export declare function toRowStatus(status: ArtifactStatus): RowStatus;
+/**
+ * Whole-file artifact rows come straight from the reconciler's own plan
+ * vocabulary. `forget` gets its own status, distinct from `noop`'s
+ * "current" — a forget entry always changes `state.json` (see
+ * `planChangesLedger`), even though it never touches the file itself, so
+ * folding it into "current"/"unchanged" would hide the one row that explains
+ * why the trailing state row says "updated".
+ */
+export declare function rowStatusFromPlanAction(action: PlanAction): RowStatus;
+export declare function rowFromPlanEntry(target: string, entry: PlanEntry): Row;
+export declare const VERB: Record<RowStatus, {
+    dry: string;
+    real: string;
+}>;
+/**
+ * Table cell label per status — the same word in dry-run and real, so the
+ * table asserts one outcome vocabulary instead of reconjugating per row
+ * (matching `kubectl apply`'s created/configured/unchanged). Dry-run-ness is
+ * already announced once above the table and in the summary sentence, which
+ * keeps its own tense (`VERB` above) since "would create" is a sentence
+ * construction, not a table cell.
+ *
+ * `modified` is deliberately not "modified" here: that word would read as
+ * Grounder having modified the file, when the row means the opposite — a
+ * local edit was found and Grounder left it untouched. "conflict" names that
+ * outcome without implying an action was taken (see the STATUS header below,
+ * not ACTION, for the same reason).
+ *
+ * `forget` is deliberately not "unchanged" here, even though the file itself
+ * is untouched: the ledger entry for it is dropped, which is exactly the
+ * "updated" the trailing state row reports — collapsing it into "unchanged"
+ * would leave that state-row change unexplained by any visible row.
+ */
+export declare const TABLE_LABEL: Record<RowStatus, string>;
+/**
+ * Runtime + per-agent whole-file/hook rows shared by `setup` and `migrate` —
+ * both callers add the trailing state/ledger row on top since that isn't
+ * part of `applyAgentInstalls`'s result. Tombstone retirement is already
+ * folded into each agent's own `plan`, so it lands right after that agent's
+ * own artifact rows with no separate grouping step needed.
+ */
+export declare function rowsFromApplyResult(applyResult: ApplyAgentInstallsResult): Row[];
+/**
+ * The trailing `state` row both `setup` and `migrate` append — same
+ * create/update/current rule either way, so the two callers can't drift on
+ * how a ledger write is reported. `ledgerChanged` is each caller's own
+ * computation; this only owns turning that bit plus prior-state nullness
+ * into a `Row`.
+ */
+export declare function stateRow(ledgerChanged: boolean, priorState: GrounderState | null, path: string): Row;
+export declare function plural(count: number, noun: string): string;
+export declare function renderTable(rows: Row[]): void;
+export declare function renderSummary(rows: Row[], dryRun: boolean): void;
+/**
+ * Per-agent hook failures `applyAgentInstalls` isolated (see
+ * `AgentApplyResult#error`) — printed after the table/summary so a failing
+ * agent's hook error doesn't obscure whether other agents (or this agent's
+ * own whole-file artifacts, already applied by this point) succeeded.
+ */
+export declare function renderAgentErrors(applyResult: ApplyAgentInstallsResult): void;
+/**
+ * @param forceCommand The command line (without `--force`) the reader should
+ * re-run to resolve conflicts. Both `setup` and `migrate` pass `"grounder
+ * migrate"` today — `setup --force` applies just as well, but pointing every
+ * conflict at one canonical command keeps the remediation message the same
+ * regardless of which command surfaced the conflict.
+ */
+export declare function renderModifiedNote(rows: Row[], forceCommand: string): void;
+//# sourceMappingURL=render-artifact-table.d.ts.map

package/dist/commands/render-artifact-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-artifact-table.d.ts","sourceRoot":"","sources":["../../src/commands/render-artifact-table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D;qFACqF;AACrF,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE3F,MAAM,WAAW,GAAG;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,WAAW,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;CACtC;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,CAS7D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAerE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,GAAG,CAOtE;AAED,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,SAAS,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAOjE,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAOjD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,wBAAwB,GAAG,GAAG,EAAE,CA8BhF;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,aAAa,EAAE,OAAO,EACtB,UAAU,EAAE,aAAa,GAAG,IAAI,EAChC,IAAI,EAAE,MAAM,GACX,GAAG,CAGL;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAW7C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CA4DhE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,wBAAwB,GAAG,IAAI,CAa7E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAuB1E"}