@oalo-ai/cli 0.0.0-stage → 0.1.1

package/src/commands/deploy.js

@@ -0,0 +1,431 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, statSync, createReadStream, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT, readConfig, writeConfig } from "../config.js";
+import { requireFeature } from "../server.js";
+import { targetEnv } from "../data.js";
+import { dim } from "../events.js";
+import { readValue } from "./env.js";
+
+/**
+ * `oalo deploy`: send this repo's commits to an app on the workspace and run them.
+ *
+ *   oalo deploy [--app <slug>]                 to the preview (dev)
+ *   oalo deploy --new [<name>]                 a new app from this repo, its history kept
+ *   oalo deploy --new [<name>] --from <url>    a new app from a Git URL, cloned by the Base
+ *   oalo deploy --app <slug> --env prod        build and swap the live release
+ *   oalo deploy --app <slug> --pull            fetch the app's code from Oalo as oalo/<slug>
+ *   oalo deploy --app <slug> --replace         make this branch the app's code (old code is tagged)
+ *   oalo deploy --app <slug> --history         the live releases it has had
+ *   oalo deploy --app <slug> --rollback [--to <sha>]   make an earlier release live again
+ *
+ * What is sent is the current branch's commits, as a git bundle, signed in with
+ * the CLI token: no git remote or Forgejo credential is needed. Uncommitted
+ * changes are not deployed. The box only fast-forwards, so if the app has
+ * commits this repo lacks (the builder agent changed it), the deploy stops and
+ * says to `--pull` and merge first.
+ */
+export async function deploy(flags) {
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) return fail(`oalo deploy needs a CLI token.\n\n${HOW_TO_CONNECT}`, 2);
+
+  // --new [<name>] --from <url>: the code comes from a Git URL, not this folder.
+  if (flags.from !== undefined) return fromGit(url, token, flags);
+
+  // --new [<name>]: a new app from this repo (its slug from the name, or the
+  // repo's folder).
+  const creating = flags.new !== undefined;
+  let app = typeof flags.app === "string" ? flags.app : cfg.appId;
+  if (creating) {
+    let top;
+    try {
+      top = git(["rev-parse", "--show-toplevel"]);
+    } catch {
+      return fail("not inside a git repo. oalo deploy --new makes an app from this repo's commits.", 2);
+    }
+    app = slugify(typeof flags.new === "string" ? flags.new : top.split("/").pop());
+    if (!app) return fail("give the new app a name: oalo deploy --new <name>", 2);
+  }
+  if (!app) return fail("which app? Pass --app <slug> (`oalo apps` lists them), save it with `oalo link --app <slug>`, or make one from this repo with `oalo deploy --new`.", 2);
+
+  try {
+    await requireFeature(url, "deploy", "oalo deploy");
+  } catch (e) {
+    return fail(e.message, 1);
+  }
+
+  if (flags.history || flags.rollback) return releases(url, token, app, flags);
+
+  let root;
+  try {
+    root = git(["rev-parse", "--show-toplevel"]);
+  } catch {
+    return fail(
+      flags.pull
+        ? `not inside a git repo. --pull fetches ${app}'s code into one: \`git init\` here (or cd into the app's repo), then run it again.`
+        : "not inside a git repo. oalo deploy sends this repo's commits.",
+      2,
+    );
+  }
+
+  if (flags.pull) return pull(url, token, app, root);
+
+  let env;
+  try {
+    env = targetEnv(flags, cfg);
+  } catch (e) {
+    return fail(e.message, 2);
+  }
+  if (creating && env !== "dev") return fail("a new app starts on its preview: run `oalo deploy --new` without --env prod, then deploy it live.", 2);
+
+  const dirty = git(["status", "--porcelain", "--untracked-files=no"], root);
+  if (dirty && !flags["allow-dirty"]) {
+    return fail("you have uncommitted changes, and a deploy sends commits. Commit them (or stash), or pass --allow-dirty to deploy the last commit anyway.", 2);
+  }
+
+  // Files that decide how the app runs, written but never committed: the
+  // deploy sends commits only, so they'd be silently left out (audit R4).
+  const untracked = untrackedRunFiles(root);
+  if (untracked.length) {
+    console.error(`not committed, so this deploy leaves them out: ${untracked.join(", ")}`);
+    console.error(dim(`  git add ${untracked.join(" ")} && git commit, then deploy again (they decide how the app installs and starts).`));
+  }
+
+  const sha = git(["rev-parse", "HEAD"], root);
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], root);
+  const tracked = `refs/remotes/oalo/${app}`;
+  const base = !creating && refExists(tracked, root) ? git(["rev-parse", tracked], root) : null;
+  // Send only commits the app lacks. When it already runs this commit (say, dev
+  // before prod), one step back is enough: the box has that too.
+  const parent = refExists(`${sha}~1`, root) ? git(["rev-parse", `${sha}~1`], root) : null;
+  const incremental = base && isAncestor(base, sha, root) ? (base === sha ? parent : base) : null;
+
+  console.error(dim(creating ? `creating ${app} from ${branch} at ${sha.slice(0, 8)} on ${url}` : `deploying ${branch} at ${sha.slice(0, 8)} to ${app} (${env}) on ${url}`));
+  if (env === "prod") console.error(dim("live visitors get this release when the build finishes"));
+
+  const create = creating ? { name: typeof flags.name === "string" ? flags.name : app } : null;
+  let result = await send({ url, token, app, env, sha, root, base: incremental, replace: !!flags.replace, create });
+  if (result?.error?.code === "needs_full_bundle" && incremental) {
+    console.error(dim("the app doesn't have the commits this builds on; sending the full history"));
+    result = await send({ url, token, app, env, sha, root, base: null, replace: !!flags.replace });
+  }
+
+  if (!result) return fail("the connection closed before the deploy finished. Check `oalo apps` for the app's state, then try again.", 1);
+
+  if (result.error) {
+    const e = result.error;
+    console.error(`deploy failed: ${e.message}`);
+    for (const c of e.box_only || []) console.error(dim(`  on Oalo only: ${c}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  // A new app: this project now deploys to it (as `oalo link --app` saves).
+  if (result.created) {
+    writeConfig({ ...(readConfig(root) || {}), serverUrl: url, appId: result.app, env: "dev" }, root);
+    if (result.app_type === "code_only") {
+      // The server's progress line already said what to add.
+      console.log(`created ${result.app} from ${result.commit.slice(0, 8)}, its history kept. Nothing runs yet (see above).`);
+      console.log(dim("After adding what it needs: commit, then `oalo deploy`. `oalo docs bring-your-repo` has the details."));
+    } else {
+      console.log(`created ${result.app} (${result.app_type}) from ${result.commit.slice(0, 8)}, its history kept: ${result.url}`);
+      console.log(dim("Its preview is being set up (`oalo logs` shows it). Next deploys: `oalo deploy`; live: `oalo deploy --env prod`."));
+    }
+  }
+
+  // Remember what the app now runs, so the next deploy sends only new commits.
+  git(["update-ref", `refs/remotes/oalo/${result.app || app}`, result.commit], root);
+  if (result.created) return flags.json ? void console.log(JSON.stringify(result, null, 2)) : undefined;
+  // The code is saved either way; a preview that doesn't run is still a failed
+  // deploy for whoever checks the exit code.
+  const previewFailed = env === "dev" && result.preview === "failed";
+  if (previewFailed) process.exitCode = 1;
+  if (flags.json) return void console.log(JSON.stringify(result, null, 2));
+  if (result.code_only) {
+    console.log(`saved ${result.commit.slice(0, 8)} to ${app}, but nothing runs yet: Oalo still can't tell what kind of app it is (see above).`);
+    return;
+  }
+  // A live deploy of the commit that's already live still builds and swaps it
+  // (a relaunch, e.g. for changed prod variables); a dev one restarts the preview.
+  const short = result.commit.slice(0, 8);
+  console.log(
+    result.relation !== "up_to_date"
+      ? `deployed ${sha} to ${app} (${env}): ${result.url}`
+      : env === "prod"
+        ? `relaunched ${app} at ${sha}, already its live commit (prod): ${result.url}`
+        : `no new commits; restarted ${app}'s preview at ${sha} (dev): ${result.url}`,
+  );
+  if (previewFailed) {
+    console.error(`the preview isn't running: ${result.preview_error || "it didn't start"}. Your code is saved; fix it and deploy again. \`oalo logs --app ${app}\` shows why.`);
+    return;
+  }
+  if (result.install === "failed") console.log(dim("The install failed, so the preview may be missing packages (see above)."));
+  if (env === "dev") console.log(dim(`When the preview looks right: oalo deploy --app ${app} --env prod`));
+}
+
+/**
+ * `--new --from <url>`: the Base clones the repository (https to a public
+ * host, one branch with its whole history) and makes the app exactly as
+ * `--new` does from a local repo. A private repo's access token comes from an
+ * environment variable (`--token-env VAR`) or, at a terminal, a hidden prompt
+ * when the host asks for one: never a flag value, which would stay in shell
+ * history. It is sent once, over HTTPS, for that clone only.
+ */
+async function fromGit(url, token, flags, opts = {}) {
+  const from = typeof flags.from === "string" ? flags.from.trim() : "";
+  if (flags.new === undefined) return fail("--from makes a new app: oalo deploy --new [<name>] --from <url>. To update an app, deploy from a clone of its repo.", 2);
+  if (!from) return fail("--from needs the repository's https address: oalo deploy --new --from https://github.com/you/repo", 2);
+  if (!/^https:\/\//i.test(from)) return fail("--from takes an https:// address, as the repository's Clone button shows it. ssh and git@ addresses can't be used.", 2);
+  if (flags.env !== undefined && flags.env !== "dev") return fail("a new app starts on its preview: run it without --env prod, then deploy it live.", 2);
+  const branch = typeof flags.branch === "string" ? flags.branch : undefined;
+  if (flags.branch !== undefined && !branch) return fail("--branch needs a branch name", 2);
+
+  let gitToken;
+  if (flags["token-env"] !== undefined) {
+    const name = typeof flags["token-env"] === "string" ? flags["token-env"] : "";
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) return fail("--token-env takes the name of the environment variable that holds the token, like --token-env GITHUB_TOKEN", 2);
+    gitToken = (opts.env || process.env)[name];
+    if (!gitToken) return fail(`${name} is empty or not set. Put the access token in it, then run this again.`, 2);
+  }
+
+  const app = slugify(typeof flags.new === "string" ? flags.new : repoName(from));
+  if (!app) return fail("give the new app a name: oalo deploy --new <name> --from <url>", 2);
+
+  try {
+    await requireFeature(url, "deploy_from_git", "oalo deploy --from");
+  } catch (e) {
+    return fail(e.message, 1);
+  }
+
+  const name = typeof flags.name === "string" ? flags.name : app;
+  console.error(dim(`creating ${app} from ${from}${branch ? ` (branch ${branch})` : ""} on ${url}: the Base clones it, then sets up its preview`));
+  let result = await importGit({ url, token, app, body: { url: from, name, ...(branch ? { branch } : {}), ...(gitToken ? { token: gitToken } : {}) } });
+
+  // A private repo and no token yet: ask for one, hidden, at a terminal.
+  const ask = opts.readToken || (process.stdin.isTTY ? () => readValue("access token") : null);
+  if (result?.error?.code === "needs_token" && !gitToken && ask) {
+    console.error(result.error.message);
+    try {
+      gitToken = (await ask()).trim();
+    } catch {
+      return fail("cancelled", 1);
+    }
+    if (gitToken) result = await importGit({ url, token, app, body: { url: from, name, ...(branch ? { branch } : {}), token: gitToken } });
+  }
+
+  if (!result) return fail("the connection closed before the import finished. `oalo apps` shows whether the app was made; the Base finishes an import it started.", 1);
+  if (result.error) {
+    console.error(`import failed: ${result.error.message}`);
+    if (result.error.code === "needs_token") console.error(dim("For a private repository, put a token that can read it in an environment variable and pass --token-env VAR."));
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flags.json) return void console.log(JSON.stringify(result, null, 2));
+  if (result.app_type === "code_only") {
+    console.log(`created ${result.app} from ${result.commit.slice(0, 8)}, its history kept. Nothing runs yet (see above).`);
+  } else {
+    console.log(`created ${result.app} (${result.app_type}) from ${result.commit.slice(0, 8)}, its history kept: ${result.url}`);
+    console.log(dim("Its preview is being set up (`oalo logs` shows it)."));
+  }
+  console.log(dim(`To work on it here: clone the repository, run \`oalo link --app ${result.app}\` in it, then \`oalo deploy\` (the app has the same commits, so it fast-forwards).`));
+}
+
+export const _fromGit = fromGit;
+
+/** The repository's name from its address: https://github.com/acme/shop.git -> shop. */
+export function repoName(address) {
+  try {
+    return new URL(address).pathname.replace(/\/+$/, "").split("/").pop().replace(/\.git$/, "");
+  } catch {
+    return "";
+  }
+}
+
+async function importGit({ url, token, app, body }) {
+  const res = await fetch(`${url}/api/cli/v1/apps/${encodeURIComponent(app)}/import`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok && !(res.headers.get("content-type") || "").includes("ndjson")) {
+    const reply = await res.json().catch(() => ({}));
+    return { error: { code: String(res.status), message: reply?.error?.message || `HTTP ${res.status}` } };
+  }
+  return await follow(res);
+}
+
+async function send({ url, token, app, env, sha, root, base, replace, create }) {
+  const dir = mkdtempSync(join(tmpdir(), "oalo-deploy-"));
+  const bundle = join(dir, "app.bundle");
+  try {
+    git(["bundle", "create", "--quiet", bundle, base ? `${base}..HEAD` : "HEAD"], root);
+    const size = statSync(bundle).size;
+    console.error(dim(`sending ${base ? "new commits" : "the full history"} (${(size / 1024).toFixed(0)} KB)`));
+
+    const q = new URLSearchParams({ env, sha, ...(replace ? { replace: "true" } : {}), ...(create ? { create: "true", name: create.name } : {}) });
+    const res = await fetch(`${url}/api/cli/v1/apps/${encodeURIComponent(app)}/deploy?${q}`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/octet-stream", "Content-Length": String(size) },
+      body: Readable.toWeb(createReadStream(bundle)),
+      duplex: "half",
+    });
+
+    if (!res.ok && !(res.headers.get("content-type") || "").includes("ndjson")) {
+      const body = await res.json().catch(() => ({}));
+      return { error: { code: String(res.status), message: body?.error?.message || `HTTP ${res.status}` } };
+    }
+    return await follow(res);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Print each progress line; return the last line (done or error). */
+async function follow(res) {
+  const decoder = new TextDecoder();
+  let buf = "";
+  let last = null;
+  for await (const part of res.body) {
+    buf += decoder.decode(part, { stream: true });
+    let i;
+    while ((i = buf.indexOf("\n")) >= 0) {
+      const raw = buf.slice(0, i).trim();
+      buf = buf.slice(i + 1);
+      if (!raw) continue;
+      let msg;
+      try {
+        msg = JSON.parse(raw);
+      } catch {
+        continue;
+      }
+      if (msg.done || msg.error) last = msg;
+      else if (msg.phase === "waiting") process.stderr.write(dim("."));
+      else if (msg.message) console.error(dim(`  ${msg.phase}: ${msg.message}`));
+    }
+  }
+  return last;
+}
+
+async function pull(url, token, app, root) {
+  const res = await fetch(`${url}/api/cli/v1/apps/${encodeURIComponent(app)}/bundle`, { headers: { Authorization: `Bearer ${token}` } });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    return fail(`could not fetch ${app}: ${body?.error?.message || `HTTP ${res.status}`}`, 1);
+  }
+  const dir = mkdtempSync(join(tmpdir(), "oalo-pull-"));
+  try {
+    const file = join(dir, "app.bundle");
+    writeFileSync(file, Buffer.from(await res.arrayBuffer()));
+    const ref = `refs/remotes/oalo/${app}`;
+    git(["fetch", "--quiet", "--no-tags", file, `+HEAD:${ref}`], root);
+    const sha = git(["rev-parse", ref], root);
+    console.log(`fetched ${app} as it is on Oalo (${sha.slice(0, 8)}) into oalo/${app}.`);
+    console.log(dim(`Merge it, then deploy again:\n  git merge oalo/${app}\n  oalo deploy --app ${app}`));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// The files at the repo's root (and in .oalo/) that decide how an app builds,
+// installs and starts.
+const RUN_FILES = new Set([
+  "Procfile", "Dockerfile", ".dockerignore", ".oalo/app.json",
+  "package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lock", "bun.lockb",
+  "requirements.txt", "pyproject.toml", "poetry.lock", "uv.lock", "Pipfile.lock",
+  "Gemfile", "Gemfile.lock", "go.mod", "go.sum", "Cargo.toml", "Cargo.lock", "composer.json", "composer.lock",
+  "mix.exs", "mix.lock", "pubspec.yaml", "pubspec.lock", "deno.json", "deno.jsonc",
+]);
+
+export function untrackedRunFiles(root) {
+  let out = "";
+  try {
+    out = git(["ls-files", "--others", "--exclude-standard"], root);
+  } catch {
+    return [];
+  }
+  return out.split("\n").filter((f) => RUN_FILES.has(f));
+}
+
+function git(args, cwd = process.cwd()) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function refExists(ref, cwd) {
+  try {
+    git(["rev-parse", "--verify", "--quiet", ref], cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isAncestor(a, b, cwd) {
+  try {
+    git(["merge-base", "--is-ancestor", a, b], cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function fail(message, code) {
+  console.error(message);
+  process.exitCode = code;
+}
+
+/**
+ * `--history` lists the live releases; `--rollback` launches the one before the
+ * current release (or `--to <sha>`). A rollback builds and checks that commit
+ * like any live deploy, so a failing one leaves the current release live. It
+ * doesn't touch the app's code on Oalo: the next deploy carries on from there.
+ */
+async function releases(url, token, app, flags, opts = {}) {
+  const { OaloChannel } = await import("../channel.js");
+  const ch = (opts.channel || ((o) => new OaloChannel(o)))({ url, token });
+  try {
+    await ch.connect();
+    if (flags.history) {
+      const r = await ch.call("release:history", { app });
+      if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+      if (!r.releases?.length) return void console.log(`${r.app} has never been live. \`oalo deploy --env prod\` launches it.`);
+      r.releases.forEach((x, i) => console.log(`${x.commit_hash.slice(0, 8)}  ${dim(`${String(x.launched_at || "").slice(0, 16).replace("T", " ")}${i === 0 ? ", live now" : ""}`)}`));
+      return;
+    }
+    console.error(dim(`rolling ${app} back${typeof flags.to === "string" ? ` to ${flags.to}` : " to the release before this one"}: building it, then swapping when it answers`));
+    // The Base pushes the build's progress while it runs (a newer Base does).
+    const off = ch.onEvent?.((event, p) => {
+      if (event === "rollback_progress" && p?.message) console.error(dim(`  ${p.phase}: ${p.message}`));
+    });
+    let r;
+    try {
+      r = await ch.call("release:rollback", { app, ...(typeof flags.to === "string" ? { to: flags.to } : {}) }, ROLLBACK_WAIT_MS);
+    } finally {
+      off?.();
+    }
+    if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+    console.log(`${r.app} is live at ${r.commit.slice(0, 8)}: ${r.url}`);
+  } catch (e) {
+    if (/timed out/.test(e.message)) {
+      return fail(`stopped waiting after ${ROLLBACK_WAIT_MS / 60_000} minutes, but the rollback may still be running on the Base. ` +
+        `\`oalo deploy --app ${app} --history\` shows which release is live; don't start another rollback until it changes or \`oalo logs --app ${app} --env prod\` shows it failed.`, 1);
+    }
+    fail(`rollback failed: ${e.message}`, 1);
+  } finally {
+    ch.close();
+  }
+}
+
+export const _releases = releases;
+
+// A rollback builds like a live deploy: CodeBuild allows 30 minutes, then the
+// new release has a minute to answer. Wait longer than that.
+export const ROLLBACK_WAIT_MS = 35 * 60_000;
+
+/** An app slug from a name: lowercase letters, digits and dashes. */
+export function slugify(name) {
+  return String(name || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+}

package/src/commands/dockerfile.js

@@ -0,0 +1,81 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+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 dockerfile`: how a server app's live image is built, and the
+ * Dockerfile it builds from.
+ *
+ *   oalo dockerfile [--app <slug>]                  print it
+ *   oalo dockerfile --write [--force] [--app <slug>]  save Oalo's at the repo's root
+ *
+ * A server app builds from the repo's own Dockerfile; with none, from Oalo's
+ * for its runtime (Bun, Elixir, Rust, Deno, Dart); otherwise with buildpacks (Node,
+ * Python, Ruby, Go, Java, PHP, .NET). `--write` puts Oalo's in the repo, to
+ * change: once committed, the repo's copy is used.
+ */
+export async function dockerfile(flags, rest, opts = {}) {
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) return fail(`oalo dockerfile 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);
+
+  if (!opts.channel) {
+    try {
+      await requireFeature(url, "dockerfile", "oalo dockerfile");
+    } catch (e) {
+      return fail(e.message, 1);
+    }
+  }
+
+  const ch = (opts.channel || ((o) => new OaloChannel(o)))({ url, token });
+  let r;
+  try {
+    await ch.connect();
+    r = await ch.call("cli_api:dockerfile", { app });
+  } catch (e) {
+    return fail(e.message, 1);
+  } finally {
+    ch.close();
+  }
+
+  if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+
+  if (r.method === "buildpacks") {
+    console.log(`${r.app} builds with buildpacks: no Dockerfile needed (Node, Python, Ruby, Go, Java, PHP or .NET, found from the repo).`);
+    console.log(dim("To build it your own way, commit a Dockerfile at the repo's root; it's used from the next deploy."));
+    return;
+  }
+
+  if (!flags.write) {
+    const from = r.source === "repo" ? "the repo's Dockerfile" : `Oalo's ${r.runtime} Dockerfile (the repo has none)`;
+    console.error(dim(`${r.app} builds from ${from}:\n`));
+    process.stdout.write(r.dockerfile);
+    if (r.source === "oalo") console.error(dim("\n`oalo dockerfile --write` saves it at the repo's root to change; once committed, the repo's copy is used."));
+    return;
+  }
+
+  if (r.source === "repo") return fail(`${r.app} already builds from its own Dockerfile.`, 1);
+  // At the repo's root, wherever in it this runs: that's where a build looks.
+  let root = ".";
+  try {
+    root = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    /* not a git repo: the current folder */
+  }
+  const path = opts.path || join(root, "Dockerfile");
+  if (existsSync(path) && !flags.force) return fail(`${path} exists. Pass --force to replace it.`, 1);
+  writeFileSync(path, r.dockerfile);
+  console.log(`wrote ${path} (Oalo's ${r.runtime} Dockerfile). Commit it, and the next deploy builds from it.`);
+}
+
+function fail(message, code) {
+  console.error(message);
+  process.exitCode = code;
+}

package/src/commands/docs.js

@@ -0,0 +1,70 @@
+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 docs`: the platform knowledge pages, from the workspace's own box, so
+ * they match what it runs.
+ *
+ *   oalo docs                       every page: slug and one-line summary
+ *   oalo docs <slug>                one page, as markdown on stdout
+ *   oalo docs --search "<words>"    pages ranked for the words, with a snippet
+ *   oalo docs --audience developer  only pages for developers (or trainer)
+ *
+ * Pages are written for people and agents alike. `oalo docs sync-rest-api >
+ * notes.md` saves one; `--json` gives the structured form.
+ */
+export async function docs(flags, rest) {
+  const slug = rest[1];
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) {
+    console.error(`oalo docs needs a CLI token.\n\n${HOW_TO_CONNECT}`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const ch = new OaloChannel({ url, token });
+  try {
+    await requireFeature(url, "docs", "oalo docs");
+    await ch.connect();
+
+    if (slug) {
+      let r;
+      try {
+        r = await ch.call("docs:get", { slug });
+      } catch (e) {
+        const sugg = e.reply?.suggestions || [];
+        console.error(`${e.message}${sugg.length ? `. Did you mean: ${sugg.join(", ")}?` : ""}\nList the pages with \`oalo docs\`, or search with \`oalo docs --search "<words>"\`.`);
+        process.exitCode = 1;
+        return;
+      }
+      if (flags.json) return void console.log(JSON.stringify(r.doc, null, 2));
+      process.stdout.write(r.doc.markdown.endsWith("\n") ? r.doc.markdown : r.doc.markdown + "\n");
+      if (r.doc.related?.length) console.error(dim(`related: ${r.doc.related.join(", ")}`));
+      return;
+    }
+
+    const q = typeof flags.search === "string" ? flags.search : null;
+    const params = q ? { q } : typeof flags.audience === "string" ? { audience: flags.audience } : {};
+    const { docs: list } = await ch.call("docs:list", params);
+    if (flags.json) return void console.log(JSON.stringify(list, null, 2));
+
+    if (!list.length) {
+      console.log(q ? `no page matches "${q}". Try other words, or \`oalo docs\` for the full list.` : "no pages on this workspace");
+      return;
+    }
+    const width = Math.min(32, Math.max(...list.map((d) => d.slug.length)));
+    for (const d of list) {
+      console.log(`${d.slug.padEnd(width)}  ${d.summary || d.title}`);
+      if (q && d.snippet && d.snippet !== d.summary) console.log(dim(`${" ".repeat(width)}  ${d.snippet}`));
+    }
+    console.error(dim(`\nRead one with: oalo docs <slug>`));
+  } catch (e) {
+    console.error(e.message);
+    process.exitCode = 1;
+  } finally {
+    ch.close();
+  }
+}