fullstackgtm 0.23.2 → 0.24.0

package/src/cli.ts

@@ -101,6 +101,22 @@ import {
   pullApolloRecords,
   type ApolloPullKey,
 } from "./enrichApollo.ts";
+import {
+  computeMissedFirings,
+  createFileScheduleRunStore,
+  createFileScheduleStore,
+  nextCronFiring,
+  parseCron,
+  renderManagedBlock,
+  replaceManagedBlock,
+  scheduleId,
+  systemCrontabIo,
+  tokenizeCommand,
+  validateSchedulableArgv,
+  type ScheduleEntry,
+  type ScheduleRunRecord,
+  type ScheduleRunTrigger,
+} from "./schedule.ts";
 import { resolveRecord, type ResolveCandidate } from "./resolve.ts";
 import { buildBulkUpdatePlan } from "./bulkUpdate.ts";
 import { buildDedupePlan, type DedupeOptions } from "./dedupe.ts";
@@ -216,6 +232,16 @@ Usage:
                                                value) → with --yes, apply through the provider and print a
                                                stage-by-stage summary. Without --yes it stops after
                                                approval and prints the apply command.
+  fullstackgtm schedule add "<command>" --cron "<expr>" [--label <name>] [--provider local]
+  fullstackgtm schedule list | remove <id> | enable <id> | disable <id> | run <id>
+  fullstackgtm schedule install | uninstall [--provider local]
+  fullstackgtm schedule status [<id>] [--runs <n>]
+                                               declare a cadence for any read/plan-side command (audit,
+                                               snapshot, enrich append|refresh, market capture|refresh,
+                                               suggest, report, doctor); install materializes enabled
+                                               entries into a sentinel-delimited managed crontab block.
+                                               Scheduling never auto-approves: apply is schedulable only
+                                               as apply --plan-id <id>, re-checked approved at run time.
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -1731,6 +1757,421 @@ async function enrichStatus(store: EnrichRunStore, rest: string[], configFile: s
   }
 }
 
