@indigoai-us/hq-cli 5.138.0 → 5.139.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [5.139.0] — 2026-09-23
+
+### Added
+
+- `hq mesh project ensure <projectId> --company <slug> --stories-file prd.json` registers a missing Board view, merges an existing one without replacing live story status or assignee, then checks the company, project id, story ids, and repo paths. `hq mesh project set --create` writes a view when the GET is a 404.
+
+### Fixed
+
+- `hq report` now resolves report ids through local channel context and channel report lists instead of probing every channel with a report GET that can produce avoidable 404s.
+
 ## [5.138.0] — 2026-09-23
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -5708,11 +5708,36 @@ export declare const COMMAND_CATALOG: readonly [{
             }, {
                 readonly flags: "--repo <path[@branch]>";
                 readonly description: "Repository binding (repeatable)";
+            }, {
+                readonly flags: "--create";
+                readonly description: "Create the Board view when the GET is a 404";
             }, {
                 readonly flags: "--json";
                 readonly description: "Print machine-readable JSON";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "ensure";
+            readonly description: "Idempotently register a PRD on the Board and verify the view";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <projectId>";
+            readonly arguments: readonly [{
+                readonly name: "projectId";
+                readonly required: true;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [{
+                readonly flags: "--company <slug|uid>";
+                readonly description: "Company slug or cloud uid";
+            }, {
+                readonly flags: "--stories-file <path>";
+                readonly description: "PRD JSON file with userStories and metadata.repos";
+            }, {
+                readonly flags: "--json";
+                readonly description: "Print {projectId, threadId, channelId, version, stories}";
+            }];
+            readonly subcommands: readonly [];
         }, {
             readonly name: "register";
             readonly description: "POST project registration to create or bind its project channel and Board";

package/dist/command-catalog.generated.js

@@ -7367,6 +7367,10 @@ export const COMMAND_CATALOG = [
                                 "flags": "--repo <path[@branch]>",
                                 "description": "Repository binding (repeatable)"
                             },
+                            {
+                                "flags": "--create",
+                                "description": "Create the Board view when the GET is a 404"
+                            },
                             {
                                 "flags": "--json",
                                 "description": "Print machine-readable JSON"
@@ -7374,6 +7378,35 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "ensure",
+                        "description": "Idempotently register a PRD on the Board and verify the view",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <projectId>",
+                        "arguments": [
+                            {
+                                "name": "projectId",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--company <slug|uid>",
+                                "description": "Company slug or cloud uid"
+                            },
+                            {
+                                "flags": "--stories-file <path>",
+                                "description": "PRD JSON file with userStories and metadata.repos"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "Print {projectId, threadId, channelId, version, stories}"
+                            }
+                        ],
+                        "subcommands": []
+                    },
                     {
                         "name": "register",
                         "description": "POST project registration to create or bind its project channel and Board",

package/dist/commands/mesh.js

@@ -282,6 +282,33 @@ function parseProjectPlan(raw, source) {
         throw err;
     }
 }
+function httpStatus(err) {
+    if (err && typeof err === "object" && "status" in err && typeof err.status === "number") {
+        return err.status;
+    }
+    return undefined;
+}
+function mergeProjectStories(current, planned) {
+    const currentById = new Map(current.map((story) => [story.id, story]));
+    const plannedIds = new Set(planned.map((story) => story.id));
+    const merged = planned.map((story) => {
+        const live = currentById.get(story.id);
+        if (!live)
+            return story;
+        const status = live.status || story.status;
+        return {
+            ...story,
+            ...(status ? { status } : {}),
+            passes: status === "done" ? true : typeof live.passes === "boolean" ? live.passes : story.passes,
+            ...(live.assigneeUid ? { assigneeUid: live.assigneeUid } : {}),
+        };
+    });
+    return [...merged, ...current.filter((story) => !plannedIds.has(story.id))];
+}
+function mergeProjectRepos(current, planned) {
+    const plannedPaths = new Set(planned.map((repo) => repo.path));
+    return [...planned, ...current.filter((repo) => !plannedPaths.has(repo.path))];
+}
 async function runProjectSet(projectId, opts) {
     if (opts.storiesFile && opts.storiesJson) {
         fail("Pass only one of --stories-file or --stories-json.");
@@ -300,21 +327,45 @@ async function runProjectSet(projectId, opts) {
             ? opts.repo.map((repo, index) => parseProjectRepoSpec(repo, `--repo[${index}]`))
             : undefined;
     const { token, company } = await withCompany(opts);
-    const current = await getProjectView(token, company.companyUid, projectId);
+    let current;
+    try {
+        current = await getProjectView(token, company.companyUid, projectId);
+    }
+    catch (err) {
+        if (httpStatus(err) === 404 && opts.create) {
+            if (!source && !opts.name?.trim()) {
+                fail("`--create` needs --name or a stories file when the Board view does not exist.");
+            }
+            current = undefined;
+        }
+        else {
+            throw err;
+        }
+    }
+    if (!current && !opts.create) {
+        fail(`Work mesh project ${projectId} has no Board view. Re-run with --create to add one.`);
+    }
+    if (!current) {
+        // Register requires a genesis thread and a project view. Create the thread
+        // before the PUT; register runs after the view exists.
+        await ensureProjectThread(token, company, projectId, {
+            summary: opts.name?.trim() || source?.name || projectId,
+        });
+    }
     const principalUid = await resolveMeshPrincipalUid(token, loadCachedTokens());
     const PROJECT_CHANGED = "The Board changed while you were editing. Re-run to pick up the latest.";
     let view;
     try {
         view = await putProjectView(token, company.companyUid, projectId, {
-            name: opts.name?.trim() || source?.name || current.name,
+            name: opts.name?.trim() || source?.name || current?.name || projectId,
             ...(opts.description !== undefined
                 ? { description: opts.description }
                 : source?.description !== undefined
                     ? { description: source.description }
-                    : { description: current.description }),
-            stories: source?.stories ?? current.stories,
-            repos: explicitRepos ?? source?.repos ?? current.repos,
-            ...(current.version !== undefined ? { expectedVersion: current.version } : {}),
+                    : { description: current?.description ?? "" }),
+            stories: source?.stories ?? current?.stories ?? [],
+            repos: explicitRepos ?? source?.repos ?? current?.repos ?? [],
+            ...(current?.version !== undefined ? { expectedVersion: current.version } : {}),
         });
     }
     catch (err) {
@@ -327,6 +378,16 @@ async function runProjectSet(projectId, opts) {
         }
         throw err;
     }
+    if (!current) {
+        const registration = await registerMeshProject(token, company.companyUid, projectId);
+        if (!registration.threadId || !registration.channelId) {
+            fail("Work mesh registration did not return a threadId and channelId.");
+        }
+        const verified = await getProjectView(token, company.companyUid, projectId);
+        if (verified.projectId !== projectId || verified.companyUid !== company.companyUid) {
+            fail(`Work mesh project set --create: verified view does not match ${company.companyUid}/${projectId}.`);
+        }
+    }
     if (opts.json) {
         console.log(JSON.stringify({ ok: true, action: "project.set", principalUid, ...view }, null, 2));
         return;
@@ -347,6 +408,90 @@ async function runProjectRegister(projectId, opts) {
     }
     console.log(`Work mesh: project ${registration.projectId} registered (${boardState}; channel ${registration.channelId} ${registration.channelCreated ? "created" : "bound"})`);
 }
+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 { token, company } = await withCompany(opts);
+    let current;
+    try {
+        current = await getProjectView(token, company.companyUid, projectId);
+    }
+    catch (err) {
+        if (httpStatus(err) !== 404)
+            throw err;
+    }
+    // Genesis thread, then the view, then register. Register returns 403
+    // PROJECT_NOT_IN_COMPANY until both exist.
+    const genesis = await ensureProjectThread(token, company, projectId, {
+        summary: source.name || projectId,
+    });
+    if (!genesis.threadId)
+        fail("Work mesh did not return a threadId.");
+    if (!current) {
+        await putProjectView(token, company.companyUid, projectId, {
+            name: source.name || projectId,
+            description: source.description ?? "",
+            stories: source.stories,
+            repos: source.repos ?? [],
+        });
+    }
+    else {
+        const stories = mergeProjectStories(current.stories, source.stories);
+        const repos = mergeProjectRepos(current.repos, source.repos ?? []);
+        const name = source.name || current.name;
+        const description = source.description !== undefined ? source.description : current.description;
+        const changed = name !== current.name ||
+            description !== current.description ||
+            JSON.stringify(stories) !== JSON.stringify(current.stories) ||
+            JSON.stringify(repos) !== JSON.stringify(current.repos);
+        if (changed) {
+            await putProjectView(token, company.companyUid, projectId, {
+                name,
+                description,
+                stories,
+                repos,
+                ...(current.version !== undefined ? { expectedVersion: current.version } : {}),
+            });
+        }
+    }
+    const registration = await registerMeshProject(token, company.companyUid, projectId);
+    if (!registration.threadId || !registration.channelId) {
+        fail("Work mesh registration did not return a threadId and channelId.");
+    }
+    const verified = await getProjectView(token, company.companyUid, projectId);
+    if (verified.companyUid !== company.companyUid) {
+        fail(`Work mesh project ensure: company mismatch (expected ${company.companyUid}, got ${verified.companyUid}).`);
+    }
+    if (verified.projectId !== projectId) {
+        fail(`Work mesh project ensure: project id mismatch (expected ${projectId}, got ${verified.projectId}).`);
+    }
+    for (const story of source.stories) {
+        if (!verified.stories.some((row) => row.id === story.id)) {
+            fail(`Work mesh project ensure: missing story ${story.id}.`);
+        }
+    }
+    for (const repo of source.repos ?? []) {
+        if (!verified.repos.some((row) => row.path === repo.path)) {
+            fail(`Work mesh project ensure: missing repo ${repo.path}.`);
+        }
+    }
+    if (verified.version === undefined) {
+        fail("Work mesh project ensure: verified view has no version.");
+    }
+    const payload = {
+        projectId: verified.projectId,
+        threadId: registration.threadId,
+        channelId: registration.channelId,
+        version: verified.version,
+        stories: verified.stories,
+    };
+    if (opts.json) {
+        console.log(JSON.stringify(payload));
+        return;
+    }
+    console.log(`Work mesh: project ${payload.projectId} ensured (thread ${payload.threadId}, channel ${payload.channelId}, ${payload.stories.length} stories)`);
+}
 async function runDoctor(opts) {
     if (opts.apply) {
         fail("`hq mesh doctor --apply` (paced Board PUTs from local prd.json) is not in the CLI yet.\n" +
@@ -1347,8 +1492,16 @@ export function registerMeshCommand(program) {
         .option("--stories-json <json>", "Story array or JSON object with userStories")
         .option("--repos-json <json>", "Repository array, such as [{path,branch}]")
         .option("--repo <path[@branch]>", "Repository binding (repeatable)", collectRepeatable)
+        .option("--create", "Create the Board view when the GET is a 404")
         .option("--json", "Print machine-readable JSON")
         .action((projectId, opts) => wrap(() => runProjectSet(projectId, opts))());
+    project
+        .command("ensure <projectId>")
+        .description("Idempotently register a PRD on the Board and verify the view")
+        .requiredOption("--company <slug|uid>", "Company slug or cloud uid")
+        .requiredOption("--stories-file <path>", "PRD JSON file with userStories and metadata.repos")
+        .option("--json", "Print {projectId, threadId, channelId, version, stories}")
+        .action((projectId, opts) => wrap(() => runProjectEnsure(projectId, opts))());
     project
         .command("register <projectId>")
         .description("POST project registration to create or bind its project channel and Board")

package/dist/commands/report.d.ts

@@ -1,4 +1,3 @@
-/** `hq report` — safe channel-report lifecycle commands for bot runbooks. */
 import { Command } from "commander";
 import { buildReportTarball, deployOrgContext, type ChannelReport, type DeployAccessPolicy, type ReportDeployment, type ReportPatch } from "../lib/report-publish.js";
 /** Explicit context has priority; discovery is the authenticated fallback for normal CLI use. */

package/dist/commands/report.js

@@ -1,11 +1,80 @@
+/** `hq report` — safe channel-report lifecycle commands for bot runbooks. */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import { ensureCognitoToken, } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
 import { listReportTemplates } from "../lib/report-templates.js";
 import { adoptReport, buildReportTarball, conventionReportDir, deployOrgContext, ReportPublishError, plainFailureReason, publishReport, } from "../lib/report-publish.js";
 const DEPLOY_API_URL = process.env.HQ_DEPLOY_API_URL ?? "https://api.indigo-hq.com";
+const REPORT_CHANNEL_STATE_FILE = "report-channels.json";
+const MAX_REPORT_DISCOVERY_CHANNELS = 50;
 function reportPath(channelId, reportId) {
     return `/v1/notify/channels/${encodeURIComponent(channelId)}/reports/${encodeURIComponent(reportId)}`;
 }
+function reportListPath(channelId) {
+    return `/v1/notify/channels/${encodeURIComponent(channelId)}/reports`;
+}
+function reportChannelStatePath() {
+    const stateDir = process.env.HQ_STATE_DIR?.trim() || path.join(os.homedir(), ".hq");
+    return path.join(stateDir, REPORT_CHANNEL_STATE_FILE);
+}
+function readReportChannelState() {
+    const file = reportChannelStatePath();
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { version: 1, channels: {} };
+        }
+        throw new ReportPublishError("Could not read the local report channel state.");
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || !parsed.channels || typeof parsed.channels !== "object")
+            throw new Error("invalid state");
+        const channels = Object.fromEntries(Object.entries(parsed.channels).filter((entry) => typeof entry[1] === "string" && entry[1].length > 0));
+        return { version: 1, channels };
+    }
+    catch {
+        throw new ReportPublishError("Could not read the local report channel state.");
+    }
+}
+function rememberReportChannel(reportId, channelId) {
+    const file = reportChannelStatePath();
+    const state = readReportChannelState();
+    state.channels[reportId] = channelId;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        if (fs.existsSync(temporary))
+            fs.rmSync(temporary, { force: true });
+    }
+}
+function rememberReportChannelAfterSuccess(report) {
+    try {
+        rememberReportChannel(report.reportId, report.channelId);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : "local state write failed";
+        console.warn(`Report succeeded but local channel context was not saved: ${reason}`);
+    }
+}
+function locallyRecordedChannel(reportId) {
+    return readReportChannelState().channels[reportId];
+}
+function notFoundMessage(scannedChannels) {
+    const scope = scannedChannels >= MAX_REPORT_DISCOVERY_CHANNELS
+        ? `the first ${MAX_REPORT_DISCOVERY_CHANNELS} channels`
+        : `${scannedChannels} channel${scannedChannels === 1 ? "" : "s"}`;
+    return `Report not found. Pass --channel or set HQ_REPORT_CHANNEL_ID. Searched ${scope}.`;
+}
 function errorMessage(error) {
     if (error instanceof ReportPublishError)
         return plainFailureReason(error);
@@ -29,30 +98,38 @@ export async function resolveReport(token, reportId, requestedChannelId) {
             throw new ReportPublishError("Report response was incomplete.");
         return body.report;
     }
+    const recordedChannel = locallyRecordedChannel(reportId);
+    if (recordedChannel) {
+        const res = await vaultApiFetch({ token, path: reportPath(recordedChannel, reportId) });
+        if (res.ok) {
+            const body = await res.json();
+            if (body.report)
+                return body.report;
+        }
+    }
     // The report API is intentionally channel-scoped. Discover only among the
-    // caller's existing channels rather than inventing an unscoped report route.
+    // caller's existing channels, using list endpoints so missing reports never
+    // become one server-side 404 per channel.
     const channels = await vaultApiFetch({ token, path: "/v1/notify/channels" });
     if (!channels.ok)
         throw new ReportPublishError("Could not resolve the report channel.");
     const listed = await channels.json();
-    const matches = [];
+    let scannedChannels = 0;
     for (const row of listed.channels ?? []) {
         if (!row.channelId)
             continue;
-        const res = await vaultApiFetch({ token, path: reportPath(row.channelId, reportId) });
-        if (res.status === 404)
-            continue;
+        if (scannedChannels >= MAX_REPORT_DISCOVERY_CHANNELS)
+            break;
+        scannedChannels += 1;
+        const res = await vaultApiFetch({ token, path: reportListPath(row.channelId) });
         if (!res.ok)
             continue;
         const body = await res.json();
-        if (body.report)
-            matches.push(body.report);
+        const match = body.reports?.find((report) => report.reportId === reportId);
+        if (match)
+            return match;
     }
-    if (matches.length === 1)
-        return matches[0];
-    if (matches.length > 1)
-        throw new ReportPublishError("Report ID is ambiguous; pass --channel or set HQ_REPORT_CHANNEL_ID.");
-    throw new ReportPublishError("Report not found. Pass --channel or set HQ_REPORT_CHANNEL_ID.");
+    throw new ReportPublishError(notFoundMessage(scannedChannels));
 }
 export async function patchReport(token, report, patch) {
     const res = await vaultApiFetch({ token, path: reportPath(report.channelId, report.reportId), method: "PATCH", body: patch });
@@ -146,7 +223,7 @@ export async function deployReportStatic(token, input) {
     return { appId: app.id, url, deployId };
 }
 async function publishWithOrg(token, report, directory, draft) {
-    return publishReport(report, directory, draft, {
+    const published = await publishReport(report, directory, draft, {
         patch: (current, patch) => patchReport(token, current, patch),
         deploy: async (input) => {
             const org = await orgFor(token, report);
@@ -154,6 +231,8 @@ async function publishWithOrg(token, report, directory, draft) {
         },
         now: () => new Date().toISOString(),
     });
+    rememberReportChannelAfterSuccess(published);
+    return published;
 }
 async function publishAction(reportId, options) {
     const token = await ensureCognitoToken();
@@ -246,6 +325,7 @@ async function adoptAction(reportId, options) {
         },
         patch: (current, patch) => patchReport(token, current, patch),
     });
+    rememberReportChannelAfterSuccess(updated);
     print(updated, options.json === true);
 }
 async function decommissionAction(reportId, options) {

package/dist/lib/mesh/api.d.ts

@@ -31,6 +31,7 @@ export interface MeshProjectStoryInput {
     status?: string;
     passes?: boolean;
     priority?: number;
+    assigneeUid?: string;
 }
 export interface MeshProjectRepo {
     path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.138.0",
+  "version": "5.139.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {