@meffecta/agent 1.0.3 → 1.0.7

package/lib/commands.js

@@ -1,23 +1,41 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { configPath, decideAnalytics, readConfig, resolvePosthog, writeConfig } from "./analytics.js";
 import { requireDeployment, UserError } from "./config.js";
+import { checkJobs, createJob } from "./create-job.js";
 import { runDoctor } from "./doctor.js";
 import { parseFlags } from "./flags.js";
 import { api, requireCommand, stream } from "./gcloud.js";
 import { connect } from "./integrations.js";
+import { resources } from "./resources.js";
+import { verifyCredentials } from "./verify-credentials.js";
+import { cliVersion, installMethod, invocation, isNewer, latestPublished } from "./version.js";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
+// Re-exported so the entrypoint keeps one import site for everything it prints.
+export { cliVersion };
+
 /**
  * Where the operator scripts are. In the published package they sit at its root; in a
  * checkout of the engine repo they are one level up, beside cli/. Same files either way —
  * the pack step copies them in, so the CLI is a front on exactly the scripts a deployment
  * would otherwise run by hand.
+ *
+ * **A checkout wins outright**, even when a vendored copy is present. `prepack` leaves one
+ * in cli/scripts, it is gitignored so it never shows up in `git status`, and a linked CLI
+ * reading that frozen snapshot is how you edit a script, run the command, and watch it
+ * behave exactly as though you had not. Same failure as a stale engine.json pinning a tag
+ * that was never published, and it gets the same guard: the engine's source sitting
+ * alongside means this is the repo, not an install of it.
  */
