@workflow-cannon/workspace-kit 0.2.0 → 0.3.0

package/dist/cli.js

@@ -2,6 +2,13 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { ModuleRegistry } from "./core/module-registry.js";
+import { ModuleCommandRouter } from "./core/module-command-router.js";
+import { documentationModule } from "./modules/documentation/index.js";
+import { taskEngineModule } from "./modules/task-engine/index.js";
+import { approvalsModule } from "./modules/approvals/index.js";
+import { planningModule } from "./modules/planning/index.js";
+import { improvementModule } from "./modules/improvement/index.js";
 const EXIT_SUCCESS = 0;
 const EXIT_VALIDATION_FAILURE = 1;
 const EXIT_USAGE_ERROR = 2;
@@ -305,7 +312,7 @@ export async function runCli(args, options = {}) {
     const writeError = options.writeError ?? console.error;
     const [command] = args;
     if (!command) {
-        writeError("Usage: workspace-kit <init|doctor|check|upgrade>");
+        writeError("Usage: workspace-kit <init|doctor|check|upgrade|drift-check|run>");
         return EXIT_USAGE_ERROR;
     }
     if (command === "init") {
@@ -525,8 +532,59 @@ export async function runCli(args, options = {}) {
         }
         return EXIT_SUCCESS;
     }
+    if (command === "run") {
+        const allModules = [
+            documentationModule,
+            taskEngineModule,
+            approvalsModule,
+            planningModule,
+            improvementModule
+        ];
+        const registry = new ModuleRegistry(allModules);
+        const router = new ModuleCommandRouter(registry);
+        const subcommand = args[1];
+        if (!subcommand) {
+            const commands = router.listCommands();
+            writeLine("Available module commands:");
+            for (const cmd of commands) {
+                const desc = cmd.description ? ` — ${cmd.description}` : "";
+                writeLine(`  ${cmd.name} (${cmd.moduleId})${desc}`);
+            }
+            writeLine("");
+            writeLine("Usage: workspace-kit run <command> [json-args]");
+            return EXIT_SUCCESS;
+        }
+        let commandArgs = {};
+        if (args[2]) {
+            try {
+                const parsed = JSON.parse(args[2]);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    commandArgs = parsed;
+                }
+                else {
+                    writeError("Command args must be a JSON object.");
+                    return EXIT_USAGE_ERROR;
+                }
+            }
+            catch {
+                writeError(`Invalid JSON args: ${args[2]}`);
+                return EXIT_USAGE_ERROR;
+            }
+        }
+        const ctx = { runtimeVersion: "0.1", workspacePath: cwd };
+        try {
+            const result = await router.execute(subcommand, commandArgs, ctx);
+            writeLine(JSON.stringify(result, null, 2));
+            return result.ok ? EXIT_SUCCESS : EXIT_VALIDATION_FAILURE;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            writeError(`Module command failed: ${message}`);
+            return EXIT_INTERNAL_ERROR;
+        }
+    }
     if (command !== "doctor") {
-        writeError(`Unknown command '${command}'. Supported commands: init, doctor, check, upgrade, drift-check.`);
+        writeError(`Unknown command '${command}'. Supported commands: init, doctor, check, upgrade, drift-check, run.`);
         return EXIT_USAGE_ERROR;
     }
     const issues = [];

package/dist/modules/documentation/index.d.ts

@@ -1,3 +1,3 @@
 import type { WorkflowModule } from "../../contracts/module-contract.js";
-export type { DocumentationConflict, DocumentationGenerateOptions, DocumentationGenerateResult, DocumentationGenerationEvidence, DocumentationValidationIssue } from "./types.js";
+export type { DocumentationBatchResult, DocumentationConflict, DocumentationGenerateOptions, DocumentationGenerateResult, DocumentationGenerationEvidence, DocumentationValidationIssue } from "./types.js";
 export declare const documentationModule: WorkflowModule;

package/dist/modules/documentation/index.js

