@dogsbay/commands 0.2.0-beta.101

package/README.md

@@ -0,0 +1,137 @@
+# @dogsbay/commands
+
+Typed, headless-first command engine for the Dogsbay platform (Plan 04
+Phase 1). One command definition — a name, a zod input schema, and a
+pure handler over a `Workspace` — yields every surface: the `dogsbay`
+CLI generates its flags from the schema, and the JSON-RPC and MCP
+servers (Phase 3) will consume the same registry. Parity between
+surfaces is by construction, enforced by a schema conformance test.
+
+## Architecture
+
+```
+Storage (injected I/O)      NodeStorage | MemoryStorage | (Electron IPC …)
+   └─ Workspace             lazy indexes + invalidate()/reindex()
+        └─ CommandContext   what every handler sees
+             └─ CommandRegistry.run(name, input, ctx) → CommandResult
+```
+
+- **Storage** is the only I/O boundary. Commands never touch `node:fs`.
+  All paths are workspace-root-relative posix paths.
+- **Indexes** are built in one pass: per-doc table (frontmatter,
+  headings, anchors, links, includes, `key:` uses), topic-map table,
+  key-definition table (from `*.keys.yaml`), and the inverted
+  inbound-reference graph.
+- **Results** are envelopes, never exceptions: `{ ok, data, issues }`
+  for success (issues = workspace problems), `{ ok: false, error }` for
+  input/execution failures.
+
+## Built-in commands
+
+| Command | What it does |
+|---|---|
+| `validate` | Broken links, missing anchors, missing include targets, undefined keys, key conflicts, malformed keys files, topic-map errors, missing map targets, cross-map cycles |
+| `where-used <target>` | Inbound references to a file, `file#anchor`, or `key:name` — links, images, includes, topic-map entries, key uses |
+| `keys-list` | Every key definition with defining file, conflicts, and uses |
+| `keys-resolve <name>` | Winning definition + all definitions + uses for one key |
+| `topicmap-resolve <map>` | Resolve a topic map (recursive includes + minja variables) through injected storage |
+| `reindex` | Rebuild indexes and report statistics |
+
+## Refactor commands (Plan 04 Phase 2)
+
+All reuse-safe: mutations are index lookups plus surgical text edits,
+inbound references are rewritten in the same run, and anything that
+cannot be repaired mechanically becomes an issue — never a silent drop.
+Golden-diff tests pin the exact rewrites, and `validate` must stay
+error-free after every refactor.
+
+| Command | What it does |
+|---|---|
+| `rename-file <from> <to>` | Move/rename; rewrites inbound links (fragments kept), includes, and topic-map hrefs, AND the moved doc's own outbound relative references |
+| `safe-delete <file> [--force]` | Delete only when nothing references it (links, includes, maps, key hrefs); `--force` deletes and issues each now-broken referrer |
+| `extract-include <file> --start N --end M --snippet path` | Extract a line range into a snippet, replace it with `{% include %}`; refuses ranges that split a code fence |
+| `rename-key <from> <to>` | Rename across keys files, `key:` links, and `{{ var }}` text references (flagged for attribute-name ambiguity) |
+| `keyify <file> <key>` | Define a key for a file and convert inbound direct links to `key:` references (fragment links skipped with a note) |
+| `split-topic <file>` | Split at level-2 headings into sibling topics + a topic map; inbound `#anchor` links follow their sections |
+| `merge-topics <into> --sources a.md --sources b.md` | Merge sources as anchored H2 sections (headings shifted, links/includes rebased, source-to-source links become same-document anchors); inbound refs re-pointed |
+| `topic-read <file>` | Enriched read: title, frontmatter, section outline (levels, ids, slugs, line ranges), links, includes, key uses, inbound refs, directive count; `--includeBody` |
+| `topic-set-title <file> <title>` | Rewrite the H1 text only (keeps `{#id}`); warns when frontmatter `title` differs |
+| `section-replace <file> <section> --body` | Replace one section's content (heading kept unless `--keepHeading false`); selector = `{#id}`, heading text or slug; ambiguity refused |
+| `block-insert <file> --content [--section --position start\|end] [--line N]` | Insert a block; refuses mid-fence |
+| `block-delete <file> <section>` | Delete a section subtree; warns about orphaned inbound `#anchor` links; refuses the H1 |
+| `props-get <file>` / `props-set <file> --set k=v --unset k` | Frontmatter read / in-place set+unset (only the touched keys' lines change; creates frontmatter when absent) |
+| `map-list <map>` | Topic-map entries with dotted pointers |
+| `map-add-ref <map> <href> [--navtitle --parent --index --format --toc --singlePage]` | Add an entry; dangling local href / self-include refused |
+| `map-move-ref <map> <from> [--toParent --index]` | Move a subtree; into-own-subtree refused |
+| `map-remove-ref <map> <at> [--keepChildren]` | Remove (children go with it and are reported) or hoist |
+| `map-set-props <map> <at> [--navtitle --href --format --toc --singlePage]` | Set/unset (null) entry props; new href must resolve |
+
+## Using the engine
+
+```ts
+import {
+  createDefaultRegistry,
+  Workspace,
+  NodeStorage,
+  MemoryStorage,
+} from "@dogsbay/commands";
+
+const registry = createDefaultRegistry();
+const workspace = new Workspace(new NodeStorage("/path/to/docs"));
+
+const result = await registry.run("validate", {}, { workspace });
+if (result.ok) {
+  console.log(result.summary, result.issues);
+}
+```
+
+In tests (or a browser), swap the storage:
+
+```ts
+const workspace = new Workspace(
+  new MemoryStorage({ "index.md": "# Home\n[link](guide.md)" })
+);
+```
+
+## Defining a command
+
+```ts
+import { z } from "zod";
+import { defineCommand } from "@dogsbay/commands";
+
+export const outlineCommand = defineCommand({
+  name: "outline",
+  description: "Heading outline of one document",
+  input: z.object({
+    file: z.string().min(1).describe("Workspace-relative .md path"),
+  }).strict(),
+  positionals: ["file"],          // CLI: `dogsbay outline <file>`
+  async run(ctx, { file }) {
+    const index = await ctx.workspace.index();
+    const doc = index.docs.get(file);
+    return { data: { headings: doc?.headings ?? [] } };
+  },
+});
+```
+
+Register it and every surface picks it up. Schema fields may be:
+`string`, `number`, `boolean`, `enum`, `array(string)`,
+`record(string)` — each optionally `.optional()`, `.default()`,
+`.describe()`. The conformance test (`tests/engine.test.ts`) fails CI
+if a registered command uses anything the surface generators cannot
+express.
+
+## CLI surface
+
+Every command is available on the `dogsbay` CLI with uniform flags:
+
+```bash
+dogsbay validate --root docs/            # exit 1 on errors
+dogsbay where-used guide/setup.md --root docs/
+dogsbay where-used key:product-name --root docs/ --json
+dogsbay keys-list --root docs/
+dogsbay topicmap-resolve root.topicmap.yml --variables product=Acme --root docs/
+```
+
+`--root <dir>` selects the workspace (default: cwd); `--json` prints
+the full machine-readable envelope for CI and agents.

package/dist/commands/content.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Content verbs — the agent broker's typed alternative to "edit the file"
+ * (plans/agent-broker.md Phase 3): `topic-read`, `topic-set-title`,
+ * `section-replace`, `block-insert`, `block-delete`, `props-get`,
+ * `props-set`.
+ *
+ * All of them are LINE-WISE edits on the shared fence grammar (a `## x`
+ * inside a code example is never structure) with the frontmatter split
+ * off first, so every byte outside the edited span is untouched by
+ * construction — no parse/serialize round-trip that could normalise
+ * directives, tables, or whitespace elsewhere in the file. Every mutation
+ * invalidates the workspace index and reports what changed; what cannot
+ * be done safely (a mid-fence insert, an ambiguous section, deleting the
+ * H1) is refused with an issue, never guessed.
+ */
+import { z } from "zod";
+export interface SectionInfo {
+    level: number;
+    text: string;
+    id?: string;
+    /** The anchor the site assigns: the explicit id, else the deduped text slug (`usage`, `usage-1`). */
+    slug: string;
+    /** 0-based line index of the heading within the BODY (after frontmatter). */
+    line: number;
+    /** 0-based exclusive end line of the section (next heading of level ≤ this, or EOF). */
+    end: number;
+    /** 0-based exclusive end of the section's OWN text (before its first sub-heading). */
+    ownEnd: number;
+}
+/**
+ * Divergence gate (plans/ide-change-review.md §3): a short content hash the
+ * agent gets from `topic-read` and hands back as `expect` on a mutation. If
+ * the target changed in between (a human typing, another agent), the verb
+ * refuses with the current hash instead of writing over the newer text.
+ */
+export declare const contentHash: (text: string) => string;
+export declare const topicReadCommand: import("../engine.js").CommandDef<z.ZodObject<{
+    file: z.ZodString;
+    includeBody: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>>;
+export declare const topicSetTitleCommand: import("../engine.js").CommandDef<z.ZodObject<{
+    file: z.ZodString;
+    title: z.ZodString;
+    expect: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const sectionReplaceCommand: import("../engine.js").CommandDef<z.ZodObject<{
+    file: z.ZodString;
+    section: z.ZodString;
+    body: z.ZodString;
+    keepHeading: z.ZodDefault<z.ZodBoolean>;
+    expect: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const blockInsertCommand: import("../engine.js").CommandDef<z.ZodObject<{
+    file: z.ZodString;
+    content: z.ZodString;
+    section: z.ZodOptional<z.ZodString>;
+    position: z.ZodDefault<z.ZodEnum<{
+        start: "start";
+        end: "end";
+    }>>;
+    line: z.ZodOptional<z.ZodNumber>;
+    expect: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const blockDeleteCommand: import("../engine.js").CommandDef<z.ZodObject<{
+    file: z.ZodString;
+    section: z.ZodString;
+    expect: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const propsGetCommand: import("../engine.js").CommandDef<z.ZodObject<{
+    file: z.ZodString;
+}, z.core.$strict>>;
+export declare const propsSetCommand: import("../engine.js").CommandDef<z.ZodObject<{
+    file: z.ZodString;
+    set: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+    unset: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    expect: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+//# sourceMappingURL=content.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/commands/content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qGAAqG;IACrG,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;CAChB;AAiFD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,MAAsE,CAAC;AAqGlH,eAAO,MAAM,gBAAgB;;;mBA4D3B,CAAC;AAIH,eAAO,MAAM,oBAAoB;;;;mBAsC/B,CAAC;AAIH,eAAO,MAAM,qBAAqB;;;;;;mBA2ChC,CAAC;AAIH,eAAO,MAAM,kBAAkB;;;;;;;;;;mBA6D7B,CAAC;AAIH,eAAO,MAAM,kBAAkB;;;;mBA2C7B,CAAC;AAIH,eAAO,MAAM,eAAe;;mBAc1B,CAAC;AAKH,eAAO,MAAM,eAAe;;;;;mBAkG1B,CAAC"}