@workflow-cannon/workspace-kit 0.2.0 → 0.4.0

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

@@ -1,7 +1,29 @@
+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";
+function taskStorePath(ctx) {
+    const tasks = ctx.effectiveConfig?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return undefined;
+    }
+    const p = tasks.storeRelativePath;
+    return typeof p === "string" && p.trim().length > 0 ? p.trim() : undefined;
+}
 export const taskEngineModule = {
     registration: {
         id: "task-engine",
-        version: "0.1.0",
+        version: "0.4.0",
         contractVersion: "1",
         capabilities: ["task-engine"],
         dependsOn: [],
@@ -22,9 +44,222 @@ 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, taskStorePath(ctx));
+        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
+                : ctx.resolvedActor !== undefined
+                    ? ctx.resolvedActor
+                    : 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;

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

@@ -0,0 +1,51 @@
+const PRIORITY_ORDER = {
+    P1: 0,
+    P2: 1,
+    P3: 2
+};
+function priorityRank(task) {
+    return PRIORITY_ORDER[task.priority ?? ""] ?? 99;
+}
+function buildStateSummary(tasks) {
+    const counts = {
+        proposed: 0,
+        ready: 0,
+        in_progress: 0,
+        blocked: 0,
+        completed: 0,
+        cancelled: 0
+    };
+    for (const task of tasks) {
+        counts[task.status]++;
+    }
+    return { ...counts, total: tasks.length };
+}
+function buildBlockingAnalysis(tasks) {
+    const completedIds = new Set(tasks.filter((t) => t.status === "completed").map((t) => t.id));
+    const entries = [];
+    for (const task of tasks) {
+        if (task.status !== "blocked")
+            continue;
+        const deps = task.dependsOn ?? [];
+        const blockedBy = deps.filter((depId) => !completedIds.has(depId));
+        if (blockedBy.length > 0) {
+            entries.push({
+                taskId: task.id,
+                blockedBy,
+                blockingCount: blockedBy.length
+            });
+        }
+    }
+    return entries.sort((a, b) => b.blockingCount - a.blockingCount);
+}
+export function getNextActions(tasks) {
+    const readyQueue = tasks
+        .filter((t) => t.status === "ready")
+        .sort((a, b) => priorityRank(a) - priorityRank(b));
+    return {
+        readyQueue,
+        suggestedNext: readyQueue[0] ?? null,
+        stateSummary: buildStateSummary(tasks),
+        blockingAnalysis: buildBlockingAnalysis(tasks)
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { TaskEntity, TaskStatus, TransitionGuard, GuardResult, TransitionContext, TaskEngineErrorCode } from "./types.js";
+export declare class TaskEngineError extends Error {
+    readonly code: TaskEngineErrorCode;
+    constructor(code: TaskEngineErrorCode, message: string);
+}
+export declare function isTransitionAllowed(from: TaskStatus, to: TaskStatus): boolean;
+export declare function getTransitionAction(from: TaskStatus, to: TaskStatus): string | undefined;
+export declare function resolveTargetState(from: TaskStatus, action: string): TaskStatus | undefined;
+export declare function getAllowedTransitionsFrom(status: TaskStatus): {
+    to: TaskStatus;
+    action: string;
+}[];
+export declare const stateValidityGuard: TransitionGuard;
+export declare const dependencyCheckGuard: TransitionGuard;
+export declare class TransitionValidator {
+    private readonly guards;
+    constructor(customGuards?: TransitionGuard[]);
+    validate(task: TaskEntity, targetState: TaskStatus, context: TransitionContext): {
+        allowed: boolean;
+        guardResults: GuardResult[];
+    };
+    getGuards(): TransitionGuard[];
+}

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

@@ -0,0 +1,109 @@
+export class TaskEngineError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "TaskEngineError";
+        this.code = code;
+    }
+}
+const ALLOWED_TRANSITIONS = {
+    "proposed->ready": { action: "accept" },
+    "proposed->cancelled": { action: "reject" },
+    "ready->in_progress": { action: "start" },
+    "ready->blocked": { action: "block" },
+    "ready->cancelled": { action: "cancel" },
+    "in_progress->completed": { action: "complete" },
+    "in_progress->blocked": { action: "block" },
+    "in_progress->ready": { action: "pause" },
+    "blocked->ready": { action: "unblock" },
+    "blocked->cancelled": { action: "cancel" }
+};
+export function isTransitionAllowed(from, to) {
+    return `${from}->${to}` in ALLOWED_TRANSITIONS;
+}
+export function getTransitionAction(from, to) {
+    return ALLOWED_TRANSITIONS[`${from}->${to}`]?.action;
+}
+export function resolveTargetState(from, action) {
+    for (const [key, entry] of Object.entries(ALLOWED_TRANSITIONS)) {
+        if (entry.action === action && key.startsWith(`${from}->`)) {
+            return key.split("->")[1];
+        }
+    }
+    return undefined;
+}
+export function getAllowedTransitionsFrom(status) {
+    const results = [];
+    for (const [key, entry] of Object.entries(ALLOWED_TRANSITIONS)) {
+        const [from, to] = key.split("->");
+        if (from === status) {
+            results.push({ to, action: entry.action });
+        }
+    }
+    return results;
+}
+export const stateValidityGuard = {
+    name: "state-validity",
+    canTransition(task, targetState) {
+        if (isTransitionAllowed(task.status, targetState)) {
+            return { allowed: true, guardName: "state-validity" };
+        }
+        return {
+            allowed: false,
+            guardName: "state-validity",
+            code: "invalid-transition",
+            message: `Transition from '${task.status}' to '${targetState}' is not allowed`
+        };
+    }
+};
+export const dependencyCheckGuard = {
+    name: "dependency-check",
+    canTransition(task, targetState, context) {
+        const needsDepCheck = (task.status === "ready" && targetState === "in_progress") ||
+            (task.status === "blocked" && targetState === "ready");
+        if (!needsDepCheck) {
+            return { allowed: true, guardName: "dependency-check" };
+        }
+        const deps = task.dependsOn ?? [];
+        if (deps.length === 0) {
+            return { allowed: true, guardName: "dependency-check" };
+        }
+        const taskMap = new Map(context.allTasks.map((t) => [t.id, t]));
+        const unsatisfied = [];
+        for (const depId of deps) {
+            const depTask = taskMap.get(depId);
+            if (!depTask || depTask.status !== "completed") {
+                unsatisfied.push(depId);
+            }
+        }
+        if (unsatisfied.length > 0) {
+            return {
+                allowed: false,
+                guardName: "dependency-check",
+                code: "dependency-unsatisfied",
+                message: `Dependencies not satisfied: ${unsatisfied.join(", ")}`
+            };
+        }
+        return { allowed: true, guardName: "dependency-check" };
+    }
+};
+export class TransitionValidator {
+    guards;
+    constructor(customGuards = []) {
+        this.guards = [stateValidityGuard, dependencyCheckGuard, ...customGuards];
+    }
+    validate(task, targetState, context) {
+        const guardResults = [];
+        for (const guard of this.guards) {
+            const result = guard.canTransition(task, targetState, context);
+            guardResults.push(result);
+            if (!result.allowed) {
+                return { allowed: false, guardResults };
+            }
+        }
+        return { allowed: true, guardResults };
+    }
+    getGuards() {
+        return [...this.guards];
+    }
+}