@backburner/cli 0.1.0

package/dist/src/workstreams/wave-assessment/store.js

@@ -0,0 +1,51 @@
+import * as path from "node:path";
+import { readJsonFileIfExists, writeJsonFileAtomic } from "../../utils/json.js";
+export class WaveAssessmentSessionStore {
+    logDir;
+    sessions = new Map();
+    constructor(logDir) {
+        this.logDir = logDir;
+    }
+    async saveSession(session) {
+        this.sessions.set(session.sessionId, session);
+        if (this.logDir) {
+            await writeJsonFileAtomic(this.sessionFilePath(session.sessionId), session);
+        }
+    }
+    async getSession(sessionId) {
+        const cached = this.sessions.get(sessionId);
+        if (cached) {
+            return cached;
+        }
+        if (!this.logDir) {
+            return undefined;
+        }
+        const persisted = await readJsonFileIfExists(this.sessionFilePath(sessionId));
+        if (persisted) {
+            this.sessions.set(sessionId, persisted);
+        }
+        return persisted;
+    }
+    getSessionSync(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    listSessions() {
+        return Array.from(this.sessions.values());
+    }
+    sessionFilePath(sessionId) {
+        if (!this.logDir) {
+            throw new Error("Cannot resolve session file path without a log directory.");
+        }
+        assertSafeSessionId(sessionId);
+        return path.join(this.logDir, "wave-assessment-sessions", `${sessionId}.json`);
+    }
+}
+function assertSafeSessionId(sessionId) {
+    if (sessionId.trim() === "" ||
+        sessionId.includes("/") ||
+        sessionId.includes("\\") ||
+        sessionId === "." ||
+        sessionId === "..") {
+        throw new Error(`Invalid wave assessment session ID: ${sessionId}`);
+    }
+}

package/dist/src/workstreams/wave-assessment/tools.js

@@ -0,0 +1,419 @@
+import { WAVE_ASSESSMENT_DECISIONS, WAVE_ASSESSMENT_FINDING_CATEGORIES, addWaveAssessmentFinding, completeWaveAssessmentSession, createWaveAssessmentSession, exportWaveAssessmentSession } from "./session.js";
+import { validateWaveAssessmentSession } from "./validate.js";
+export class WaveAssessmentToolService {
+    store;
+    logger;
+    namespace = "wave_assessment";
+    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 existing = await this.store.getSession(args.sessionId);
+                    if (existing) {
+                        const identityIssues = validateWaveAssessmentSession(existing, {
+                            currentIdentity: {
+                                workstreamId: args.workstreamId,
+                                waveId: args.waveId,
+                                parentPrNumber: args.parentPrNumber,
+                                parentHeadSha: args.assessedParentHeadSha,
+                                planRevision: args.currentPlanRevision
+                            }
+                        }).filter((issue) => issue.code.startsWith("stale-"));
+                        if (identityIssues.length > 0 ||
+                            existing.originalPlanningSessionId !== args.originalPlanningSessionId ||
+                            !arraysEqual(existing.planNodeIds, args.planNodeIds)) {
+                            return invalidSessionFailure(name, args.sessionId, [
+                                ...identityIssues,
+                                ...(existing.originalPlanningSessionId !== args.originalPlanningSessionId
+                                    ? [{
+                                            severity: "error",
+                                            code: "stale-plan-revision",
+                                            message: `Original planning session ${args.originalPlanningSessionId} does not match existing session ${existing.originalPlanningSessionId}.`,
+                                            path: ["originalPlanningSessionId"]
+                                        }]
+                                    : []),
+                                ...(!arraysEqual(existing.planNodeIds, args.planNodeIds)
+                                    ? [{
+                                            severity: "error",
+                                            code: "unknown-node-reference",
+                                            message: "Provided plan node IDs do not match the existing session.",
+                                            path: ["planNodeIds"]
+                                        }]
+                                    : [])
+                            ]);
+                        }
+                        this.logInvocation(startedAt, name, { sessionId: args.sessionId }, "ok");
+                        return success(name, `Loaded existing wave assessment session: ${args.sessionId}`, {
+                            sessionId: args.sessionId,
+                            status: existing.status
+                        });
+                    }
+                    const session = createWaveAssessmentSession(args);
+                    await this.store.saveSession(session);
+                    this.logInvocation(startedAt, name, { sessionId: session.sessionId }, "ok");
+                    return success(name, `Started wave assessment session: ${session.sessionId}`, {
+                        sessionId: session.sessionId,
+                        status: session.status
+                    });
+                }
+                case "add_finding": {
+                    const args = validateAddFindingArgs(rawArguments);
+                    const session = await this.requireSession(args.sessionId);
+                    ensureOpenSession(session);
+                    assertAffectedPlanNodeIdsKnown(session, args.affectedPlanNodeIds);
+                    const updatedSession = addWaveAssessmentFinding(session, args);
+                    await this.store.saveSession(updatedSession);
+                    this.logInvocation(startedAt, name, { sessionId: args.sessionId }, "ok");
+                    return success(name, `Added finding to wave assessment session: ${args.sessionId}`, {
+                        sessionId: args.sessionId,
+                        findingCount: updatedSession.findings.length
+                    });
+                }
+                case "complete_session": {
+                    const args = validateCompleteSessionArgs(rawArguments);
+                    const session = await this.requireSession(args.sessionId);
+                    ensureOpenSession(session);
+                    const issues = validateWaveAssessmentSession(session, {
+                        decision: args.decision,
+                        summary: args.summary,
+                        currentIdentity: args.currentIdentity
+                    });
+                    if (issues.length > 0) {
+                        const updatedSession = { ...session, validationIssues: issues };
+                        await this.store.saveSession(updatedSession);
+                        return invalidSessionFailure(name, args.sessionId, issues);
+                    }
+                    const updatedSession = completeWaveAssessmentSession(session, args);
+                    await this.store.saveSession(updatedSession);
+                    this.logInvocation(startedAt, name, { sessionId: args.sessionId }, "ok");
+                    return success(name, `Completed wave assessment session: ${args.sessionId}`, {
+                        sessionId: args.sessionId,
+                        decision: updatedSession.decision,
+                        findingCount: updatedSession.findings.length
+                    });
+                }
+                case "export_session": {
+                    const args = validateExportSessionArgs(rawArguments);
+                    const session = await this.requireSession(args.sessionId);
+                    const issues = validateWaveAssessmentSession(session, {
+                        currentIdentity: args.currentIdentity
+                    });
+                    if (issues.length > 0) {
+                        return invalidSessionFailure(name, args.sessionId, issues);
+                    }
+                    if (session.status !== "completed") {
+                        return {
+                            ok: false,
+                            tool: name,
+                            error: {
+                                code: "session_not_completed",
+                                message: `Cannot export incomplete wave assessment session ${args.sessionId}.`
+                            }
+                        };
+                    }
+                    const result = exportWaveAssessmentSession(session);
+                    this.logInvocation(startedAt, name, { sessionId: args.sessionId }, "ok");
+                    return success(name, `Exported wave assessment session: ${args.sessionId}`, result);
+                }
+                default:
+                    return {
+                        ok: false,
+                        tool: name,
+                        error: {
+                            code: "tool_not_found",
+                            message: `Unknown wave assessment 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 WaveAssessmentToolError("session_not_found", `Session not found: ${sessionId}`);
+        }
+        return session;
+    }
+    logInvocation(timestamp, toolName, args, status, message) {
+        this.logger.info(JSON.stringify({
+            component: "wave-assessment-tool-service",
+            timestamp,
+            toolName,
+            resultStatus: status,
+            arguments: args,
+            ...(message ? { message } : {})
+        }));
+    }
+}
+class WaveAssessmentToolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function success(tool, summary, result) {
+    return { ok: true, tool, summary, result };
+}
+function invalidSessionFailure(tool, sessionId, issues) {
+    return {
+        ok: false,
+        tool,
+        error: {
+            code: "invalid_session",
+            message: `Wave assessment session ${sessionId} failed validation: ${issues.map((issue) => issue.code).join(", ")}`
+        }
+    };
+}
+function toFailure(name, error) {
+    if (error instanceof WaveAssessmentToolError) {
+        return {
+            ok: false,
+            tool: name,
+            error: {
+                code: error.code,
+                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 {
+        sessionId: expectString(obj.sessionId, "sessionId"),
+        workstreamId: expectString(obj.workstreamId, "workstreamId"),
+        waveId: expectString(obj.waveId, "waveId"),
+        parentPrNumber: expectPositiveInteger(obj.parentPrNumber, "parentPrNumber"),
+        assessedParentHeadSha: expectString(obj.assessedParentHeadSha, "assessedParentHeadSha"),
+        originalPlanningSessionId: expectString(obj.originalPlanningSessionId, "originalPlanningSessionId"),
+        currentPlanRevision: expectStringOrNumber(obj.currentPlanRevision, "currentPlanRevision"),
+        planNodeIds: expectUniqueStringArray(obj.planNodeIds, "planNodeIds")
+    };
+}
+function validateAddFindingArgs(args) {
+    const obj = expectObject(args);
+    return {
+        sessionId: expectString(obj.sessionId, "sessionId"),
+        category: expectEnum(obj.category, "category", WAVE_ASSESSMENT_FINDING_CATEGORIES),
+        summary: expectString(obj.summary, "summary"),
+        details: expectString(obj.details, "details"),
+        affectedPlanNodeIds: expectStringArray(obj.affectedPlanNodeIds ?? [], "affectedPlanNodeIds")
+    };
+}
+function validateCompleteSessionArgs(args) {
+    const obj = expectObject(args);
+    return {
+        sessionId: expectString(obj.sessionId, "sessionId"),
+        decision: expectEnum(obj.decision, "decision", WAVE_ASSESSMENT_DECISIONS),
+        summary: expectString(obj.summary, "summary"),
+        currentIdentity: expectCurrentIdentity(obj.currentIdentity)
+    };
+}
+function validateExportSessionArgs(args) {
+    const obj = expectObject(args);
+    return {
+        sessionId: expectString(obj.sessionId, "sessionId"),
+        currentIdentity: expectCurrentIdentity(obj.currentIdentity)
+    };
+}
+function expectCurrentIdentity(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const obj = expectObject(value, "currentIdentity");
+    const result = {};
+    if (obj.workstreamId !== undefined)
+        result.workstreamId = expectString(obj.workstreamId, "currentIdentity.workstreamId");
+    if (obj.waveId !== undefined)
+        result.waveId = expectString(obj.waveId, "currentIdentity.waveId");
+    if (obj.parentPrNumber !== undefined)
+        result.parentPrNumber = expectPositiveInteger(obj.parentPrNumber, "currentIdentity.parentPrNumber");
+    if (obj.parentHeadSha !== undefined)
+        result.parentHeadSha = expectString(obj.parentHeadSha, "currentIdentity.parentHeadSha");
+    if (obj.planRevision !== undefined)
+        result.planRevision = expectStringOrNumber(obj.planRevision, "currentIdentity.planRevision");
+    return result;
+}
+function ensureOpenSession(session) {
+    if (session.status !== "open") {
+        throw new WaveAssessmentToolError("session_already_completed", `Wave assessment session ${session.sessionId} is already completed.`);
+    }
+}
+function assertAffectedPlanNodeIdsKnown(session, affectedPlanNodeIds) {
+    const knownPlanNodeIds = new Set(session.planNodeIds);
+    const unknownNodeIds = affectedPlanNodeIds.filter((nodeId) => !knownPlanNodeIds.has(nodeId));
+    if (unknownNodeIds.length > 0) {
+        throw new WaveAssessmentToolError("unknown_node_reference", `Unknown affected plan node IDs: ${unknownNodeIds.join(", ")}`);
+    }
+}
+function arraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function expectObject(value, name = "arguments") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new WaveAssessmentToolError("invalid_arguments", `Expected ${name} to be an object.`);
+    }
+    return value;
+}
+function expectString(value, name) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new WaveAssessmentToolError("invalid_arguments", `Expected ${name} to be a non-empty string.`);
+    }
+    return value.trim();
+}
+function expectStringOrNumber(value, name) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return String(value);
+    }
+    return expectString(value, name);
+}
+function expectPositiveInteger(value, name) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new WaveAssessmentToolError("invalid_arguments", `Expected ${name} to be a positive integer.`);
+    }
+    return value;
+}
+function expectStringArray(value, name) {
+    if (!Array.isArray(value)) {
+        throw new WaveAssessmentToolError("invalid_arguments", `Expected ${name} to be an array.`);
+    }
+    return value.map((item, index) => expectString(item, `${name}[${index}]`));
+}
+function expectUniqueStringArray(value, name) {
+    const items = expectStringArray(value, name);
+    const seen = new Set();
+    for (const item of items) {
+        if (seen.has(item)) {
+            throw new WaveAssessmentToolError("invalid_arguments", `Expected ${name} to contain unique values. Duplicate: ${item}`);
+        }
+        seen.add(item);
+    }
+    return items;
+}
+function expectEnum(value, name, choices) {
+    const str = expectString(value, name);
+    if (!choices.includes(str)) {
+        throw new WaveAssessmentToolError("invalid_arguments", `Expected ${name} to be one of: ${choices.join(", ")}.`);
+    }
+    return str;
+}
+const TOOL_DEFINITIONS = [
+    {
+        name: "start_session",
+        title: "Start Wave Assessment Session",
+        description: "Start or load a wave assessment session for one parent PR head and plan revision.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                "sessionId",
+                "workstreamId",
+                "waveId",
+                "parentPrNumber",
+                "assessedParentHeadSha",
+                "originalPlanningSessionId",
+                "currentPlanRevision",
+                "planNodeIds"
+            ],
+            properties: {
+                sessionId: { type: "string" },
+                workstreamId: { type: "string" },
+                waveId: { type: "string" },
+                parentPrNumber: { type: "number" },
+                assessedParentHeadSha: { type: "string" },
+                originalPlanningSessionId: { type: "string" },
+                currentPlanRevision: { oneOf: [{ type: "string" }, { type: "number" }] },
+                planNodeIds: { type: "array", items: { type: "string" } }
+            }
+        }
+    },
+    {
+        name: "add_finding",
+        title: "Add Wave Assessment Finding",
+        description: "Record a finding discovered while assessing the integrated parent PR.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["sessionId", "category", "summary", "details", "affectedPlanNodeIds"],
+            properties: {
+                sessionId: { type: "string" },
+                category: { type: "string", enum: [...WAVE_ASSESSMENT_FINDING_CATEGORIES] },
+                summary: { type: "string" },
+                details: { type: "string" },
+                affectedPlanNodeIds: { type: "array", items: { type: "string" } }
+            }
+        }
+    },
+    {
+        name: "complete_session",
+        title: "Complete Wave Assessment Session",
+        description: "Finalize a wave assessment decision after validating summary, findings, plan nodes, and optional freshness identity.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["sessionId", "decision", "summary"],
+            properties: {
+                sessionId: { type: "string" },
+                decision: { type: "string", enum: [...WAVE_ASSESSMENT_DECISIONS] },
+                summary: { type: "string" },
+                currentIdentity: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        workstreamId: { type: "string" },
+                        waveId: { type: "string" },
+                        parentPrNumber: { type: "number" },
+                        parentHeadSha: { type: "string" },
+                        planRevision: { oneOf: [{ type: "string" }, { type: "number" }] }
+                    }
+                }
+            }
+        }
+    },
+    {
+        name: "export_session",
+        title: "Export Wave Assessment Session",
+        description: "Export a completed and still-fresh wave assessment result.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["sessionId"],
+            properties: {
+                sessionId: { type: "string" },
+                currentIdentity: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        workstreamId: { type: "string" },
+                        waveId: { type: "string" },
+                        parentPrNumber: { type: "number" },
+                        parentHeadSha: { type: "string" },
+                        planRevision: { oneOf: [{ type: "string" }, { type: "number" }] }
+                    }
+                }
+            }
+        }
+    }
+];

package/dist/src/workstreams/wave-assessment/types.js

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

package/dist/src/workstreams/wave-assessment/validate.js

@@ -0,0 +1,78 @@
+export function validateWaveAssessmentSession(session, options) {
+    const issues = [];
+    const decision = options?.decision ?? session.decision;
+    const summary = options?.summary ?? session.summary;
+    if (summary.trim() === "") {
+        issues.push({
+            severity: "error",
+            code: "missing-summary",
+            message: "A non-empty assessment summary is required.",
+            path: ["summary"]
+        });
+    }
+    if (decision === "replan" && session.findings.length === 0) {
+        issues.push({
+            severity: "error",
+            code: "missing-findings-for-replan",
+            message: "A replan decision requires at least one finding.",
+            path: ["findings"]
+        });
+    }
+    const knownPlanNodeIds = new Set(session.planNodeIds);
+    session.findings.forEach((finding, findingIndex) => {
+        finding.affectedPlanNodeIds.forEach((nodeId, nodeIndex) => {
+            if (!knownPlanNodeIds.has(nodeId)) {
+                issues.push({
+                    severity: "error",
+                    code: "unknown-node-reference",
+                    message: `Finding ${finding.id} references unknown plan node "${nodeId}".`,
+                    path: ["findings", String(findingIndex), "affectedPlanNodeIds", String(nodeIndex)]
+                });
+            }
+        });
+    });
+    const currentIdentity = options?.currentIdentity;
+    if (currentIdentity) {
+        if (currentIdentity.workstreamId !== undefined && currentIdentity.workstreamId !== session.workstreamId) {
+            issues.push({
+                severity: "error",
+                code: "stale-workstream",
+                message: `Current workstream ${currentIdentity.workstreamId} does not match session workstream ${session.workstreamId}.`,
+                path: ["currentIdentity", "workstreamId"]
+            });
+        }
+        if (currentIdentity.waveId !== undefined && currentIdentity.waveId !== session.waveId) {
+            issues.push({
+                severity: "error",
+                code: "stale-wave",
+                message: `Current wave ${currentIdentity.waveId} does not match session wave ${session.waveId}.`,
+                path: ["currentIdentity", "waveId"]
+            });
+        }
+        if (currentIdentity.parentPrNumber !== undefined && currentIdentity.parentPrNumber !== session.parentPrNumber) {
+            issues.push({
+                severity: "error",
+                code: "stale-parent-pr",
+                message: `Current parent PR ${currentIdentity.parentPrNumber} does not match session parent PR ${session.parentPrNumber}.`,
+                path: ["currentIdentity", "parentPrNumber"]
+            });
+        }
+        if (currentIdentity.parentHeadSha !== undefined && currentIdentity.parentHeadSha !== session.assessedParentHeadSha) {
+            issues.push({
+                severity: "error",
+                code: "stale-parent-head",
+                message: `Current parent head ${currentIdentity.parentHeadSha} does not match assessed head ${session.assessedParentHeadSha}.`,
+                path: ["currentIdentity", "parentHeadSha"]
+            });
+        }
+        if (currentIdentity.planRevision !== undefined && currentIdentity.planRevision !== session.currentPlanRevision) {
+            issues.push({
+                severity: "error",
+                code: "stale-plan-revision",
+                message: `Current plan revision ${currentIdentity.planRevision} does not match session plan revision ${session.currentPlanRevision}.`,
+                path: ["currentIdentity", "planRevision"]
+            });
+        }
+    }
+    return issues;
+}