@indigoai-us/hq-cli 5.345.178 → 5.345.180

package/dist/commands/sources.js

@@ -11,18 +11,34 @@
  *   hq sources get       Fetch one source by id.
  *   hq sources channels  Print the canonical SOURCE_CHANNELS enum.
  *   hq sources entities  List entities the caller has access to.
+ *   hq sources runs      Show the local hot-channel run ledger for one day.
+ *   hq sources sync      Run every hot channel now for the signed-in person.
  *
  * Defaults:
  *   --entity   falls back to .hq/config.json activeCompany (per sync.ts).
  *   --format   'table' when stdout is a TTY, 'json' when piped.
  *   --limit    50.
  */
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import chalk from "chalk";
 import { SOURCE_CHANNELS, assertSourceChannel, resolveEntity, listAvailableEntities, listSources, getSource, VaultClient, } from "@indigoai-us/hq-cloud";
-import { ensureCognitoToken, buildVaultConfig, DEFAULT_HQ_ROOT, } from "../utils/cognito-session.js";
+import { ensureCognitoToken, ensureCognitoIdToken, buildVaultConfig, DEFAULT_HQ_ROOT, } from "../utils/cognito-session.js";
+import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { isAuthError } from "../utils/auth-error.js";
+import { IntegrationsCliError, callGateway, fetchUsableApps, gatewayResultIsError, isBuiltInGatewayProvider, raiseForResponse, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
 import { Sentry } from "../sentry.js";
+import { resolveUploadAuthor } from "../utils/upload-author.js";
+import { createSignalsAlertChannelPoster, raiseSignalsFailureAlerts } from "../lib/hot-channels/alert.js";
+import { audienceKey } from "../lib/hot-channels/audience.js";
+import { appendRunLedgerEntry, ledgerDay, readRunLedger, summarizeRunLedger, } from "../lib/hot-channels/ledger.js";
+import { createClaudeSignalsPass } from "../lib/hot-channels/signals-pass.js";
+import { assertSafeSegment } from "../lib/hot-channels/landing.js";
+import { acquireSyncLock, SYNC_LOCK_BUSY_REASON } from "../lib/hot-channels/sync-lock.js";
+import { createBuiltinHotChannelRegistry } from "../lib/hot-channels/adapters/index.js";
+import { listActiveMembers } from "./members.js";
+import { runOnDemandSync, } from "../lib/hot-channels/run.js";
 // ---------------------------------------------------------------------------
 // Access token resolution — honors HQ_ACCESS_TOKEN for tests + CI smoke
 // ---------------------------------------------------------------------------
@@ -209,6 +225,330 @@ async function runEntities(options) {
         .join("\n");
     process.stdout.write([headerLine, sep, body].join("\n") + "\n");
 }
+/**
+ * Reads one day's run ledger (`sources/_runs/@{personKey}/{day}.jsonl` in the
+ * company folder of the local HQ tree). The person key is
+ * `audienceKey([email])` of the signed-in person. No network calls.
+ */
+export async function runRuns(options, now = new Date()) {
+    if (options.today && options.date) {
+        throw new Error("Pass either --today or --date, not both.");
+    }
+    if (options.date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(options.date)) {
+        throw new Error(`--date must be YYYY-MM-DD (got '${options.date}').`);
+    }
+    const day = options.date ?? ledgerDay(now);
+    const company = options.company ?? readActiveCompanySlug(options.hqRoot);
+    if (!company) {
+        throw new Error("No company specified. Pass --company <slug> or set activeCompany in .hq/config.json.");
+    }
+    const email = options.email ?? resolveUploadAuthor()?.email;
+    if (!email) {
+        throw new Error("Could not tell who is signed in. Run `hq login` or pass --email <address>.");
+    }
+    const personKey = audienceKey([email]);
+    const vaultRoot = path.join(options.hqRoot, "companies", company);
+    const { entries, malformed } = await readRunLedger(vaultRoot, personKey, day);
+    const report = {
+        company,
+        personKey,
+        day,
+        adapters: summarizeRunLedger(entries),
+        entries,
+        malformed,
+    };
+    const format = options.format ?? defaultListFormat();
+    if (format === "json") {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        return report;
+    }
+    process.stdout.write(renderRunsTable(report) + "\n");
+    return report;
+}
+function renderRunsTable(report) {
+    const lines = [`Runs for ${report.company} on ${report.day} (UTC), person key @${report.personKey}`];
+    if (report.entries.length === 0) {
+        lines.push("(no runs logged)");
+    }
+    else {
+        const pad = (s, w) => s + " ".repeat(Math.max(0, w - s.length));
+        const header = ["ADAPTER", "RUNS", "SOURCES", "SIGNALS", "FAILED", "LAST FINISHED"];
+        const rows = report.adapters.map((a) => [
+            a.adapter,
+            String(a.runs),
+            String(a.sourcesLanded),
+            String(a.signalsGenerated),
+            String(a.failed),
+            a.lastFinishedAt,
+        ]);
+        const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+        lines.push("", header.map((h, i) => pad(h, widths[i])).join("  "));
+        for (const row of rows)
+            lines.push(row.map((cell, i) => pad(cell, widths[i])).join("  "));
+        lines.push("", "Runs:");
+        for (const e of [...report.entries].sort((a, b) => a.startedAt.localeCompare(b.startedAt))) {
+            const outcome = e.status === "ok"
+                ? "ok"
+                : e.status === "skipped"
+                    ? `skipped: ${e.reason ?? "no reason given"}`
+                    : `failed: ${e.error ?? "unknown error"}`;
+            lines.push(`  ${e.startedAt}  ${e.adapter}  ${e.trigger}  sources=${e.sourcesLanded} signals=${e.signalsGenerated}  ${outcome}`);
+        }
+    }
+    if (report.malformed > 0)
+        lines.push(`(${report.malformed} unreadable line(s) skipped)`);
+    return lines.join("\n");
+}
+const SIGN_IN_PROMPT = "Your HQ session has expired or you're not signed in. Run `hq login`, then `hq sources sync` again.";
+const MAX_TOOL_ERROR_TEXT = 500;
+/** The catalog API's `hotChannels` array, or null when the server has none. */
+async function fetchHotChannels(token, companyUid) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/factory/catalog",
+        query: { companyUid },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to read the integrations catalog");
+    const data = (await res.json());
+    return Array.isArray(data.hotChannels) ? data.hotChannels : null;
+}
+/**
+ * Network access for one sync: the catalog, the person's usable connections,
+ * and tool calls through the HQ gateway. Integration tokens stay server-side;
+ * the gateway routes each call by connection id.
+ */
+export function gatewaySyncDeps(token, companyUid) {
+    return {
+        fetchHotChannels: () => fetchHotChannels(token, companyUid),
+        fetchUsableApps: async () => (await fetchUsableApps(token, companyUid)).apps,
+        async callTool(app, tool, args) {
+            const idempotencyKey = `hq-sources-sync-${randomUUID()}`;
+            const params = isBuiltInGatewayProvider(app.provider)
+                ? {
+                    companyUid,
+                    acceptAsync: true,
+                    name: tool,
+                    arguments: { ...args, companyUid, connectionId: app.connectionId, idempotencyKey },
+                }
+                : {
+                    companyUid,
+                    acceptAsync: true,
+                    name: `${toolPrefixForProvider(app.provider)}.mcp.tools.call`,
+                    arguments: { companyUid, connectionId: app.connectionId, toolName: tool, arguments: args, idempotencyKey },
+                };
+            const message = await callGateway(token, params, idempotencyKey, "tools/call");
+            const payload = unwrapGatewayResult(message.result);
+            if (gatewayResultIsError(message.result) || gatewayResultIsError(payload)) {
+                const text = typeof payload === "string" ? payload : JSON.stringify(payload);
+                throw new IntegrationsCliError((text ?? "tool call failed").slice(0, MAX_TOOL_ERROR_TEXT), {
+                    expected: true,
+                });
+            }
+            return payload;
+        },
+    };
+}
+function signInReport() {
+    return {
+        runId: null,
+        signInRequired: true,
+        outcomes: [],
+        entries: [],
+        notices: [SIGN_IN_PROMPT],
+        exitCode: 1,
+    };
+}
+async function signedInSession(company) {
+    let token;
+    try {
+        token = process.env.HQ_ACCESS_TOKEN || (await ensureCognitoIdToken({ interactive: false }));
+    }
+    catch {
+        return null;
+    }
+    try {
+        return { token, companyUid: await getCompanyUid(token, company) };
+    }
+    catch (err) {
+        if (isAuthError(err) || err.status === 401)
+            return null;
+        throw err;
+    }
+}
+/** The signed-in member's `prs_` uid from the company roster, or null when the roster is unavailable. */
+async function rosterPersonUid(token, companyUid, email) {
+    try {
+        const wanted = email.toLowerCase();
+        const member = (await listActiveMembers(token, companyUid)).find((m) => m.personEmail?.toLowerCase() === wanted);
+        return member?.personUid ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The signed-in person's identities a meeting audience can name: their email
+ * and their `prs_` person uid. The run's `personUid` is the Cognito sub, which
+ * meeting transcripts never carry.
+ */
+async function meetingIdentities(input, session, email) {
+    const personUid = await (input.resolvePersonUid ?? rosterPersonUid)(session.token, session.companyUid, email);
+    return personUid ? [email, personUid] : [email];
+}
+/**
+ * One hot-channel sync for the signed-in person in one company: each adapter
+ * once per usable connection. Writes under `companies/{company}/`: landed
+ * sources in `sources/`, index rows in `sources/_index/`, cursors in
+ * `sources/_cursors/`, one ledger line per adapter in `sources/_runs/`, and
+ * signals in `signals/@{key}/`. `hq sources sync` and the bot's scheduled
+ * hot-signal-sync job both call it. Only one run per person per company goes
+ * at a time: a second one writes a `skipped` ledger line and lands nothing.
+ */
+export async function runCompanyHotChannelSync(input) {
+    assertSafeSegment(input.company, "company");
+    const author = resolveUploadAuthor();
+    const session = author ? await signedInSession(input.company) : null;
+    if (!author || !session)
+        return signInReport();
+    const vaultRoot = path.join(input.hqRoot, "companies", input.company);
+    const personKey = audienceKey([author.email]);
+    const now = input.now ?? (() => new Date());
+    const lock = await acquireSyncLock(vaultRoot, personKey, { now });
+    if (!lock)
+        return skippedReport(input, vaultRoot, personKey, author.userSub, now);
+    try {
+        return await runLockedCompanySync(input, vaultRoot, personKey, author, session, lock.assertHeld);
+    }
+    finally {
+        await lock.release();
+    }
+}
+async function skippedReport(input, vaultRoot, personKey, personUid, now) {
+    const at = now().toISOString();
+    const line = {
+        runId: `run_${randomUUID()}`,
+        trigger: input.trigger ?? "on-demand",
+        adapter: "all",
+        connectionId: null,
+        sourcesLanded: 0,
+        signalsGenerated: 0,
+        startedAt: at,
+        finishedAt: at,
+        status: "skipped",
+        error: null,
+        reason: SYNC_LOCK_BUSY_REASON,
+        personUid,
+        catchUp: input.catchUp ?? false,
+    };
+    await appendRunLedgerEntry(vaultRoot, personKey, line);
+    return {
+        runId: line.runId,
+        signInRequired: false,
+        skipped: true,
+        outcomes: [],
+        entries: [line],
+        notices: [`Another hot-channel sync for ${input.company} is already running, so this one was skipped.`],
+        exitCode: 0,
+    };
+}
+async function runLockedCompanySync(input, vaultRoot, personKey, author, session, lockHeld) {
+    const deps = gatewaySyncDeps(session.token, session.companyUid);
+    const report = await runOnDemandSync({
+        deps,
+        registry: input.registry ??
+            createBuiltinHotChannelRegistry({ vaultRoot, identities: await meetingIdentities(input, session, author.email) }),
+        vaultRoot,
+        personUid: author.userSub,
+        personKey,
+        ...(input.adapter !== undefined ? { adapter: input.adapter } : {}),
+        ...(input.now ? { now: input.now } : {}),
+        ...(input.trigger ? { trigger: input.trigger } : {}),
+        ...(input.catchUp === undefined ? {} : { catchUp: input.catchUp }),
+        ...(input.signalsGenerated ? { signalsGenerated: input.signalsGenerated } : {}),
+        beforeWrite: lockHeld,
+    });
+    if (input.signalsAlert) {
+        const postCompanyChannel = input.signalsAlert.postCompanyChannel ??
+            createSignalsAlertChannelPoster({ hqRoot: input.hqRoot, company: input.company, deps });
+        await raiseSignalsFailureAlerts({
+            vaultRoot,
+            personKey,
+            entries: report.entries,
+            now: input.now ?? (() => new Date()),
+            personName: author.email,
+            sendOwnerDm: input.signalsAlert.sendOwnerDm,
+            ...(postCompanyChannel ? { postCompanyChannel } : {}),
+            ...(input.signalsAlert.log ? { log: input.signalsAlert.log } : {}),
+        });
+    }
+    return report;
+}
+/**
+ * Run every hot channel for the signed-in person now: each adapter once per
+ * usable connection. Writes cursors, landed sources and an `on-demand` ledger
+ * line under `companies/{company}/sources/`, and nothing else.
+ */
+export async function runSync(options, overrides = {}) {
+    const company = options.company ?? readActiveCompanySlug(options.hqRoot);
+    if (!company) {
+        throw new Error("No company specified. Pass --company <slug> or set activeCompany in .hq/config.json.");
+    }
+    const report = await runCompanyHotChannelSync({
+        hqRoot: options.hqRoot,
+        company,
+        ...(options.adapter !== undefined ? { adapter: options.adapter } : {}),
+        ...(overrides.registry ? { registry: overrides.registry } : {}),
+        ...(overrides.now ? { now: overrides.now } : {}),
+        signalsGenerated: overrides.signalsGenerated ?? createClaudeSignalsPass({ hqRoot: options.hqRoot, company }),
+        // The CLI has no owner-DM sender: the terminal is the primary alert here.
+        signalsAlert: {
+            sendOwnerDm: async (text) => {
+                process.stderr.write(chalk.red(`${text}\n`));
+            },
+            log: (message) => process.stderr.write(chalk.yellow(`${message}\n`)),
+        },
+    });
+    if (options.json) {
+        process.stdout.write(JSON.stringify({ company, ...report }, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(renderSyncTable(company, report) + "\n");
+    }
+    for (const outcome of report.outcomes) {
+        if (outcome.reconnect)
+            process.stderr.write(chalk.yellow(`${outcome.reconnect.prompt}\n`));
+    }
+    if (report.signInRequired)
+        process.stderr.write(chalk.yellow(`${SIGN_IN_PROMPT}\n`));
+    if (report.exitCode !== 0)
+        process.exitCode = report.exitCode;
+    return report;
+}
+function renderSyncTable(company, report) {
+    const lines = [`Hot-channel sync for ${company}`];
+    for (const notice of report.notices) {
+        if (!report.signInRequired)
+            lines.push(notice);
+    }
+    if (report.outcomes.length > 0) {
+        const pad = (s, w) => s + " ".repeat(Math.max(0, w - s.length));
+        const header = ["ADAPTER", "CONNECTION", "LANDED", "STATUS"];
+        const rows = report.outcomes.map((o) => [
+            o.adapter,
+            o.connectionId ?? "-",
+            String(o.landed),
+            o.status === "ok" ? "ok" : o.message ? `${o.status}: ${o.message}` : o.status,
+        ]);
+        const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+        lines.push("", header.map((h, i) => pad(h, widths[i])).join("  "));
+        for (const row of rows)
+            lines.push(row.map((cell, i) => pad(cell, widths[i])).join("  "));
+        const landed = report.outcomes.reduce((sum, o) => sum + o.landed, 0);
+        lines.push("", `${landed} source(s) landed.`);
+    }
+    return lines.join("\n");
+}
 // ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------
@@ -260,5 +600,27 @@ export function registerSourcesCommand(program) {
         .description("List entities (companies/personal) your account has access to")
         .option("--format <fmt>", "Output format: table | json (default: table for TTY, json piped)")
         .action(withErrorHandling(async (options) => runEntities(options)));
+    sources
+        .command("runs")
+        .description("Show the hot-channel run log: sources landed and signals generated per adapter")
+        .option("--today", "Show today's runs (UTC); the default")
+        .option("--date <YYYY-MM-DD>", "Show runs for this UTC day")
+        .option("--company <slug>", "Company slug (defaults to .hq/config.json activeCompany)")
+        .option("--email <address>", "Whose runs to show (defaults to the signed-in person)")
+        .option("--format <fmt>", "Output format: table | json (default: table for TTY, json piped)")
+        .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
+        .action(withErrorHandling(async (options) => {
+        await runRuns(options);
+    }));
+    sources
+        .command("sync")
+        .description("Run every hot channel now: each adapter once per connection you can use")
+        .option("--adapter <id>", "Run one adapter only (a catalog provider or adapter id)")
+        .option("--company <slug>", "Company slug (defaults to .hq/config.json activeCompany)")
+        .option("--json", "Print the run report as JSON")
+        .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
+        .action(withErrorHandling(async (options) => {
+        await runSync(options);
+    }));
 }
 //# sourceMappingURL=sources.js.map