fullstackgtm 0.44.0 → 0.46.0

package/dist/progress.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The shared progress-event vocabulary — ONE set of semantics for every
+ * long-running process, rendered natively by each surface:
+ *
+ *   CLI  → ui.ts (spinner / checklist / apply-ticker; TTY-only styling)
+ *   app  → Convex heartbeat patches → reactive ProgressChip / StageTimeline
+ *   both → optional broker streaming (a paired CLI POSTs heartbeats to the
+ *          hosted app under its clientRunId, so long local runs tick live in
+ *          the org's activity feed)
+ *
+ * Renderer-agnostic by contract: no event assumes persistence (the CLI drops
+ * them after painting) or ANSI (the app can't use it). Listeners are
+ * best-effort — a throwing renderer must never fail the work — and the
+ * throttle policy lives HERE so both surfaces feel identical.
+ *
+ * Standing convention: if a verb loops, it emits. New long-running verbs wire
+ * an emitter at the package layer; surfaces get feedback for free.
+ */
+export type ProgressEvent = {
+    kind: "stage";
+    stage: string;
+    stageIndex: number;
+    stageCount: number;
+} | {
+    kind: "items";
+    done: number;
+    total?: number;
+} | {
+    kind: "note";
+    note: string;
+} | {
+    kind: "opResult";
+    opId: string;
+    status: "applied" | "skipped" | "failed" | "conflict";
+    detail?: string;
+} | {
+    kind: "meter";
+    spent: number;
+    budget: number;
+    unit: string;
+};
+/** Accumulated state — what a heartbeat persists / a chip renders. */
+export type ProgressSnapshot = {
+    stage?: string;
+    stageIndex?: number;
+    stageCount?: number;
+    itemsDone?: number;
+    itemsTotal?: number;
+    note?: string;
+    opsApplied: number;
+    opsSkipped: number;
+    opsFailed: number;
+    updatedAt: number;
+};
+export type ProgressListener = (event: ProgressEvent, snapshot: ProgressSnapshot) => void;
+export type ProgressEmitter = {
+    stage(stage: string, stageIndex: number, stageCount: number): void;
+    items(done: number, total?: number): void;
+    note(note: string): void;
+    opResult(opId: string, status: "applied" | "skipped" | "failed" | "conflict", detail?: string): void;
+    meter(spent: number, budget: number, unit: string): void;
+    /** Current accumulated state (always fresh, ignoring the throttle). */
+    snapshot(): ProgressSnapshot;
+    /** Force-deliver the latest state (call at stage ends / completion). */
+    flush(): void;
+};
+/**
+ * Throttled emitter: `items` heartbeats coalesce to at most one delivery per
+ * throttle window (terminal `done === total` always delivers); `stage`,
+ * `opResult`, `note`, and `meter` are structural and always deliver.
+ */
+export declare function createProgressEmitter(listener: ProgressListener, options?: {
+    throttleMs?: number;
+    now?: () => number;
+}): ProgressEmitter;
+/**
+ * Fan one event stream out to several listeners (e.g. the CLI's local renderer
+ * plus the broker heartbeat streamer). Each listener is isolated: one throwing
+ * never starves the others, matching the emitter's own best-effort contract.
+ */
+export declare function composeListeners(...listeners: Array<ProgressListener | undefined | null>): ProgressListener;
+export declare const CRM_SYNC_STAGES: readonly ["owners", "accounts", "contacts", "deals", "counters", "health"];
+/** A connector snapshot pull — the CRM-sync stages that happen CLI-side. */
+export declare const SNAPSHOT_PULL_STAGES: readonly ["owners", "accounts", "contacts", "deals"];
+/** The Stripe connector's snapshot pull (billing systems have no owners). */
+export declare const STRIPE_SNAPSHOT_STAGES: readonly ["customers", "subscriptions"];
+export declare const CALL_SYNC_STAGES: readonly ["notes", "transcripts", "insights"];
+export declare const BACKFILL_STRIPE_STAGES: readonly ["invoices", "snapshot", "matching", "plan"];
+/** `backfill runs` — replaying local plan runs + health history to the broker. */
+export declare const RUNS_REPLAY_STAGES: readonly ["runs", "health"];
+export declare const APPLY_STAGES: readonly ["preflight", "operations", "results"];
+/** `enrich acquire` — routing sourced candidate rows into a create plan. */
+export declare const ACQUIRE_STAGES: readonly ["candidates"];
+export declare const MARKET_CAPTURE_STAGES: readonly ["sources", "capture", "classify", "persist"];
+/** No-op emitter for callers that don't care (keeps signatures simple). */
+export declare function nullProgressEmitter(): ProgressEmitter;

package/dist/progress.js

@@ -0,0 +1,142 @@
+/**
+ * The shared progress-event vocabulary — ONE set of semantics for every
+ * long-running process, rendered natively by each surface:
+ *
+ *   CLI  → ui.ts (spinner / checklist / apply-ticker; TTY-only styling)
+ *   app  → Convex heartbeat patches → reactive ProgressChip / StageTimeline
+ *   both → optional broker streaming (a paired CLI POSTs heartbeats to the
+ *          hosted app under its clientRunId, so long local runs tick live in
+ *          the org's activity feed)
+ *
+ * Renderer-agnostic by contract: no event assumes persistence (the CLI drops
+ * them after painting) or ANSI (the app can't use it). Listeners are
+ * best-effort — a throwing renderer must never fail the work — and the
+ * throttle policy lives HERE so both surfaces feel identical.
+ *
+ * Standing convention: if a verb loops, it emits. New long-running verbs wire
+ * an emitter at the package layer; surfaces get feedback for free.
+ */
+const DEFAULT_THROTTLE_MS = 2000;
+/**
+ * Throttled emitter: `items` heartbeats coalesce to at most one delivery per
+ * throttle window (terminal `done === total` always delivers); `stage`,
+ * `opResult`, `note`, and `meter` are structural and always deliver.
+ */
+export function createProgressEmitter(listener, options = {}) {
+    const throttleMs = options.throttleMs ?? DEFAULT_THROTTLE_MS;
+    const now = options.now ?? Date.now;
+    const state = {
+        opsApplied: 0,
+        opsSkipped: 0,
+        opsFailed: 0,
+        updatedAt: now(),
+    };
+    let lastItemsDelivery = 0;
+    let pendingItems = false;
+    function deliver(event) {
+        state.updatedAt = now();
+        try {
+            listener(event, { ...state });
+        }
+        catch {
+            // Renderers are presentation-only; never fail the work.
+        }
+    }
+    return {
+        stage(stage, stageIndex, stageCount) {
+            state.stage = stage;
+            state.stageIndex = stageIndex;
+            state.stageCount = stageCount;
+            state.itemsDone = undefined;
+            state.itemsTotal = undefined;
+            state.note = undefined;
+            pendingItems = false;
+            deliver({ kind: "stage", stage, stageIndex, stageCount });
+        },
+        items(done, total) {
+            state.itemsDone = done;
+            state.itemsTotal = total;
+            const terminal = total !== undefined && done >= total;
+            const due = now() - lastItemsDelivery >= throttleMs;
+            if (terminal || due) {
+                lastItemsDelivery = now();
+                pendingItems = false;
+                deliver({ kind: "items", done, total });
+            }
+            else {
+                pendingItems = true;
+            }
+        },
+        note(note) {
+            state.note = note;
+            deliver({ kind: "note", note });
+        },
+        opResult(opId, status, detail) {
+            if (status === "applied")
+                state.opsApplied += 1;
+            else if (status === "skipped")
+                state.opsSkipped += 1;
+            else
+                state.opsFailed += 1;
+            deliver({ kind: "opResult", opId, status, detail });
+        },
+        meter(spent, budget, unit) {
+            deliver({ kind: "meter", spent, budget, unit });
+        },
+        snapshot() {
+            return { ...state, updatedAt: now() };
+        },
+        flush() {
+            if (pendingItems && state.itemsDone !== undefined) {
+                lastItemsDelivery = now();
+                pendingItems = false;
+                deliver({ kind: "items", done: state.itemsDone, total: state.itemsTotal });
+            }
+        },
+    };
+}
+/**
+ * Fan one event stream out to several listeners (e.g. the CLI's local renderer
+ * plus the broker heartbeat streamer). Each listener is isolated: one throwing
+ * never starves the others, matching the emitter's own best-effort contract.
+ */
+export function composeListeners(...listeners) {
+    const active = listeners.filter((listener) => Boolean(listener));
+    return (event, snapshot) => {
+        for (const listener of active) {
+            try {
+                listener(event, snapshot);
+            }
+            catch {
+                // Listeners are presentation/observability only; never fail the work.
+            }
+        }
+    };
+}
+// ── Shared stage registries ─────────────────────────────────────────────────
+// Package constants so the CLI checklist and the app StageTimeline render
+// LITERALLY the same stages in the same order — one mental model everywhere.
+export const CRM_SYNC_STAGES = [
+    "owners",
+    "accounts",
+    "contacts",
+    "deals",
+    "counters",
+    "health",
+];
+/** A connector snapshot pull — the CRM-sync stages that happen CLI-side. */
+export const SNAPSHOT_PULL_STAGES = ["owners", "accounts", "contacts", "deals"];
+/** The Stripe connector's snapshot pull (billing systems have no owners). */
+export const STRIPE_SNAPSHOT_STAGES = ["customers", "subscriptions"];
+export const CALL_SYNC_STAGES = ["notes", "transcripts", "insights"];
+export const BACKFILL_STRIPE_STAGES = ["invoices", "snapshot", "matching", "plan"];
+/** `backfill runs` — replaying local plan runs + health history to the broker. */
+export const RUNS_REPLAY_STAGES = ["runs", "health"];
+export const APPLY_STAGES = ["preflight", "operations", "results"];
+/** `enrich acquire` — routing sourced candidate rows into a create plan. */
+export const ACQUIRE_STAGES = ["candidates"];
+export const MARKET_CAPTURE_STAGES = ["sources", "capture", "classify", "persist"];
+/** No-op emitter for callers that don't care (keeps signatures simple). */
+export function nullProgressEmitter() {
+    return createProgressEmitter(() => { });
+}

package/dist/runReport.d.ts

@@ -1,3 +1,4 @@
+import type { ProgressListener } from "./progress.ts";
 /**
  * Per-row finding for the hosted run timeline. IDs + issue type ONLY — no field
  * values ever leave the CLI, keeping the audit's row data on the operator's side
@@ -28,6 +29,29 @@ export declare function reportFindings(values: RunFinding[]): void;
 export declare function reportCrm(value: RunCrm): void;
 /** A command annotates a structured event (plan saved, meter charged, …). */
 export declare function reportEvent(type: string, detail?: string): void;
+/**
+ * Arm heartbeat streaming for this invocation. Call once from the entry point
+ * (alongside capturing `startedAt`); without it, progress listeners from
+ * `progressReporter()` are inert. Safe to call for any command — skip-listed
+ * commands simply never stream.
+ */
+export declare function beginRunReport(args: string[], startedAt: number): void;
+/**
+ * A ProgressListener that streams the run's progress snapshot to the paired
+ * hosted app. Verbs compose it with their local renderer:
+ *
+ *   createProgressEmitter(composeListeners(renderer.listener, progressReporter()))
+ *
+ * Throttled to one POST per ~5s, first no earlier than ~5s into the run,
+ * 2s-capped and fire-and-forget. Privacy: stage names and counts only — notes
+ * must stay generic ("batch 4/12"); CRM field values never leave the machine.
+ */
+export declare function progressReporter(overrides?: {
+    now?: () => number;
+    intervalMs?: number;
+    minRunMs?: number;
+    fetchImpl?: typeof fetch;
+}): ProgressListener;
 /**
  * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
  * swallows every error. Call once per process from the entry point.

package/dist/runReport.js

@@ -31,6 +31,15 @@ export function reportCrm(value) {
 export function reportEvent(type, detail) {
     events.push({ ts: Date.now(), type, detail });
 }
+// FNV-1a — the stable-id hash used across the package (see backfill.ts).
+function fnv1a(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
 // Setup/inspection verbs aren't interesting as "runs" — skip the noise.
 const SKIP_COMMANDS = new Set([
     "login",
@@ -43,25 +52,151 @@ const SKIP_COMMANDS = new Set([
     "--version",
     "-v",
 ]);
+/** The stable per-invocation identity flushRunReport and heartbeats share. */
+function runIdentity(args, startedAt) {
+    const command = args[0];
+    if (!command || SKIP_COMMANDS.has(command))
+        return null;
+    const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
+    const full = `${command}${sub}`;
+    return { command: full, clientRunId: `run_${fnv1a(`${full}:${startedAt}:${process.pid}`)}` };
+}
+// ── Live progress streaming ─────────────────────────────────────────────────
+// While a long command runs, a paired CLI streams heartbeats to the hosted
+// app: POST /api/cli/run with the SAME clientRunId the final flushRunReport
+// will use, status "in_progress", and the progress emitter's snapshot. The
+// server upserts by clientRunId, so the terminal flush simply wins. Same
+// invariants as flushRunReport: opt-in (paired only), fire-and-forget,
+// time-capped, never affects the command's outcome or output.
+const HEARTBEAT_INTERVAL_MS = 5000;
+/** No heartbeat before the run is ~this old — fast commands never stream. */
+const HEARTBEAT_MIN_RUN_MS = 5000;
+const HEARTBEAT_TIMEOUT_MS = 2000;
+let runContext = null;
+let lastHeartbeatAt = 0;
+// Broker credential resolved once per run (undefined = not looked up yet;
+// null = looked up, not paired).
+let heartbeatBroker;
+let inflightHeartbeat = null;
+/**
+ * Arm heartbeat streaming for this invocation. Call once from the entry point
+ * (alongside capturing `startedAt`); without it, progress listeners from
+ * `progressReporter()` are inert. Safe to call for any command — skip-listed
+ * commands simply never stream.
+ */
+export function beginRunReport(args, startedAt) {
+    lastHeartbeatAt = 0;
+    heartbeatBroker = undefined;
+    inflightHeartbeat = null;
+    const identity = runIdentity(args, startedAt);
+    runContext = identity ? { ...identity, startedAt } : null;
+}
+/**
+ * A ProgressListener that streams the run's progress snapshot to the paired
+ * hosted app. Verbs compose it with their local renderer:
+ *
+ *   createProgressEmitter(composeListeners(renderer.listener, progressReporter()))
+ *
+ * Throttled to one POST per ~5s, first no earlier than ~5s into the run,
+ * 2s-capped and fire-and-forget. Privacy: stage names and counts only — notes
+ * must stay generic ("batch 4/12"); CRM field values never leave the machine.
+ */
+export function progressReporter(overrides = {}) {
+    const now = overrides.now ?? Date.now;
+    const intervalMs = overrides.intervalMs ?? HEARTBEAT_INTERVAL_MS;
+    const minRunMs = overrides.minRunMs ?? HEARTBEAT_MIN_RUN_MS;
+    const fetchImpl = overrides.fetchImpl ?? fetch;
+    return (_event, snapshot) => {
+        try {
+            if (!runContext)
+                return;
+            const at = now();
+            if (at - runContext.startedAt < minRunMs)
+                return;
+            if (at - lastHeartbeatAt < intervalMs)
+                return;
+            if (heartbeatBroker === undefined) {
+                const broker = getCredential("broker");
+                heartbeatBroker =
+                    broker?.baseUrl && broker.accessToken
+                        ? { baseUrl: broker.baseUrl.replace(/\/+$/, ""), accessToken: broker.accessToken }
+                        : null; // opt-in: only when paired
+            }
+            if (!heartbeatBroker)
+                return;
+            lastHeartbeatAt = at;
+            sendHeartbeat(fetchImpl, heartbeatBroker, runContext, snapshot, at);
+        }
+        catch {
+            // Observability is best-effort; never affect the command.
+        }
+    };
+}
+function sendHeartbeat(fetchImpl, broker, context, snapshot, at) {
+    // One heartbeat in flight at a time: a stalled POST is superseded, and the
+    // terminal flush aborts any straggler so it can never delay process exit.
+    inflightHeartbeat?.abort();
+    const controller = new AbortController();
+    inflightHeartbeat = controller;
+    const timer = setTimeout(() => controller.abort(), HEARTBEAT_TIMEOUT_MS);
+    timer.unref?.();
+    void fetchImpl(`${broker.baseUrl}/api/cli/run`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            command: context.command,
+            clientRunId: context.clientRunId,
+            status: "in_progress",
+            startedAt: context.startedAt,
+            finishedAt: at,
+            durationMs: at - context.startedAt,
+            progress: {
+                // Stage names + counts only — never CRM field values.
+                stage: snapshot.stage,
+                stageIndex: snapshot.stageIndex,
+                stageCount: snapshot.stageCount,
+                itemsDone: snapshot.itemsDone,
+                itemsTotal: snapshot.itemsTotal,
+                note: snapshot.note,
+                heartbeatAt: at,
+            },
+        }),
+        signal: controller.signal,
+    })
+        .catch(() => {
+        // fire-and-forget
+    })
+        .finally(() => {
+        clearTimeout(timer);
+        if (inflightHeartbeat === controller)
+            inflightHeartbeat = null;
+    });
+}
 /**
  * Send the run record if the CLI is paired. Best-effort: a 4s-capped POST that
  * swallows every error. Call once per process from the entry point.
  */
 export async function flushRunReport(args, status, startedAt, error) {
-    const command = args[0];
-    if (!command || SKIP_COMMANDS.has(command))
+    // The terminal upsert supersedes any streaming heartbeat still in flight.
+    inflightHeartbeat?.abort();
+    inflightHeartbeat = null;
+    // Stable per-invocation identity: the server dedupes on clientRunId, so a
+    // retried report, an "in_progress" heartbeat, or a later `backfill runs`
+    // replay of local history never duplicates.
+    const identity = runIdentity(args, startedAt);
+    if (!identity)
         return;
     const broker = getCredential("broker");
     if (!broker?.baseUrl || !broker.accessToken)
         return; // opt-in: only when paired
-    const sub = args[1] && !args[1].startsWith("-") ? ` ${args[1]}` : "";
     const finishedAt = Date.now();
     try {
         await fetch(`${broker.baseUrl.replace(/\/+$/, "")}/api/cli/run`, {
             method: "POST",
             headers: { Authorization: `Bearer ${broker.accessToken}`, "Content-Type": "application/json" },
             body: JSON.stringify({
-                command: `${command}${sub}`,
+                command: identity.command,
+                clientRunId: identity.clientRunId,
                 status,
                 startedAt,
                 finishedAt,

package/dist/schedule.d.ts

@@ -40,9 +40,11 @@ export type ScheduleRunRecord = {
      * recorded for visibility but nothing ran. Reasons: "plan_not_approved"
      * (scheduled apply against a plan that is not approved — there is no flag
      * that relaxes this), "not_schedulable" (the stored argv no longer passes
-     * the allowlist, e.g. after a hand edit of schedules.json).
+     * the allowlist, e.g. after a hand edit of schedules.json),
+     * "duplicate_firing" (a cron-triggered run already recorded in this minute
+     * — launchd can double-trigger the Vixie dom+dow OR corner).
      */
-    noopReason?: "plan_not_approved" | "not_schedulable";
+    noopReason?: "plan_not_approved" | "not_schedulable" | "duplicate_firing";
 };
 export declare function scheduleId(label: string, cron: string, argv: string[], createdAt: string): string;
 /**
@@ -158,3 +160,79 @@ export declare function renderManagedBlock(profile: string, entries: ScheduleEnt
  * Idempotent: re-applying the same block yields identical content.
  */
 export declare function replaceManagedBlock(existing: string, profile: string, block: string | null): string;
+/**
+ * One launchd StartCalendarInterval dict: every present key must match (AND),
+ * a missing key is a wildcard, and an array of dicts fires when ANY dict
+ * matches. Weekday 0 is Sunday, as in cron.
+ */
+export type LaunchdCalendarInterval = {
+    Minute?: number;
+    Hour?: number;
+    Day?: number;
+    Weekday?: number;
+    Month?: number;
+};
+/**
+ * Compile a cron expression to StartCalendarInterval dicts. Full-range fields
+ * (`*`, but also spellings like `0-59`) are omitted (launchd wildcard); the
+ * rest cross-product, capped so a dense expression cannot render a megabyte
+ * plist. Vixie day semantics: when day-of-month AND day-of-week are both
+ * restricted, either may match — launchd ANDs keys within one dict, so that
+ * becomes the union of a Day dict set and a Weekday dict set. A date matching
+ * both sets makes launchd trigger twice in the same minute; the run entry
+ * point drops the second via isDuplicateCronFiring.
+ */
+export declare function cronToCalendarIntervals(cron: CronExpression, cap?: number): LaunchdCalendarInterval[];
+/**
+ * True when a cron-triggered run was already recorded in `firedAt`'s minute.
+ * The `schedule run` entry point checks this for trigger:cron so a launchd
+ * double-trigger (dom+dow OR corner above) records a duplicate_firing no-op
+ * instead of running the command twice. Manual runs are never deduplicated.
+ */
+export declare function isDuplicateCronFiring(runs: ScheduleRunRecord[], firedAt: string): boolean;
+/** Reverse-DNS namespace for one profile's agents; install/uninstall own this prefix wholesale. */
+export declare function launchdAgentPrefix(profile: string): string;
+export declare function launchdLabel(profile: string, scheduleEntryId: string): string;
+/**
+ * Render one LaunchAgent plist. ProgramArguments is an argv array — launchd
+ * execs it directly, no shell, so there is no quoting/injection surface at
+ * all (values are XML-escaped for the document, nothing more).
+ */
+export declare function renderLaunchdPlist(options: {
+    label: string;
+    programArguments: string[];
+    calendarIntervals: LaunchdCalendarInterval[];
+    environment?: Record<string, string>;
+    standardOutPath?: string;
+    standardErrorPath?: string;
+}): string;
+export type LaunchdIo = {
+    /** Plist file names currently in the agents directory. */
+    list(): string[];
+    write(fileName: string, content: string): void;
+    remove(fileName: string): void;
+    /** Load one agent plist into the user's gui domain; throws on failure. */
+    bootstrap(fileName: string): void;
+    /** Best-effort unload by label; a label that is not loaded is not an error. */
+    bootout(label: string): void;
+};
+/**
+ * The real ~/Library/LaunchAgents + launchctl. Everything above takes a
+ * LaunchdIo so tests inject fakes and never touch the user's agents.
+ */
+export declare function systemLaunchdIo(agentsDirOverride?: string): LaunchdIo;
+/**
+ * Materialize enabled entries as one LaunchAgent each, replacing the
+ * profile's com.fullstackgtm.<profile>.* fleet wholesale (stale agents are
+ * booted out and deleted; plists outside the prefix are never touched).
+ * `cliArgv` is the argv-array analog of the crontab invocation line.
+ */
+export declare function installLaunchdAgents(profile: string, entries: ScheduleEntry[], cliArgv: string[], io: LaunchdIo, options?: {
+    environment?: Record<string, string>;
+    logDir?: string;
+}): {
+    installed: string[];
+    removed: string[];
+};
+/** Boot out and delete every agent in the profile's prefix; returns the removed labels. */
+export declare function uninstallLaunchdAgents(profile: string, io: LaunchdIo): string[];