@backburner/cli 0.1.0

package/dist/src/workstreams/plan-breakdown-generator/inspect.js

@@ -0,0 +1,50 @@
+import { validateSession } from "./validate.js";
+export function inspectSession(session) {
+    const structuralIssues = validateSession(session);
+    const validationIssues = [...(session.validationIssues ?? []), ...structuralIssues];
+    const isValid = !validationIssues.some((i) => i.severity === "error");
+    const waveOrder = Array.isArray(session.waveOrder) ? session.waveOrder : [];
+    const sessionTasks = (session.tasks && typeof session.tasks === "object") ? session.tasks : {};
+    const taskToWave = new Map();
+    for (const waveId of waveOrder) {
+        const wave = session.waves?.[waveId];
+        if (wave) {
+            const taskIds = Array.isArray(wave.taskIds) ? wave.taskIds : [];
+            for (const taskId of taskIds) {
+                taskToWave.set(taskId, waveId);
+            }
+        }
+    }
+    return {
+        sessionId: session.id ?? "",
+        title: session.title ?? "",
+        summary: session.summary ?? "",
+        taskCount: Object.keys(sessionTasks).length,
+        waveCount: waveOrder.length,
+        tasks: Object.entries(sessionTasks).map(([id, task]) => ({
+            id,
+            title: task?.title,
+            waveId: taskToWave.get(id),
+            dependencies: Array.isArray(task?.dependsOn) ? task.dependsOn : [],
+            validationIssues: validationIssues.filter((i) => i.path?.[0] === "tasks" && i.path?.[1] === id)
+        })),
+        waves: waveOrder.map((id) => {
+            const wave = session.waves?.[id];
+            return {
+                id,
+                taskIds: Array.isArray(wave?.taskIds) ? wave.taskIds : [],
+                validationIssues: validationIssues.filter((i) => i.path?.[0] === "waves" && i.path?.[1] === id)
+            };
+        }),
+        validationIssues: validationIssues.filter((i) => {
+            if (!i.path)
+                return true;
+            if (i.path[0] === "tasks" && i.path[1])
+                return false;
+            if (i.path[0] === "waves" && i.path[1])
+                return false;
+            return true;
+        }),
+        isValid
+    };
+}

package/dist/src/workstreams/plan-breakdown-generator/patch.js