+/**
+ * The schedule layer: declarative cadences for read/plan-side commands,
+ * materialized through a provider (MVP: the user crontab), with an
+ * append-only run history. The governance invariant — scheduling never
+ * auto-approves — is enforced at `add` time and re-checked at `run` time.
+ * Spec: docs/schedule.md (monorepo).
+ */
+async function scheduleCommand(args: string[]) {
+  const [subcommand, ...rest] = args;
+
+  // Catch --help BEFORE any store read, credential access, or crontab
+  // round-trip (the enrich/market early-catch pattern — `schedule install
+  // --help` must never touch the crontab).
+  if (!subcommand || subcommand === "--help" || subcommand === "-h" || rest.includes("--help") || rest.includes("-h")) {
+    console.log(`Usage:
+schedule add "<fullstackgtm command>" --cron "<expr>" [--label <name>] [--provider local]
+schedule list [--json]
+schedule remove <id>
+schedule enable <id> | disable <id>
+schedule run <id>                     execute now; the single entry point every provider's timer calls
+schedule install [--provider local]   render enabled entries into the managed crontab block
+schedule uninstall [--provider local] remove the managed block (nothing else)
+schedule status [<id>] [--runs <n>] [--json]
+
+add validates the command against the schedulable allowlist — read/plan-side
+only: audit, snapshot, enrich append|refresh, market capture|refresh,
+suggest, report, doctor — and parses the 5-field cron expression (*, lists,
+ranges, steps), but touches NO crontab: entries are declarative until install
+materializes them (the plan/apply split — declare, then deliberately
+activate).
+
+Scheduling never auto-approves. apply is schedulable ONLY as
+\`apply --plan-id <id>\`, and every firing re-checks the plan's status is
+approved — an unapproved plan records a plan_not_approved no-op run instead
+of executing. There is no flag that relaxes this. Unattended runs accumulate
+proposals (plans, run records, reports), never surprise CRM writes.
+
+install renders all enabled entries into a sentinel-delimited block
+(# >>> fullstackgtm <profile> >>> ... # <<< fullstackgtm <profile> <<<) in
+the user crontab; each line invokes \`schedule run <id> --profile <profile>\`
+and nothing else. Re-install replaces the block wholesale and never touches
+lines outside the sentinels. Providers other than local (modal, aws) are not
+yet implemented — they will be scaffold generators calling the same
+\`schedule run\` contract.
+
+run executes the command in-process and records the outcome (exit code,
+output tail, artifacts: plan ids / enrich run labels) under the profile's
+schedule/runs/<id>/; the exit code propagates. Manual runs record
+trigger: manual. status shows next firing and surfaces missed firings
+(laptop asleep = cron skips silently; visibility only, no catch-up).`);
+    return;
+  }
+
+  const store = createFileScheduleStore();
+  const runStore = createFileScheduleRunStore();
+
+  if (subcommand === "add") {
+    const commandText = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
+    if (!commandText) {
+      throw new Error('Usage: fullstackgtm schedule add "<fullstackgtm command>" --cron "<expr>" [--label <name>] [--provider local]');
+    }
+    const cronText = option(rest, "--cron");
+    if (!cronText) throw new Error('schedule add requires --cron "<minute hour day-of-month month day-of-week>"');
+    requireLocalScheduleProvider(option(rest, "--provider") ?? "local");
+
+    let argv = tokenizeCommand(commandText);
+    if (argv[0] === "fullstackgtm") argv = argv.slice(1);
+    validateSchedulableArgv(argv);
+    const cron = parseCron(cronText);
+    const next = nextCronFiring(cron, new Date()); // also rejects never-firing expressions
+    const createdAt = new Date().toISOString();
+    const label =
+      option(rest, "--label") ??
+      argv.filter((arg) => !arg.startsWith("--")).slice(0, 2).join("-").replace(/[^\w.-]+/g, "-");
+    const entry: ScheduleEntry = {
+      id: scheduleId(label, cron.source, argv, createdAt),
+      label,
+      argv,
+      cron: cron.source,
+      provider: "local",
+      enabled: true,
+      createdAt,
+    };
+    await store.add(entry);
+    console.log(`Added ${entry.id} "${label}": \`${argv.join(" ")}\` at \`${cron.source}\` (next firing: ${next.toISOString()}).`);
+    console.log("Declarative until materialized — activate with `fullstackgtm schedule install`.");
+    return;
+  }
+
+  if (subcommand === "list") {
+    const entries = await store.list();
+    const now = new Date();
+    const withNext = entries.map((entry) => ({
+      ...entry,
+      nextFiring: entry.enabled ? safeNextFiring(entry.cron, now) : null,
+    }));
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(withNext, null, 2));
+      return;
+    }
+    if (entries.length === 0) {
+      console.log('No schedules. Add one with `fullstackgtm schedule add "<command>" --cron "<expr>"`.');
+      return;
+    }
+    for (const entry of withNext) {
+      console.log(
+        `${entry.id}  ${entry.enabled ? "on " : "off"}  ${entry.cron.padEnd(14)} next ${entry.nextFiring ?? "—"}  ${entry.label}: ${entry.argv.join(" ")}`,
+      );
+    }
+    console.log("\nEntries are declarative — `schedule install` materializes enabled ones into the crontab.");
+    return;
+  }
+
+  if (subcommand === "remove") {
+    const id = positionalArg(rest, "Usage: fullstackgtm schedule remove <id>");
+    if (!(await store.remove(id))) throw new Error(`No schedule with id ${id}.`);
+    console.log(`Removed ${id}. Run \`fullstackgtm schedule install\` to update the crontab block.`);
+    return;
+  }
+
+  if (subcommand === "enable" || subcommand === "disable") {
+    const id = positionalArg(rest, `Usage: fullstackgtm schedule ${subcommand} <id>`);
+    const entry = await store.setEnabled(id, subcommand === "enable");
+    console.log(
+      `${subcommand === "enable" ? "Enabled" : "Disabled"} ${entry.id} "${entry.label}". ` +
+        "Run `fullstackgtm schedule install` to update the crontab block.",
+    );
+    return;
+  }
+
+  if (subcommand === "run") {
+    const id = positionalArg(rest, "Usage: fullstackgtm schedule run <id>");
+    const entry = await store.get(id);
+    if (!entry) throw new Error(`No schedule with id ${id} in profile "${activeProfile()}".`);
+    if (!entry.enabled) {
+      throw new Error(`Schedule ${id} is disabled — enable it with \`fullstackgtm schedule enable ${id}\`.`);
+    }
+    const trigger = (option(rest, "--trigger") ?? "manual") as ScheduleRunTrigger;
+    if (trigger !== "cron" && trigger !== "manual") {
+      throw new Error("--trigger must be cron or manual");
+    }
+    const run = await executeScheduledRun(entry, trigger);
+    if (run.exitCode !== 0) process.exitCode = run.exitCode;
+    return;
+  }
+
+  if (subcommand === "install" || subcommand === "uninstall") {
+    requireLocalScheduleProvider(option(rest, "--provider") ?? "local");
+    const profile = activeProfile();
+    const io = systemCrontabIo();
+    const existing = io.read();
+    if (subcommand === "uninstall") {
+      io.write(replaceManagedBlock(existing, profile, null));
+      console.log(`Removed the fullstackgtm managed crontab block for profile "${profile}" (lines outside the sentinels untouched).`);
+      return;
+    }
+    const enabled = (await store.list()).filter((entry) => entry.enabled && entry.provider === "local");
+    if (enabled.length === 0) {
+      io.write(replaceManagedBlock(existing, profile, null));
+      console.log(`No enabled schedules for profile "${profile}" — removed the managed block.`);
+      return;
+    }
+    const block = renderManagedBlock(profile, enabled, scheduleCliInvocation());
+    io.write(replaceManagedBlock(existing, profile, block));
+    console.log(
+      `Installed ${enabled.length} schedule(s) into the managed crontab block for profile "${profile}". ` +
+        "Re-running install replaces the block wholesale; `schedule uninstall` removes it.",
+    );
+    return;
+  }
+
+  if (subcommand === "status") {
+    const id = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
+    const entries = await store.list();
+    const selected = id ? entries.filter((entry) => entry.id === id) : entries;
+    if (id && selected.length === 0) throw new Error(`No schedule with id ${id}.`);
+    if (selected.length === 0) {
+      console.log('No schedules. Add one with `fullstackgtm schedule add "<command>" --cron "<expr>"`.');
+      return;
+    }
+    const showRuns = numericOption(rest, "--runs");
+    const now = new Date();
+    const report = [] as Array<Record<string, unknown>>;
+    for (const entry of selected) {
+      const runs = await runStore.list(entry.id);
+      const last = runs.length > 0 ? runs[runs.length - 1] : null;
+      let streak = 0;
+      for (let index = runs.length - 1; index >= 0; index -= 1) {
+        if ((runs[index].exitCode === 0) !== (last!.exitCode === 0)) break;
+        streak += 1;
+      }
+      const missed = computeMissedFirings(entry, runs, now);
+      report.push({
+        id: entry.id,
+        label: entry.label,
+        argv: entry.argv,
+        cron: entry.cron,
+        enabled: entry.enabled,
+        nextFiring: entry.enabled ? safeNextFiring(entry.cron, now) : null,
+        lastRun: last
+          ? {
+              firedAt: last.firedAt,
+              trigger: last.trigger,
+              exitCode: last.exitCode,
+              noopReason: last.noopReason,
+              artifacts: last.artifacts,
+            }
+          : null,
+        streak: last ? { outcome: last.exitCode === 0 ? "success" : "failure", length: streak } : null,
+        missedFirings: missed.missed.map((firing) => firing.toISOString()),
+        missedFiringsCapped: missed.capped,
+        runs: showRuns !== undefined ? runs.slice(-showRuns) : undefined,
+      });
+    }
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    for (const entry of report) {
+      const last = entry.lastRun as { firedAt: string; trigger: string; exitCode: number; noopReason?: string; artifacts: { planIds: string[]; runLabels: string[] } } | null;
+      const streak = entry.streak as { outcome: string; length: number } | null;
+      const missed = entry.missedFirings as string[];
+      console.log(`${entry.id}  ${entry.enabled ? "on " : "off"}  ${entry.cron}  ${entry.label}: ${(entry.argv as string[]).join(" ")}`);
+      console.log(`  next: ${entry.nextFiring ?? "— (disabled)"}`);
+      if (last) {
+        const artifacts = [
+          ...last.artifacts.planIds.map((planId) => `plan ${planId}`),
+          ...last.artifacts.runLabels.map((runLabel) => `run ${runLabel}`),
+        ];
+        console.log(
+          `  last: ${last.firedAt} (${last.trigger}) exit ${last.exitCode}` +
+            (last.noopReason ? ` — no-op: ${last.noopReason}` : "") +
+            (artifacts.length ? ` — ${artifacts.join(", ")}` : ""),
+        );
+        console.log(`  streak: ${streak!.length} ${streak!.outcome}(s)`);
+      } else {
+        console.log("  last: never fired");
+      }
+      if (missed.length > 0) {
+        console.log(
+          `  missed: ${missed.length}${entry.missedFiringsCapped ? "+" : ""} expected firing(s) with no run record ` +
+            `(latest: ${missed[missed.length - 1]}) — local cron has no catch-up; this is visibility only`,
+        );
+      }
+      const runs = entry.runs as ScheduleRunRecord[] | undefined;
+      if (runs) {
+        for (const run of runs) {
+          console.log(`    ${run.firedAt}  ${run.trigger.padEnd(6)} exit ${run.exitCode}${run.noopReason ? `  no-op: ${run.noopReason}` : ""}`);
+        }
+      }
+    }
+    return;
+  }
+
+  throw new Error(
+    `Unknown schedule subcommand: ${subcommand} (try: add, list, remove, enable, disable, run, install, uninstall, status)`,
+  );
+}
+
+function positionalArg(rest: string[], usage: string): string {
+  const value = rest.find((arg) => !arg.startsWith("--") && !isOptionValue(rest, arg));
+  if (!value) throw new Error(usage);
+  return value;
+}
+
+function safeNextFiring(cron: string, now: Date): string | null {
+  try {
+    return nextCronFiring(parseCron(cron), now).toISOString();
+  } catch {
+    return null;
+  }
+}
+
+/** The provider seam: local ships now; modal/aws arrive as scaffold generators. */
+function requireLocalScheduleProvider(provider: string) {
+  if (provider === "local") return;
+  if (provider === "modal" || provider === "aws") {
+    throw new Error(
+      `Provider "${provider}" is not yet implemented — it will be a scaffold generator that emits a ` +
+        "deploy-ready artifact whose runner calls the same `schedule run <id>` contract. MVP provider: local.",
+    );
+  }
+  throw new Error(`Unknown provider "${provider}" — not yet implemented. MVP provider: local.`);
+}
+
+/**
+ * Resolve how cron should invoke this CLI: the current node binary plus the
+ * entry script (source checkouts need --experimental-strip-types), with
+ * FSGTM_HOME pinned when set so the cron environment sees the same store.
+ */
+function scheduleCliInvocation(): string {
+  const script = process.argv[1] ? resolve(process.argv[1]) : null;
+  if (!script || !existsSync(script)) {
+    throw new Error("Cannot resolve the fullstackgtm entry point for crontab lines (process.argv[1] is missing).");
+  }
+  const quote = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`;
+  const parts = [quote(process.execPath)];
+  if (script.endsWith(".ts")) parts.push("--experimental-strip-types");
+  parts.push(quote(script));
+  const home = process.env.FSGTM_HOME ? `FSGTM_HOME=${quote(process.env.FSGTM_HOME)} ` : "";
+  return home + parts.join(" ");
+}
+
+/**
+ * The single provider entry point: execute the scheduled command in-process
+ * (dispatch into the CLI router — never a shell), capture the output tail and
+ * exit code as a run record, and hand the exit code back to the caller. Cron
+ * calls it, cloud providers will call it, and a human running it manually
+ * produces the same record (trigger: manual).
+ *
+ * Governance re-checks happen here, not just at `add` time: the allowlist is
+ * re-validated (schedules.json is user-editable), and a scheduled apply
+ * hard-checks the plan is approved — an unapproved plan records a
+ * plan_not_approved no-op run and does NOT execute. Scheduling never
+ * auto-approves.
+ */
+async function executeScheduledRun(
+  entry: ScheduleEntry,
+  trigger: ScheduleRunTrigger,
+): Promise<ScheduleRunRecord> {
+  const runStore = createFileScheduleRunStore();
+  const firedAt = new Date().toISOString();
+  const noop = async (
+    reason: NonNullable<ScheduleRunRecord["noopReason"]>,
+    exitCode: number,
+    message: string,
+  ): Promise<ScheduleRunRecord> => {
+    const run: ScheduleRunRecord = {
+      scheduleId: entry.id,
+      firedAt,
+      completedAt: new Date().toISOString(),
+      trigger,
+      exitCode,
+      outputTail: message,
+      artifacts: { planIds: [], runLabels: [] },
+      noopReason: reason,
+    };
+    await runStore.record(run);
+    console.error(message);
+    return run;
+  };
+
+  try {
+    validateSchedulableArgv(entry.argv);
+  } catch (error) {
+    return noop("not_schedulable", 1, error instanceof Error ? error.message : String(error));
+  }
+  if (entry.argv[0] === "apply") {
+    const planId = option(entry.argv.slice(1), "--plan-id")!;
+    const stored = await createFilePlanStore().get(planId);
+    const status = stored ? stored.status : "missing";
+    if (status !== "approved") {
+      // The governance gate holding is not a machinery failure: exit 0, with
+      // the refusal recorded on the run for `schedule status` to surface.
+      return noop(
+        "plan_not_approved",
+        0,
+        `Plan ${planId} is ${status}, not approved — scheduled apply refuses to execute. ` +
+          `Scheduling never auto-approves; review and approve with \`fullstackgtm plans approve ${planId} --operations <ids|all>\`.`,
+      );
+    }
+  }
+
+  // Artifact attribution by store diff: anything new in the plan store or the
+  // enrich run store after the command ran was produced by this firing.
+  const planStore = createFilePlanStore();
+  const plansBefore = new Set((await planStore.list()).map((stored) => stored.plan.id));
+  const enrichStore = createFileEnrichRunStore();
+  const enrichBefore = new Set((await enrichStore.list()).map((run) => run.runLabel));
+
+  const lines: string[] = [];
+  const originalLog = console.log;
+  const originalError = console.error;
+  const tee =
+    (original: (...args: unknown[]) => void) =>
+    (...args: unknown[]) => {
+      for (const line of args.map(String).join(" ").split("\n")) lines.push(line);
+      original(...args);
+    };
+  console.log = tee(originalLog);
+  console.error = tee(originalError);
+  const priorExitCode = process.exitCode;
+  process.exitCode = undefined;
+  let exitCode = 0;
+  try {
+    await runCli([...entry.argv]);
+    exitCode = typeof process.exitCode === "number" ? process.exitCode : 0;
+  } catch (error) {
+    exitCode = 1;
+    lines.push(error instanceof Error ? error.message : String(error));
+  } finally {
+    console.log = originalLog;
+    console.error = originalError;
+    process.exitCode = priorExitCode;
+  }
+
+  const planIds = (await planStore.list())
+    .map((stored) => stored.plan.id)
+    .filter((planId) => !plansBefore.has(planId));
+  const runLabels = (await enrichStore.list())
+    .map((run) => run.runLabel)
+    .filter((runLabel) => !enrichBefore.has(runLabel));
+  const run: ScheduleRunRecord = {
+    scheduleId: entry.id,
+    firedAt,
+    completedAt: new Date().toISOString(),
+    trigger,
+    exitCode,
+    outputTail: lines.slice(-50).join("\n"),
+    artifacts: { planIds, runLabels },
+  };
+  await runStore.record(run);
+  return run;
+}
+
 /**
  * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or
  * ambiguous — do NOT blind-create), exit 1 = error. Built for sync jobs and
@@ -2806,8 +3247,8 @@ export async function runCli(argv: string[]) {
   }
   // Commands without bespoke help fall back to the top-level usage on --help
   // instead of executing (audit used to silently run the sample audit).
-  // call/market/enrich/bulk-update print their own richer help.
-  if (!["call", "market", "enrich", "bulk-update"].includes(command) && (args.includes("--help") || args.includes("-h"))) {
+  // call/market/enrich/bulk-update/schedule print their own richer help.
+  if (!["call", "market", "enrich", "bulk-update", "schedule"].includes(command) && (args.includes("--help") || args.includes("-h"))) {
     console.log(usage());
     return;
   }
@@ -2876,6 +3317,10 @@ export async function runCli(argv: string[]) {
     await enrichCommand(args);
     return;
   }
+  if (command === "schedule") {
+    await scheduleCommand(args);
+    return;
+  }
   if (command === "profiles") {
     profilesCommand(args);
     return;

package/src/index.ts

@@ -254,6 +254,32 @@ export {
   type VendorScale,
 } from "./marketScale.ts";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
+export {
+  computeMissedFirings,
+  createFileScheduleRunStore,
+  createFileScheduleStore,
+  cronMatches,
+  crontabSentinels,
+  expectedFirings,
+  nextCronFiring,
+  parseCron,
+  renderManagedBlock,
+  replaceManagedBlock,
+  scheduleId,
+  scheduleRunsDir,
+  schedulesPath,
+  systemCrontabIo,
+  tokenizeCommand,
+  validateSchedulableArgv,
+  type CronExpression,
+  type CrontabIo,
+  type ScheduleEntry,
+  type ScheduleProvider,
+  type ScheduleRunRecord,
+  type ScheduleRunStore,
+  type ScheduleRunTrigger,
+  type ScheduleStore,
+} from "./schedule.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type {
   ApprovalStatus,