@rizom/ops 0.2.0-alpha.3 → 0.2.0-alpha.30

package/templates/rover-pilot/README.md

@@ -36,8 +36,11 @@ When a push changes only deploy contract files, CI prints `No affected user conf
 ## Commands
 
 - `brains-ops init <repo>`
-- `brains-ops render <repo>`
+- `brains-ops render <repo>` — regenerates `views/users.md` with live DNS, `/health`, and unauthenticated `/mcp` status checks
 - `brains-ops onboard <repo> <handle>`
-- `brains-ops secrets:push <repo> <handle>`
+- `brains-ops age-key:bootstrap <repo>`
+- `brains-ops ssh-key:bootstrap <repo>`
+- `brains-ops cert:bootstrap <repo>`
+- `brains-ops secrets:encrypt <repo> <handle>`
 - `brains-ops reconcile-cohort <repo> <cohort>`
 - `brains-ops reconcile-all <repo>`

package/templates/rover-pilot/deploy/Dockerfile

@@ -1,15 +1,30 @@
 ARG BUN_VERSION=1.3.10
-FROM oven/bun:${BUN_VERSION}-slim
+FROM oven/bun:${BUN_VERSION}-slim AS runtime
 
-ARG BRAIN_VERSION
 WORKDIR /app
 
-RUN test -n "$BRAIN_VERSION" \
- && printf '{"name":"rover-pilot-runtime","private":true}\n' > package.json \
- && bun add @rizom/brain@$BRAIN_VERSION
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl ca-certificates git \
+    && rm -rf /var/lib/apt/lists/*
 
 ENV XDG_DATA_HOME=/data
 ENV XDG_CONFIG_HOME=/config
-RUN mkdir -p /app/brain-data /data /config && chmod -R 777 /app/brain-data /data /config
+RUN mkdir -p /app/data /app/cache /app/brain-data && \
+    chmod -R 777 /app/data /app/cache /app/brain-data
+
+EXPOSE 8080
+
+CMD ["./node_modules/.bin/brain", "start"]
 
-CMD ["sh", "-c", "exec ./node_modules/.bin/brain start"]
+# --- standalone: bake full project into image (brain-cli deploy) ---
+FROM runtime AS standalone
+COPY package.json ./package.json
+RUN bun install --production --ignore-scripts
+COPY . .
+
+# --- fleet: install published brain at pinned version (ops deploy) ---
+FROM runtime AS fleet
+ARG BRAIN_VERSION
+RUN test -n "$BRAIN_VERSION" \
+ && printf '{"name":"rover-pilot-runtime","private":true}\n' > package.json \
+ && bun add @rizom/brain@$BRAIN_VERSION

package/templates/rover-pilot/deploy/kamal/deploy.yml

@@ -2,7 +2,7 @@ service: rover
 image: <%= ENV['IMAGE_REPOSITORY'] %>
 
 servers:
-  mcp:
+  web:
     hosts:
       - <%= ENV['SERVER_IP'] %>
 
@@ -12,7 +12,8 @@ proxy:
     private_key_pem: PRIVATE_KEY_PEM
   hosts:
     - <%= ENV['BRAIN_DOMAIN'] %>
-  app_port: 3333
+    - <%= ENV['PREVIEW_DOMAIN'] %>
+  app_port: 8080
   healthcheck:
     path: /health
 

package/templates/rover-pilot/deploy/scripts/decrypt-user-secrets.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from "node:fs";
+
+import { Decrypter, armor } from "age-encryption";
+
+import { requireEnv, writeGitHubEnv, writeGitHubOutput } from "./helpers";
+
+const handle = process.argv[2] ?? requireEnv("HANDLE");
+const ageSecretKey = extractAgeIdentity(requireEnv("AGE_SECRET_KEY"));
+const encryptedPath = `users/${handle}.secrets.yaml.age`;
+
+const armored = readFileSync(encryptedPath, "utf8");
+const decoded = armor.decode(armored);
+
+const decrypter = new Decrypter();
+decrypter.addIdentity(ageSecretKey);
+
+const plaintext = await decrypter.decrypt(decoded, "text");
+const secrets = parseFlatYaml(plaintext);
+const pilot = parseFlatYaml(readFileSync("pilot.yaml", "utf8"));
+
+writeGitHubEnv("AI_API_KEY", secrets["aiApiKey"] ?? "");
+writeGitHubEnv("GIT_SYNC_TOKEN", secrets["gitSyncToken"] ?? "");
+writeGitHubEnv("MCP_AUTH_TOKEN", secrets["mcpAuthToken"] ?? "");
+writeGitHubEnv("DISCORD_BOT_TOKEN", secrets["discordBotToken"] ?? "");
+
+writeGitHubOutput(
+  "shared_ai_api_key_secret_name",
+  requireFlatValue(pilot, "aiApiKey", "pilot.yaml"),
+);
+writeGitHubOutput(
+  "shared_git_sync_token_secret_name",
+  requireFlatValue(pilot, "gitSyncToken", "pilot.yaml"),
+);
+writeGitHubOutput(
+  "shared_mcp_auth_token_secret_name",
+  requireFlatValue(pilot, "mcpAuthToken", "pilot.yaml"),
+);
+
+function extractAgeIdentity(contents: string): string {
+  const line = contents
+    .split(/\r?\n/)
+    .map((entry) => entry.trim())
+    .find((entry) => entry.startsWith("AGE-SECRET-KEY-"));
+
+  if (!line) {
+    throw new Error("Missing AGE-SECRET-KEY in AGE_SECRET_KEY");
+  }
+
+  return line;
+}
+
+function parseFlatYaml(contents: string): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const match = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+    if (!match) {
+      continue;
+    }
+
+    const [, key, rawValue] = match;
+    result[key] = rawValue.replace(/^['"]|['"]$/g, "");
+  }
+
+  return result;
+}
+
+function requireFlatValue(
+  values: Record<string, string>,
+  key: string,
+  label: string,
+): string {
+  const value = values[key];
+  if (!value) {
+    throw new Error(`Missing ${key} in ${label}`);
+  }
+  return value;
+}

package/templates/rover-pilot/deploy/scripts/provision-server.ts

@@ -101,7 +101,7 @@ while (server.status !== "running" || !server.public_net?.ipv4?.ip) {
   server = await getServer(server.id);
 }
 
-const serverIp = server.public_net?.ipv4?.ip;
+const serverIp = server.public_net.ipv4.ip;
 if (!serverIp) {
   throw new Error(`Server ${server.id} running but has no IPv4 address`);
 }

package/templates/rover-pilot/deploy/scripts/resolve-deploy-handles.ts

@@ -32,7 +32,9 @@ const handles = [
     diffOutput
       .split(/\r?\n/)
       .map((path) => {
-        const match = path.match(/^users\/([^/]+)\/(?:\.env|brain\.yaml)$/);
+        const match =
+          path.match(/^users\/([^/]+)\/(?:\.env|brain\.yaml|content\/.*)$/) ??
+          path.match(/^users\/([^/]+)\.secrets\.yaml\.age$/);
         return match?.[1] ?? null;
       })
       .filter((handle): handle is string => handle !== null)

package/templates/rover-pilot/deploy/scripts/resolve-user-config.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+
 import { parseEnvFile, requireEnv, writeGitHubOutput } from "./helpers";
 
 const handle = requireEnv("HANDLE");
@@ -12,32 +13,31 @@ const repositoryOwner = repository.split("/")[0] ?? "";
 const brainYaml = readFileSync(brainYamlPath, "utf8");
 const domainMatch = brainYaml.match(/^domain:\s*(.+)$/m);
 const brainDomain = domainMatch?.[1]?.trim().replace(/^['"]|['"]$/g, "") ?? "";
-
 if (!brainDomain) {
   throw new Error(`Missing domain in ${brainYamlPath}`);
 }
 
+const zone =
+  brainDomain.startsWith(`${handle}.`) && brainDomain.length > handle.length + 1
+    ? brainDomain.slice(handle.length + 1)
+    : "";
+if (!zone) {
+  throw new Error(`Could not derive preview domain from ${brainDomain}`);
+}
+const previewDomain = `${handle}-preview.${zone}`;
+
 const outputs: Record<string, string> = {
   brain_version: envEntries["BRAIN_VERSION"] ?? "",
-  ai_api_key_secret_name: envEntries["AI_API_KEY_SECRET"] ?? "",
-  git_sync_token_secret_name: envEntries["GIT_SYNC_TOKEN_SECRET"] ?? "",
-  mcp_auth_token_secret_name: envEntries["MCP_AUTH_TOKEN_SECRET"] ?? "",
-  discord_bot_token_secret_name: envEntries["DISCORD_BOT_TOKEN_SECRET"] ?? "",
   content_repo: envEntries["CONTENT_REPO"] ?? "",
   brain_domain: brainDomain,
+  preview_domain: previewDomain,
   brain_yaml_path: brainYamlPath,
   instance_name: `rover-${handle}`,
   image_repository: `ghcr.io/${repository}`,
   registry_username: repositoryOwner,
 };
 
-const required = [
-  "brain_version",
-  "ai_api_key_secret_name",
-  "git_sync_token_secret_name",
-  "mcp_auth_token_secret_name",
-  "registry_username",
-];
+const required = ["brain_version", "registry_username"];
 for (const key of required) {
   if (!outputs[key]) {
     throw new Error(`Missing ${key} (derived from ${envPath})`);

package/templates/rover-pilot/deploy/scripts/sync-content-repo.ts

@@ -0,0 +1,179 @@
+import { cp, mkdtemp, mkdir, readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { readJsonResponse, requireEnv } from "./helpers";
+
+const handle = requireEnv("HANDLE");
+const contentRepo = requireEnv("CONTENT_REPO");
+const token = requireEnv("GIT_SYNC_TOKEN");
+const sourceDir = join("users", handle, "content");
+
+if (!existsSync(sourceDir)) {
+  process.exit(0);
+}
+
+const { owner, repo } = parseRepoSlug(contentRepo);
+await ensureGitHubRepo({ owner, repo, token });
+
+const tempRoot = await mkdtemp(join(tmpdir(), "brains-ops-content-"));
+const checkoutDir = join(tempRoot, "repo");
+const remoteUrl = buildAuthenticatedRemoteUrl(owner, repo, token);
+
+runGit(["clone", remoteUrl, checkoutDir]);
+runGit(["-C", checkoutDir, "checkout", "-B", "main"]);
+
+const copiedFiles = await copyMissingFiles(sourceDir, checkoutDir);
+if (copiedFiles === 0) {
+  process.exit(0);
+}
+
+runGit(["-C", checkoutDir, "config", "user.name", "brains-ops[bot]"]);
+runGit([
+  "-C",
+  checkoutDir,
+  "config",
+  "user.email",
+  "41898282+github-actions[bot]@users.noreply.github.com",
+]);
+runGit(["-C", checkoutDir, "add", "."]);
+
+if (hasNoStagedChanges(checkoutDir)) {
+  process.exit(0);
+}
+
+runGit([
+  "-C",
+  checkoutDir,
+  "commit",
+  "-m",
+  `chore(content): seed ${handle} anchor profile`,
+]);
+runGit(["-C", checkoutDir, "push", "origin", "HEAD:main"]);
+
+const STALE_ANCHOR_PROFILE_MARKERS = [
+  "name: Your Name Here",
+  "Delete this and write your own",
+];
+
+interface EnsureGitHubRepoOptions {
+  owner: string;
+  repo: string;
+  token: string;
+}
+
+interface GitHubRepoResponse {
+  clone_url?: string;
+  private?: boolean;
+}
+
+async function ensureGitHubRepo(
+  options: EnsureGitHubRepoOptions,
+): Promise<void> {
+  const headers = {
+    Authorization: `Bearer ${options.token}`,
+    Accept: "application/vnd.github+json",
+    "Content-Type": "application/json",
+  };
+  const repoUrl = `https://api.github.com/repos/${options.owner}/${options.repo}`;
+  const repoResponse = await fetch(repoUrl, { headers });
+
+  if (repoResponse.ok) {
+    await readJsonResponse(repoResponse, "GitHub repo lookup");
+    return;
+  }
+
+  if (repoResponse.status !== 404) {
+    const payload = await readJsonResponse(repoResponse, "GitHub repo lookup");
+    throw new Error(`GitHub repo lookup failed: ${JSON.stringify(payload)}`);
+  }
+
+  const createResponse = await fetch(
+    `https://api.github.com/orgs/${options.owner}/repos`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        name: options.repo,
+        private: true,
+        auto_init: false,
+      }),
+    },
+  );
+  const payload = (await readJsonResponse(
+    createResponse,
+    "GitHub repo create",
+  )) as GitHubRepoResponse;
+
+  if (!createResponse.ok) {
+    throw new Error(`GitHub repo create failed: ${JSON.stringify(payload)}`);
+  }
+}
+
+function parseRepoSlug(contentRepo: string): { owner: string; repo: string } {
+  const [owner, repo] = contentRepo.split("/");
+  if (!owner || !repo) {
+    throw new Error(`Invalid CONTENT_REPO: ${contentRepo}`);
+  }
+  return { owner, repo };
+}
+
+function buildAuthenticatedRemoteUrl(
+  owner: string,
+  repo: string,
+  token: string,
+): string {
+  return `https://x-access-token:${encodeURIComponent(token)}@github.com/${owner}/${repo}.git`;
+}
+
+function runGit(args: string[]): void {
+  execFileSync("git", args, { stdio: "inherit" });
+}
+
+function hasNoStagedChanges(checkoutDir: string): boolean {
+  try {
+    execFileSync("git", ["-C", checkoutDir, "diff", "--cached", "--quiet"], {
+      stdio: "ignore",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyMissingFiles(
+  sourceDir: string,
+  targetDir: string,
+): Promise<number> {
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+  let copiedFiles = 0;
+
+  for (const entry of entries) {
+    const sourcePath = join(sourceDir, entry.name);
+    const targetPath = join(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await mkdir(targetPath, { recursive: true });
+      copiedFiles += await copyMissingFiles(sourcePath, targetPath);
+      continue;
+    }
+
+    const existing = await readFile(targetPath, "utf8").catch(() => undefined);
+    if (existing !== undefined && !isStaleAnchorProfile(existing)) {
+      continue;
+    }
+
+    await mkdir(dirname(targetPath), { recursive: true });
+    await cp(sourcePath, targetPath, { force: true });
+    copiedFiles += existing === (await readFile(sourcePath, "utf8")) ? 0 : 1;
+  }
+
+  return copiedFiles;
+}
+
+function isStaleAnchorProfile(content: string): boolean {
+  return STALE_ANCHOR_PROFILE_MARKERS.some((marker) =>
+    content.includes(marker),
+  );
+}

package/templates/rover-pilot/docs/onboarding-checklist.md

@@ -1,11 +1,31 @@
 # Onboarding Checklist
 
 1. Run `bun install` so the repo uses its pinned `@rizom/ops` version.
-2. Fill in `pilot.yaml`.
-3. Add or edit `users/<handle>.yaml`.
-4. Add the user to a cohort in `cohorts/*.yaml`.
-5. Run `bunx brains-ops render <repo>`.
-6. Run `bunx brains-ops secrets:push <repo> <handle>`.
-7. Run `bunx brains-ops onboard <repo> <handle>`.
-8. For fleet upgrades, edit `pilot.yaml.brainVersion` and push once; CI rebuilds the shared image tag, refreshes generated user env files, and redeploys affected users.
-9. Hand the MCP connection details to the user.
+2. Run `bunx brains-ops age-key:bootstrap <repo> --push-to gh`.
+3. Fill in `pilot.yaml`.
+   - keep your pinned `brainVersion`
+   - confirm shared selectors for `aiApiKey`, `gitSyncToken`, and `mcpAuthToken`
+   - confirm `agePublicKey`
+4. Add or edit `users/<handle>.yaml`.
+   - Discord is enabled by default for pilot users
+   - if the user should be an anchor there, set `discord.anchorUserId` to their Discord user ID
+5. Add the user to a cohort in `cohorts/*.yaml`.
+6. Run `bunx brains-ops render <repo>`.
+7. Run `bunx brains-ops ssh-key:bootstrap <repo> --push-to gh`.
+8. Run `bunx brains-ops cert:bootstrap <repo> --push-to gh`.
+9. Keep raw user secret material locally for now (`.env.local`, file-backed env vars, or equivalent local inputs).
+10. Run `bunx brains-ops secrets:encrypt <repo> <handle>`.
+11. Commit and push `users/<handle>.secrets.yaml.age`.
+12. Run `bunx brains-ops onboard <repo> <handle>`.
+13. Verify the deployed rover core contract:
+    - `https://<handle>.rizom.ai/health` returns `200`
+    - unauthenticated `POST https://<handle>.rizom.ai/mcp` returns `401`
+14. For fleet upgrades, edit `pilot.yaml.brainVersion` and push once; CI rebuilds the shared image tag, refreshes generated user env files, and redeploys affected users.
+15. Hand the Discord setup details to the user.
+16. Hand over the browser defaults:
+    - Dashboard: `https://<handle>.rizom.ai/`
+    - CMS: `https://<handle>.rizom.ai/cms`
+    - GitHub token guidance for CMS access to the user's private content repo
+17. If they need direct client access, also hand over the MCP connection details.
+18. If you are also giving them a content repo workflow, describe it as optional and frame git/Obsidian as an advanced file-based path, not the default.
+19. Send `docs/user-onboarding.md` to the user as the pilot handoff guide.

package/templates/rover-pilot/docs/operator-playbook.md

@@ -33,6 +33,24 @@ When a push changes only deploy contract files and no generated `users/<handle>/
 
 They are scaffolded from `@rizom/ops`, then versioned in this repo like any other deploy contract.
 
+## Bootstrap flow
+
+For this fleet, operator-local secret material remains the source of truth during onboarding and rotation. The repo stores encrypted per-user secrets, not raw values.
+
+For a new pilot user, the operator bootstrap order is:
+
+1. `bunx brains-ops age-key:bootstrap <repo> --push-to gh`
+2. `bunx brains-ops ssh-key:bootstrap <repo> --push-to gh`
+3. `bunx brains-ops cert:bootstrap <repo> --push-to gh`
+4. `bunx brains-ops secrets:encrypt <repo> <handle>`
+5. `bunx brains-ops onboard <repo> <handle>`
+
+`age-key:bootstrap` keeps a repo-local canonical age identity under `.brains-ops/age/identity.txt`, writes the matching public recipient to `pilot.yaml.agePublicKey`, and can push the private key to GitHub as `AGE_SECRET_KEY`.
+
+The shared cert bootstrap writes local cert artifacts under `.brains-ops/certs/shared/`, which stays repo-local and ignored by git.
+
+Preview hosts use the shape `<handle>-preview.rizom.ai`, so one wildcard origin cert for `*.rizom.ai` covers both the primary and preview hosts for every pilot user.
+
 ## Upgrading operator behavior
 
 When `@rizom/ops` changes the scaffolded deploy contract:
@@ -42,6 +60,47 @@ When `@rizom/ops` changes the scaffolded deploy contract:
 3. review the resulting changes to `.env.schema`, `deploy/scripts/`, and workflows in git
 4. commit the updated deploy artifacts together
 
+## Rover-core verification notes
+
+Rover core is MCP-only. Do not expect the bare domain to serve a website.
+
+Use these checks after deploy:
+
+- `https://<handle>.rizom.ai/health` should return `200`
+- unauthenticated `POST https://<handle>.rizom.ai/mcp` should return `401 Unauthorized: Bearer token required`
+- a bare `GET /` may also return `401`; that is expected for rover core and does not indicate a bad deploy
+
+## Discord bot token checklist
+
+Use this when enabling Discord for a pilot user.
+
+1. Pick the user handle (for example `smoke`).
+2. Open the Discord Developer Portal.
+3. Create a **new application** for that user's rover.
+4. Add a **Bot** to the application.
+5. Copy the bot token.
+6. Put that value in `.env` or `.env.local` in this repo as `DISCORD_BOT_TOKEN=...` while onboarding that user.
+7. Keep `discord.enabled: true` in `users/<handle>.yaml` unless you explicitly want to disable the primary pilot interface.
+8. Encrypt the current per-user secret payload:
+   - `bunx brains-ops secrets:encrypt . <handle>`
+9. Reconcile/deploy the user or cohort:
+
+- `bunx brains-ops onboard . <handle>`
+- or `bunx brains-ops reconcile-cohort . <cohort>`
+
+11. In the Discord Developer Portal, generate an install URL and invite the bot to the right server.
+12. Send a test message in Discord and confirm the rover responds.
+
+Notes:
+
+- Use **one bot token per user/rover**.
+- Do not reuse the same Discord bot token across multiple pilot users.
+- Discord is the default pilot interface moving forward.
+- The encrypted `users/<handle>.secrets.yaml.age` file is the durable checked-in deploy input; your local env is only the operator staging source.
+- MCP is optional and mainly for direct client access or specific testing workflows.
+- When explaining the content workflow, describe it first as a normal **git repo** of **markdown/text files**.
+- Position **Obsidian** as optional: it is just one possible editor for those same files, not the default requirement.
+
 ## Recovery notes
 
 Document known failure modes, recovery steps, and operator notes here.