@workflow-cannon/workspace-kit 0.15.0 → 0.16.1

package/dist/modules/task-engine/store.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import crypto from "node:crypto";
 import { TaskEngineError } from "./transitions.js";
-const DEFAULT_STORE_PATH = ".workspace-kit/tasks/state.json";
+export const DEFAULT_TASK_STORE_PATH = ".workspace-kit/tasks/state.json";
 function emptyStore() {
     return {
         schemaVersion: 1,
@@ -14,49 +14,73 @@ function emptyStore() {
 }
 export class TaskStore {
     document;
-    filePath;
-    constructor(workspacePath, storePath) {
-        this.filePath = path.resolve(workspacePath, storePath ?? DEFAULT_STORE_PATH);
+    persistence;
+    constructor(persistence) {
+        this.persistence = persistence;
         this.document = emptyStore();
     }
-    async load() {
-        try {
-            const raw = await fs.readFile(this.filePath, "utf8");
-            const parsed = JSON.parse(raw);
-            if (parsed.schemaVersion !== 1) {
-                throw new TaskEngineError("storage-read-error", `Unsupported schema version: ${parsed.schemaVersion}`);
-            }
-            this.document = parsed;
-            if (!Array.isArray(this.document.mutationLog)) {
-                this.document.mutationLog = [];
+    static forJsonFile(workspacePath, storeRelativePath) {
+        const filePath = path.resolve(workspacePath, storeRelativePath ?? DEFAULT_TASK_STORE_PATH);
+        return new TaskStore({
+            pathLabel: filePath,
+            loadDocument: async () => {
+                try {
+                    const raw = await fs.readFile(filePath, "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (parsed.schemaVersion !== 1) {
+                        throw new TaskEngineError("storage-read-error", `Unsupported schema version: ${parsed.schemaVersion}`);
+                    }
+                    if (!Array.isArray(parsed.mutationLog)) {
+                        parsed.mutationLog = [];
+                    }
+                    return parsed;
+                }
+                catch (err) {
+                    if (err.code === "ENOENT") {
+                        return emptyStore();
+                    }
+                    if (err instanceof TaskEngineError) {
+                        throw err;
+                    }
+                    throw new TaskEngineError("storage-read-error", `Failed to read task store: ${err.message}`);
+                }
+            },
+            saveDocument: async (doc) => {
+                const dir = path.dirname(filePath);
+                const tmpPath = `${filePath}.${crypto.randomUUID().slice(0, 8)}.tmp`;
+                try {
+                    await fs.mkdir(dir, { recursive: true });
+                    await fs.writeFile(tmpPath, JSON.stringify(doc, null, 2) + "\n", "utf8");
+                    await fs.rename(tmpPath, filePath);
+                }
+                catch (err) {
+                    try {
+                        await fs.unlink(tmpPath);
+                    }
+                    catch {
+                        /* cleanup best-effort */
+                    }
+                    throw new TaskEngineError("storage-write-error", `Failed to write task store: ${err.message}`);
+                }
             }
-        }
-        catch (err) {
-            if (err.code === "ENOENT") {
-                this.document = emptyStore();
-                return;
+        });
+    }
+    static forSqliteDual(dual) {
+        return new TaskStore({
+            pathLabel: `${dual.getDisplayPath()}#task_engine`,
+            loadDocument: async () => dual.taskDocument,
+            saveDocument: async (doc) => {
+                dual.seedFromDocuments(doc, dual.wishlistDocument);
+                dual.persistSync();
             }
-            if (err instanceof TaskEngineError)
-                throw err;
-            throw new TaskEngineError("storage-read-error", `Failed to read task store: ${err.message}`);
-        }
+        });
+    }
+    async load() {
+        this.document = await this.persistence.loadDocument();
     }
     async save() {
         this.document.lastUpdated = new Date().toISOString();
-        const dir = path.dirname(this.filePath);
-        const tmpPath = `${this.filePath}.${crypto.randomUUID().slice(0, 8)}.tmp`;
-        try {
-            await fs.mkdir(dir, { recursive: true });
-            await fs.writeFile(tmpPath, JSON.stringify(this.document, null, 2) + "\n", "utf8");
-            await fs.rename(tmpPath, this.filePath);
-        }
-        catch (err) {
-            try {
-                await fs.unlink(tmpPath);
-            }
-            catch { /* cleanup best-effort */ }
-            throw new TaskEngineError("storage-write-error", `Failed to write task store: ${err.message}`);
-        }
+        await this.persistence.saveDocument(this.document);
     }
     getAllTasks() {
         return [...this.document.tasks];
@@ -99,7 +123,7 @@ export class TaskStore {
         this.document.tasks = tasks.map((t) => ({ ...t }));
     }
     getFilePath() {
-        return this.filePath;
+        return this.persistence.pathLabel;
     }
     getLastUpdated() {
         return this.document.lastUpdated;

package/dist/modules/task-engine/wishlist-store.d.ts

@@ -1,8 +1,17 @@
-import type { WishlistItem } from "./wishlist-types.js";
+import type { WishlistItem, WishlistStoreDocument } from "./wishlist-types.js";
+import type { SqliteDualPlanningStore } from "./sqlite-dual-planning.js";
+export declare const DEFAULT_WISHLIST_PATH = ".workspace-kit/wishlist/state.json";
+export type WishlistStorePersistence = {
+    loadDocument: () => Promise<WishlistStoreDocument>;
+    saveDocument: (doc: WishlistStoreDocument) => Promise<void>;
+    pathLabel: string;
+};
 export declare class WishlistStore {
     private document;
-    private readonly filePath;
-    constructor(workspacePath: string, storeRelativePath?: string);
+    private readonly persistence;
+    constructor(persistence: WishlistStorePersistence);
+    static forJsonFile(workspacePath: string, storeRelativePath?: string): WishlistStore;
+    static forSqliteDual(dual: SqliteDualPlanningStore): WishlistStore;
     load(): Promise<void>;
     save(): Promise<void>;
     getAllItems(): WishlistItem[];

package/dist/modules/task-engine/wishlist-store.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import crypto from "node:crypto";
 import { TaskEngineError } from "./transitions.js";
-const DEFAULT_WISHLIST_PATH = ".workspace-kit/wishlist/state.json";
+export const DEFAULT_WISHLIST_PATH = ".workspace-kit/wishlist/state.json";
 function emptyWishlistDoc() {
     return {
         schemaVersion: 1,
@@ -12,51 +12,73 @@ function emptyWishlistDoc() {
 }
 export class WishlistStore {
     document;
-    filePath;
-    constructor(workspacePath, storeRelativePath) {
-        this.filePath = path.resolve(workspacePath, storeRelativePath ?? DEFAULT_WISHLIST_PATH);
+    persistence;
+    constructor(persistence) {
+        this.persistence = persistence;
         this.document = emptyWishlistDoc();
     }
-    async load() {
-        try {
-            const raw = await fs.readFile(this.filePath, "utf8");
-            const parsed = JSON.parse(raw);
-            if (parsed.schemaVersion !== 1) {
-                throw new TaskEngineError("storage-read-error", `Unsupported wishlist schema version: ${parsed.schemaVersion}`);
-            }
-            if (!Array.isArray(parsed.items)) {
-                throw new TaskEngineError("storage-read-error", "Wishlist store 'items' must be an array");
+    static forJsonFile(workspacePath, storeRelativePath) {
+        const filePath = path.resolve(workspacePath, storeRelativePath ?? DEFAULT_WISHLIST_PATH);
+        return new WishlistStore({
+            pathLabel: filePath,
+            loadDocument: async () => {
+                try {
+                    const raw = await fs.readFile(filePath, "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (parsed.schemaVersion !== 1) {
+                        throw new TaskEngineError("storage-read-error", `Unsupported wishlist schema version: ${parsed.schemaVersion}`);
+                    }
+                    if (!Array.isArray(parsed.items)) {
+                        throw new TaskEngineError("storage-read-error", "Wishlist store 'items' must be an array");
+                    }
+                    return parsed;
+                }
+                catch (err) {
+                    if (err.code === "ENOENT") {
+                        return emptyWishlistDoc();
+                    }
+                    if (err instanceof TaskEngineError) {
+                        throw err;
+                    }
+                    throw new TaskEngineError("storage-read-error", `Failed to read wishlist store: ${err.message}`);
+                }
+            },
+            saveDocument: async (doc) => {
+                const dir = path.dirname(filePath);
+                const tmpPath = `${filePath}.${crypto.randomUUID().slice(0, 8)}.tmp`;
+                try {
+                    await fs.mkdir(dir, { recursive: true });
+                    await fs.writeFile(tmpPath, JSON.stringify(doc, null, 2) + "\n", "utf8");
+                    await fs.rename(tmpPath, filePath);
+                }
+                catch (err) {
+                    try {
+                        await fs.unlink(tmpPath);
+                    }
+                    catch {
+                        /* cleanup best-effort */
+                    }
+                    throw new TaskEngineError("storage-write-error", `Failed to write wishlist store: ${err.message}`);
+                }
             }
-            this.document = parsed;
-        }
-        catch (err) {
-            if (err.code === "ENOENT") {
-                this.document = emptyWishlistDoc();
-                return;
+        });
+    }
+    static forSqliteDual(dual) {
+        return new WishlistStore({
+            pathLabel: `${dual.getDisplayPath()}#wishlist`,
+            loadDocument: async () => dual.wishlistDocument,
+            saveDocument: async (doc) => {
+                dual.seedFromDocuments(dual.taskDocument, doc);
+                dual.persistSync();
             }
-            if (err instanceof TaskEngineError)
-                throw err;
-            throw new TaskEngineError("storage-read-error", `Failed to read wishlist store: ${err.message}`);
-        }
+        });
+    }
+    async load() {
+        this.document = await this.persistence.loadDocument();
     }
     async save() {
         this.document.lastUpdated = new Date().toISOString();
-        const dir = path.dirname(this.filePath);
-        const tmpPath = `${this.filePath}.${crypto.randomUUID().slice(0, 8)}.tmp`;
-        try {
-            await fs.mkdir(dir, { recursive: true });
-            await fs.writeFile(tmpPath, JSON.stringify(this.document, null, 2) + "\n", "utf8");
-            await fs.rename(tmpPath, this.filePath);
-        }
-        catch (err) {
-            try {
-                await fs.unlink(tmpPath);
-            }
-            catch {
-                /* cleanup best-effort */
-            }
-            throw new TaskEngineError("storage-write-error", `Failed to write wishlist store: ${err.message}`);
-        }
+        await this.persistence.saveDocument(this.document);
     }
     getAllItems() {
         return [...this.document.items];
@@ -78,7 +100,7 @@ export class WishlistStore {
         this.document.items[idx] = { ...item };
     }
     getFilePath() {
-        return this.filePath;
+        return this.persistence.pathLabel;
     }
     getLastUpdated() {
         return this.document.lastUpdated;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -41,6 +41,7 @@
     "ui:watch": "cd extensions/cursor-workflow-cannon && npm run watch"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.5.0",
     "typescript": "^5.9.3"
   },
@@ -48,5 +49,13 @@
     "dist",
     "src/modules/documentation",
     "package.json"
-  ]
+  ],
+  "dependencies": {
+    "better-sqlite3": "^12.8.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
+  }
 }

package/src/modules/documentation/README.md

@@ -24,6 +24,7 @@ Files under `templates/`; `documentType` is the filename (basename). Keep this l
 - `AGENTS.md`
 - `ARCHITECTURE.md`
 - `PRINCIPLES.md`
+- `README.md`
 - `RELEASING.md`
 - `ROADMAP.md`
 - `SECURITY.md`

package/src/modules/documentation/instructions/document-project.md

@@ -18,6 +18,7 @@ All `.md` files under `sources.templatesRoot` (default `src/modules/documentatio
 - `AGENTS.md`
 - `ARCHITECTURE.md`
 - `PRINCIPLES.md`
+- `README.md`
 - `RELEASING.md`
 - `ROADMAP.md`
 - `SECURITY.md`

package/src/modules/documentation/instructions/generate-document.md

@@ -8,6 +8,7 @@ Generate a single document for both canonical AI and human-readable surfaces usi
   - `AGENTS.md`
   - `ARCHITECTURE.md`
   - `PRINCIPLES.md`
+  - `README.md`
   - `RELEASING.md`
   - `ROADMAP.md`
   - `SECURITY.md`

package/src/modules/documentation/templates/README.md

@@ -0,0 +1,89 @@
+<!--
+  Human output path: docs/maintainers/README.md (image uses ../title_image.png from that location).
+  Root README.md: mirror this body but use title_image.png and keep the agent notice line at the very top.
+  Audience: developers cloning the repo or adding @workflow-cannon/workspace-kit to a project who want to run something useful in minutes.
+-->
+
+<div align="center">
+  <img src="../title_image.png" alt="Workflow Cannon" width="720" />
+</div>
+
+# Workflow Cannon
+
+**[`@workflow-cannon/workspace-kit`](https://www.npmjs.com/package/@workflow-cannon/workspace-kit)** — CLI, task engine, and workflow contracts for repos that want deterministic, policy-governed automation with clear evidence.
+
+## Quick start (clone this repo)
+
+**Needs:** Node.js **22+** (see CI), **pnpm 10** (see `packageManager` in `package.json`).
+
+```bash
+git clone https://github.com/NJLaPrell/workflow-cannon.git
+cd workflow-cannon
+pnpm install
+pnpm run build
+```
+
+Verify the kit sees your workspace:
+
+```bash
+node dist/cli.js doctor
+node dist/cli.js --help
+```
+
+Try **read-only** task-engine queries:
+
+```bash
+node dist/cli.js run list-tasks '{}'
+node dist/cli.js run get-next-actions '{}'
+```
+
+**Developing:** after edits, `pnpm run build` then `pnpm test` (or `pnpm run phase5-gates` before larger changes). If `workspace-kit` is not on your `PATH`, use `node dist/cli.js …` from the repo root (same as above).
+
+## Quick start (use the package in another project)
+
+```bash
+npm install @workflow-cannon/workspace-kit
+npx workspace-kit --help
+```
+
+Or with pnpm: `pnpm add @workflow-cannon/workspace-kit` then `pnpm exec workspace-kit --help`.
+
+## What this repo contains
+
+| Area | What |
+| --- | --- |
+| **CLI** | `workspace-kit` — `doctor`, `config`, `run <module-command>` (see `workspace-kit run` with no args for the list). |
+| **Task engine** | Canonical queue in `.workspace-kit/tasks/state.json`; lifecycle via `run-transition`. Wishlist ideation uses ids `W###` (see maintainer runbooks). |
+| **Docs** | Maintainer process, roadmap, and changelog under `docs/maintainers/`. |
+| **Cursor extension** (optional) | Thin UI in `extensions/cursor-workflow-cannon/` — build with `pnpm run ui:prepare`. |
+
+There is **no** built-in IDE slash command like `/qt` from this package; editor integrations are **your** config (e.g. `.cursor/commands/`), while **`workspace-kit`** is the supported CLI.
+
+## Policy and approvals (read this before mutating state)
+
+Sensitive `workspace-kit run` commands require JSON **`policyApproval`** in the third CLI argument. Chat approval is not enough. Env-based approval applies to `init` / `upgrade` / `config`, not the `run` path.
+
+- **Human guide:** [`docs/maintainers/POLICY-APPROVAL.md`](POLICY-APPROVAL.md)
+- **Copy-paste table:** [`docs/maintainers/AGENT-CLI-MAP.md`](AGENT-CLI-MAP.md)
+
+## Project status and roadmap
+
+Release cadence, phase history, and strategic decisions: [`docs/maintainers/ROADMAP.md`](ROADMAP.md). **Live execution queue:** `.workspace-kit/tasks/state.json` (`status` and `id` are authoritative — not this README’s milestone bullets).
+
+Snapshot: [`docs/maintainers/data/workspace-kit-status.yaml`](data/workspace-kit-status.yaml).
+
+## Where to go next
+
+| Goal | Start here |
+| --- | --- |
+| Goals, trade-offs, gates | [`.ai/PRINCIPLES.md`](../.ai/PRINCIPLES.md) |
+| Roadmap & versions | [`ROADMAP.md`](ROADMAP.md) |
+| Changelog | [`CHANGELOG.md`](CHANGELOG.md) |
+| Release process | [`RELEASING.md`](RELEASING.md) |
+| Glossary | [`TERMS.md`](TERMS.md) |
+| Architecture | [`ARCHITECTURE.md`](ARCHITECTURE.md) |
+| Agent/CLI execution | [`AGENTS.md`](AGENTS.md) |
+
+## License
+
+MIT. See [`LICENSE`](../LICENSE) at the repository root.