@@ -0,0 +1,139 @@
+import { PatchError } from "./types.js";
+export function applyPatches(session, patches) {
+    let current = { ...session, validationIssues: [...(session.validationIssues || [])] };
+    const now = new Date().toISOString();
+    for (const patch of patches) {
+        switch (patch.op) {
+            case "set-title":
+                current.title = patch.value;
+                break;
+            case "set-summary":
+                current.summary = patch.value;
+                break;
+            case "add-task":
+                if (current.tasks[patch.task.id]) {
+                    throw new PatchError(`Task ID ${patch.task.id} already exists`);
+                }
+                current.tasks = { ...current.tasks, [patch.task.id]: patch.task };
+                break;
+            case "update-task":
+                if (!current.tasks[patch.id]) {
+                    throw new PatchError(`Task ${patch.id} not found`);
+                }
+                current.tasks = {
+                    ...current.tasks,
+                    [patch.id]: { ...current.tasks[patch.id], ...patch.patch }
+                };
+                break;
+            case "remove-task": {
+                if (!current.tasks[patch.id]) {
+                    throw new PatchError(`Task ${patch.id} not found`);
+                }
+                const { [patch.id]: _, ...remainingTasks } = current.tasks;
+                current.tasks = remainingTasks;
+                // Also remove from waves
+                const updatedWaves = {};
+                for (const [waveId, wave] of Object.entries(current.waves)) {
+                    if (wave.taskIds.includes(patch.id)) {
+                        updatedWaves[waveId] = {
+                            ...wave,
+                            taskIds: wave.taskIds.filter((id) => id !== patch.id)
+                        };
+                    }
+                    else {
+                        updatedWaves[waveId] = wave;
+                    }
+                }
+                current.waves = updatedWaves;
+                // Clear validation issues for this task
+                current.validationIssues = current.validationIssues.filter(i => !(i.path?.[0] === "tasks" && i.path?.[1] === patch.id));
+                break;
+            }
+            case "add-wave":
+                if (current.waves[patch.wave.id]) {
+                    throw new PatchError(`Wave ID ${patch.wave.id} already exists`);
+                }
+                current.waves = { ...current.waves, [patch.wave.id]: patch.wave };
+                if (patch.index !== undefined) {
+                    const newOrder = current.waveOrder.filter(id => id !== patch.wave.id);
+                    newOrder.splice(patch.index, 0, patch.wave.id);
+                    current.waveOrder = newOrder;
+                }
+                else if (!current.waveOrder.includes(patch.wave.id)) {
+                    current.waveOrder = [...current.waveOrder, patch.wave.id];
+                }
+                break;
+            case "update-wave":
+                if (!current.waves[patch.id]) {
+                    throw new PatchError(`Wave ${patch.id} not found`);
+                }
+                current.waves = {
+                    ...current.waves,
+                    [patch.id]: { ...current.waves[patch.id], ...patch.patch }
+                };
+                break;
+            case "remove-wave": {
+                if (!current.waves[patch.id]) {
+                    throw new PatchError(`Wave ${patch.id} not found`);
+                }
+                const { [patch.id]: __, ...remainingWaves } = current.waves;
+                current.waves = remainingWaves;
+                current.waveOrder = current.waveOrder.filter((id) => id !== patch.id);
+                if (current.recommendedFirstWaveId === patch.id) {
+                    current.recommendedFirstWaveId = "";
+                }
+                // Clear validation issues for this wave
+                current.validationIssues = current.validationIssues.filter(i => !(i.path?.[0] === "waves" && i.path?.[1] === patch.id));
+                break;
+            }
+            case "reorder-waves": {
+                const existingWaveIds = Object.keys(current.waves);
+                if (patch.waveIds.length !== existingWaveIds.length) {
+                    throw new PatchError(`reorder-waves must include all existing waves. Expected ${existingWaveIds.length} waves, got ${patch.waveIds.length}.`);
+                }
+                // Validate all wave IDs exist and there are no duplicates
+                const seen = new Set();
+                for (const waveId of patch.waveIds) {
+                    if (!current.waves[waveId]) {
+                        throw new PatchError(`Wave ${waveId} not found for reorder`);
+                    }
+                    if (seen.has(waveId)) {
+                        throw new PatchError(`Duplicate wave ID ${waveId} in reorder`);
+                    }
+                    seen.add(waveId);
+                }
+                current.waveOrder = patch.waveIds;
+                break;
+            }
+            case "set-recommended-first-wave":
+                if (!current.waves[patch.id]) {
+                    throw new PatchError(`Wave ${patch.id} not found for recommended first wave`);
+                }
+                current.recommendedFirstWaveId = patch.id;
+                break;
+            case "add-graph-concern":
+                current.graphConcerns = [...current.graphConcerns, patch.value];
+                break;
+            case "remove-graph-concern":
+                if (patch.index < 0 || patch.index >= current.graphConcerns.length) {
+                    throw new PatchError(`Graph concern index ${patch.index} out of bounds`);
+                }
+                current.graphConcerns = current.graphConcerns.filter((_, i) => i !== patch.index);
+                break;
+            case "add-human-decision":
+                current.humanDecisionsNeeded = [...current.humanDecisionsNeeded, patch.value];
+                break;
+            case "remove-human-decision":
+                if (patch.index < 0 || patch.index >= current.humanDecisionsNeeded.length) {
+                    throw new PatchError(`Human decision index ${patch.index} out of bounds`);
+                }
+                current.humanDecisionsNeeded = current.humanDecisionsNeeded.filter((_, i) => i !== patch.index);
+                break;
+            case "set-suggested-next-action":
+                current.suggestedNextAction = patch.value;
+                break;
+        }
+    }
+    current.updatedAt = now;
+    return current;
+}

