@oalo-ai/cli 0.0.0-stage → 0.1.0

package/src/commands/run.js

@@ -0,0 +1,152 @@
+import { OaloChannel } from "../channel.js";
+import { appIdFor } from "../app-ref.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { isInternal, NOISY, format, clock, dim } from "../events.js";
+
+/**
+ * `oalo run` — make something happen, and see what it did.
+ *
+ * `tail` could already watch, but nothing could ACT, so testing a loop or a bot
+ * still meant opening the dashboard. Both underlying events already existed:
+ *
+ *   loops:run_now           {"name": ...}          -> {"run_id": ...}
+ *   chat:bots:test_message  {"bot_id", "text"}     -> replies stream back
+ *
+ * NOTE `run loop` fires the loop DIRECTLY. It does not exercise the loop's
+ * trigger binding, because triggers come from the event bus (a real form
+ * submission, a real inbound message) which nothing exposes for simulation yet.
+ * So this proves the loop's BODY works, not that its trigger is wired.
+ */
+async function connect(flags) {
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+
+  if (!url || !token) {
+    console.error(
+      `oalo run needs a CLI token.\n\n${HOW_TO_CONNECT}`,
+    );
+    return null;
+  }
+
+  return { ch: new OaloChannel({ url, token }), url, env: cfg.env };
+}
+
+/** Stream events for `seconds`, or until `done` says we have seen enough. */
+function watch(ch, { seconds, done }) {
+  return new Promise((finish) => {
+    const timer = setTimeout(finish, seconds * 1000);
+
+    ch.onEvent((event, payload) => {
+      if (isInternal(event) || NOISY.test(event)) return;
+      const at = payload && typeof payload === "object" ? payload.at : null;
+      console.log(`${dim(clock(at))}  ${event.padEnd(22)} ${format(event, payload)}`);
+      if (done && done(event, payload)) {
+        clearTimeout(timer);
+        finish();
+      }
+    });
+  });
+}
+
+export async function run(flags, rest) {
+  const what = rest[1];
+
+  if (!what || !["loop", "bot"].includes(what)) {
+    console.error("usage:\n  oalo run loop <name> [--env dev|prod] [--watch]\n  oalo run bot <id> \"<message>\" [--watch]");
+    process.exitCode = 2;
+    return;
+  }
+
+  const conn = await connect(flags);
+  if (!conn) {
+    process.exitCode = 2;
+    return;
+  }
+  const { ch, env } = conn;
+
+  const seconds = Number(flags.timeout) > 0 ? Number(flags.timeout) : 30;
+  const shouldWatch = flags.watch !== false && (flags.watch || what === "bot");
+
+  try {
+    await ch.connect();
+
+    if (what === "loop") {
+      const name = rest[2];
+      if (!name) {
+        console.error("which loop? oalo run loop <name>");
+        process.exitCode = 2;
+        return;
+      }
+
+      const params = { name, env: flags.env || env };
+      // A loop pinned to one app: by slug (`oalo apps`) or id.
+      if (typeof flags.app === "string") params.app_id = await appIdFor(ch, flags.app);
+
+      const reply = await ch.call("loops:run_now", params);
+      const runId = reply?.run_id ?? reply?.["run_id"];
+      console.log(`started ${name}${runId ? ` (run ${runId})` : ""}`);
+      console.error(dim("note: fires the loop directly; does not exercise its trigger"));
+
+      // Loop run events go to a PER-RUN topic ("loop_run:<id>") that the client
+      // must opt into. Without this the watch sits silent for its whole window
+      // and looks like the loop did nothing. That is the worst failure for a
+      // debugging tool, since it looks exactly like a real stall.
+      if (shouldWatch && runId != null) {
+        try {
+          await ch.call("loops:subscribe_run", { run_id: runId });
+        } catch (e) {
+          console.error(dim(`could not subscribe to run ${runId}: ${e.message}`));
+        }
+      }
+
+      if (shouldWatch) {
+        console.error(dim(`watching for ${seconds}s; ctrl-c stops`));
+        // Loop statuses are: running, waiting, success, error, cancelled.
+        // `waiting` is NOT a stall: the loop parked on a durable wait that may
+        // resume hours later, so say so and stop rather than burning the window.
+        let final = null;
+        await watch(ch, {
+          seconds,
+          done: (event, p) => {
+            if (event !== "loop_run_status") return false;
+            const status = String(p?.status || "");
+            final = status;
+
+            if (status === "waiting") {
+              console.error(dim("run is parked on a durable wait; it will resume on its own"));
+              return true;
+            }
+
+            return ["success", "error", "cancelled"].includes(status);
+          },
+        });
+        // A run that failed is a failed command, for scripts and agents (audit C2).
+        if (final === "error" || final === "cancelled") process.exitCode = 1;
+      }
+      return;
+    }
+
+    // bot
+    const botId = rest[2];
+    const text = rest[3];
+    if (!botId || !text) {
+      console.error('usage: oalo run bot <id> "<message>"');
+      process.exitCode = 2;
+      return;
+    }
+
+    // bot_id accepts an integer, a numeric string, or a public bot_ id — the
+    // server normalises all three at the channel boundary.
+    await ch.call("chat:bots:test_message", { bot_id: botId, text });
+    console.error(dim(`sent to ${botId}; watching for ${seconds}s; ctrl-c stops`));
+    await watch(ch, {
+      seconds,
+      done: (event) => event === "response:done",
+    });
+  } catch (e) {
+    console.error(`run failed: ${e.message}`);
+    process.exitCode = 1;
+  } finally {
+    ch.close();
+  }
+}

