@workflow-cannon/workspace-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,157 @@
+import fs from "node:fs/promises";
+import { TaskEngineError } from "./transitions.js";
+const STATUS_MAP = {
+    "[p]": "proposed",
+    "[ ]": "ready",
+    "[~]": "in_progress",
+    "[!]": "blocked",
+    "[x]": "completed",
+    "[-]": "cancelled"
+};
+function parseTaskId(heading) {
+    const match = heading.match(/^###\s+\[[^\]]*\]\s+(T\d+)/);
+    return match?.[1] ?? null;
+}
+function parseStatus(heading) {
+    for (const [marker, status] of Object.entries(STATUS_MAP)) {
+        if (heading.includes(marker))
+            return status;
+    }
+    return "ready";
+}
+function parseTitle(heading) {
+    const match = heading.match(/^###\s+\[[^\]]*\]\s+T\d+\s+(.+)/);
+    return match?.[1]?.trim() ?? "Untitled";
+}
+function extractField(lines, prefix) {
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith(prefix)) {
+            return trimmed.slice(prefix.length).trim();
+        }
+    }
+    return undefined;
+}
+function extractListField(lines, fieldPrefix) {
+    const items = [];
+    let capturing = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith(fieldPrefix)) {
+            capturing = true;
+            continue;
+        }
+        if (capturing) {
+            if (/^\s{2,}-\s/.test(line)) {
+                items.push(line.replace(/^\s*-\s*/, "").trim());
+                continue;
+            }
+            if (trimmed.startsWith("- ")) {
+                capturing = false;
+                continue;
+            }
+            if (trimmed === "") {
+                continue;
+            }
+        }
+    }
+    return items;
+}
+function parseTaskIds(text) {
+    if (!text || text.trim() === "none")
+        return [];
+    const ids = [];
+    const matches = text.matchAll(/`?(T\d+)`?/g);
+    for (const m of matches) {
+        ids.push(m[1]);
+    }
+    return ids;
+}
+function parsePriority(text) {
+    if (!text)
+        return undefined;
+    const match = text.match(/(P[123])/);
+    return match?.[1];
+}
+function parsePhase(sectionHeading) {
+    const match = sectionHeading.match(/^##\s+(.+)/);
+    return match?.[1]?.trim();
+}
+export async function importTasksFromMarkdown(sourcePath) {
+    let content;
+    try {
+        content = await fs.readFile(sourcePath, "utf8");
+    }
+    catch (err) {
+        throw new TaskEngineError("import-parse-error", `Failed to read TASKS.md: ${err.message}`);
+    }
+    const lines = content.split("\n");
+    const tasks = [];
+    const errors = [];
+    let skipped = 0;
+    let currentPhase;
+    const now = new Date().toISOString();
+    let taskStartIdx = -1;
+    let taskLines = [];
+    function flushTask() {
+        if (taskStartIdx === -1 || taskLines.length === 0)
+            return;
+        const heading = taskLines[0];
+        const id = parseTaskId(heading);
+        if (!id) {
+            errors.push(`Line ${taskStartIdx + 1}: Could not parse task ID from heading`);
+            skipped++;
+            return;
+        }
+        const status = parseStatus(heading);
+        const title = parseTitle(heading);
+        const priorityStr = extractField(taskLines, "- Priority:");
+        const approach = extractField(taskLines, "- Approach:");
+        const dependsOnStr = extractField(taskLines, "- Depends on:");
+        const unblocksStr = extractField(taskLines, "- Unblocks:");
+        const technicalScope = extractListField(taskLines, "- Technical scope:");
+        const acceptanceCriteria = extractListField(taskLines, "- Acceptance criteria:");
+        const task = {
+            id,
+            status,
+            type: "workspace-kit",
+            title,
+            createdAt: now,
+            updatedAt: now,
+            priority: parsePriority(priorityStr),
+            dependsOn: parseTaskIds(dependsOnStr ?? ""),
+            unblocks: parseTaskIds(unblocksStr ?? ""),
+            phase: currentPhase,
+            approach: approach || undefined,
+            technicalScope: technicalScope.length > 0 ? technicalScope : undefined,
+            acceptanceCriteria: acceptanceCriteria.length > 0 ? acceptanceCriteria : undefined
+        };
+        tasks.push(task);
+    }
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith("## ") && !line.startsWith("### ")) {
+            flushTask();
+            taskStartIdx = -1;
+            taskLines = [];
+            currentPhase = parsePhase(line);
+            continue;
+        }
+        if (line.startsWith("### ")) {
+            flushTask();
+            taskStartIdx = i;
+            taskLines = [line];
+            continue;
+        }
+        if (taskStartIdx !== -1) {
+            taskLines.push(line);
+        }
+    }
+    flushTask();
+    return {
+        imported: tasks.length,
+        skipped,
+        errors,
+        tasks
+    };
+}

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

