@indigoai-us/hq-cli 5.345.32 → 5.345.33

package/dist/commands/mesh.js

@@ -14,8 +14,8 @@ import chalk from "chalk";
 import { ensureCognitoToken, isExpiring, isMachineIdentity, loadCachedTokens, } from "../utils/cognito-session.js";
 import * as readline from "node:readline/promises";
 import { STORY_STATUSES, appendThreadEvent, addProjectMember, ensureProjectThread, eventPayload, getProjectView, listActiveMembershipCompanies, listActiveThreads, patchStory, putProjectView, registerMeshProject, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
-import { closeSupersededProjectThread, ensureMissingBoardStories, ensureProjectBoard, boardStoryStatus, formatStoryStatusChanges, mergeProjectStories, prdSyncEventsThatChangeBoard, } from "../lib/mesh/project-board.js";
-import { mapSourceStoryStatus } from "../lib/mesh/story-status.js";
+import { closeSupersededProjectThread, ensureMissingBoardStories, ensureProjectBoard, boardStoryStatus, formatStoryStatusChanges, mergeProjectStories, prdSyncEventsThatChangeBoard, reconcileProjectStories, } from "../lib/mesh/project-board.js";
+import { ACCEPTED_LEDGER_STATES, mapSourceStoryStatus, UnknownProjectStoryStateError } from "../lib/mesh/story-status.js";
 import { buildPreflightFixtures } from "../lib/work-context/preflight-contract.js";
 import { createCandidatesFetcher, createMigratePoster, createOrganizePoster, createWorkSessionDeliverer, fetchCompanyLive, formatCompanyLiveTable, openMeshTransport, probeMigrationCapabilityForMemberships, requireToken, } from "../lib/mesh/client.js";
 import { clearDefaultCompany, effectiveUsageAttribution, isDefaultCompanyDisabled, readDeviceConfig, recordMigrationCapabilitySnapshot, setRepairHeldWithDefault, setDefaultCompany, setUsageAttribution, } from "../lib/work-context/config.js";
@@ -257,32 +257,43 @@ function projectStoriesFromJson(value, source) {
     if (!rawStories) {
         fail(`${source} must be a JSON story array or an object with userStories.`);
     }
-    const stories = rawStories.map((raw, index) => {
+    const rejectedStories = [];
+    const stories = rawStories.flatMap((raw, index) => {
         const story = record(raw);
         const id = typeof story?.id === "string" ? story.id.trim() : "";
         const title = typeof story?.title === "string" ? story.title.trim() : "";
         if (!story || !id || !title) {
             fail(`${source} userStories[${index}] requires string id and title.`);
         }
-        const status = mapSourceStoryStatus(story, `${source} userStories[${index}]`);
+        let status;
+        try {
+            status = mapSourceStoryStatus({ ...story, id }, `${source} userStories[${index}]`);
+        }
+        catch (err) {
+            if (!(err instanceof UnknownProjectStoryStateError))
+                throw err;
+            rejectedStories.push(err);
+            return [];
+        }
         const resolvedStatus = status || (story.passes === true ? "done" : undefined);
-        return {
-            id,
-            title,
-            ...(typeof story.description === "string" ? { description: story.description } : {}),
-            ...(Array.isArray(story.acceptanceCriteria)
-                ? {
-                    acceptanceCriteria: story.acceptanceCriteria.filter((item) => typeof item === "string"),
-                }
-                : {}),
-            ...(resolvedStatus ? { status: resolvedStatus } : {}),
-            // hq-pro makes passes mirror the Board status. A completed PRD story
-            // without an explicit status must therefore become done.
-            passes: resolvedStatus === "done",
-            ...(typeof story.priority === "number" && Number.isFinite(story.priority)
-                ? { priority: story.priority }
-                : {}),
-        };
+        return [{
+                id,
+                title,
+                ...(typeof story.description === "string" ? { description: story.description } : {}),
+                ...(Array.isArray(story.acceptanceCriteria)
+                    ? {
+                        acceptanceCriteria: story.acceptanceCriteria.filter((item) => typeof item === "string"),
+                    }
+                    : {}),
+                ...(resolvedStatus ? { status: resolvedStatus } : {}),
+                ...(typeof story.state === "string" ? { ledgerState: story.state.trim() } : {}),
+                // hq-pro makes passes mirror the Board status. A completed PRD story
+                // without an explicit status must therefore become done.
+                passes: resolvedStatus === "done",
+                ...(typeof story.priority === "number" && Number.isFinite(story.priority)
+                    ? { priority: story.priority }
+                    : {}),
+            }];
     });
     const metadata = record(plan?.metadata);
     const repos = metadata && Object.hasOwn(metadata, "repos")
@@ -292,12 +303,44 @@ function projectStoriesFromJson(value, source) {
         ...(typeof plan?.name === "string" ? { name: plan.name } : {}),
         ...(typeof plan?.description === "string" ? { description: plan.description } : {}),
         stories,
+        rejectedStories,
         ...(repos ? { repos } : {}),
     };
 }
-function parseProjectPlan(raw, source) {
+function projectStateErrors(rejected) {
+    return rejected.map((error) => ({
+        code: error.code,
+        file: error.source.split(" userStories[")[0],
+        storyId: error.storyId,
+        field: "state",
+        value: error.value,
+        accepted: ACCEPTED_LEDGER_STATES,
+    }));
+}
+class RejectedProjectStoryStatesError extends Error {
+    rejected;
+    code = "PROJECT_STORY_STATE_INVALID";
+    constructor(rejected) {
+        super(rejected.map((error) => `${error.code}: ${error.message}`).join("\n"));
+        this.rejected = rejected;
+        this.name = "RejectedProjectStoryStatesError";
+    }
+}
+function failProjectStoryStates(rejected, json) {
+    if (json)
+        console.log(JSON.stringify({ ok: false, errors: projectStateErrors(rejected) }));
+    else
+        for (const error of rejected)
+            console.error(`${error.code}: ${error.message}`);
+    process.exitCode = 1;
+}
+function parseProjectPlan(raw, source, options = {}) {
     try {
-        return projectStoriesFromJson(JSON.parse(raw), source);
+        const plan = projectStoriesFromJson(JSON.parse(raw), source);
+        if (plan.rejectedStories.length && !options.allowRejectedStories) {
+            throw new RejectedProjectStoryStatesError(plan.rejectedStories);
+        }
+        return plan;
     }
     catch (err) {
         if (err instanceof SyntaxError)
@@ -330,6 +373,10 @@ async function runProjectSet(projectId, opts) {
         : opts.storiesJson
             ? parseProjectPlan(opts.storiesJson, "--stories-json")
             : undefined;
+    if (source?.rejectedStories.length) {
+        failProjectStoryStates(source.rejectedStories, Boolean(opts.json));
+        return;
+    }
     const explicitRepos = opts.reposJson
         ? parseProjectReposJson(opts.reposJson, "--repos-json")
         : opts.repo?.length
@@ -479,8 +526,12 @@ async function runProjectMemberAdd(projectId, personUid, opts) {
 async function runProjectEnsure(projectId, opts) {
     if (!opts.storiesFile?.trim())
         fail("`--stories-file <prd.json>` is required.");
-    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile);
+    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { allowRejectedStories: true });
     const { token, company } = await withCompany(opts);
+    if (source.rejectedStories.length && source.stories.length === 0) {
+        failProjectStoryStates(source.rejectedStories, Boolean(opts.json));
+        return;
+    }
     let current;
     try {
         current = await getProjectView(token, company.companyUid, projectId);
@@ -506,12 +557,13 @@ async function runProjectEnsure(projectId, opts) {
         }));
         if (opts.json) {
             console.log(JSON.stringify({
-                ok: true,
+                ok: source.rejectedStories.length === 0,
                 action: "project.ensure.dry-run",
                 projectId,
                 companyUid: company.companyUid,
                 sourceStatuses,
                 stories: boardStatuses,
+                ...(source.rejectedStories.length ? { errors: projectStateErrors(source.rejectedStories) } : {}),
             }, null, 2));
         }
         else {
@@ -523,6 +575,8 @@ async function runProjectEnsure(projectId, opts) {
             for (const story of boardStatuses)
                 console.log(`${story.id}\t${story.status}`);
         }
+        if (source.rejectedStories.length)
+            process.exitCode = 1;
         return;
     }
     // Genesis thread, then the view, then register. Register returns 403
@@ -606,13 +660,74 @@ async function runProjectEnsure(projectId, opts) {
         channelId: registration.channelId,
         version: verified.version,
         stories: verified.stories,
+        ...(source.rejectedStories.length ? { ok: false, errors: projectStateErrors(source.rejectedStories) } : {}),
     };
     noteCallingSessionBound(payload.projectId, company);
     if (opts.json) {
         console.log(JSON.stringify(payload));
+        if (source.rejectedStories.length)
+            process.exitCode = 1;
         return;
     }
     console.log(`Work mesh: project ${payload.projectId} ensured (thread ${payload.threadId}, channel ${payload.channelId}, ${payload.stories.length} stories)`);
+    if (source.rejectedStories.length)
+        failProjectStoryStates(source.rejectedStories, false);
+}
+async function runProjectReconcile(projectId, opts) {
+    if (!opts.storiesFile?.trim())
+        fail("`--stories-file <prd.json>` is required.");
+    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { allowRejectedStories: true });
+    const { token, company } = await withCompany(opts);
+    let current;
+    try {
+        current = await getProjectView(token, company.companyUid, projectId);
+    }
+    catch (err) {
+        if (httpStatus(err) !== 404)
+            throw err;
+    }
+    if (current && (current.companyUid !== company.companyUid || current.projectId !== projectId)) {
+        fail("Work mesh project reconcile: Board company or project id did not match the request.");
+    }
+    const reconciliation = reconcileProjectStories(source.stories, current?.stories ?? []);
+    const errors = [
+        ...projectStateErrors(source.rejectedStories),
+        ...(!current ? [{ code: "PROJECT_BOARD_NOT_FOUND", projectId }] : []),
+    ];
+    const mismatches = reconciliation.mismatches;
+    const clean = mismatches.length === 0 && errors.length === 0;
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: clean,
+            action: "project.reconcile",
+            projectId,
+            companyUid: company.companyUid,
+            mismatches,
+            stateDriftCount: reconciliation.stateDriftCount,
+            ledgerStateUnsupported: reconciliation.ledgerStateUnsupported,
+            errors,
+        }, null, 2));
+    }
+    else if (clean) {
+        const note = reconciliation.ledgerStateUnsupported.length
+            ? `; Board does not return ledgerState for ${reconciliation.ledgerStateUnsupported.length} stories yet`
+            : "";
+        console.log(`Work mesh: project ${projectId} matches ${source.stories.length} ledger stories${note}`);
+    }
+    else {
+        for (const mismatch of mismatches) {
+            console.log(`${mismatch.storyId}\tledger=${mismatch.ledgerState ?? "<none>"}\texpected=${mismatch.expectedBoardStatus ?? "<none>"}\tboard=${mismatch.boardStatus ?? "<missing>"}\tboardLedger=${mismatch.boardLedgerState ?? "<unsupported>"}\tstateDrift=${mismatch.stateDrift}\tmissing=${mismatch.missingOnBoard}\textra=${mismatch.extraOnBoard}`);
+        }
+        if (reconciliation.ledgerStateUnsupported.length) {
+            console.log(`Board does not return ledgerState for ${reconciliation.ledgerStateUnsupported.length} stories: ${reconciliation.ledgerStateUnsupported.join(", ")}`);
+        }
+        if (!current)
+            console.error(`PROJECT_BOARD_NOT_FOUND: Board project ${projectId} was not found.`);
+        for (const error of source.rejectedStories)
+            console.error(`${error.code}: ${error.message}`);
+    }
+    if (!clean)
+        process.exitCode = 1;
 }
 async function runPrdSync(opts) {
     const sessionId = opts.session.trim();
@@ -689,6 +804,8 @@ async function runPrdSync(opts) {
             });
         }
         catch (err) {
+            if (err instanceof RejectedProjectStoryStatesError)
+                throw err;
             const reason = err instanceof Error ? err.message : String(err);
             console.error(`work-mesh: prd-sync ensure failed; emitting anyway (${reason.slice(0, 160)})`);
         }