package/src/commands/secrets.js

@@ -0,0 +1,68 @@
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { requireFeature } from "../server.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo secrets`: keys and tokens OALO found committed to an app's code (on
+ * import, and in each push or deploy's new commits). Only where each one is
+ * and what it looks like: no value is ever kept.
+ *
+ *   oalo secrets [--app <slug>] [--all] [--json]
+ *   oalo secrets dismiss <fingerprint> [--app <slug>]
+ *
+ * For each finding: rotate the key with its provider (it stays in the repo's
+ * history), set the new one with `oalo env set NAME --secret`, and read it
+ * from the environment in the code. Dismiss one that isn't a secret.
+ */
+export async function secrets(flags, rest, opts = {}) {
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) return fail(`oalo secrets needs a CLI token.\n\n${HOW_TO_CONNECT}`, 2);
+
+  const app = typeof flags.app === "string" ? flags.app : cfg.appId;
+  if (!app) return fail("which app? Pass --app <slug> (`oalo apps` lists them), or save it with `oalo link --app <slug>`.", 2);
+  const [action, fingerprint] = rest;
+  if (action && action !== "dismiss") return fail(`unknown: oalo secrets ${action}. Try \`oalo secrets\` or \`oalo secrets dismiss <fingerprint>\`.`, 2);
+  if (action === "dismiss" && !fingerprint) return fail("oalo secrets dismiss needs the finding's fingerprint (from `oalo secrets`).", 2);
+
+  if (!opts.channel) {
+    try {
+      await requireFeature(url, "secrets", "oalo secrets");
+    } catch (e) {
+      return fail(e.message, 1);
+    }
+  }
+
+  const ch = (opts.channel || ((o) => new OaloChannel(o)))({ url, token });
+  try {
+    await ch.connect();
+    if (action === "dismiss") {
+      const r = await ch.call("secrets:dismiss", { app, fingerprint });
+      console.log(`dismissed ${r.dismissed} for ${r.app}`);
+      return;
+    }
+
+    const r = await ch.call("secrets:list", { app, all: flags.all === true });
+    if (flags.json) return console.log(JSON.stringify(r.findings, null, 2));
+    if (!r.findings.length) return console.log(`no ${flags.all ? "" : "open "}findings for ${r.app}`);
+    for (const f of r.findings) {
+      const at = f.commit ? ` commit ${f.commit.slice(0, 8)}` : "";
+      const gone = f.dismissed_at ? dim(" (dismissed)") : "";
+      console.log(`${f.file}:${f.line}  ${f.rule.replace(/-/g, " ")}${at}${gone}`);
+      console.log(dim(`  ${f.fingerprint}`));
+    }
+    console.error(
+      dim(`\nFor each: rotate it with its provider (it stays in the repo's history), set the new one with \`oalo env set NAME --secret --app ${r.app}\`, and read it from the environment. \`oalo secrets dismiss <fingerprint>\` for one that isn't a secret.`),
+    );
+  } catch (e) {
+    fail(e.message, 1);
+  } finally {
+    ch.close();
+  }
+}
+
+function fail(message, code) {
+  console.error(`oalo secrets: ${message}`);
+  process.exitCode = code;
+}