-export const scriptsDir = [resolve(packageRoot, "scripts"), resolve(packageRoot, "..", "scripts")].find((candidate) =>
-  existsSync(candidate),
-);
+const inCheckout = existsSync(resolve(packageRoot, "..", "src", "index.ts"));
+export const scriptsDir = [
+  ...(inCheckout ? [resolve(packageRoot, "..", "scripts")] : []),
+  resolve(packageRoot, "scripts"),
+  resolve(packageRoot, "..", "scripts"),
+].find((candidate) => existsSync(candidate));
 
 /**
  * The engine build this CLI was published alongside. CI writes it at pack time, so
@@ -45,14 +63,6 @@ export function engineTag() {
   }
 }
 
-export function cliVersion() {
-  try {
-    return JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8")).version;
-  } catch {
-    return "unknown";
-  }
-}
-
 /** A command that is one of the shipped scripts, with every argument passed straight on. */
 function script(file, { interpreter } = {}) {
   return async (args) => {
@@ -64,7 +74,12 @@ function script(file, { interpreter } = {}) {
       throw new UserError(`Missing script: ${file}`);
     }
     const runner = interpreter ?? (file.endsWith(".mjs") ? "node" : "bash");
-    const { code, error } = await stream(runner, [path, ...args]);
+    // MEFFECTA_CLI is how a script knows it was reached through the CLI, and what to call
+    // the next step: `meffecta-agent deploy`, never ./scripts/deploy.sh. A deployment run
+    // by someone outside Meffecta cannot clone this repo and has never seen those files.
+    const { code, error } = await stream(runner, [path, ...args], {
+      env: { ...process.env, MEFFECTA_CLI: invocation() },
+    });
     if (error) {
       throw new UserError(`Could not run ${runner}: ${error.message}`);
     }
@@ -72,6 +87,87 @@ function script(file, { interpreter } = {}) {
   };
 }
 
+/** The engine tag the deployment is actually running, from the image on its live revision. */
+async function runningEngineTag() {
+  try {
+    const d = requireDeployment();
+    const { capture, gcloudArgs } = await import("./gcloud.js");
+    const json = capture(
+      "gcloud",
+      gcloudArgs(d, [
+        "run",
+        "services",
+        "describe",
+        d.SERVICE,
+        `--region=${d.REGION}`,
+        "--format=value(spec.template.spec.containers[0].image)",
+      ]),
+    );
+    return json.trim().split(":").pop() || undefined;
+  } catch {
+    // No deployment.env, no gcloud, no service yet — all fine, this line is just omitted.
+    return undefined;
+  }
+}
+
+/**
+ * Am I current? Three numbers, because being "up to date" here has three parts and the
+ * dangerous state is between them: new tooling pins a NEW engine tag, but the deployment
+ * keeps running the old image until `deploy`. Tooling that provisions a shape the running
+ * engine does not implement is exactly what releasing the pair together prevents — and it
+ * reopens here, on the operator's machine, at upgrade time.
+ */
+async function upgrade(args) {
+  const checkOnly = args.includes("--check");
+  const installed = cliVersion();
+  const latest = await latestPublished();
+  const running = await runningEngineTag();
+  const how = installMethod();
+
+  console.log(`▶ @meffecta/agent`);
+  console.log(`   installed  ${installed}${how.kind === "checkout" ? "  (a checkout, not an installed package)" : ""}`);
+  console.log(`   published  ${latest ?? "unknown — could not reach the npm registry"}`);
+  if (running) {
+    console.log(`   engine     ${running}   (what your deployment is running now)`);
+  }
+  console.log("");
+
+  const behind = latest && isNewer(latest, installed);
+  if (!latest) {
+    console.log("Could not check for a newer version. Being offline is not a problem — this");
+    console.log("command only reads the registry; nothing else needs it.");
+    return 0;
+  }
+  if (!behind) {
+    console.log(`Up to date.`);
+  } else {
+    console.log(`A newer version is out: ${installed} → ${latest}`);
+    if (how.note) {
+      console.log(`   ${how.note}`);
+    }
+    console.log("");
+    console.log(`  ${how.upgrade}`);
+    if (how.kind !== "checkout") {
+      console.log(`  meffecta-agent deploy`);
+      console.log("");
+      console.log("Both lines. The first gets tooling that pins a newer engine; the second is");
+      console.log("what actually moves your deployment onto it. Stopping after the first leaves");
+      console.log("tooling that provisions a shape the running engine may not implement.");
+    }
+  }
+
+  // A deployment can be behind the CLI without the CLI being behind npm — someone upgraded
+  // the tooling and never deployed. That is the half-upgraded state, and it is worth saying
+  // out loud rather than leaving to be noticed.
+  const { tag, pinned } = engineTag();
+  if (pinned && running && running !== tag && !checkOnly) {
+    console.log("");
+    console.log(`⚠ This CLI deploys engine ${tag}, but the deployment is running ${running}.`);
+    console.log(`  meffecta-agent deploy      (rolls it onto ${tag} and re-syncs the triggers)`);
+  }
+  return 0;
+}
+
 /** What the deployment looks like right now: revision, shape, triggers, pending work. */
 async function status() {
   requireCommand("gcloud", "the CLI reads your deployment through it");
@@ -116,7 +212,7 @@ async function status() {
     const crons = jobs.filter((name) => name.startsWith(`${d.SERVICE}-job-`));
     const sweep = jobs.find((name) => name === `${d.SERVICE}-sweep`);
     console.log(
-      `   scheduler  ${crons.length} cron trigger(s)${sweep ? " + sweep" : " — NO SWEEP (run setup-scheduler)"}`,
+      `   scheduler  ${crons.length} cron trigger(s)${sweep ? " + sweep" : " — NO SWEEP (run sync-triggers)"}`,
     );
     if (crons.length === 0) {
       console.log("              ⚠ scaled to zero with no triggers: this service runs nothing.");
@@ -223,6 +319,67 @@ async function ask(args) {
   return 0;
 }
 
+/**
+ * `analytics` — the transparency surface, and the switch.
+ *
+ * Nothing is collected that could identify a deployment, but "trust me" is not a policy.
+ * This prints the exhaustive list of what is and is not sent, where the choice is stored,
+ * the state and the reason for it, and the one command that turns it off.
+ */
+const ANALYTICS_REASONS = {
+  "do-not-track": "the DO_NOT_TRACK environment variable is set",
+  "env-disabled": "MEFFECTA_ANALYTICS_DISABLED is set",
+  "config-disabled": "you ran `meffecta-agent analytics off`",
+  "config-enabled": "you ran `meffecta-agent analytics on`",
+  ci: "this looks like CI, where it is off by default",
+  default: "the default (on, and one command to turn off)",
+};
+
+async function analytics(args) {
+  const [action] = args;
+  if (action === "on" || action === "enable") {
+    writeConfig({ analytics: "enabled" });
+    console.log("✔ Anonymous analytics on. It steers what gets fixed and documented next.");
+    console.log(`  Recorded in ${configPath()}`);
+    return 0;
+  }
+  if (action === "off" || action === "disable") {
+    writeConfig({ analytics: "disabled" });
+    console.log("✔ Anonymous analytics off. Nothing further is sent from this machine.");
+    console.log(`  Recorded in ${configPath()}`);
+    return 0;
+  }
+  if (action && action !== "status") {
+    throw new UserError(`Unknown: analytics ${action}. Try: analytics status | on | off`);
+  }
+
+  const config = readConfig();
+  const decision = decideAnalytics({ config });
+  const { host, key } = resolvePosthog();
+  console.log(`Analytics: ${decision.enabled ? "ON" : "OFF"} — ${ANALYTICS_REASONS[decision.reason]}.`);
+  console.log(`  choice stored in  ${configPath()}`);
+  console.log(`  anonymous id      ${config.anonymousId ?? "(none yet — assigned on the first run with it on)"}`);
+  if (decision.enabled) {
+    console.log(`  sent to           ${key ? host : "nowhere — no key is configured in this build"}`);
+  }
+  console.log("");
+  console.log("Sent, and nothing else:");
+  console.log("  • which command you ran, from the fixed list — never a word you typed");
+  console.log("  • whether it worked, how long it took, and the class of any error");
+  console.log("  • this CLI's version, the engine tag it deploys, Node, OS, architecture");
+  console.log("  • how you installed it, and whether a deployment.env was found");
+  console.log("  • a random id, made on this machine, so repeat runs count as one install");
+  console.log("");
+  console.log("Never sent: your GCP project or service name, region, repo URLs, account or");
+  console.log("email, file paths, arguments, secret names or values, job names, prompts —");
+  console.log("or any error message. Only the error's class, because messages quote paths");
+  console.log("and project ids.");
+  console.log("");
+  console.log("Turn it off:  meffecta-agent analytics off      (or set DO_NOT_TRACK=1)");
+  console.log("Turn it on:   meffecta-agent analytics on");
+  return 0;
+}
+
 async function sweep() {
   requireCommand("gcloud", "the sweep is a Cloud Scheduler job");
   const d = requireDeployment();
@@ -318,7 +475,7 @@ async function triggers() {
 
   if (rows.length === 0) {
     console.log("No triggers. If this service is scaled to zero it is running nothing:");
-    console.log("  meffecta-agent setup-scheduler");
+    console.log("  meffecta-agent sync-triggers");
     return 0;
   }
   const width = Math.max(...rows.map(([id]) => id.length));
@@ -341,7 +498,7 @@ async function triggers() {
     ).split("\t");
     console.log(`\nTask queue ${d.SERVICE}-runs: ${queue[0] ?? "?"}, ${queue[1] || 0} task(s) waiting`);
   } catch {
-    console.log(`\nTask queue ${d.SERVICE}-runs: not created — run setup-scheduler`);
+    console.log(`\nTask queue ${d.SERVICE}-runs: not created — run setup-infra`);
   }
   return 0;
 }
@@ -367,22 +524,35 @@ async function logs(args) {
 // Scaffolded by `init` into a new content repo. Deliberately short: an empty table with the
 // columns that matter is a thing an operator fills in, where a long example is a thing they
 // delete.
-const REGISTER_TEMPLATE = `# Deployment environment
-
-The register of systems this agent can reach. The agent reads this file **at run time** —
-its skills are shared across deployments and name no deployment's variables, so a skill
-says what kind of credential it needs and comes here for the name.
+/**
+ * One example entry, scaffolded so the shape is obvious from a real file rather than from
+ * documentation. What the fields MEAN lives in SYSTEM.base.md, because every run needs to
+ * know it and no content repo should be carrying its own copy of an engine rule.
+ */
+const REGISTER_EXAMPLE = `---
+system: Example — rename this file after the system, and delete it once you have a real one
+skill: cloudflare
+requires: CLOUDFLARE_API_KEY, CLOUDFLARE_ACCOUNT_ID
+access: read; writes only when a job says so explicitly
+probe: list zones
+---
 
-A system that is not listed here is one the agent will report as unavailable.
+One file per system, in this directory. The agent reads them **at run time**: its skills
+are shared across every deployment and name no deployment's variables, so a skill says what
+kind of credential it needs and comes here for the name.
 
-| System | Skill | Variables | Access |
-| --- | --- | --- | --- |
-|  |  |  |  |
+**A system with no file here is one the agent will report as unavailable.** That is the
+point of the register, and it is why an absence means as much as an entry.
 
-Fill the Access column honestly — "read-only", "may send mail", "may change DNS". It is
-what a person reads when deciding whether a job is safe to let run unattended.
+- \`requires\` is exact variable names, all of which must be set. Use \`none\` for a system
+  that authenticates as the runtime service account instead.
+- \`selectors\` is for optional per-project pointers — one per world.
+- \`access\` is what a JOB may do, written honestly: "read-only", "may send mail", "may
+  change DNS". It is what a person reads when deciding whether to let a job run unattended.
+- \`probe\` is the cheapest read that proves the credential works, with no side effect —
+  list domains rather than send, read quota rather than generate.
 
-Set the values themselves with \`meffecta-agent set-secret <NAME>\` (credentials) or
+Set the values with \`meffecta-agent set-secret <NAME>\` (credentials) or
 \`set-env <NAME>=<value>\` (ids, addresses, URLs); \`meffecta-agent connect\` lists the
 systems the engine already has skills for and walks through each.
 `;
@@ -408,17 +578,19 @@ async function init(args) {
   console.log("set of jobs runs as is a fact about the deployment and none of it is secret.\n");
 
   // The register is read by the agent itself at run time, not just by people: the skills
-  // are shared across deployments and name no deployment's variables, so without this file
-  // a run knows how a system works and not which variable holds its credential.
-  const register = resolve(process.cwd(), "ENVIRONMENT.md");
-  if (exists(register)) {
-    console.log("ENVIRONMENT.md already exists here. Leaving it alone.\n");
+  // are shared across deployments and name no deployment's variables, so without it a run
+  // knows how a system works and not which variable holds its credential.
+  const { mkdirSync } = await import("node:fs");
+  const registerDir = resolve(process.cwd(), "systems");
+  if (exists(registerDir)) {
+    console.log("systems/ already exists here. Leaving it alone.\n");
   } else {
-    writeFileSync(register, REGISTER_TEMPLATE);
-    console.log("✅ Wrote ENVIRONMENT.md here — the register of systems this agent can reach.\n");
-    console.log("Add a row per system as you connect one. The agent reads this file at run");
-    console.log("time to find out which variable holds which credential, so a system that is");
-    console.log("not listed is a system it will report as unavailable.\n");
+    mkdirSync(registerDir, { recursive: true });
+    writeFileSync(resolve(registerDir, "example.md"), REGISTER_EXAMPLE);
+    console.log("✅ Wrote systems/example.md — the register of what this agent can reach.\n");
+    console.log("One file per system, added as you connect each one. The agent reads them at");
+    console.log("run time to find out which variable holds which credential, so a system with");
+    console.log("no file here is one it will report as unavailable.\n");
   }
   console.log("Next: meffecta-agent steps");
   return 0;
@@ -444,13 +616,17 @@ export const GROUPS = [
       ["init", "Start a deployment.env here, from the template", init],
       [
         "setup-infra",
-        "Provision GCP: registry, buckets, service account, service shell",
+        "Provision GCP: registry, buckets, service account, run queue, service shell",
         script("setup-infrastructure.sh"),
       ],
       ["set-secret", "AGENT_API_SECRET --random, CLAUDE_CODE_OAUTH_TOKEN, GITHUB_TOKEN", script("set-secret.sh")],
       ["set-env", "GIT_REPO_URL — the one setting the service will not boot without", script("set-env.sh")],
       ["deploy", "Roll out an engine image and assert the runtime shape", script("deploy.sh")],
-      ["setup-scheduler", "Create the external triggers — Cloud Scheduler + Cloud Tasks", script("setup-scheduler.sh")],
+      [
+        "sync-triggers",
+        "Re-sync the Cloud Scheduler triggers without a rollout (deploy does it)",
+        script("sync-triggers.sh"),
+      ],
     ],
   },
   {
@@ -484,15 +660,24 @@ export const GROUPS = [
       ["secrets", "What is in Secret Manager, and whether the service reads it", secretsList],
       ["triggers", "The Cloud Scheduler jobs and task queue that drive it", triggers],
       ["logs", "Recent service logs (--limit N)", logs],
+      ["check-jobs", "Validate the job files here — after you have edited one by hand", checkJobs],
+      ["analytics", "What anonymous usage data is sent, and how to turn it off", analytics],
+      ["resources", "Everything the set-up built in Google Cloud, and what each part is for", resources],
     ],
   },
   {
     title: "Operate it",
     commands: [
+      ["create-job", 'Write a new job from a description: create-job "a report every Wednesday 2pm"', createJob],
       ["run", "Trigger one job now, or --in <seconds>", runJob],
       ["ask", "Ask it something as a one-off run", ask],
       ["sweep", "Run the housekeeping sweep now", sweep],
-      ["verify-credentials", "Exercise every configured credential from here", script("verify-credentials.mjs")],
+      [
+        "verify-credentials",
+        "Test every credential the deployment holds, from inside it (--quick skips the slow half)",
+        verifyCredentials(ask),
+      ],
+      ["upgrade", "Check for a newer CLI, and what your deployment is running", upgrade],
       ["update-tooling", "Refresh the shipped scripts from an engine image (docker path)", script("update-tooling.sh")],
     ],
   },