@@ -1,2 +1,9 @@
 import type { WorkflowModule } from "../../contracts/module-contract.js";
+export type { TaskEntity, TaskStatus, TaskPriority, TaskStoreDocument, TransitionEvidence, TransitionGuard, TransitionContext, GuardResult, TaskEngineError as TaskEngineErrorType, TaskEngineErrorCode, TaskAdapter, TaskAdapterCapability, NextActionSuggestion, BlockingAnalysisEntry } from "./types.js";
+export { TaskStore } from "./store.js";
+export { TransitionService } from "./service.js";
+export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
+export { generateTasksMd } from "./generator.js";
+export { importTasksFromMarkdown } from "./importer.js";
+export { getNextActions } from "./suggestions.js";
 export declare const taskEngineModule: WorkflowModule;

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

@@ -1,7 +1,21 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { TaskStore } from "./store.js";
+import { TransitionService } from "./service.js";
+import { TaskEngineError } from "./transitions.js";
+import { generateTasksMd } from "./generator.js";
+import { importTasksFromMarkdown } from "./importer.js";
+import { getNextActions } from "./suggestions.js";
+export { TaskStore } from "./store.js";
+export { TransitionService } from "./service.js";
+export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
+export { generateTasksMd } from "./generator.js";
+export { importTasksFromMarkdown } from "./importer.js";
+export { getNextActions } from "./suggestions.js";
 export const taskEngineModule = {
     registration: {
         id: "task-engine",
-        version: "0.1.0",
+        version: "0.3.0",
         contractVersion: "1",
         capabilities: ["task-engine"],
         dependsOn: [],
@@ -22,9 +36,218 @@ export const taskEngineModule = {
                 {
                     name: "run-transition",
                     file: "run-transition.md",
-                    description: "Run a validated task status transition."
+                    description: "Execute a validated task status transition."
+                },
+                {
+                    name: "get-task",
+                    file: "get-task.md",
+                    description: "Retrieve a single task by ID."
+                },
+                {
+                    name: "list-tasks",
+                    file: "list-tasks.md",
+                    description: "List tasks with optional status/phase filters."
+                },
+                {
+                    name: "get-ready-queue",
+                    file: "get-ready-queue.md",
+                    description: "Get ready tasks sorted by priority."
+                },
+                {
+                    name: "import-tasks",
+                    file: "import-tasks.md",
+                    description: "One-time import from TASKS.md into engine state."
+                },
+                {
+                    name: "generate-tasks-md",
+                    file: "generate-tasks-md.md",
+                    description: "Generate read-only TASKS.md from engine state."
+                },
+                {
+                    name: "get-next-actions",
+                    file: "get-next-actions.md",
+                    description: "Get prioritized next-action suggestions with blocking analysis."
                 }
             ]
         }
+    },
+    async onCommand(command, ctx) {
+        const args = command.args ?? {};
+        const store = new TaskStore(ctx.workspacePath);
+        try {
+            await store.load();
+        }
+        catch (err) {
+            if (err instanceof TaskEngineError) {
+                return { ok: false, code: err.code, message: err.message };
+            }
+            return {
+                ok: false,
+                code: "storage-read-error",
+                message: `Failed to load task store: ${err.message}`
+            };
+        }
+        if (command.name === "run-transition") {
+            const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
+            const action = typeof args.action === "string" ? args.action : undefined;
+            const actor = typeof args.actor === "string" ? args.actor : undefined;
+            if (!taskId || !action) {
+                return {
+                    ok: false,
+                    code: "invalid-task-schema",
+                    message: "run-transition requires 'taskId' and 'action' arguments"
+                };
+            }
+            try {
+                const service = new TransitionService(store);
+                const result = await service.runTransition({ taskId, action, actor });
+                return {
+                    ok: true,
+                    code: "transition-applied",
+                    message: `${taskId}: ${result.evidence.fromState} → ${result.evidence.toState} (${action})`,
+                    data: {
+                        evidence: result.evidence,
+                        autoUnblocked: result.autoUnblocked
+                    }
+                };
+            }
+            catch (err) {
+                if (err instanceof TaskEngineError) {
+                    return { ok: false, code: err.code, message: err.message };
+                }
+                return {
+                    ok: false,
+                    code: "invalid-transition",
+                    message: err.message
+                };
+            }
+        }
+        if (command.name === "get-task") {
+            const taskId = typeof args.taskId === "string" ? args.taskId : undefined;
+            if (!taskId) {
+                return {
+                    ok: false,
+                    code: "invalid-task-schema",
+                    message: "get-task requires 'taskId' argument"
+                };
+            }
+            const task = store.getTask(taskId);
+            if (!task) {
+                return {
+                    ok: false,
+                    code: "task-not-found",
+                    message: `Task '${taskId}' not found`
+                };
+            }
+            return {
+                ok: true,
+                code: "task-retrieved",
+                data: { task }
+            };
+        }
+        if (command.name === "list-tasks") {
+            const statusFilter = typeof args.status === "string" ? args.status : undefined;
+            const phaseFilter = typeof args.phase === "string" ? args.phase : undefined;
+            let tasks = store.getAllTasks();
+            if (statusFilter) {
+                tasks = tasks.filter((t) => t.status === statusFilter);
+            }
+            if (phaseFilter) {
+                tasks = tasks.filter((t) => t.phase === phaseFilter);
+            }
+            return {
+                ok: true,
+                code: "tasks-listed",
+                message: `Found ${tasks.length} tasks`,
+                data: { tasks, count: tasks.length }
+            };
+        }
+        if (command.name === "get-ready-queue") {
+            const tasks = store.getAllTasks();
+            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);
+            });
+            return {
+                ok: true,
+                code: "ready-queue-retrieved",
+                message: `${ready.length} tasks in ready queue`,
+                data: { tasks: ready, count: ready.length }
+            };
+        }
+        if (command.name === "import-tasks") {
+            const sourcePath = typeof args.sourcePath === "string"
+                ? path.resolve(ctx.workspacePath, args.sourcePath)
+                : path.resolve(ctx.workspacePath, "docs/maintainers/TASKS.md");
+            try {
+                const result = await importTasksFromMarkdown(sourcePath);
+                store.replaceAllTasks(result.tasks);
+                await store.save();
+                return {
+                    ok: true,
+                    code: "tasks-imported",
+                    message: `Imported ${result.imported} tasks (${result.skipped} skipped)`,
+                    data: {
+                        imported: result.imported,
+                        skipped: result.skipped,
+                        errors: result.errors
+                    }
+                };
+            }
+            catch (err) {
+                if (err instanceof TaskEngineError) {
+                    return { ok: false, code: err.code, message: err.message };
+                }
+                return {
+                    ok: false,
+                    code: "import-parse-error",
+                    message: err.message
+                };
+            }
+        }
+        if (command.name === "generate-tasks-md") {
+            const outputPath = typeof args.outputPath === "string"
+                ? path.resolve(ctx.workspacePath, args.outputPath)
+                : path.resolve(ctx.workspacePath, "docs/maintainers/TASKS.md");
+            const tasks = store.getAllTasks();
+            const markdown = generateTasksMd(tasks);
+            try {
+                await fs.mkdir(path.dirname(outputPath), { recursive: true });
+                await fs.writeFile(outputPath, markdown, "utf8");
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    code: "storage-write-error",
+                    message: `Failed to write TASKS.md: ${err.message}`
+                };
+            }
+            return {
+                ok: true,
+                code: "tasks-md-generated",
+                message: `Generated TASKS.md with ${tasks.length} tasks`,
+                data: { outputPath, taskCount: tasks.length }
+            };
+        }
+        if (command.name === "get-next-actions") {
+            const tasks = store.getAllTasks();
+            const suggestion = getNextActions(tasks);
+            return {
+                ok: true,
+                code: "next-actions-retrieved",
+                message: suggestion.suggestedNext
+                    ? `Suggested next: ${suggestion.suggestedNext.id} — ${suggestion.suggestedNext.title}`
+                    : "No tasks in ready queue",
+                data: suggestion
+            };
+        }
+        return {
+            ok: false,
+            code: "unsupported-command",
+            message: `Task Engine does not support command '${command.name}'`
+        };
     }
 };

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