package/dist/src/workstreams/plan-breakdown-generator/session.js

@@ -0,0 +1,19 @@
+import { randomUUID } from "node:crypto";
+export function createSession(options) {
+    const now = new Date().toISOString();
+    return {
+        id: options?.id ?? randomUUID(),
+        title: options?.title ?? "",
+        summary: options?.summary ?? "",
+        tasks: {},
+        waves: {},
+        waveOrder: [],
+        recommendedFirstWaveId: "",
+        graphConcerns: [],
+        humanDecisionsNeeded: [],
+        suggestedNextAction: "",
+        createdAt: now,
+        updatedAt: now,
+        validationIssues: []
+    };
+}

package/dist/src/workstreams/plan-breakdown-generator/store.js

@@ -0,0 +1,27 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+export class PlanBreakdownSessionStore {
+    logDir;
+    sessions = new Map();
+    constructor(logDir) {
+        this.logDir = logDir;
+    }
+    async saveSession(session) {
+        this.sessions.set(session.id, session);
+        if (this.logDir) {
+            const sessionsDir = path.join(this.logDir, "plan-breakdown-sessions");
+            await fs.mkdir(sessionsDir, { recursive: true });
+            const filePath = path.join(sessionsDir, `${session.id}.json`);
+            await fs.writeFile(filePath, JSON.stringify(session, null, 2), "utf8");
+        }
+    }
+    async getSession(id) {
+        return this.sessions.get(id);
+    }
+    getSessionSync(id) {
+        return this.sessions.get(id);
+    }
+    listSessions() {
+        return Array.from(this.sessions.values());
+    }
+}

package/dist/src/workstreams/plan-breakdown-generator/tools.js