@@ -828,8 +945,8 @@ async function runBindProject(target, opts) {
         }
         if (!current.companyUid)
             fail(`Session ${sessionId} has no company. Bind a company first.`);
-        const { token, company } = await withCompany({ company: opts.company ?? current.companySlug });
         const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath);
+        const { token, company } = await withCompany({ company: opts.company ?? current.companySlug });
         await ensureProjectBoard({
             token,
             company: {
@@ -2026,6 +2143,13 @@ export function registerMeshCommand(program, deps = {}) {
         .option("--dry-run", "Read the current Board and print computed story statuses without writing")
         .option("--json", "Print {projectId, threadId, channelId, version, stories}")
         .action((projectId, opts) => wrap(() => runProjectEnsure(projectId, opts))());
+    project
+        .command("reconcile <projectId>")
+        .description("Read the project Board and report drift from a PRD ledger")
+        .requiredOption("--company <slug|uid>", "Company slug or cloud uid")
+        .requiredOption("--stories-file <path>", "PRD JSON file with userStories")
+        .option("--json", "Print machine-readable mismatch records")
+        .action((projectId, opts) => wrap(() => runProjectReconcile(projectId, opts))());
     project
         .command("register <projectId>")
         .description("Register an existing Board and bind its project channel; use project ensure to create or repair a Board")