@@ -1,8 +1,19 @@
-import { generateDocument } from "./runtime.js";
+import { generateDocument, generateAllDocuments } from "./runtime.js";
+function parseOptions(raw) {
+    return {
+        dryRun: typeof raw.dryRun === "boolean" ? raw.dryRun : undefined,
+        overwrite: typeof raw.overwrite === "boolean" ? raw.overwrite : undefined,
+        overwriteAi: typeof raw.overwriteAi === "boolean" ? raw.overwriteAi : undefined,
+        overwriteHuman: typeof raw.overwriteHuman === "boolean" ? raw.overwriteHuman : undefined,
+        strict: typeof raw.strict === "boolean" ? raw.strict : undefined,
+        maxValidationAttempts: typeof raw.maxValidationAttempts === "number" ? raw.maxValidationAttempts : undefined,
+        allowWithoutTemplate: typeof raw.allowWithoutTemplate === "boolean" ? raw.allowWithoutTemplate : undefined,
+    };
+}
 export const documentationModule = {
     registration: {
         id: "documentation",
-        version: "0.1.0",
+        version: "0.2.0",
         contractVersion: "1",
         capabilities: ["documentation"],
         dependsOn: [],
@@ -23,51 +34,65 @@ export const documentationModule = {
                 {
                     name: "document-project",
                     file: "document-project.md",
-                    description: "Generate aligned project docs for .ai and docs surfaces."
+                    description: "Generate all project docs from templates to .ai and docs/maintainers surfaces."
+                },
+                {
+                    name: "generate-document",
+                    file: "generate-document.md",
+                    description: "Generate a single document by type for .ai and docs/maintainers surfaces."
                 }
             ]
         }
     },
     async onCommand(command, ctx) {
-        if (command.name !== "document-project" && command.name !== "generate-document") {
-            return {
-                ok: false,
-                code: "unsupported-command",
-                message: `Documentation module does not support command '${command.name}'`
-            };
-        }
         const args = command.args ?? {};
         const rawOptions = typeof args.options === "object" && args.options !== null
             ? args.options
-            : undefined;
-        const options = rawOptions
-            ? {
-                dryRun: typeof rawOptions.dryRun === "boolean" ? rawOptions.dryRun : undefined,
-                overwrite: typeof rawOptions.overwrite === "boolean" ? rawOptions.overwrite : undefined,
-                strict: typeof rawOptions.strict === "boolean" ? rawOptions.strict : undefined,
-                maxValidationAttempts: typeof rawOptions.maxValidationAttempts === "number"
-                    ? rawOptions.maxValidationAttempts
-                    : undefined,
-                allowWithoutTemplate: typeof rawOptions.allowWithoutTemplate === "boolean"
-                    ? rawOptions.allowWithoutTemplate
-                    : undefined
-            }
-            : undefined;
-        const result = await generateDocument({
-            documentType: typeof args.documentType === "string" ? args.documentType : undefined,
-            options
-        }, ctx);
+            : {};
+        const options = parseOptions(rawOptions);
+        if (command.name === "document-project") {
+            const batchResult = await generateAllDocuments({ options }, ctx);
+            return {
+                ok: batchResult.ok,
+                code: batchResult.ok ? "documented-project" : "documentation-batch-failed",
+                message: batchResult.ok
+                    ? `Generated ${batchResult.summary.succeeded} documents (${batchResult.summary.skipped} skipped)`
+                    : `Batch failed: ${batchResult.summary.failed} of ${batchResult.summary.total} documents failed`,
+                data: {
+                    summary: batchResult.summary,
+                    results: batchResult.results.map((r) => ({
+                        documentType: r.evidence.documentType,
+                        ok: r.ok,
+                        aiOutputPath: r.aiOutputPath,
+                        humanOutputPath: r.humanOutputPath,
+                        filesWritten: r.evidence.filesWritten,
+                        filesSkipped: r.evidence.filesSkipped,
+                    }))
+                }
+            };
+        }
+        if (command.name === "generate-document") {
+            const result = await generateDocument({
+                documentType: typeof args.documentType === "string" ? args.documentType : undefined,
+                options
+            }, ctx);
+            return {
+                ok: result.ok,
+                code: result.ok ? "generated-document" : "generation-failed",
+                message: result.ok
+                    ? `Generated document '${args.documentType ?? "unknown"}'`
+                    : `Failed to generate document '${args.documentType ?? "unknown"}'`,
+                data: {
+                    aiOutputPath: result.aiOutputPath,
+                    humanOutputPath: result.humanOutputPath,
+                    evidence: result.evidence
+                }
+            };
+        }
         return {
-            ok: result.ok,
-            code: result.ok ? "generated-document" : "generation-failed",
-            message: result.ok
-                ? `Generated document '${args.documentType ?? "unknown"}'`
-                : `Failed to generate document '${args.documentType ?? "unknown"}'`,
-            data: {
-                aiOutputPath: result.aiOutputPath,
-                humanOutputPath: result.humanOutputPath,
-                evidence: result.evidence
-            }
+            ok: false,
+            code: "unsupported-command",
+            message: `Documentation module does not support command '${command.name}'`
         };
     }
 };

package/dist/modules/documentation/runtime.d.ts

