@indigoai-us/hq-cli 5.128.0 → 5.129.0

package/dist/commands/report.js

@@ -0,0 +1,310 @@
+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";
+function reportPath(channelId, reportId) {
+    return `/v1/notify/channels/${encodeURIComponent(channelId)}/reports/${encodeURIComponent(reportId)}`;
+}
+function errorMessage(error) {
+    if (error instanceof ReportPublishError)
+        return plainFailureReason(error);
+    return "Report command failed. Check the report context and try again.";
+}
+function print(value, json) {
+    if (json)
+        console.log(JSON.stringify(value, null, 2));
+    else
+        console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
+}
+/** Explicit context has priority; discovery is the authenticated fallback for normal CLI use. */
+export async function resolveReport(token, reportId, requestedChannelId) {
+    const explicit = requestedChannelId ?? process.env.HQ_REPORT_CHANNEL_ID;
+    if (explicit) {
+        const res = await vaultApiFetch({ token, path: reportPath(explicit, reportId) });
+        if (!res.ok)
+            throw new ReportPublishError("Report was not found in the supplied channel context.");
+        const body = await res.json();
+        if (!body.report)
+            throw new ReportPublishError("Report response was incomplete.");
+        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.
+    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 = [];
+    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 (!res.ok)
+            continue;
+        const body = await res.json();
+        if (body.report)
+            matches.push(body.report);
+    }
+    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.");
+}
+export async function patchReport(token, report, patch) {
+    const res = await vaultApiFetch({ token, path: reportPath(report.channelId, report.reportId), method: "PATCH", body: patch });
+    if (res.status === 409) {
+        const body = await res.json().catch(() => ({}));
+        if (body.error === "already-running")
+            throw new ReportPublishError("already running", "already-running");
+        throw new ReportPublishError("Report changed while it was being updated.");
+    }
+    if (!res.ok)
+        throw new ReportPublishError("Could not update the report record.");
+    const body = await res.json();
+    if (!body.report)
+        throw new ReportPublishError("Report update response was incomplete.");
+    return body.report;
+}
+function deployHeaders(token, json = true, extra = {}) {
+    return {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+        ...(json ? { "Content-Type": "application/json" } : {}),
+        ...extra,
+    };
+}
+async function deployJson(token, route, method, body, extraHeaders = {}) {
+    let res;
+    try {
+        res = await fetch(`${DEPLOY_API_URL.replace(/\/+$/, "")}${route}`, {
+            method,
+            headers: deployHeaders(token, body !== undefined, extraHeaders),
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+    }
+    catch {
+        throw new ReportPublishError("Could not reach hq-deploy.");
+    }
+    if (!res.ok)
+        throw new ReportPublishError("hq-deploy rejected the report deployment.");
+    return await res.json();
+}
+export async function resolveCompanySlug(token, companyUid) {
+    const res = await vaultApiFetch({ token, path: `/entity/${encodeURIComponent(companyUid)}` });
+    if (!res.ok)
+        throw new ReportPublishError("Could not resolve the report's company for deploy.");
+    const body = await res.json();
+    const slug = body.entity?.slug;
+    if (!slug)
+        throw new ReportPublishError("Could not resolve the report's company for deploy.");
+    return slug;
+}
+async function orgFor(token, report) {
+    const slug = report.companyUid ? await resolveCompanySlug(token, report.companyUid) : undefined;
+    return deployOrgContext(report, slug);
+}
+async function findOrCreateApp(token, slug, org) {
+    const listed = await deployJson(token, "/api/apps", "GET", undefined, org.headers);
+    const existing = Array.isArray(listed.apps)
+        ? listed.apps.find((app) => !!app && typeof app === "object" && (app.subdomain === slug || app.name === slug))
+        : undefined;
+    const app = existing ?? await deployJson(token, "/api/apps", "POST", { name: slug, type: "static" }, org.headers);
+    const id = typeof app.id === "string" ? app.id : undefined;
+    const subdomain = typeof app.subdomain === "string" ? app.subdomain : undefined;
+    if (!id || !subdomain)
+        throw new ReportPublishError("hq-deploy returned an incomplete app record.");
+    return { id, subdomain };
+}
+export async function deployReportStatic(token, input) {
+    const app = await findOrCreateApp(token, input.slug, input.org);
+    await deployJson(token, `/api/apps/${encodeURIComponent(app.id)}/access-policy`, "PUT", input.access, input.org.headers);
+    const tarball = buildReportTarball(input.files);
+    const deployment = await deployJson(token, "/api/deploys", "POST", {
+        appSlug: app.subdomain,
+        ...(input.org.org ? { org: input.org.org } : {}),
+        manifest: { files: [], size: tarball.sizeBytes, sha256: tarball.sha256 },
+    }, input.org.headers);
+    const deployId = typeof deployment.deployId === "string" ? deployment.deployId : undefined;
+    const presignedUrl = typeof deployment.presignedUrl === "string" ? deployment.presignedUrl : undefined;
+    if (!deployId || !presignedUrl)
+        throw new ReportPublishError("hq-deploy did not create an upload.");
+    let upload;
+    try {
+        upload = await fetch(presignedUrl, { method: "PUT", headers: { "Content-Type": "application/gzip" }, body: tarball.bytes });
+    }
+    catch {
+        throw new ReportPublishError("Report upload failed.");
+    }
+    if (!upload.ok)
+        throw new ReportPublishError("Report upload failed.");
+    const completed = await deployJson(token, `/api/deploys/${encodeURIComponent(deployId)}/complete`, "POST", { appSlug: app.subdomain }, input.org.headers);
+    const url = typeof completed.url === "string" ? completed.url : `https://${app.subdomain}.indigo-hq.com`;
+    return { appId: app.id, url, deployId };
+}
+async function publishWithOrg(token, report, directory, draft) {
+    return publishReport(report, directory, draft, {
+        patch: (current, patch) => patchReport(token, current, patch),
+        deploy: async (input) => {
+            const org = await orgFor(token, report);
+            return deployReportStatic(token, { ...input, org });
+        },
+        now: () => new Date().toISOString(),
+    });
+}
+async function publishAction(reportId, options) {
+    const token = await ensureCognitoToken();
+    const report = await resolveReport(token, reportId, options.channel);
+    print(await publishWithOrg(token, report, options.dir, options.draft === true), options.json === true);
+}
+async function promoteAction(reportId, options) {
+    const token = await ensureCognitoToken();
+    const report = await resolveReport(token, reportId, options.channel);
+    const directory = options.dir?.trim() ? options.dir : conventionReportDir(reportId);
+    const published = await publishWithOrg(token, report, directory, false);
+    // A promotion makes the freshly deployed live page authoritative. Null clears
+    // the draft pointer; omitting the field would leave the old draft in place.
+    const updated = published.draft
+        ? await patchReport(token, published, { draft: null, state: "live" })
+        : published;
+    print(updated, options.json === true);
+}
+async function getAction(reportId, options) {
+    const report = await resolveReport(await ensureCognitoToken(), reportId, options.channel);
+    print(report, options.json === true);
+}
+async function discardDraftAction(reportId, options) {
+    const token = await ensureCognitoToken();
+    const report = await resolveReport(token, reportId, options.channel);
+    const org = await orgFor(token, report);
+    if (report.draft?.appId) {
+        const res = await fetch(`${DEPLOY_API_URL.replace(/\/+$/, "")}/api/apps/${encodeURIComponent(report.draft.appId)}`, {
+            method: "DELETE",
+            headers: deployHeaders(token, false, org.headers),
+        });
+        if (!res.ok && res.status !== 404)
+            throw new ReportPublishError("Could not remove the draft deployment.");
+    }
+    const updated = await patchReport(token, report, { draft: null, state: report.url ? "live" : "draft-pending" });
+    print(updated, options.json === true);
+}
+async function accessAction(reportId, options) {
+    if (!["company", "selected", "password", "public"].includes(options.mode)) {
+        throw new ReportPublishError("Access mode must be company, selected, password, or public.");
+    }
+    if (options.mode === "password" && !options.password) {
+        throw new ReportPublishError("A password is required for password access mode.");
+    }
+    const token = await ensureCognitoToken();
+    const report = await resolveReport(token, reportId, options.channel);
+    const appId = report.deployAppId ?? report.draft?.appId;
+    if (!appId)
+        throw new ReportPublishError("Publish the report before changing its access policy.");
+    const companyUid = report.companyUid ?? "personal";
+    const policy = {
+        mode: options.mode,
+        companyUid,
+        users: options.mode === "selected" ? [{ id: report.createdBy }] : [],
+        groups: [],
+        ...(options.mode === "password" && options.password ? { password: options.password } : {}),
+    };
+    const org = await orgFor(token, report);
+    const result = await deployJson(token, `/api/apps/${encodeURIComponent(appId)}/access-policy`, "PUT", policy, org.headers);
+    print(result, options.json === true);
+}
+async function cancelOwnedJob(token, agentUid, jobId) {
+    const res = await vaultApiFetch({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/jobs/${encodeURIComponent(jobId)}/cancel`,
+        method: "POST",
+    });
+    if (!res.ok && res.status !== 404)
+        throw new ReportPublishError("Could not remove the report job.");
+}
+async function adoptAction(reportId, options) {
+    const token = await ensureCognitoToken();
+    const report = await resolveReport(token, reportId, options.channel);
+    const updated = await adoptReport(report, {
+        cancelJob: (jobId) => cancelOwnedJob(token, report.ownerAgentUid, jobId),
+        createJob: async (input) => {
+            const res = await vaultApiFetch({
+                token,
+                path: `/v1/agents/${encodeURIComponent(report.ownerAgentUid)}/jobs`,
+                method: "POST",
+                body: input,
+            });
+            if (!res.ok)
+                throw new ReportPublishError("Could not install the report job.");
+            const body = await res.json();
+            const jobId = body.job?.jobId ?? body.jobId;
+            if (!jobId)
+                throw new ReportPublishError("Jobs API returned an incomplete job.");
+            return { jobId };
+        },
+        patch: (current, patch) => patchReport(token, current, patch),
+    });
+    print(updated, options.json === true);
+}
+async function decommissionAction(reportId, options) {
+    const token = await ensureCognitoToken();
+    const report = await resolveReport(token, reportId, options.channel);
+    const org = await orgFor(token, report);
+    const leftover = [];
+    for (const id of [report.deployAppId, report.draft?.appId]) {
+        if (!id)
+            continue;
+        try {
+            const res = await fetch(`${DEPLOY_API_URL.replace(/\/+$/, "")}/api/apps/${encodeURIComponent(id)}`, {
+                method: "DELETE",
+                headers: deployHeaders(token, false, org.headers),
+            });
+            if (res.status === 404)
+                leftover.push("The published page was already gone.");
+            else if (!res.ok)
+                leftover.push("A deployment could not be deactivated.");
+        }
+        catch {
+            leftover.push("A deployment could not be reached.");
+        }
+    }
+    // The durable report is marked decommissioned by hq-pro before this prompt.
+    // Cleanup gaps stay on the result so a missing app or offline bot does not roll the record back.
+    if (report.jobId) {
+        try {
+            await cancelOwnedJob(token, report.ownerAgentUid, report.jobId);
+        }
+        catch {
+            leftover.push("The report job is still installed.");
+        }
+    }
+    const note = leftover.length ? [...new Set(leftover)].join(" ") : null;
+    print({ reportId: report.reportId, decommissioned: true, note }, options.json === true);
+}
+export function registerReportCommand(program) {
+    const report = program.command("report").description("Publish and manage a channel report owned by this bot.");
+    const context = (command) => command.option("--channel <channelId>", "report channel context (or set HQ_REPORT_CHANNEL_ID)");
+    context(report.command("get <reportId>").option("--json").action((reportId, options) => runReportCommand(() => getAction(reportId, options))));
+    context(report.command("publish <reportId>").requiredOption("--dir <path>").option("--draft").option("--json").action((reportId, options) => runReportCommand(() => publishAction(reportId, options))));
+    context(report.command("promote <reportId>").option("--dir <path>", "report folder; defaults to <workerDir>/reports/<reportId>").option("--json").action((reportId, options) => runReportCommand(() => promoteAction(reportId, options))));
+    context(report.command("discard-draft <reportId>").option("--json").action((reportId, options) => runReportCommand(() => discardDraftAction(reportId, options))));
+    context(report.command("access <reportId>").requiredOption("--mode <mode>", "company|selected|password|public").option("--password <password>").option("--json").action((reportId, options) => runReportCommand(() => accessAction(reportId, options))));
+    context(report.command("decommission <reportId>").option("--json").action((reportId, options) => runReportCommand(() => decommissionAction(reportId, options))));
+    context(report.command("adopt <reportId>").option("--json").action((reportId, options) => runReportCommand(() => adoptAction(reportId, options))));
+    report.command("templates").option("--json").action((options) => {
+        const templates = listReportTemplates().map(({ name, path: templatePath }) => ({ name, path: templatePath }));
+        print(templates, options.json === true);
+    });
+}
+export async function runReportCommand(action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        console.error(errorMessage(error));
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/lib/report-publish.d.ts

@@ -0,0 +1,173 @@
+/** Mirrors the deploy skill's static-report guardrails. */
+export declare const REPORT_SOURCE_MAX_BYTES: number;
+export declare const REPORT_BUNDLE_MAX_BYTES: number;
+export declare const REPORT_SOURCE_MAX_FILES = 100;
+export declare const REPORT_CSP = "default-src 'none'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'none'; frame-src 'none'; form-action 'none'";
+export type ReportLastRun = {
+    at: string;
+    status: "running" | "succeeded" | "failed";
+    reason?: string;
+    version?: string;
+};
+export type ReportSchedule = {
+    kind: "daily" | "weekly" | "manual";
+    time: string;
+    timezone: string;
+    weekday?: number;
+};
+export type ChannelReport = {
+    reportId: string;
+    channelId: string;
+    companyUid?: string;
+    createdBy: string;
+    ownerAgentUid: string;
+    deploySlug: string;
+    state: "draft-pending" | "draft-ready" | "live" | "decommissioned";
+    instructions: string;
+    revision: number;
+    deployAppId?: string;
+    url?: string;
+    draft?: {
+        url: string;
+        appId: string;
+        generatedAt: string;
+        note?: string;
+    };
+    lastRun?: ReportLastRun;
+    jobId?: string;
+    jobState?: "pending" | "adopted" | "failed";
+    jobStateReason?: string;
+    schedule?: ReportSchedule;
+};
+export type ReportPatch = Partial<Pick<ChannelReport, "deployAppId" | "url" | "state" | "lastRun">> & {
+    previewImage?: string;
+    previewTitle?: string;
+    jobState?: "pending" | "adopted" | "failed";
+    jobStateReason?: string | null;
+    /** Null clears the live draft pointer or the adopted job id. */
+    draft?: ChannelReport["draft"] | null;
+    jobId?: string | null;
+};
+export type DeployOrgContext = {
+    headers: Record<string, string>;
+    org?: string;
+};
+export type StaticFile = {
+    path: string;
+    content: string;
+    encoding?: "utf8" | "base64";
+};
+export type ReportSource = {
+    files: StaticFile[];
+    previewTitle?: string;
+    previewImage?: string;
+};
+export type DeployAccessPolicy = {
+    mode: "company" | "selected" | "password" | "public";
+    companyUid: string;
+    users: Array<{
+        id: string;
+    }>;
+    groups: Array<{
+        id: string;
+    }>;
+    password?: string;
+};
+export type ReportDeployment = {
+    appId: string;
+    url: string;
+    deployId: string;
+};
+export interface ReportPublishDependencies {
+    patch(report: ChannelReport, patch: ReportPatch): Promise<ChannelReport>;
+    deploy(input: {
+        slug: string;
+        files: StaticFile[];
+        access: DeployAccessPolicy;
+    }): Promise<ReportDeployment>;
+    now(): string;
+    /** Owner DM for a failed run. Omitted by callers that only record lastRun. */
+    notifyOwner?(notice: {
+        to: string;
+        body: string;
+    }): Promise<void>;
+}
+/**
+ * Plain owner DM after a failed run. Suppressed for the publish lock
+ * ("already running") so a second run does not page the owner.
+ */
+export declare function ownerFailureNotice(input: {
+    code?: string | null;
+    reason: string;
+    reportUrl?: string | null;
+    ownerPersonUid: string;
+}): {
+    to: string;
+    body: string;
+} | null;
+export interface ReportAdoptDependencies {
+    createJob(input: {
+        prompt: string;
+        schedule: {
+            kind: "recurring";
+            cron: string;
+            timezone: string;
+        };
+        context: {
+            reportId: string;
+            channelId: string;
+        };
+    }): Promise<{
+        jobId: string;
+    }>;
+    cancelJob(jobId: string): Promise<void>;
+    patch(report: ChannelReport, patch: ReportPatch): Promise<ChannelReport>;
+}
+export declare class ReportPublishError extends Error {
+    readonly code: "already-running" | "source-invalid" | "deploy-failed" | "job-failed";
+    constructor(message: string, code?: "already-running" | "source-invalid" | "deploy-failed" | "job-failed");
+}
+/** A deliberately boring, token-safe failure reason stored on the report. */
+export declare function plainFailureReason(error: unknown): string;
+export declare function injectReportCsp(html: string): string;
+/** Read a deployable static report and inject its non-negotiable CSP. */
+export declare function loadReportSource(directory: string): ReportSource;
+/** Access policy defaults deliberately keep personal reports owner-only. */
+export declare function defaultAccessPolicy(report: ChannelReport): DeployAccessPolicy;
+export declare function reportDeploySlug(report: ChannelReport, draft: boolean): string;
+/** Source folder convention: `<bot workerDir>/reports/<reportId>/`. */
+export declare function conventionReportDir(reportId: string, workerDir?: string): string;
+/** Company deploys send X-Org-Slug; personal-channel reports have no company to gate on. */
+export declare function deployOrgContext(report: ChannelReport, companySlug?: string): DeployOrgContext;
+/**
+ * EventBridge Scheduler cron for the agent jobs API.
+ * Daily uses `?` on the weekday field; weekly pins the weekday and `?` on the day-of-month.
+ */
+export declare function reportJobCron(schedule: ReportSchedule): string | null;
+/** Job prompt is the stored update-report runbook with this report id filled in. */
+export declare function reportJobPrompt(reportId: string): string;
+/**
+ * Install, replace, or delete this bot's own scheduled job for a report.
+ * Jobs-API failures are recorded as jobState=failed with a plain reason.
+ */
+export declare function adoptReport(report: ChannelReport, deps: ReportAdoptDependencies): Promise<ChannelReport>;
+/**
+ * Lock, deploy, then persist a report run. Every known failure after lock
+ * acquisition writes a terminal lastRun so the 15-minute server TTL is a
+ * crash-only fallback rather than normal control flow.
+ */
+export declare function publishReport(report: ChannelReport, directory: string, draft: boolean, deps: ReportPublishDependencies): Promise<ChannelReport>;
+type BuiltTarball = {
+    bytes: Buffer;
+    sha256: string;
+    sizeBytes: number;
+};
+/** hq-deploy static payload format: index.html stays at the archive root. */
+export declare function buildReportTarball(files: StaticFile[]): BuiltTarball;
+/** Isolated test helper for creating a compliant report source. */
+export declare function makeReportFixture(html: string): {
+    directory: string;
+    cleanup: () => void;
+};
+export {};
+//# sourceMappingURL=report-publish.d.ts.map