package/src/commands/setup.js

@@ -0,0 +1,96 @@
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo setup`: the setup agent on your Base makes this app run (a repo Oalo
+ * can't run on its own), on a branch, oalo/setup, that you then accept or
+ * reject. Oalo checks each attempt itself: the app is detected and its
+ * preview answers.
+ *
+ *   oalo setup [--app <slug>]          start one
+ *   oalo setup status [--app <slug>]   how it's going, and its report
+ *   oalo setup accept [--app <slug>]   make its commits the app's code
+ *   oalo setup reject [--app <slug>]   throw them away
+ *   oalo setup auto on|off             start one by itself when a dev deploy finds nothing runs
+ */
+export async function setup(flags, rest, opts = {}) {
+  const sub = rest[1] || "start";
+  if (!["start", "status", "accept", "reject", "auto"].includes(sub)) return fail(`unknown setup command: ${sub}\n\n${USAGE}`, 2);
+  if (sub === "auto" && !["on", "off"].includes(rest[2])) return fail("usage: oalo setup auto on|off [--app <slug>]", 2);
+
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) return fail(`oalo setup needs a CLI token.\n\n${HOW_TO_CONNECT}`, 2);
+  const app = typeof flags.app === "string" ? flags.app : cfg.appId;
+  if (!app) return fail("which app? Pass --app <slug> (`oalo apps` lists them), or save it with `oalo link --app <slug>`.", 2);
+
+  const ch = (opts.channel || ((o) => new OaloChannel(o)))({ url, token });
+  let r;
+  try {
+    await ch.connect();
+    r = await ch.call(`setup:${sub}`, sub === "auto" ? { app, on: rest[2] === "on" } : { app }, 60000);
+  } catch (e) {
+    return fail(e.message, 1);
+  } finally {
+    ch.close();
+  }
+  if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+  print(sub, r, rest[2]);
+}
+
+const USAGE = [
+  "usage: oalo setup [--app <slug>]",
+  "       oalo setup status | accept | reject [--app <slug>]",
+  "       oalo setup auto on|off [--app <slug>]",
+].join("\n");
+
+function print(sub, r, onOff) {
+  const app = r.app;
+  if (sub === "auto") {
+    console.log(
+      onOff === "on"
+        ? `${app}: a dev deploy that finds nothing runs starts the setup agent by itself.`
+        : `${app}: the setup agent starts only when you ask (oalo setup).`,
+    );
+    return;
+  }
+  if (sub === "accept") {
+    console.log(`${app}: the setup's commits are its code now (${String(r.commit || "").slice(0, 8)}), and its preview restarts.`);
+    console.log(dim(`In your own copy: oalo deploy --app ${app} --pull, then git merge oalo/${app}.`));
+    return;
+  }
+  if (sub === "reject") return void console.log(`${app}: the setup's commits are gone; the app is as it was.`);
+  if (sub === "start") {
+    console.log(
+      `${app}: the setup agent is on it (up to ${r.max_attempts} attempts, $${r.budget_usd} at most). Oalo checks each attempt: the app detected and its preview answering.`,
+    );
+    console.log(dim(`oalo setup status --app ${app} shows how it's going; deploys wait until it's done and reviewed.`));
+    return;
+  }
+
+  // status
+  if (r.status === "none") return void console.log(`${app}: no setup yet. oalo setup --app ${app} starts one.`);
+  const what =
+    {
+      queued: "waiting to start",
+      running: `working: attempt ${r.attempts + 1} of ${r.max_attempts}`,
+      ready: "done: it runs. Review it, then accept or reject",
+      failed: `stopped: ${r.error || "it didn't run"}`,
+      accepted: "accepted",
+      rejected: "rejected",
+    }[r.status] || r.status;
+  console.log(`${app}: ${what}`);
+  console.log(dim(`  ${r.attempts} attempt${r.attempts === 1 ? "" : "s"}, $${r.cost_usd} of $${r.budget_usd}${r.auto ? ", starts by itself on a failing deploy" : ""}`));
+  for (const c of r.checks || []) {
+    console.log(dim(`  attempt ${c.attempt}: ${c.ok ? `runs (${c.detected})` : `didn't run: ${String(c.why || "").split("\n")[0]}`}`));
+  }
+  if (r.report) console.log(`\n${r.report.trim()}`);
+  if (r.status === "ready") console.log(dim(`\nThe preview shows it now. oalo setup accept --app ${app} keeps it; oalo setup reject --app ${app} throws it away.`));
+  if (r.status === "failed") process.exitCode = 1;
+}
+
+function fail(message, code) {
+  console.error(message);
+  process.exitCode = code;
+}

package/src/commands/skill.js

@@ -0,0 +1,142 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { CLI_VERSION } from "../server.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo skill`: teach the coding agent in this project how to work on OALO.
+ *
+ *   oalo skill            install .claude/skills/oalo/SKILL.md (Claude Code loads it)
+ *   oalo skill --agents   also add the same rules to AGENTS.md, for other agents
+ *   oalo skill --print    print the skill to stdout
+ *
+ * The skill ships inside this package (plugin/skills/oalo/SKILL.md), so it matches the
+ * CLI version that will run its commands. Re-running replaces the installed
+ * copy and the AGENTS.md section (between oalo markers), nothing else.
+ *
+ * `oalo link` installs it too, or refreshes it. The installed copy is stamped
+ * with the CLI version that wrote it, so a newer CLI can say, once, that it's
+ * behind (`skillNotice`).
+ */
+
+// One copy, shared with the Claude Code plugin (plugin/), so the two cannot drift.
+const SKILL = join(dirname(fileURLToPath(import.meta.url)), "../../plugin/skills/oalo/SKILL.md");
+const START = "<!-- oalo:start (written by `oalo skill --agents`; re-run to update) -->";
+const END = "<!-- oalo:end -->";
+const STAMP = /<!-- oalo-cli ([0-9][0-9A-Za-z.+-]*) /;
+// The skill changes between CLI versions too (the version stayed 0.1.0 through
+// a week of skill changes), so the stamp also carries a hash of its content.
+const HASH = /\(skill ([0-9a-f]+)\)/;
+
+/** A short hash of the packaged skill: what an installed copy is compared by. */
+export function skillHash() {
+  return createHash("sha256").update(readFileSync(SKILL, "utf8")).digest("hex").slice(0, 12);
+}
+
+const body = (md) => md.replace(/^---\n[\s\S]*?\n---\n+/, "");
+const skillPath = (cwd) => join(cwd, ".claude", "skills", "oalo", "SKILL.md");
+
+// The packaged skill with a stamp line after its front matter (the front matter
+// must stay first for Claude Code to read it).
+function stamped() {
+  const md = readFileSync(SKILL, "utf8");
+  const stamp = `<!-- oalo-cli ${CLI_VERSION} (skill ${skillHash()}) wrote this copy; \`oalo skill\` updates it. -->\n\n`;
+  const fm = /^---\n[\s\S]*?\n---\n+/.exec(md);
+  return fm ? md.slice(0, fm[0].length) + stamp + md.slice(fm[0].length) : stamp + md;
+}
+
+/**
+ * Write the skill into `cwd` (and the AGENTS.md section when `agents`, or when
+ * AGENTS.md already has one). `{path, agents}`: what was written.
+ */
+export function installSkill(cwd = process.cwd(), { agents = false } = {}) {
+  const md = stamped();
+  const target = skillPath(cwd);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, md);
+
+  const agentsPath = join(cwd, "AGENTS.md");
+  const current = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : "";
+  const at = current.indexOf(START);
+  const endAt = current.indexOf(END);
+  let agentsResult = null;
+
+  if (agents || at >= 0) {
+    const section = `${START}\n${body(md).trim()}\n${END}`;
+    const next =
+      at >= 0 && endAt > at
+        ? current.slice(0, at) + section + current.slice(endAt + END.length)
+        : `${current}${current && !current.endsWith("\n") ? "\n" : ""}${current ? "\n" : ""}${section}\n`;
+    writeFileSync(agentsPath, next);
+    agentsResult = at >= 0 ? "updated" : "added";
+  }
+
+  return { path: target.slice(cwd.length + 1), agents: agentsResult };
+}
+
+/**
+ * The CLI version that wrote the project's installed skill: a version string,
+ * "old" for a copy from before copies were stamped, or null when there's none.
+ */
+export function installedSkillVersion(cwd = process.cwd()) {
+  const p = skillPath(cwd);
+  if (!existsSync(p)) return null;
+  const m = STAMP.exec(readFileSync(p, "utf8"));
+  return m ? m[1] : "old";
+}
+
+/** The content hash an installed copy was stamped with, or null. */
+export function installedSkillHash(cwd = process.cwd()) {
+  const p = skillPath(cwd);
+  if (!existsSync(p)) return null;
+  const m = HASH.exec(readFileSync(p, "utf8"));
+  return m ? m[1] : null;
+}
+
+/**
+ * One line, at most once per project and CLI version, when the project's
+ * installed skill is from another CLI version or has other content. null otherwise. The notices
+ * already given are kept beside the credentials (OALO_HOME).
+ */
+export function skillNotice(cwd = process.cwd()) {
+  const installed = installedSkillVersion(cwd);
+  if (!installed) return null;
+  const hash = skillHash();
+  const sameVersion = installed === CLI_VERSION;
+  if (sameVersion && installedSkillHash(cwd) === hash) return null;
+
+  const file = join(process.env.OALO_HOME || homedir(), ".oalo", "skill-notices.json");
+  let seen = {};
+  try {
+    seen = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    /* none yet */
+  }
+  const key = `${cwd}@${CLI_VERSION}@${hash}`;
+  if (seen[key]) return null;
+
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ ...seen, [key]: true }, null, 2));
+  } catch {
+    /* a read-only home: say it every time rather than never */
+  }
+  if (sameVersion) return "This project's OALO skill (.claude/skills/oalo/SKILL.md) is older than the one this CLI carries. Run `oalo skill` to update it.";
+  const from = installed === "old" ? "an older CLI" : `CLI ${installed}`;
+  return `This project's OALO skill (.claude/skills/oalo/SKILL.md) is from ${from}; you have ${CLI_VERSION}. Run \`oalo skill\` to update it.`;
+}
+
+export async function skill(flags) {
+  if (flags.print) {
+    process.stdout.write(stamped());
+    return;
+  }
+
+  const r = installSkill(process.cwd(), { agents: !!flags.agents });
+  console.log(`installed ${r.path}`);
+  if (r.agents) console.log(`${r.agents} the OALO section in AGENTS.md`);
+  console.log(dim(`From CLI ${CLI_VERSION}. Run \`oalo skill\` again after updating the CLI.`));
+}