@@ -1,8 +1,12 @@
-import type { DocumentationGenerateOptions, DocumentationGenerateResult } from "./types.js";
+import type { DocumentationBatchResult, DocumentationGenerateOptions, DocumentationGenerateResult } from "./types.js";
 import type { ModuleLifecycleContext } from "../../contracts/module-contract.js";
 type GenerateDocumentArgs = {
     documentType?: string;
     options?: DocumentationGenerateOptions;
 };
 export declare function generateDocument(args: GenerateDocumentArgs, ctx: ModuleLifecycleContext): Promise<DocumentationGenerateResult>;
+type GenerateAllDocumentsArgs = {
+    options?: DocumentationGenerateOptions;
+};
+export declare function generateAllDocuments(args: GenerateAllDocumentsArgs, ctx: ModuleLifecycleContext): Promise<DocumentationBatchResult>;
 export {};

package/dist/modules/documentation/runtime.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { resolve, sep } from "node:path";
+import { readdir } from "node:fs/promises";
 function isPathWithinRoot(path, root) {
     return path === root || path.startsWith(`${root}${sep}`);
 }
@@ -93,6 +94,7 @@ export async function generateDocument(args, ctx) {
                 documentType: "unknown",
                 filesRead: [],
                 filesWritten: [],
+                filesSkipped: [],
                 validationIssues: [
                     {
                         check: "template-resolution",
@@ -110,6 +112,7 @@ export async function generateDocument(args, ctx) {
     const config = await loadRuntimeConfig(ctx.workspacePath);
     const filesRead = [];
     const filesWritten = [];
+    const filesSkipped = [];
     const validationIssues = [];
     const conflicts = [];
     const aiRoot = resolve(ctx.workspacePath, config.aiRoot.replace(/^\//, ""));
@@ -124,6 +127,7 @@ export async function generateDocument(args, ctx) {
                 documentType,
                 filesRead,
                 filesWritten,
+                filesSkipped,
                 validationIssues: [
                     {
                         check: "write-boundary",
@@ -156,6 +160,7 @@ export async function generateDocument(args, ctx) {
                     documentType,
                     filesRead,
                     filesWritten,
+                    filesSkipped,
                     validationIssues,
                     conflicts,
                     attemptsUsed: 0,
@@ -190,6 +195,7 @@ export async function generateDocument(args, ctx) {
                 documentType,
                 filesRead,
                 filesWritten,
+                filesSkipped,
                 validationIssues,
                 conflicts,
                 attemptsUsed,
@@ -218,6 +224,7 @@ export async function generateDocument(args, ctx) {
                 documentType,
                 filesRead,
                 filesWritten,
+                filesSkipped,
                 validationIssues,
                 conflicts,
                 attemptsUsed,
@@ -233,6 +240,7 @@ export async function generateDocument(args, ctx) {
                 documentType,
                 filesRead,
                 filesWritten,
+                filesSkipped,
                 validationIssues,
                 conflicts,
                 attemptsUsed,
@@ -241,13 +249,18 @@ export async function generateDocument(args, ctx) {
         };
     }
     if (!options.dryRun) {
-        if (!options.overwrite && (existsSync(aiOutputPath) || existsSync(humanOutputPath))) {
+        const canOverwriteAi = options.overwriteAi ?? options.overwrite ?? true;
+        const canOverwriteHuman = options.overwriteHuman ?? options.overwrite ?? true;
+        const aiExists = existsSync(aiOutputPath);
+        const humanExists = existsSync(humanOutputPath);
+        if ((!canOverwriteAi && aiExists) && (!canOverwriteHuman && humanExists)) {
             return {
                 ok: false,
                 evidence: {
                     documentType,
                     filesRead,
                     filesWritten,
+                    filesSkipped: [aiOutputPath, humanOutputPath],
                     validationIssues: [
                         ...validationIssues,
                         {
@@ -264,9 +277,20 @@ export async function generateDocument(args, ctx) {
         }
         await mkdir(aiRoot, { recursive: true });
         await mkdir(humanRoot, { recursive: true });
-        await writeFile(aiOutputPath, `${aiOutput}\n`, "utf8");
-        await writeFile(humanOutputPath, `${humanOutput}\n`, "utf8");
-        filesWritten.push(aiOutputPath, humanOutputPath);
+        if (canOverwriteAi || !aiExists) {
+            await writeFile(aiOutputPath, `${aiOutput}\n`, "utf8");
+            filesWritten.push(aiOutputPath);
+        }
+        else {
+            filesSkipped.push(aiOutputPath);
+        }
+        if (canOverwriteHuman || !humanExists) {
+            await writeFile(humanOutputPath, `${humanOutput}\n`, "utf8");
+            filesWritten.push(humanOutputPath);
+        }
+        else {
+            filesSkipped.push(humanOutputPath);
+        }
     }
     return {
         ok: true,
@@ -276,6 +300,7 @@ export async function generateDocument(args, ctx) {
             documentType,
             filesRead,
             filesWritten,
+            filesSkipped,
             validationIssues,
             conflicts,
             attemptsUsed,
@@ -283,3 +308,61 @@ export async function generateDocument(args, ctx) {
         }
     };
 }
+export async function generateAllDocuments(args, ctx) {
+    const config = await loadRuntimeConfig(ctx.workspacePath);
+    const templatesDir = resolve(ctx.workspacePath, config.templatesRoot);
+    let templateFiles = [];
+    try {
+        const entries = await readdir(templatesDir);
+        templateFiles = entries.filter((f) => f.endsWith(".md")).sort();
+    }
+    catch {
+        return {
+            ok: false,
+            results: [],
+            summary: {
+                total: 0,
+                succeeded: 0,
+                failed: 1,
+                skipped: 0,
+                timestamp: new Date().toISOString()
+            }
+        };
+    }
+    const results = [];
+    let succeeded = 0;
+    let failed = 0;
+    let skipped = 0;
+    const batchOptions = {
+        ...args.options,
+        overwriteAi: args.options?.overwriteAi ?? false,
+        overwriteHuman: args.options?.overwriteHuman ?? true,
+        strict: args.options?.strict ?? false,
+    };
+    for (const templateFile of templateFiles) {
+        const result = await generateDocument({ documentType: templateFile, options: batchOptions }, ctx);
+        results.push(result);
+        if (result.ok) {
+            if (result.evidence.filesWritten.length > 0) {
+                succeeded++;
+            }
+            else {
+                skipped++;
+            }
+        }
+        else {
+            failed++;
+        }
+    }
+    return {
+        ok: failed === 0,
+        results,
+        summary: {
+            total: templateFiles.length,
+            succeeded,
+            failed,
+            skipped,
+            timestamp: new Date().toISOString()
+        }
+    };
+}

package/dist/modules/documentation/types.d.ts

@@ -1,6 +1,8 @@
 export type DocumentationGenerateOptions = {
     dryRun?: boolean;
     overwrite?: boolean;
+    overwriteAi?: boolean;
+    overwriteHuman?: boolean;
     strict?: boolean;
     maxValidationAttempts?: number;
     allowWithoutTemplate?: boolean;
@@ -19,6 +21,7 @@ export type DocumentationGenerationEvidence = {
     documentType: string;
     filesRead: string[];
     filesWritten: string[];
+    filesSkipped: string[];
     validationIssues: DocumentationValidationIssue[];
     conflicts: DocumentationConflict[];
     attemptsUsed: number;
@@ -30,3 +33,14 @@ export type DocumentationGenerateResult = {
     humanOutputPath?: string;
     evidence: DocumentationGenerationEvidence;
 };
+export type DocumentationBatchResult = {
+    ok: boolean;
+    results: DocumentationGenerateResult[];
+    summary: {
+        total: number;
+        succeeded: number;
+        failed: number;
+        skipped: number;
+        timestamp: string;
+    };
+};

package/dist/modules/index.d.ts

@@ -3,4 +3,5 @@ export { documentationModule } from "./documentation/index.js";
 export type { DocumentationConflict, DocumentationGenerateOptions, DocumentationGenerateResult, DocumentationGenerationEvidence, DocumentationValidationIssue } from "./documentation/types.js";
 export { improvementModule } from "./improvement/index.js";
 export { planningModule } from "./planning/index.js";
-export { taskEngineModule } from "./task-engine/index.js";
+export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";
+export type { TaskEntity, TaskStatus, TaskPriority, TaskStoreDocument, TransitionEvidence, TransitionGuard, TransitionContext, GuardResult, TaskEngineErrorCode, TaskAdapter, TaskAdapterCapability, NextActionSuggestion, BlockingAnalysisEntry } from "./task-engine/index.js";

package/dist/modules/index.js

@@ -2,4 +2,4 @@ export { approvalsModule } from "./approvals/index.js";
 export { documentationModule } from "./documentation/index.js";
 export { improvementModule } from "./improvement/index.js";
 export { planningModule } from "./planning/index.js";
-export { taskEngineModule } from "./task-engine/index.js";
+export { taskEngineModule, TaskStore, TransitionService, TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard, generateTasksMd, importTasksFromMarkdown, getNextActions } from "./task-engine/index.js";

package/dist/modules/task-engine/generator.d.ts

@@ -0,0 +1,2 @@
+import type { TaskEntity } from "./types.js";
+export declare function generateTasksMd(tasks: TaskEntity[]): string;

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

@@ -0,0 +1,101 @@
+const STATUS_MARKERS = {
+    proposed: "[p]",
+    ready: "[ ]",
+    in_progress: "[~]",
+    blocked: "[!]",
+    completed: "[x]",
+    cancelled: "[-]"
+};
+function groupByPhase(tasks) {
+    const groups = new Map();
+    for (const task of tasks) {
+        const phase = task.phase ?? "Uncategorized";
+        const group = groups.get(phase) ?? [];
+        group.push(task);
+        groups.set(phase, group);
+    }
+    return groups;
+}
+function buildReadyQueueLine(tasks) {
+    const ready = tasks
+        .filter((t) => t.status === "ready")
+        .sort((a, b) => {
+        const pa = a.priority ?? "P9";
+        const pb = b.priority ?? "P9";
+        return pa.localeCompare(pb);
+    });
+    if (ready.length === 0)
+        return "- Ready queue: _(empty)_";
+    return `- Ready queue: ${ready.map((t) => `\`${t.id}\``).join(", ")}`;
+}
+function buildCurrentPhase(tasks) {
+    const inProgress = tasks.filter((t) => t.status === "in_progress");
+    const ready = tasks.filter((t) => t.status === "ready");
+    const active = [...inProgress, ...ready];
+    if (active.length === 0)
+        return "- Current phase in execution: _(no active tasks)_";
+    const phases = [...new Set(active.map((t) => t.phase).filter(Boolean))];
+    if (phases.length === 0)
+        return "- Current phase in execution: _(unknown)_";
+    return `- Current phase in execution: _${phases[0]}_`;
+}
+function renderTask(task) {
+    const marker = STATUS_MARKERS[task.status] ?? "[ ]";
+    const lines = [];
+    lines.push(`### ${marker} ${task.id} ${task.title}`);
+    if (task.priority) {
+        lines.push(`- Priority: ${task.priority}`);
+    }
+    if (task.approach) {
+        lines.push(`- Approach: ${task.approach}`);
+    }
+    const deps = task.dependsOn ?? [];
+    lines.push(`- Depends on: ${deps.length > 0 ? deps.map((d) => `\`${d}\``).join(", ") : "none"}`);
+    const unblocks = task.unblocks ?? [];
+    if (unblocks.length > 0) {
+        lines.push(`- Unblocks: ${unblocks.map((u) => `\`${u}\``).join(", ")}`);
+    }
+    if (task.technicalScope && task.technicalScope.length > 0) {
+        lines.push("- Technical scope:");
+        for (const item of task.technicalScope) {
+            lines.push(`  - ${item}`);
+        }
+    }
+    if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+        lines.push("- Acceptance criteria:");
+        for (const item of task.acceptanceCriteria) {
+            lines.push(`  - ${item}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function generateTasksMd(tasks) {
+    const lines = [];
+    lines.push("# Workflow Cannon Tasks");
+    lines.push("");
+    lines.push("> This file is generated by the Task Engine. Do not edit manually.");
+    lines.push("");
+    lines.push("Status markers:");
+    lines.push("- `[p]` proposed");
+    lines.push("- `[ ]` ready");
+    lines.push("- `[~]` in progress");
+    lines.push("- `[!]` blocked");
+    lines.push("- `[x]` completed");
+    lines.push("- `[-]` cancelled");
+    lines.push("");
+    lines.push("## Current execution state");
+    lines.push("");
+    lines.push(buildCurrentPhase(tasks));
+    lines.push(buildReadyQueueLine(tasks));
+    lines.push("");
+    const phaseGroups = groupByPhase(tasks);
+    for (const [phase, phaseTasks] of phaseGroups) {
+        lines.push(`## ${phase}`);
+        lines.push("");
+        for (const task of phaseTasks) {
+            lines.push(renderTask(task));
+            lines.push("");
+        }
+    }
+    return lines.join("\n");
+}

package/dist/modules/task-engine/importer.d.ts

@@ -0,0 +1,8 @@
+import type { TaskEntity } from "./types.js";
+export type ImportResult = {
+    imported: number;
+    skipped: number;
+    errors: string[];
+    tasks: TaskEntity[];
+};
+export declare function importTasksFromMarkdown(sourcePath: string): Promise<ImportResult>;