@@ -0,0 +1,407 @@
+import { createSession, applyPatches, inspectSession, validateSession, exportSession, PatchError } from "./index.js";
+export class PlanBreakdownToolService {
+    store;
+    logger;
+    namespace = "plan_breakdown";
+    constructor(store, logger) {
+        this.store = store;
+        this.logger = logger;
+    }
+    listTools() {
+        return TOOL_DEFINITIONS;
+    }
+    async callTool(name, rawArguments) {
+        const startedAt = new Date().toISOString();
+        try {
+            switch (name) {
+                case "start_session": {
+                    const args = validateStartSessionArgs(rawArguments);
+                    const session = createSession({ title: args.title, summary: args.summary });
+                    await this.store.saveSession(session);
+                    this.logInvocation(startedAt, name, { sessionId: session.id }, "ok");
+                    return {
+                        ok: true,
+                        tool: name,
+                        summary: `Started new plan breakdown session: ${session.id}`,
+                        result: { sessionId: session.id }
+                    };
+                }
+                case "apply_patch": {
+                    const args = validateApplyPatchArgs(rawArguments);
+                    const session = await this.requireSession(args.sessionId);
+                    const updatedSession = applyPatches(session, [args.patch]);
+                    await this.store.saveSession(updatedSession);
+                    const issues = validateSession(updatedSession);
+                    const hasErrors = issues.some(issue => issue.severity === "error");
+                    this.logInvocation(startedAt, name, { sessionId: args.sessionId }, "ok");
+                    return {
+                        ok: true,
+                        tool: name,
+                        summary: `Applied patch to session: ${args.sessionId}${hasErrors ? " (now has validation errors)" : ""}`,
+                        result: {
+                            sessionId: args.sessionId,
+                            isValid: !hasErrors,
+                            issueCount: issues.length
+                        }
+                    };
+                }
+                case "inspect_session": {
+                    const args = validateSessionLookupArgs(rawArguments);
+                    const session = await this.requireSession(args.sessionId);
+                    const inspection = inspectSession(session);
+                    this.logInvocation(startedAt, name, { sessionId: args.sessionId }, "ok");
+                    return {
+                        ok: true,
+                        tool: name,
+                        summary: `Inspected session: ${args.sessionId}`,
+                        result: inspection
+                    };
+                }
+                case "validate_session": {
+                    const args = validateSessionLookupArgs(rawArguments);
+                    const session = await this.requireSession(args.sessionId);
+                    const issues = validateSession(session);
+                    const hasErrors = issues.some(issue => issue.severity === "error");
+                    this.logInvocation(startedAt, name, { sessionId: args.sessionId }, "ok");
+                    return {
+                        ok: true,
+                        tool: name,
+                        summary: `Validated session: ${args.sessionId} (${issues.length} issues)`,
+                        result: { sessionId: args.sessionId, issues, isValid: !hasErrors }
+                    };
+                }
+                case "export_session": {
+                    const args = validateSessionLookupArgs(rawArguments);
+                    const session = await this.requireSession(args.sessionId);
+                    const issues = validateSession(session);
+                    const hasErrors = issues.some(issue => issue.severity === "error");
+                    if (hasErrors) {
+                        return {
+                            ok: false,
+                            tool: name,
+                            error: {
+                                code: "invalid_session",
+                                message: `Cannot export invalid session ${args.sessionId}. Call validate_session for details.`
+                            }
+                        };
+                    }
+                    const result = exportSession(session);
+                    this.logInvocation(startedAt, name, { sessionId: args.sessionId }, "ok");
+                    return {
+                        ok: true,
+                        tool: name,
+                        summary: `Exported session: ${args.sessionId}`,
+                        result: result
+                    };
+                }
+                default:
+                    return {
+                        ok: false,
+                        tool: name,
+                        error: {
+                            code: "tool_not_found",
+                            message: `Unknown plan breakdown tool "${name}"`
+                        }
+                    };
+            }
+        }
+        catch (error) {
+            const failure = toFailure(name, error);
+            this.logInvocation(startedAt, name, rawArguments, "error", failure.error.message);
+            return failure;
+        }
+    }
+    async requireSession(sessionId) {
+        const session = await this.store.getSession(sessionId);
+        if (!session) {
+            throw new SessionNotFoundError(`Session not found: ${sessionId}`);
+        }
+        return session;
+    }
+    logInvocation(timestamp, toolName, args, status, message) {
+        this.logger.info(JSON.stringify({
+            component: "plan-breakdown-tool-service",
+            timestamp,
+            toolName,
+            resultStatus: status,
+            arguments: args,
+            ...(message ? { message } : {})
+        }));
+    }
+}
+class SessionNotFoundError extends Error {
+}
+class ValidationError extends Error {
+}
+function toFailure(name, error) {
+    if (error instanceof SessionNotFoundError) {
+        return {
+            ok: false,
+            tool: name,
+            error: {
+                code: "session_not_found",
+                message: error.message
+            }
+        };
+    }
+    if (error instanceof ValidationError) {
+        return {
+            ok: false,
+            tool: name,
+            error: {
+                code: "invalid_arguments",
+                message: error.message
+            }
+        };
+    }
+    if (error instanceof PatchError) {
+        return {
+            ok: false,
+            tool: name,
+            error: {
+                code: "invalid_patch",
+                message: error.message
+            }
+        };
+    }
+    return {
+        ok: false,
+        tool: name,
+        error: {
+            code: "internal_error",
+            message: error instanceof Error ? error.message : String(error)
+        }
+    };
+}
+function validateStartSessionArgs(args) {
+    const obj = expectObject(args);
+    return {
+        title: expectString(obj.title, "title"),
+        summary: expectString(obj.summary, "summary")
+    };
+}
+function validateApplyPatchArgs(args) {
+    const obj = expectObject(args);
+    const patch = expectObject(obj.patch, "patch");
+    return {
+        sessionId: expectString(obj.sessionId, "sessionId"),
+        patch: validatePatchOperation(patch)
+    };
+}
+function validatePatchOperation(patch) {
+    const op = expectString(patch.op, "patch.op");
+    switch (op) {
+        case "set-title":
+            return { op, value: expectString(patch.value, "patch.value") };
+        case "set-summary":
+            return { op, value: expectString(patch.value, "patch.value") };
+        case "add-task":
+            return {
+                op,
+                task: validateTask(expectObject(patch.task, "patch.task"), "patch.task")
+            };
+        case "update-task":
+            return {
+                op,
+                id: expectString(patch.id, "patch.id"),
+                patch: validateTaskPatch(expectObject(patch.patch, "patch.patch"), "patch.patch")
+            };
+        case "remove-task":
+            return { op, id: expectString(patch.id, "patch.id") };
+        case "add-wave": {
+            const result = {
+                op,
+                wave: validateWave(expectObject(patch.wave, "patch.wave"), "patch.wave")
+            };
+            if (patch.index !== undefined) {
+                result.index = expectInteger(patch.index, "patch.index");
+            }
+            return result;
+        }
+        case "update-wave":
+            return {
+                op,
+                id: expectString(patch.id, "patch.id"),
+                patch: validateWavePatch(expectObject(patch.patch, "patch.patch"), "patch.patch")
+            };
+        case "remove-wave":
+            return { op, id: expectString(patch.id, "patch.id") };
+        case "reorder-waves":
+            return { op, waveIds: expectStringArray(patch.waveIds, "patch.waveIds") };
+        case "set-recommended-first-wave":
+            return { op, id: expectString(patch.id, "patch.id") };
+        case "add-graph-concern":
+            return { op, value: expectString(patch.value, "patch.value") };
+        case "remove-graph-concern":
+            return { op, index: expectInteger(patch.index, "patch.index") };
+        case "add-human-decision":
+            return { op, value: expectString(patch.value, "patch.value") };
+        case "remove-human-decision":
+            return { op, index: expectInteger(patch.index, "patch.index") };
+        case "set-suggested-next-action":
+            return { op, value: expectString(patch.value, "patch.value") };
+        default:
+            throw new ValidationError(`Unknown patch operation: ${op}`);
+    }
+}
+function validateTask(task, prefix) {
+    return {
+        id: expectString(task.id, `${prefix}.id`),
+        title: expectString(task.title, `${prefix}.title`),
+        description: expectString(task.description, `${prefix}.description`),
+        dependsOn: expectStringArray(task.dependsOn || task.dependencies || [], `${prefix}.dependsOn`),
+        blocks: expectStringArray(task.blocks || [], `${prefix}.blocks`),
+        canRunInParallelWith: expectStringArray(task.canRunInParallelWith || [], `${prefix}.canRunInParallelWith`),
+        risk: validateRisk(task.risk || "medium", `${prefix}.risk`),
+        filesLikelyInvolved: expectStringArray(task.filesLikelyInvolved || [], `${prefix}.filesLikelyInvolved`),
+        acceptanceCriteria: expectStringArray(task.acceptanceCriteria || [], `${prefix}.acceptanceCriteria`),
+        verification: expectStringArray(task.verification || [], `${prefix}.verification`)
+    };
+}
+function validateTaskPatch(patch, prefix) {
+    const result = {};
+    if (patch.title !== undefined)
+        result.title = expectString(patch.title, `${prefix}.title`);
+    if (patch.description !== undefined)
+        result.description = expectString(patch.description, `${prefix}.description`);
+    const dependsOn = patch.dependsOn || patch.dependencies;
+    if (dependsOn !== undefined)
+        result.dependsOn = expectStringArray(dependsOn, `${prefix}.dependsOn`);
+    if (patch.blocks !== undefined)
+        result.blocks = expectStringArray(patch.blocks, `${prefix}.blocks`);
+    if (patch.canRunInParallelWith !== undefined)
+        result.canRunInParallelWith = expectStringArray(patch.canRunInParallelWith, `${prefix}.canRunInParallelWith`);
+    if (patch.risk !== undefined)
+        result.risk = validateRisk(patch.risk, `${prefix}.risk`);
+    if (patch.filesLikelyInvolved !== undefined)
+        result.filesLikelyInvolved = expectStringArray(patch.filesLikelyInvolved, `${prefix}.filesLikelyInvolved`);
+    if (patch.acceptanceCriteria !== undefined)
+        result.acceptanceCriteria = expectStringArray(patch.acceptanceCriteria, `${prefix}.acceptanceCriteria`);
+    if (patch.verification !== undefined)
+        result.verification = expectStringArray(patch.verification, `${prefix}.verification`);
+    return result;
+}
+function validateWave(wave, prefix) {
+    return {
+        id: expectString(wave.id, `${prefix}.id`),
+        taskIds: expectStringArray(wave.taskIds, `${prefix}.taskIds`),
+        rationale: typeof wave.rationale === "string" ? wave.rationale.trim() : ""
+    };
+}
+function validateWavePatch(patch, prefix) {
+    const result = {};
+    if (patch.taskIds !== undefined)
+        result.taskIds = expectStringArray(patch.taskIds, `${prefix}.taskIds`);
+    if (patch.rationale !== undefined)
+        result.rationale = expectString(patch.rationale, `${prefix}.rationale`);
+    return result;
+}
+function validateRisk(risk, name) {
+    const r = expectString(risk, name);
+    if (r !== "low" && r !== "medium" && r !== "high") {
+        throw new ValidationError(`Expected ${name} to be one of: low, medium, high`);
+    }
+    return r;
+}
+function validateSessionLookupArgs(args) {
+    const obj = expectObject(args);
+    return {
+        sessionId: expectString(obj.sessionId, "sessionId")
+    };
+}
+function expectObject(val, name = "arguments") {
+    if (!val || typeof val !== "object" || Array.isArray(val)) {
+        throw new ValidationError(`Expected ${name} to be an object`);
+    }
+    return val;
+}
+function expectString(val, name) {
+    if (typeof val !== "string" || val.trim() === "") {
+        throw new ValidationError(`Expected ${name} to be a non-empty string`);
+    }
+    return val.trim();
+}
+function expectStringArray(val, name) {
+    if (!Array.isArray(val)) {
+        throw new ValidationError(`Expected ${name} to be an array`);
+    }
+    return val.map((item, i) => expectString(item, `${name}[${i}]`));
+}
+function expectInteger(val, name) {
+    if (typeof val !== "number" || !Number.isInteger(val)) {
+        throw new ValidationError(`Expected ${name} to be an integer`);
+    }
+    return val;
+}
+const TOOL_DEFINITIONS = [
+    {
+        name: "start_session",
+        title: "Start Plan Breakdown Session",
+        description: "Start a new plan breakdown session for generating packet plans.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["title", "summary"],
+            properties: {
+                title: { type: "string", description: "The title of the plan breakdown." },
+                summary: { type: "string", description: "A high-level summary of the breakdown." }
+            }
+        }
+    },
+    {
+        name: "apply_patch",
+        title: "Apply Patch to Session",
+        description: "Apply a patch operation to an existing plan breakdown session.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["sessionId", "patch"],
+            properties: {
+                sessionId: { type: "string" },
+                patch: {
+                    type: "object",
+                    description: "A single patch operation (e.g., add-task, update-task, add-wave)."
+                }
+            }
+        }
+    },
+    {
+        name: "inspect_session",
+        title: "Inspect Session",
+        description: "Return a human-readable overview of the current session state.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["sessionId"],
+            properties: {
+                sessionId: { type: "string" }
+            }
+        }
+    },
+    {
+        name: "validate_session",
+        title: "Validate Session",
+        description: "Run validation rules on the session and return any issues.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["sessionId"],
+            properties: {
+                sessionId: { type: "string" }
+            }
+        }
+    },
+    {
+        name: "export_session",
+        title: "Export Session",
+        description: "Export a valid session to a PlanBreakdownResult artifact.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["sessionId"],
+            properties: {
+                sessionId: { type: "string" }
+            }
+        }
+    }
+];

package/dist/src/workstreams/plan-breakdown-generator/types.js

@@ -0,0 +1,6 @@
+export class PatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PatchError";
+    }
+}