@dogsbay/commands 0.2.0-beta.101

package/dist/storage.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Injectable workspace storage — the only I/O boundary in the engine.
+ *
+ * Commands never touch node:fs: they see a `Storage` bound to a
+ * workspace root. Implementations: `NodeStorage` (real filesystem),
+ * `MemoryStorage` (tests, browser). An Electron IPC-backed
+ * implementation slots in the same way.
+ *
+ * All paths are workspace-root-relative posix paths ("a/b.md") — no
+ * leading "./", no backslashes, no absolute paths.
+ */
+export interface Storage {
+    /** Every file path in the workspace (recursive), sorted, posix-relative. */
+    list(): Promise<string[]>;
+    /** Read a file as UTF-8 text. Rejects if missing. */
+    read(path: string): Promise<string>;
+    /** Write a file (creating parent directories as needed). */
+    write(path: string, content: string): Promise<void>;
+    /** Delete a file. Rejects if missing. */
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+}
+/** Normalize any incoming path to the workspace-relative posix form. */
+export declare const normalizeStoragePath: (path: string) => string;
+/** In-memory storage for tests and browser embedding. */
+export declare class MemoryStorage implements Storage {
+    private files;
+    constructor(files?: Record<string, string>);
+    list(): Promise<string[]>;
+    read(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+}
+/**
+ * Real-filesystem storage rooted at a directory. Node-only (dynamic
+ * fs imports keep the module loadable in browser bundles that only
+ * use MemoryStorage).
+ */
+export interface NodeStorageOptions {
+    /**
+     * Refuse symlinks whose target resolves OUTSIDE the workspace root
+     * (list skips them; read/write/delete/exists throw). Default false —
+     * pnpm/monorepo layouts legitimately symlink content in, and the CLI
+     * runs on the user's own tree. Turn it on where the tree is UNTRUSTED
+     * and the verbs are reachable by an agent (the IDE sidecar does):
+     * a repo containing `docs/x -> ~/.ssh` would otherwise expose those files
+     * to `where-used`/`validate`/`read`-style verbs.
+     */
+    containSymlinks?: boolean;
+}
+export declare class NodeStorage implements Storage {
+    private root;
+    private readonly containSymlinks;
+    private rootReal;
+    constructor(root: string, options?: NodeStorageOptions);
+    private fs;
+    private abs;
+    /** `abs()` plus, when contained, a realpath check that no symlink escapes the root. */
+    private safeAbs;
+    private isInsideRoot;
+    list(): Promise<string[]>;
+    read(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,OAAO;IACtB,4EAA4E;IAC5E,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1B,qDAAqD;IACrD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,4DAA4D;IAC5D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,yCAAyC;IACzC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxC;AAED,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAiBnD,CAAC;AAEF,yDAAyD;AACzD,qBAAa,aAAc,YAAW,OAAO;IAC3C,OAAO,CAAC,KAAK,CAAsB;gBAEvB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM;IAMxC,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMnC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAG7C;AAOD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,qBAAa,WAAY,YAAW,OAAO;IAI7B,OAAO,CAAC,IAAI;IAHxB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAA8B;gBAE1B,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;YAIpD,EAAE;IAIhB,OAAO,CAAC,GAAG;IAQX,uFAAuF;YACzE,OAAO;YASP,YAAY;IAqBpB,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAgDzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKnC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAS7C"}

package/dist/storage.js

@@ -0,0 +1,193 @@
+/**
+ * Injectable workspace storage — the only I/O boundary in the engine.
+ *
+ * Commands never touch node:fs: they see a `Storage` bound to a
+ * workspace root. Implementations: `NodeStorage` (real filesystem),
+ * `MemoryStorage` (tests, browser). An Electron IPC-backed
+ * implementation slots in the same way.
+ *
+ * All paths are workspace-root-relative posix paths ("a/b.md") — no
+ * leading "./", no backslashes, no absolute paths.
+ */
+/** Normalize any incoming path to the workspace-relative posix form. */
+export const normalizeStoragePath = (path) => {
+    const parts = [];
+    for (const seg of path.replace(/\\/g, "/").split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..") {
+            // A ".." with nothing to pop escapes the workspace — keep the
+            // marker so lookups fail loudly instead of aliasing a root file
+            if (parts.length === 0 || parts[parts.length - 1] === "..") {
+                parts.push("..");
+                continue;
+            }
+            parts.pop();
+            continue;
+        }
+        parts.push(seg);
+    }
+    return parts.join("/");
+};
+/** In-memory storage for tests and browser embedding. */
+export class MemoryStorage {
+    files;
+    constructor(files = {}) {
+        this.files = new Map(Object.entries(files).map(([path, content]) => [normalizeStoragePath(path), content]));
+    }
+    async list() {
+        return [...this.files.keys()].sort();
+    }
+    async read(path) {
+        const content = this.files.get(normalizeStoragePath(path));
+        if (content === undefined)
+            throw new Error(`File not found: ${path}`);
+        return content;
+    }
+    async write(path, content) {
+        this.files.set(normalizeStoragePath(path), content);
+    }
+    async delete(path) {
+        if (!this.files.delete(normalizeStoragePath(path))) {
+            throw new Error(`File not found: ${path}`);
+        }
+    }
+    async exists(path) {
+        return this.files.has(normalizeStoragePath(path));
+    }
+}
+/** Directories never part of a content workspace. */
+const IGNORED_DIRS = new Set([
+    "node_modules", ".git", ".dogsbay", "dist", ".astro", ".turbo",
+]);
+export class NodeStorage {
+    root;
+    containSymlinks;
+    rootReal;
+    constructor(root, options = {}) {
+        this.root = root;
+        this.containSymlinks = options.containSymlinks ?? false;
+    }
+    async fs() {
+        return import("node:fs/promises");
+    }
+    abs(path) {
+        const rel = normalizeStoragePath(path);
+        if (rel.startsWith("..")) {
+            throw new Error(`Path escapes the workspace root: ${path}`);
+        }
+        return `${this.root}/${rel}`;
+    }
+    /** `abs()` plus, when contained, a realpath check that no symlink escapes the root. */
+    async safeAbs(path) {
+        const abs = this.abs(path);
+        if (!this.containSymlinks)
+            return abs;
+        if (!(await this.isInsideRoot(abs))) {
+            throw new Error(`Path resolves outside the workspace root: ${path}`);
+        }
+        return abs;
+    }
+    async isInsideRoot(abs) {
+        const fs = await this.fs();
+        this.rootReal ??= fs.realpath(this.root).catch(() => this.root);
+        const rootReal = await this.rootReal;
+        // realpath the deepest existing ancestor (the target may not exist yet on write)
+        let probe = abs;
+        let suffix = "";
+        for (;;) {
+            try {
+                const real = await fs.realpath(probe);
+                const full = real + suffix;
+                return full === rootReal || full.startsWith(rootReal + "/");
+            }
+            catch {
+                const cut = probe.lastIndexOf("/");
+                if (cut <= 0)
+                    return false;
+                suffix = probe.slice(cut) + suffix;
+                probe = probe.slice(0, cut);
+            }
+        }
+    }
+    async list() {
+        const fs = await this.fs();
+        const out = [];
+        // Symlinked directories are walked (pnpm/monorepo layouts symlink
+        // content in); the realpath set breaks symlink cycles
+        const visited = new Set([await fs.realpath(this.root).catch(() => this.root)]);
+        const walk = async (dir, prefix) => {
+            let entries;
+            try {
+                entries = await fs.readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                const full = `${dir}/${entry.name}`;
+                let isDirectory = entry.isDirectory();
+                let isFile = entry.isFile();
+                if (entry.isSymbolicLink()) {
+                    if (this.containSymlinks && !(await this.isInsideRoot(full)))
+                        continue; // escapes the root
+                    try {
+                        const stat = await fs.stat(full); // follows the link
+                        isDirectory = stat.isDirectory();
+                        isFile = stat.isFile();
+                    }
+                    catch {
+                        continue; // dangling symlink
+                    }
+                }
+                if (isDirectory) {
+                    if (IGNORED_DIRS.has(entry.name))
+                        continue;
+                    if (entry.isSymbolicLink()) {
+                        try {
+                            const real = await fs.realpath(full);
+                            if (visited.has(real))
+                                continue;
+                            visited.add(real);
+                        }
+                        catch {
+                            continue;
+                        }
+                    }
+                    await walk(full, `${prefix}${entry.name}/`);
+                }
+                else if (isFile) {
+                    out.push(`${prefix}${entry.name}`);
+                }
+            }
+        };
+        await walk(this.root, "");
+        return out.sort();
+    }
+    async read(path) {
+        const fs = await this.fs();
+        return fs.readFile(await this.safeAbs(path), "utf-8");
+    }
+    async write(path, content) {
+        const fs = await this.fs();
+        const abs = await this.safeAbs(path);
+        const dir = abs.slice(0, abs.lastIndexOf("/"));
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(abs, content, "utf-8");
+    }
+    async delete(path) {
+        const fs = await this.fs();
+        await fs.unlink(await this.safeAbs(path));
+    }
+    async exists(path) {
+        const fs = await this.fs();
+        try {
+            await fs.access(await this.safeAbs(path));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

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

package/dist/workspace.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Workspace — storage plus lazily built indexes.
+ *
+ * Commands receive a Workspace and read indexes; they never walk files
+ * themselves. Long-lived hosts (JSON-RPC server, MCP) call
+ * `invalidate()` on file change; one-shot CLI runs build once.
+ */
+import type { Storage } from "./storage.js";
+import { type WorkspaceIndex } from "./indexes.js";
+export declare class Workspace {
+    readonly storage: Storage;
+    private indexPromise;
+    constructor(storage: Storage);
+    /** The workspace index, building it on first use. */
+    index(): Promise<WorkspaceIndex>;
+    /**
+     * Drop the cached index; the next `index()` call rebuilds. With `paths`,
+     * the next build is INCREMENTAL over the last complete index (only those
+     * files are re-read; see buildWorkspaceIndex) — a save in a 2,000-page
+     * project then costs one parse, not two thousand.
+     */
+    invalidate(paths?: string[]): void;
+    private lastIndex;
+    private pendingChanged;
+    private inflightChanged;
+    private nextBuild;
+    /** Rebuild now and return the fresh index. */
+    reindex(): Promise<WorkspaceIndex>;
+}
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAExE,qBAAa,SAAS;aAGQ,OAAO,EAAE,OAAO;IAF5C,OAAO,CAAC,YAAY,CAAsC;gBAE9B,OAAO,EAAE,OAAO;IAE5C,qDAAqD;IACrD,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;IAsBhC;;;;;OAKG;IACH,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI;IAgBlC,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,SAAS,CAA8C;IAE/D,8CAA8C;IACxC,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC;CAIzC"}

package/dist/workspace.js

@@ -0,0 +1,63 @@
+import { buildWorkspaceIndex } from "./indexes.js";
+export class Workspace {
+    storage;
+    indexPromise;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /** The workspace index, building it on first use. */
+    index() {
+        if (!this.indexPromise) {
+            const build = this.nextBuild ?? (() => buildWorkspaceIndex(this.storage));
+            const changedNow = this.pendingChanged;
+            this.nextBuild = undefined;
+            this.pendingChanged = undefined;
+            this.inflightChanged = changedNow;
+            const building = build();
+            // A rejected build must NOT be memoized — in long-lived hosts
+            // (JSON-RPC/MCP) a transient storage error would otherwise poison
+            // every later command until an explicit invalidate()
+            building.then((idx) => {
+                if (this.indexPromise === building) {
+                    this.lastIndex = idx;
+                    this.inflightChanged = undefined;
+                }
+            }, () => { if (this.indexPromise === building)
+                this.indexPromise = undefined; });
+            this.indexPromise = building;
+        }
+        return this.indexPromise;
+    }
+    /**
+     * Drop the cached index; the next `index()` call rebuilds. With `paths`,
+     * the next build is INCREMENTAL over the last complete index (only those
+     * files are re-read; see buildWorkspaceIndex) — a save in a 2,000-page
+     * project then costs one parse, not two thousand.
+     */
+    invalidate(paths) {
+        if (paths && paths.length && this.lastIndex) {
+            // a build in flight (superseded by this call) carried its own changed set; those files
+            // are in neither lastIndex nor the next build unless we fold them in
+            const changed = [...(this.pendingChanged ?? []), ...(this.inflightChanged ?? []), ...paths];
+            this.pendingChanged = changed;
+            this.indexPromise = undefined;
+            // `previous` is resolved when the build STARTS (lastIndex may advance meanwhile)
+            this.nextBuild = () => buildWorkspaceIndex(this.storage, { previous: this.lastIndex, changed });
+            return;
+        }
+        this.indexPromise = undefined;
+        this.pendingChanged = undefined;
+        this.inflightChanged = undefined;
+        this.nextBuild = undefined;
+    }
+    lastIndex;
+    pendingChanged;
+    inflightChanged;
+    nextBuild;
+    /** Rebuild now and return the fresh index. */
+    async reindex() {
+        this.invalidate();
+        return this.index();
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,cAAc,CAAC;AAExE,MAAM,OAAO,SAAS;IAGQ;IAFpB,YAAY,CAAsC;IAE1D,YAA4B,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;IAAG,CAAC;IAEhD,qDAAqD;IACrD,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YAC1E,MAAM,UAAU,GAAG,IAAI,CAAC,cAAc,CAAC;YACvC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;YAC3B,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;YAChC,IAAI,CAAC,eAAe,GAAG,UAAU,CAAC;YAClC,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC;YACzB,8DAA8D;YAC9D,kEAAkE;YAClE,qDAAqD;YACrD,QAAQ,CAAC,IAAI,CACX,CAAC,GAAG,EAAE,EAAE;gBACN,IAAI,IAAI,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;oBAAC,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC;oBAAC,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;gBAAC,CAAC;YACjG,CAAC,EACD,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,YAAY,KAAK,QAAQ;gBAAE,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC,CAAC,CAC7E,CAAC;YACF,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC;QAC/B,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,KAAgB;QACzB,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC5C,uFAAuF;YACvF,qEAAqE;YACrE,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,eAAe,IAAI,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC;YAC5F,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC;YAC9B,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;YAC9B,iFAAiF;YACjF,IAAI,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;YAChG,OAAO;QACT,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAC9B,IAAI,CAAC,cAAc,GAAG,SAAS,CAAC;QAChC,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IACO,SAAS,CAA6B;IACtC,cAAc,CAAuB;IACrC,eAAe,CAAuB;IACtC,SAAS,CAA8C;IAE/D,8CAA8C;IAC9C,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@dogsbay/commands",
+  "version": "0.2.0-beta.101",
+  "description": "Typed, headless-first command engine for the Dogsbay platform — one zod-defined command yields CLI, JSON-RPC, and MCP surfaces",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.9.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "js-yaml": "^5.2.1",
+    "zod": "^4.4.3",
+    "@dogsbay/format-topicmap": "0.2.0-beta.101",
+    "@dogsbay/minja": "0.2.0-beta.101",
+    "@dogsbay/types": "0.2.0-beta.101",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.101"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/commands"
+  },
+  "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/commands",
+  "bugs": {
+    "url": "https://github.com/dogsbay/dogsbay/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}