@@ -0,0 +1,21 @@
+import type { TransitionEvidence, TransitionGuard } from "./types.js";
+import { TransitionValidator } from "./transitions.js";
+import { TaskStore } from "./store.js";
+export type TransitionRequest = {
+    taskId: string;
+    action: string;
+    actor?: string;
+};
+export type TransitionResult = {
+    evidence: TransitionEvidence;
+    autoUnblocked: TransitionEvidence[];
+};
+export declare class TransitionService {
+    private readonly store;
+    private readonly validator;
+    constructor(store: TaskStore, customGuards?: TransitionGuard[]);
+    runTransition(request: TransitionRequest): Promise<TransitionResult>;
+    private autoUnblock;
+    getStore(): TaskStore;
+    getValidator(): TransitionValidator;
+}

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

@@ -0,0 +1,105 @@
+import crypto from "node:crypto";
+import { TaskEngineError, TransitionValidator, getTransitionAction, resolveTargetState } from "./transitions.js";
+export class TransitionService {
+    store;
+    validator;
+    constructor(store, customGuards = []) {
+        this.store = store;
+        this.validator = new TransitionValidator(customGuards);
+    }
+    async runTransition(request) {
+        const task = this.store.getTask(request.taskId);
+        if (!task) {
+            throw new TaskEngineError("task-not-found", `Task '${request.taskId}' not found`);
+        }
+        const targetState = resolveTargetState(task.status, request.action);
+        if (!targetState) {
+            throw new TaskEngineError("invalid-transition", `Action '${request.action}' is not valid from state '${task.status}'`);
+        }
+        const timestamp = new Date().toISOString();
+        const context = {
+            allTasks: this.store.getAllTasks(),
+            timestamp,
+            actor: request.actor
+        };
+        const validation = this.validator.validate(task, targetState, context);
+        if (!validation.allowed) {
+            const rejection = validation.guardResults.find((r) => !r.allowed);
+            if (rejection?.code === "dependency-unsatisfied") {
+                throw new TaskEngineError("dependency-unsatisfied", rejection.message ?? "Dependencies not satisfied");
+            }
+            if (rejection?.code === "invalid-transition") {
+                throw new TaskEngineError("invalid-transition", rejection.message ?? "Invalid transition");
+            }
+            throw new TaskEngineError("guard-rejected", rejection?.message ?? "Transition rejected by guard");
+        }
+        const fromState = task.status;
+        const updatedTask = {
+            ...task,
+            status: targetState,
+            updatedAt: timestamp
+        };
+        this.store.updateTask(updatedTask);
+        const action = getTransitionAction(fromState, targetState) ?? request.action;
+        const autoUnblockResults = targetState === "completed"
+            ? this.autoUnblock(request.taskId, timestamp, request.actor)
+            : [];
+        const evidence = {
+            transitionId: `${request.taskId}-${timestamp}-${crypto.randomUUID().slice(0, 8)}`,
+            taskId: request.taskId,
+            fromState,
+            toState: targetState,
+            action,
+            guardResults: validation.guardResults,
+            dependentsUnblocked: autoUnblockResults.map((r) => r.taskId),
+            timestamp,
+            actor: request.actor
+        };
+        this.store.addEvidence(evidence);
+        for (const unblockEvidence of autoUnblockResults) {
+            this.store.addEvidence(unblockEvidence);
+        }
+        await this.store.save();
+        return { evidence, autoUnblocked: autoUnblockResults };
+    }
+    autoUnblock(completedTaskId, timestamp, actor) {
+        const results = [];
+        const allTasks = this.store.getAllTasks();
+        const dependents = allTasks.filter((t) => t.status === "blocked" && t.dependsOn?.includes(completedTaskId));
+        for (const dependent of dependents) {
+            const deps = dependent.dependsOn ?? [];
+            const allDepsComplete = deps.every((depId) => {
+                if (depId === completedTaskId)
+                    return true;
+                const depTask = this.store.getTask(depId);
+                return depTask?.status === "completed";
+            });
+            if (!allDepsComplete)
+                continue;
+            const updatedDependent = {
+                ...dependent,
+                status: "ready",
+                updatedAt: timestamp
+            };
+            this.store.updateTask(updatedDependent);
+            results.push({
+                transitionId: `${dependent.id}-${timestamp}-${crypto.randomUUID().slice(0, 8)}`,
+                taskId: dependent.id,
+                fromState: "blocked",
+                toState: "ready",
+                action: "unblock",
+                guardResults: [{ allowed: true, guardName: "auto-unblock" }],
+                dependentsUnblocked: [],
+                timestamp,
+                actor
+            });
+        }
+        return results;
+    }
+    getStore() {
+        return this.store;
+    }
+    getValidator() {
+        return this.validator;
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { TaskEntity, TransitionEvidence } from "./types.js";
+export declare class TaskStore {
+    private document;
+    private readonly filePath;
+    constructor(workspacePath: string, storePath?: string);
+    load(): Promise<void>;
+    save(): Promise<void>;
+    getAllTasks(): TaskEntity[];
+    getTask(id: string): TaskEntity | undefined;
+    addTask(task: TaskEntity): void;
+    updateTask(task: TaskEntity): void;
+    addEvidence(evidence: TransitionEvidence): void;
+    getTransitionLog(): TransitionEvidence[];
+    replaceAllTasks(tasks: TaskEntity[]): void;
+    getFilePath(): string;
+}

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

@@ -0,0 +1,88 @@
+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";
+function emptyStore() {
+    return {
+        schemaVersion: 1,
+        tasks: [],
+        transitionLog: [],
+        lastUpdated: new Date().toISOString()
+    };
+}
+export class TaskStore {
+    document;
+    filePath;
+    constructor(workspacePath, storePath) {
+        this.filePath = path.resolve(workspacePath, storePath ?? DEFAULT_STORE_PATH);
+        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;
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                this.document = emptyStore();
+                return;
+            }
+            if (err instanceof TaskEngineError)
+                throw err;
+            throw new TaskEngineError("storage-read-error", `Failed to read task store: ${err.message}`);
+        }
+    }
+    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}`);
+        }
+    }
+    getAllTasks() {
+        return [...this.document.tasks];
+    }
+    getTask(id) {
+        return this.document.tasks.find((t) => t.id === id);
+    }
+    addTask(task) {
+        if (this.document.tasks.some((t) => t.id === task.id)) {
+            throw new TaskEngineError("duplicate-task-id", `Task '${task.id}' already exists`);
+        }
+        this.document.tasks.push({ ...task });
+    }
+    updateTask(task) {
+        const idx = this.document.tasks.findIndex((t) => t.id === task.id);
+        if (idx === -1) {
+            throw new TaskEngineError("task-not-found", `Task '${task.id}' not found`);
+        }
+        this.document.tasks[idx] = { ...task };
+    }
+    addEvidence(evidence) {
+        this.document.transitionLog.push(evidence);
+    }
+    getTransitionLog() {
+        return [...this.document.transitionLog];
+    }
+    replaceAllTasks(tasks) {
+        this.document.tasks = tasks.map((t) => ({ ...t }));
+    }
+    getFilePath() {
+        return this.filePath;
+    }
+}

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

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