@indigoai-us/hq-cli 5.292.0 → 5.294.0

package/dist/commands/lanes-stories.js

@@ -0,0 +1,308 @@
+import { activeLaneStories, laneStories, laneStory, storyWarning } from "../lib/lanes/stories.js";
+import { LanesError } from "../lib/lanes/errors.js";
+import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
+export function createLaneStoryHandlers(deps) {
+    const { assertLaneRunsHereForOperatorMutation, casUpdateLane, combinedStoryWarning, emitLaneMeshEvent, ensureLaneThreadRecord, printJson, readLane, storyBoardCheck, storyNotOnBoardWarning, updateLane, validateProjectStories, } = deps;
+    function storyCommandTarget(lane, storyId, project) {
+        const projectId = project?.trim() || lane.project_id;
+        const normalizedStoryId = storyId.trim();
+        if (!projectId) {
+            throw new LanesError("missing_project", "--project is required", {});
+        }
+        if (!normalizedStoryId) {
+            throw new LanesError("missing_story", "<story-id> is required", {});
+        }
+        const story = laneStory(lane, projectId, normalizedStoryId);
+        if (!story) {
+            throw new LanesError("story_not_on_lane", `Story ${projectId}/${normalizedStoryId} is not carried by lane ${lane.lane_id}`, { lane_id: lane.lane_id, project_id: projectId, story_id: normalizedStoryId });
+        }
+        return { projectId, storyId: normalizedStoryId, story };
+    }
+    function updateCarriedStory(lane, projectId, storyId, status, at, extras = {}) {
+        const stories = laneStories(lane).map((story) => story.project_id === projectId && story.story_id === storyId
+            ? {
+                ...story,
+                status,
+                updated_at: at,
+                blocked_reason: extras.blocked_reason,
+                verified_at: extras.verified_at,
+                verified_by: extras.verified_by,
+            }
+            : story);
+        return {
+            ...lane,
+            project_id: projectId,
+            story_id: storyId,
+            stories,
+        };
+    }
+    function addCarriedStory(lane, projectId, storyId, at) {
+        if (laneStory(lane, projectId, storyId)) {
+            throw new LanesError("story_already_on_lane", `Story ${projectId}/${storyId} is already carried by lane ${lane.lane_id}`, {
+                lane_id: lane.lane_id,
+                project_id: projectId,
+                story_id: storyId,
+            });
+        }
+        return {
+            ...lane,
+            ...(lane.story_id.trim() ? {} : { project_id: projectId, story_id: storyId }),
+            stories: [
+                ...laneStories(lane),
+                { project_id: projectId, story_id: storyId, status: "in_progress", added_at: at, updated_at: at },
+            ],
+        };
+    }
+    function callerMayVerifyStory(ctx, lane) {
+        const callerLaneId = ctx.env.HQ_LANE_ID?.trim();
+        if (callerLaneId) {
+            return lane.senior.kind === "lane" && lane.senior.id === callerLaneId;
+        }
+        if (lane.senior.kind === "user")
+            return true;
+        if (lane.senior.kind === "lane")
+            return false;
+        return sessionIdFromEnv(ctx.env) === lane.senior.id;
+    }
+    async function ensureStoryThread(ctx, lane, projectId, storyId = lane.story_id) {
+        const company = lane.mesh_company ?? lane.company;
+        if (!company)
+            return lane;
+        return ensureLaneThreadRecord(ctx, lane, projectId, storyId);
+    }
+    async function ensureStoryThreadForTransition(ctx, lane, projectId, storyId) {
+        try {
+            return { lane: await ensureStoryThread(ctx, lane, projectId, storyId) };
+        }
+        catch (err) {
+            const warning = storyNotOnBoardWarning(err);
+            if (warning === undefined)
+                throw err;
+            return { lane, warning };
+        }
+    }
+    async function emitStoryTransition(ctx, lane, projectId, storyId, event, status, payload = {}, skipStoryStatusPatch = false) {
+        const company = lane.mesh_company ?? lane.company;
+        if (!company)
+            return;
+        const ready = await ensureStoryThread(ctx, lane, projectId, storyId);
+        if (!ready.thread_id)
+            return;
+        await emitLaneMeshEvent(ctx, company, ready.thread_id, event, {
+            lane_id: ready.lane_id,
+            project_id: projectId,
+            story_id: storyId,
+            ...payload,
+            lane_status: lane.state,
+        });
+        if (!skipStoryStatusPatch && projectId?.trim() && storyId?.trim()) {
+            await ctx.mesh.patchStoryStatus(company, projectId, storyId, status === "blocked" ? "in_progress" : status);
+        }
+    }
+    function sameCommittedStory(current, expected, projectId, storyId) {
+        const currentStory = laneStory(current, projectId, storyId);
+        const expectedStory = laneStory(expected, projectId, storyId);
+        return (current.project_id === expected.project_id &&
+            current.story_id === expected.story_id &&
+            JSON.stringify(currentStory) === JSON.stringify(expectedStory));
+    }
+    async function commitStoryTransition(ctx, before, next, projectId, storyId, event, status, payload = {}, skipStoryStatusPatch = false) {
+        try {
+            await emitStoryTransition(ctx, next, projectId, storyId, event, status, payload, skipStoryStatusPatch);
+            return undefined;
+        }
+        catch (err) {
+            const warning = storyNotOnBoardWarning(err);
+            if (warning !== undefined)
+                return warning;
+            try {
+                const current = readLane(ctx.hqRoot(), next.lane_id);
+                if (!sameCommittedStory(current, next, projectId, storyId)) {
+                    throw new LanesError("story_transition_rollback_conflict", `Story ${projectId}/${storyId} changed while mesh publication failed`, { lane_id: next.lane_id, project_id: projectId, story_id: storyId });
+                }
+                updateLane(ctx.hqRoot(), next.lane_id, current.version, "command", (latest) => {
+                    if (!sameCommittedStory(latest, next, projectId, storyId)) {
+                        throw new LanesError("story_transition_rollback_conflict", `Story ${projectId}/${storyId} changed before rollback`, { lane_id: next.lane_id, project_id: projectId, story_id: storyId });
+                    }
+                    return {
+                        ...latest,
+                        project_id: before.project_id,
+                        story_id: before.story_id,
+                        stories: before.stories,
+                    };
+                });
+            }
+            catch (rollbackErr) {
+                process.stderr.write(`hq lanes: story transition rollback failed for ${next.lane_id}/${projectId}/${storyId}: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}\n`);
+            }
+            throw err;
+        }
+    }
+    async function runStoryList(ctx, laneId) {
+        const lane = readLane(ctx.hqRoot(), laneId);
+        printJson({
+            ok: true,
+            action: "story.list",
+            lane_id: laneId,
+            stories: laneStories(lane),
+            active_stories: activeLaneStories(lane),
+            story_warning: storyWarning(lane) ?? null,
+        });
+    }
+    async function runStoryAdd(ctx, laneId, storyId, opts) {
+        const hqRoot = ctx.hqRoot();
+        let lane = readLane(hqRoot, laneId);
+        assertLaneRunsHereForOperatorMutation(ctx, lane, "update story status for");
+        const projectId = opts.project?.trim() || lane.project_id;
+        if (!projectId)
+            throw new LanesError("missing_project", "--project is required", {});
+        const normalizedStoryId = storyId.trim();
+        if (!normalizedStoryId)
+            throw new LanesError("missing_story", "<story-id> is required", {});
+        if (ctx.storyLedgerEnabled()) {
+            validateProjectStories(hqRoot, projectId, [normalizedStoryId], lane.company?.slug);
+        }
+        const company = lane.mesh_company ?? lane.company;
+        const warnings = [];
+        let storyKnownAbsent = false;
+        if (company) {
+            const boardCheck = await storyBoardCheck(ctx, company, projectId, [normalizedStoryId]);
+            if (boardCheck.warning !== undefined)
+                warnings.push(boardCheck.warning);
+            storyKnownAbsent = boardCheck.absentStoryIds.has(normalizedStoryId);
+        }
+        const at = ctx.now().toISOString();
+        const thread = await ensureStoryThreadForTransition(ctx, lane, projectId, normalizedStoryId);
+        lane = thread.lane;
+        if (thread.warning !== undefined)
+            warnings.push(thread.warning);
+        const before = lane;
+        const next = casUpdateLane(hqRoot, laneId, (current) => {
+            assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
+            const added = addCarriedStory(current, projectId, normalizedStoryId, at);
+            return {
+                ...added,
+                no_story_reason: undefined,
+            };
+        });
+        const transitionWarning = await commitStoryTransition(ctx, before, next, projectId, normalizedStoryId, "lane_started", "in_progress", {}, storyKnownAbsent);
+        if (transitionWarning !== undefined)
+            warnings.push(transitionWarning);
+        const finalLane = readLane(hqRoot, laneId);
+        printJson({
+            ok: true,
+            action: "story.add",
+            lane_id: laneId,
+            project_id: projectId,
+            story_id: normalizedStoryId,
+            status: "in_progress",
+            story_warning: combinedStoryWarning(finalLane, warnings),
+            lane: finalLane,
+        });
+    }
+    async function runStoryStart(ctx, laneId, storyId, opts) {
+        const hqRoot = ctx.hqRoot();
+        let lane = readLane(hqRoot, laneId);
+        assertLaneRunsHereForOperatorMutation(ctx, lane, "update story status for");
+        const target = storyCommandTarget(lane, storyId, opts.project);
+        if (target.story.status === "done") {
+            throw new LanesError("story_already_done", `Story ${target.projectId}/${target.storyId} is done and cannot be started again`, {
+                lane_id: laneId,
+                project_id: target.projectId,
+                story_id: target.storyId,
+            });
+        }
+        const at = ctx.now().toISOString();
+        const warnings = [];
+        const thread = await ensureStoryThreadForTransition(ctx, lane, target.projectId, target.storyId);
+        lane = thread.lane;
+        if (thread.warning !== undefined)
+            warnings.push(thread.warning);
+        const before = lane;
+        const next = casUpdateLane(hqRoot, laneId, (current) => {
+            assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
+            return updateCarriedStory(current, target.projectId, target.storyId, "in_progress", at);
+        });
+        const transitionWarning = await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_started", "in_progress");
+        if (transitionWarning !== undefined)
+            warnings.push(transitionWarning);
+        const finalLane = readLane(hqRoot, laneId);
+        printJson({ ok: true, action: "story.start", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "in_progress", story_warning: combinedStoryWarning(finalLane, warnings), lane: finalLane });
+    }
+    async function runStoryBlock(ctx, laneId, storyId, opts) {
+        const hqRoot = ctx.hqRoot();
+        let lane = readLane(hqRoot, laneId);
+        assertLaneRunsHereForOperatorMutation(ctx, lane, "update story status for");
+        const target = storyCommandTarget(lane, storyId, opts.project);
+        if (target.story.status === "done") {
+            throw new LanesError("story_already_done", `Story ${target.projectId}/${target.storyId} is done and cannot be blocked again`, {
+                lane_id: laneId,
+                project_id: target.projectId,
+                story_id: target.storyId,
+            });
+        }
+        const reason = opts.reason?.trim();
+        if (!reason)
+            throw new LanesError("missing_block_reason", "--reason is required", {});
+        const at = ctx.now().toISOString();
+        const warnings = [];
+        const thread = await ensureStoryThreadForTransition(ctx, lane, target.projectId, target.storyId);
+        lane = thread.lane;
+        if (thread.warning !== undefined)
+            warnings.push(thread.warning);
+        const before = lane;
+        const next = casUpdateLane(hqRoot, laneId, (current) => {
+            assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
+            return updateCarriedStory(current, target.projectId, target.storyId, "blocked", at, { blocked_reason: reason });
+        });
+        const transitionWarning = await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_blocked", "blocked", { blocked_reason: reason });
+        if (transitionWarning !== undefined)
+            warnings.push(transitionWarning);
+        const finalLane = readLane(hqRoot, laneId);
+        printJson({ ok: true, action: "story.block", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "blocked", blocked_reason: reason, story_warning: combinedStoryWarning(finalLane, warnings), lane: finalLane });
+    }
+    async function runStoryDone(ctx, laneId, storyId, opts) {
+        const hqRoot = ctx.hqRoot();
+        let lane = readLane(hqRoot, laneId);
+        assertLaneRunsHereForOperatorMutation(ctx, lane, "update story status for");
+        if (!opts.verified) {
+            throw new LanesError("senior_verification_required", "Only a senior may mark a story done; pass --verified after reviewing or merging it", { lane_id: laneId });
+        }
+        if (!callerMayVerifyStory(ctx, lane)) {
+            throw new LanesError("senior_verification_required", `Caller is not the senior for lane ${laneId}`, {
+                lane_id: laneId,
+                senior: lane.senior,
+            });
+        }
+        const target = storyCommandTarget(lane, storyId, opts.project);
+        if (target.story.status !== "review") {
+            throw new LanesError("story_not_ready_for_verification", `Story ${target.projectId}/${target.storyId} must be in review before senior verification`, {
+                lane_id: laneId,
+                project_id: target.projectId,
+                story_id: target.storyId,
+                status: target.story.status,
+            });
+        }
+        const at = ctx.now().toISOString();
+        const warnings = [];
+        const thread = await ensureStoryThreadForTransition(ctx, lane, target.projectId, target.storyId);
+        lane = thread.lane;
+        if (thread.warning !== undefined)
+            warnings.push(thread.warning);
+        const before = lane;
+        const next = casUpdateLane(hqRoot, laneId, (current) => {
+            assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
+            return updateCarriedStory(current, target.projectId, target.storyId, "done", at, {
+                verified_at: at,
+                verified_by: current.senior,
+            });
+        });
+        const transitionWarning = await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_done", "done", { summary: "Senior verification complete" });
+        if (transitionWarning !== undefined)
+            warnings.push(transitionWarning);
+        const finalLane = readLane(hqRoot, laneId);
+        printJson({ ok: true, action: "story.done", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "done", verified: true, story_warning: combinedStoryWarning(finalLane, warnings), lane: finalLane });
+    }
+    return { runStoryList, runStoryAdd, runStoryStart, runStoryBlock, runStoryDone };
+}
+//# sourceMappingURL=lanes-stories.js.map

package/dist/commands/lanes.d.ts

@@ -114,6 +114,8 @@ export declare function parseQuestionBody(raw: unknown): QuestionBody | null;
  */
 export declare const ASK_BACKOFF_MS: readonly [5000, 15000];
 export declare const ASK_ATTEMPTS: number;
+/** Flip to true in the next release to make --priority mandatory. */
+export declare const ASK_PRIORITY_REQUIRED = false;
 export declare function casUpdateQuestion(hqRoot: string, questionId: string, updater: (current: QuestionRecord) => QuestionRecord): QuestionRecord;
 export declare function casUpdateLane(hqRoot: string, laneId: string, updater: (current: LaneRecord) => LaneRecord): LaneRecord;
 /**