@workflow-cannon/workspace-kit 0.1.0 → 0.3.0

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];
+    }
+}

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

@@ -0,0 +1,82 @@
+export type TaskStatus = "proposed" | "ready" | "in_progress" | "blocked" | "completed" | "cancelled";
+export type TaskPriority = "P1" | "P2" | "P3";
+export type TaskEntity = {
+    id: string;
+    status: TaskStatus;
+    type: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    priority?: TaskPriority;
+    dependsOn?: string[];
+    unblocks?: string[];
+    phase?: string;
+    metadata?: Record<string, unknown>;
+    ownership?: string;
+    approach?: string;
+    technicalScope?: string[];
+    acceptanceCriteria?: string[];
+};
+export type GuardResult = {
+    allowed: boolean;
+    guardName: string;
+    code?: string;
+    message?: string;
+};
+export type TransitionContext = {
+    allTasks: TaskEntity[];
+    timestamp: string;
+    actor?: string;
+};
+export type TransitionGuard = {
+    name: string;
+    canTransition: (task: TaskEntity, targetState: TaskStatus, context: TransitionContext) => GuardResult;
+};
+export type TransitionEvidence = {
+    transitionId: string;
+    taskId: string;
+    fromState: TaskStatus;
+    toState: TaskStatus;
+    action: string;
+    guardResults: GuardResult[];
+    dependentsUnblocked: string[];
+    timestamp: string;
+    actor?: string;
+};
+export type TaskStoreDocument = {
+    schemaVersion: 1;
+    tasks: TaskEntity[];
+    transitionLog: TransitionEvidence[];
+    lastUpdated: string;
+};
+export type TaskEngineError = {
+    code: TaskEngineErrorCode;
+    message: string;
+};
+export type TaskEngineErrorCode = "invalid-transition" | "guard-rejected" | "dependency-unsatisfied" | "task-not-found" | "duplicate-task-id" | "invalid-task-schema" | "storage-read-error" | "storage-write-error" | "invalid-adapter" | "import-parse-error";
+export type TaskAdapter = {
+    name: string;
+    supports: () => TaskAdapterCapability[];
+    load: () => Promise<TaskEntity[]>;
+    save?: (tasks: TaskEntity[]) => Promise<void>;
+};
+export type TaskAdapterCapability = "read" | "write" | "watch";
+export type NextActionSuggestion = {
+    readyQueue: TaskEntity[];
+    suggestedNext: TaskEntity | null;
+    stateSummary: {
+        proposed: number;
+        ready: number;
+        in_progress: number;
+        blocked: number;
+        completed: number;
+        cancelled: number;
+        total: number;
+    };
+    blockingAnalysis: BlockingAnalysisEntry[];
+};
+export type BlockingAnalysisEntry = {
+    taskId: string;
+    blockedBy: string[];
+    blockingCount: number;
+};

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

@@ -0,0 +1 @@
+export {};

package/dist/ops/index.d.ts

@@ -0,0 +1 @@
+export type OpsVersion = "0.1";

package/dist/ops/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -22,7 +22,9 @@
     "check": "tsc -p tsconfig.json --noEmit",
     "clean": "rm -rf dist",
     "test": "pnpm run build && node --test test/**/*.test.mjs",
-    "pack:dry-run": "pnpm run build && pnpm pack --pack-destination ./artifacts/workspace-kit-pack"
+    "pack:dry-run": "pnpm run build && pnpm pack --pack-destination ./artifacts/workspace-kit-pack",
+    "check-release-metadata": "node scripts/check-release-metadata.mjs",
+    "parity": "node scripts/run-parity.mjs"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",