@meffecta/agent 0.0.1 → 1.0.1

package/lib/doctor.js

@@ -0,0 +1,452 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { requireDeployment, UserError } from "./config.js";
+import { api, capture, gcloudArgs, requireCommand } from "./gcloud.js";
+
+/**
+ * Judge a deployment, rather than describe it.
+ *
+ * `status` tells you what the service looks like; this tells you what is wrong with it.
+ * Every check here corresponds to a way a deployment has actually gone quiet or gone
+ * double — a scaled-to-zero service with no triggers looks perfectly healthy and runs
+ * nothing; an always-on one with triggers runs every cron twice; a sweep whose cadence no
+ * longer matches the inbox poll interval checks mail on the old schedule for ever. None of
+ * those show up as an error anywhere until someone notices the work stopped.
+ *
+ * Read-only, and every failure carries the command that fixes it.
+ */
+
+const OK = "ok";
+const WARN = "warn";
+const FAIL = "fail";
+
+class Report {
+  constructor() {
+    this.rows = [];
+  }
+  add(level, title, detail, fix) {
+    this.rows.push({ level, title, detail, fix });
+  }
+  ok(title, detail) {
+    this.add(OK, title, detail);
+  }
+  warn(title, detail, fix) {
+    this.add(WARN, title, detail, fix);
+  }
+  fail(title, detail, fix) {
+    this.add(FAIL, title, detail, fix);
+  }
+}
+
+const MARK = { [OK]: "✓", [WARN]: "!", [FAIL]: "✗" };
+
+/** Cron minutes the sweep should run at, given the poll interval. Mirrors setup-scheduler.sh. */
+
+/**
+ * The jobs the content repo declares on disk, parsed the way the engine parses them.
+ *
+ * This is a different question from what `GET /jobs` answers. That reports what the running
+ * service registered from a clone taken at *its* boot, so a job pushed since — or a cron
+ * changed since — is invisible to it until the service restarts. Comparing the two is the
+ * only way to see that gap, and it is the ordinary way a new job never runs.
+ */
+export function readLocalJobs(dir) {
+  if (!existsSync(dir)) {
+    return undefined;
+  }
+  const jobs = [];
+  for (const file of readdirSync(dir).filter((f) => f.endsWith(".md"))) {
+    const text = readFileSync(`${dir}/${file}`, "utf8");
+    const match = text.match(/^---\n([\s\S]*?)\n---\n/);
+    if (!match) {
+      continue;
+    }
+    const meta = {};
+    for (const line of match[1].split("\n")) {
+      const at = line.indexOf(": ");
+      if (at > 0) {
+        meta[line.slice(0, at).trim()] = line
+          .slice(at + 2)
+          .trim()
+          .replace(/^["']|["']$/g, "");
+      }
+    }
+    jobs.push({
+      name: meta.name || file.slice(0, -3),
+      cron: meta.cron,
+      webhook: meta.webhook,
+      inbox: meta.inbox,
+      disabled: meta.disabled === "true",
+    });
+  }
+  return jobs;
+}
+
+export function expectedSweepSchedule(pollSeconds) {
+  // Unset means the engine's own default; 0 must clamp to one minute rather than fall
+  // back to it, which is what setup-scheduler.sh does and what doctor has to agree with.
+  const raw = pollSeconds === undefined || pollSeconds === null || pollSeconds === "" ? 300 : Number(pollSeconds);
+  const seconds = Number.isFinite(raw) ? raw : 300;
+  const minutes = Math.max(1, Math.ceil(seconds / 60));
+  return minutes >= 60 ? "17 * * * *" : `*/${minutes} * * * *`;
+}
+
+/**
+ * Scaling and triggering are one decision expressed in two places, and both wrong pairings
+ * fail quietly: scaled to zero with nothing to drive it runs no jobs while looking
+ * perfectly healthy, and always-on with external triggers runs every cron twice — once
+ * from Cloud Scheduler and once from the in-process timer. Pure, so it can be tested
+ * without a deployment to point at.
+ */
+export function judgeTriggering({ minScale, external, throttled }) {
+  const scaledToZero = String(minScale ?? "0") === "0";
+  const findings = [];
+  if (scaledToZero && !external) {
+    findings.push({
+      level: FAIL,
+      title: "Scaled to zero with no triggers",
+      detail: "Nothing in the service fires on its own, so no job will ever run. It will look healthy.",
+      fix: "meffecta-agent setup-scheduler",
+    });
+  } else if (!scaledToZero && external) {
+    findings.push({
+      level: FAIL,
+      title: "Always-on and externally triggered",
+      detail: `min-instances=${minScale} keeps the in-process timers running while Cloud Scheduler also fires — every cron runs twice.`,
+      fix: "Set SCALING=scale-to-zero in deployment.env, then: meffecta-agent deploy",
+    });
+  } else if (external) {
+    findings.push({
+      level: OK,
+      title: "Triggering",
+      detail: "scaled to zero, driven by Cloud Scheduler and Cloud Tasks",
+    });
+  } else {
+    findings.push({
+      level: OK,
+      title: "Triggering",
+      detail: `always-on (min-instances=${minScale}), driven by in-process timers`,
+    });
+  }
+  if (scaledToZero && !throttled) {
+    findings.push({
+      level: WARN,
+      title: "Paying for idle CPU",
+      detail: "min-instances=0 with CPU always allocated — the saving of scaling to zero is not being taken.",
+      fix: "meffecta-agent deploy",
+    });
+  }
+  return findings;
+}
+
+export async function doctor() {
+  requireCommand("gcloud", "the CLI reads your deployment through it");
+  const d = requireDeployment();
+  const r = new Report();
+
+  const svc = JSON.parse(
+    capture(
+      "gcloud",
+      gcloudArgs(d, ["run", "services", "describe", d.SERVICE, `--region=${d.REGION}`, "--format=json"]),
+    ),
+  );
+  const tpl = svc.spec.template;
+  const ann = tpl.metadata.annotations ?? {};
+  const container = tpl.spec.containers[0];
+  const env = Object.fromEntries((container.env ?? []).map((e) => [e.name, e]));
+  const value = (name) => env[name]?.value;
+  const minScale = ann["autoscaling.knative.dev/minScale"] ?? "0";
+  const throttled = ann["run.googleapis.com/cpu-throttling"] !== "false";
+  const external = Boolean(value("AGENT_TASKS_QUEUE") && value("AGENT_PUBLIC_URL"));
+
+  // --- the service is actually up -------------------------------------------------
+  const ready = (svc.status?.conditions ?? []).find((c) => c.type === "Ready");
+  if (ready?.status === "True") {
+    r.ok("Service ready", `${svc.status.latestReadyRevisionName} serving`);
+  } else {
+    r.fail("Service not ready", ready?.message ?? "no Ready condition", "meffecta-agent logs");
+  }
+
+  // --- the pairing that decides whether anything runs at all ----------------------
+  for (const finding of judgeTriggering({ minScale, external, throttled })) {
+    r.add(finding.level, finding.title, finding.detail, finding.fix);
+  }
+
+  // --- configuration the engine cannot boot without -------------------------------
+  if (value("GIT_REPO_URL")) {
+    r.ok("Content repo", value("GIT_REPO_URL"));
+  } else {
+    r.fail(
+      "GIT_REPO_URL is unset",
+      "The engine clones the content repo at boot for its job registrations; without it the service will not start.",
+      "meffecta-agent set-env GIT_REPO_URL=https://github.com/<owner>/<repo>.git",
+    );
+  }
+
+  const secrets = new Set(
+    capture("gcloud", gcloudArgs(d, ["secrets", "list", "--format=value(name)"]))
+      .split("\n")
+      .filter(Boolean)
+      .map((n) => n.split("/").pop()),
+  );
+  for (const name of ["AGENT_WEBHOOK_SECRET", "CLAUDE_CODE_OAUTH_TOKEN", "GITHUB_TOKEN"]) {
+    const ref = env[name]?.valueFrom?.secretKeyRef?.name;
+    if (!env[name]) {
+      r.fail(`${name} not set`, "Required by the engine.", `meffecta-agent set-secret ${name}`);
+    } else if (ref && !secrets.has(ref)) {
+      r.fail(
+        `${name} points at a missing secret`,
+        `The service reads secret "${ref}", which is not in Secret Manager.`,
+        `meffecta-agent set-secret ${name}`,
+      );
+    }
+  }
+
+  const mounted = (container.volumeMounts ?? []).some((m) => m.mountPath === "/memory");
+  if (mounted || value("MEMORY_DIR")) {
+    r.ok("Memory", mounted ? "/memory volume mounted" : `MEMORY_DIR=${value("MEMORY_DIR")}`);
+  } else {
+    r.warn(
+      "No memory volume",
+      "Job memory, the queue journal and the spawn spool are in-process only — a restart loses pending work.",
+      "meffecta-agent setup-infra",
+    );
+  }
+
+  // --- the triggers, against what the content repo actually declares ---------------
+  if (external) {
+    let jobs = [];
+    try {
+      jobs = JSON.parse(await api(d, "/jobs"));
+      r.ok("Jobs registered", `${jobs.length} loaded from the content repo`);
+    } catch (err) {
+      r.fail("Cannot read the job list", err.message.split("\n")[0], "meffecta-agent logs");
+    }
+
+    // What the service registered came from a clone taken at its boot; the files here are
+    // current. A job pushed since, or a cron edited since, is invisible until it restarts.
+    const local = readLocalJobs(`${process.cwd()}/jobs`);
+    if (local) {
+      const registered = new Map(jobs.map((j) => [j.name, j]));
+      const unregistered = local.filter((j) => !registered.has(j.name));
+      const stale = local.filter((j) => registered.has(j.name) && registered.get(j.name).cron !== j.cron);
+      const gone = jobs.filter((j) => !local.some((l) => l.name === j.name));
+      if (unregistered.length || stale.length || gone.length) {
+        r.fail(
+          "The service has not picked up the content repo",
+          [
+            unregistered.length && `not registered: ${unregistered.map((j) => j.name).join(", ")}`,
+            stale.length && `cron changed on disk: ${stale.map((j) => j.name).join(", ")}`,
+            gone.length && `registered but no longer in jobs/: ${gone.map((j) => j.name).join(", ")}`,
+          ]
+            .filter(Boolean)
+            .join("; ") + ". Registrations are read at boot, so this needs a restart.",
+          "meffecta-agent deploy   (a rollout restarts it and re-syncs the triggers)",
+        );
+      } else {
+        r.ok("Content repo", `${local.length} job(s) on disk, all registered`);
+      }
+    }
+
+    const scheduler = capture(
+      "gcloud",
+      gcloudArgs(d, [
+        "scheduler",
+        "jobs",
+        "list",
+        `--location=${d.REGION}`,
+        "--format=value[separator='\t'](ID,schedule,state)",
+      ]),
+    )
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => line.split("\t"));
+    const byId = new Map(scheduler.map(([id, schedule, state]) => [id, { schedule, state }]));
+
+    const wanted = jobs.filter((j) => j.cron);
+    const missing = wanted.filter((j) => !byId.has(`${d.SERVICE}-job-${j.name}`));
+    const drifted = wanted.filter((j) => {
+      const found = byId.get(`${d.SERVICE}-job-${j.name}`);
+      return found && found.schedule !== j.cron;
+    });
+    const stale = [...byId.keys()].filter(
+      (id) => id.startsWith(`${d.SERVICE}-job-`) && !wanted.some((j) => `${d.SERVICE}-job-${j.name}` === id),
+    );
+    if (missing.length || drifted.length || stale.length) {
+      const parts = [
+        missing.length && `${missing.length} job(s) with no trigger: ${missing.map((j) => j.name).join(", ")}`,
+        drifted.length && `${drifted.length} schedule(s) out of date: ${drifted.map((j) => j.name).join(", ")}`,
+        stale.length && `${stale.length} trigger(s) for jobs that no longer exist: ${stale.join(", ")}`,
+      ].filter(Boolean);
+      r.fail("Triggers do not match the content repo", parts.join("; "), "meffecta-agent setup-scheduler");
+    } else if (wanted.length) {
+      r.ok("Cron triggers", `${wanted.length} in place, all matching the content repo`);
+    }
+
+    // An inbox job with no allowFrom refuses every message, so it looks registered and
+    // healthy while doing nothing at all. That is a failure, not a preference.
+    const unset = jobs.filter((job) => job.inbox && !job.allowFrom);
+    if (unset.length > 0) {
+      r.fail(
+        "Inbox jobs that refuse all mail",
+        `${unset.map((job) => `${job.name} (${job.inbox})`).join(", ")} — no allowFrom:, so every message is dropped and the job never runs.`,
+        "Add `allowFrom: you@example.com, @yourdomain.com` (or `*` for anyone) to the job, then: meffecta-agent deploy",
+      );
+    }
+    const anyone = jobs.filter((job) => job.allowFrom?.split(",").some((rule) => rule.trim() === "*"));
+    if (anyone.length > 0) {
+      r.warn(
+        "Inbox jobs anyone can trigger",
+        `${anyone.map((job) => job.name).join(", ")} — allowFrom: * accepts mail from any sender.`,
+        "Deliberate is fine; narrow it to addresses or domains if it was not.",
+      );
+    }
+
+    const sweep = byId.get(`${d.SERVICE}-sweep`);
+    if (!sweep) {
+      r.fail(
+        "No sweep",
+        "Due follow-ups, runs left behind by a dead process, and watched inboxes are all handled by the sweep. Without it they never happen.",
+        "meffecta-agent setup-scheduler",
+      );
+    } else {
+      const watchesInbox = jobs.some((j) => j.inbox);
+      const expected = watchesInbox ? expectedSweepSchedule(value("AGENT_INBOX_POLL_SECONDS")) : "17 * * * *";
+      if (sweep.schedule !== expected) {
+        r.warn(
+          "Sweep cadence is stale",
+          `Runs "${sweep.schedule}", but ${
+            watchesInbox
+              ? `AGENT_INBOX_POLL_SECONDS=${value("AGENT_INBOX_POLL_SECONDS") ?? 300} wants "${expected}"`
+              : `no job watches an inbox, so "${expected}" is enough`
+          }.`,
+          "meffecta-agent setup-scheduler",
+        );
+      } else {
+        r.ok("Sweep", `${sweep.schedule}${watchesInbox ? " — matching the inbox poll interval" : ""}`);
+      }
+    }
+
+    try {
+      const [state] = capture(
+        "gcloud",
+        gcloudArgs(d, [
+          "tasks",
+          "queues",
+          "describe",
+          `${d.SERVICE}-runs`,
+          `--location=${d.REGION}`,
+          "--format=value(state)",
+        ]),
+      ).split("\t");
+      if (state === "RUNNING") {
+        r.ok("Task queue", `${d.SERVICE}-runs running`);
+      } else {
+        r.fail(
+          "Task queue is not running",
+          `State ${state}. Webhooks, manual runs and follow-ups are delivered through it.`,
+          `gcloud tasks queues resume ${d.SERVICE}-runs --location ${d.REGION} --project ${d.PROJECT}`,
+        );
+      }
+    } catch {
+      r.fail(
+        "No task queue",
+        "External triggers are configured but the queue is missing.",
+        "meffecta-agent setup-scheduler",
+      );
+    }
+  }
+
+  // --- the image the next cold start will pull ------------------------------------
+  const repo = d.ARTIFACT_REPO ?? `${d.SERVICE}-images`;
+  try {
+    const digest = capture(
+      "gcloud",
+      gcloudArgs(d, [
+        "run",
+        "revisions",
+        "describe",
+        svc.status.latestReadyRevisionName,
+        `--region=${d.REGION}`,
+        "--format=value(status.imageDigest)",
+      ]),
+    )
+      .split("@")
+      .pop();
+    const present = capture(
+      "gcloud",
+      gcloudArgs(d, [
+        "artifacts",
+        "docker",
+        "images",
+        "list",
+        `${d.REGION}-docker.pkg.dev/${d.PROJECT}/${repo}`,
+        "--include-tags",
+        "--format=value(version)",
+      ]),
+    )
+      .split("\n")
+      .includes(digest);
+    if (present) {
+      r.ok("Running image", "still in Artifact Registry");
+    } else {
+      r.fail(
+        "The running image is gone from Artifact Registry",
+        "A revision pins a digest and a scaled-to-zero service pulls it on every cold start — the service will fail to wake.",
+        "meffecta-agent deploy",
+      );
+    }
+    const policies = capture(
+      "gcloud",
+      gcloudArgs(d, [
+        "artifacts",
+        "repositories",
+        "list-cleanup-policies",
+        repo,
+        `--location=${d.REGION}`,
+        "--format=value(name)",
+      ]),
+    );
+    if (policies.trim()) {
+      r.ok("Registry cleanup", "policy in place");
+    } else {
+      r.warn(
+        "No registry cleanup policy",
+        "Mirrored engine images accumulate; they are a cache of GHCR and can be expired freely.",
+        "meffecta-agent artifact-cleanup",
+      );
+    }
+  } catch {
+    // A deployment pulling through a remote repository has no registry of its own.
+  }
+
+  return r;
+}
+
+export function printReport(r) {
+  const width = Math.max(...r.rows.map((row) => row.title.length));
+  for (const { level, title, detail, fix } of r.rows) {
+    console.log(`${MARK[level]} ${title.padEnd(width)}  ${detail ?? ""}`);
+    if (fix) {
+      console.log(`${" ".repeat(width + 3)}→ ${fix}`);
+    }
+  }
+  const failed = r.rows.filter((row) => row.level === FAIL).length;
+  const warned = r.rows.filter((row) => row.level === WARN).length;
+  console.log("");
+  if (failed) {
+    console.log(`${failed} problem(s) that stop this deployment working${warned ? `, ${warned} worth a look` : ""}.`);
+  } else if (warned) {
+    console.log(`Nothing broken; ${warned} thing(s) worth a look.`);
+  } else {
+    console.log("Everything checks out.");
+  }
+  return failed > 0 ? 1 : 0;
+}
+
+export async function runDoctor() {
+  const report = await doctor();
+  if (report.rows.length === 0) {
+    throw new UserError("Nothing could be checked.");
+  }
+  return printReport(report);
+}

package/lib/flags.js

@@ -0,0 +1,82 @@
+import { UserError } from "./config.js";
+
+/**
+ * Argument parsing for the handful of commands this CLI implements itself.
+ *
+ * Most commands are passthrough — their arguments belong to a shell script and must arrive
+ * untouched — so what is needed here is small and strict rather than general: know the
+ * flags a command has, refuse anything else, and never guess. The rule throughout is that
+ * a malformed invocation is an error, not a default. `run <job> --in` with no value used
+ * to become an immediate run, which is the opposite of what was asked for.
+ *
+ * Supports `--name value`, `--name=value`, boolean flags, and `--` to end flag parsing.
+ */
+export function parseFlags(argv, spec = {}) {
+  const flags = {};
+  const positional = [];
+  let onlyPositional = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (onlyPositional || !token.startsWith("--")) {
+      positional.push(token);
+      continue;
+    }
+    if (token === "--") {
+      onlyPositional = true;
+      continue;
+    }
+
+    const eq = token.indexOf("=");
+    const name = (eq === -1 ? token : token.slice(0, eq)).slice(2);
+    const definition = spec[name];
+    if (!definition) {
+      const known = Object.keys(spec);
+      throw new UserError(
+        `Unknown option --${name}.` +
+          (known.length ? `\nThis command takes: ${known.map((k) => `--${k}`).join(", ")}` : "") +
+          '\nIf it is part of your text, quote the whole thing: meffecta-agent ask "…"',
+      );
+    }
+
+    if (definition.type === "boolean") {
+      flags[name] = eq === -1 ? true : argv[i].slice(eq + 1) !== "false";
+      continue;
+    }
+
+    let raw;
+    if (eq !== -1) {
+      raw = token.slice(eq + 1);
+    } else {
+      raw = argv[i + 1];
+      i += 1;
+    }
+    // A flag whose value is missing, or is the next flag, is a typo — not a default.
+    if (raw === undefined || (raw.startsWith("--") && eq === -1)) {
+      throw new UserError(`--${name} needs a value.`);
+    }
+
+    if (definition.type === "int") {
+      const value = Number(raw);
+      if (!Number.isInteger(value)) {
+        throw new UserError(`--${name} takes a whole number, not "${raw}".`);
+      }
+      if (definition.min !== undefined && value < definition.min) {
+        throw new UserError(`--${name} must be at least ${definition.min} (got ${value}).`);
+      }
+      if (definition.max !== undefined && value > definition.max) {
+        throw new UserError(`--${name} must be at most ${definition.max} (got ${value}).`);
+      }
+      flags[name] = value;
+      continue;
+    }
+
+    if (definition.choices && !definition.choices.includes(raw)) {
+      throw new UserError(`--${name} must be one of: ${definition.choices.join(", ")} (got "${raw}").`);
+    }
+    flags[name] = raw;
+  }
+
+  return { flags, positional };
+}