@rizom/ops 0.2.0-alpha.0

package/templates/rover-pilot/.github/workflows/reconcile.yml

@@ -0,0 +1,45 @@
+name: Reconcile
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main"]
+    paths:
+      - pilot.yaml
+      - cohorts/**
+      - users/*.yaml
+      - .github/workflows/reconcile.yml
+
+permissions:
+  contents: write
+
+concurrency:
+  group: reconcile
+  cancel-in-progress: true
+
+jobs:
+  reconcile:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.sha }}
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install operator tooling
+        run: bun install
+
+      - name: Reconcile generated pilot outputs
+        run: bunx brains-ops reconcile-all "$GITHUB_WORKSPACE"
+
+      - name: Commit generated outputs
+        run: |
+          if git diff --quiet -- views users; then
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add views users
+          git commit -m "chore(ops): reconcile pilot outputs"
+          git push

package/templates/rover-pilot/.kamal/hooks/pre-deploy

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BRAIN_FILE="${BRAIN_YAML_PATH:-brain.yaml}"
+SSH_USER="$(ruby -e 'require "yaml"; config = YAML.load_file("deploy/kamal/deploy.yml") || {}; puts(config.dig("ssh", "user") || "root")')"
+IFS=',' read -ra HOSTS <<< "$KAMAL_HOSTS"
+for host in "${HOSTS[@]}"; do
+  scp -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null "$BRAIN_FILE" "${SSH_USER}@${host}:/opt/brain.yaml"
+done

package/templates/rover-pilot/README.md

@@ -0,0 +1,42 @@
+# rover-pilot
+
+Private desired-state repo for the rover pilot.
+
+This is a single operator-owned repo. Pilot users do not get their own brain repos.
+Per-user deploy config lives under `users/<handle>/`, while content stays in per-user content repos.
+
+## Operator tooling
+
+This repo pins `@rizom/ops` in `package.json`.
+
+Install it with:
+
+```sh
+bun install
+```
+
+Then run commands with:
+
+```sh
+bunx brains-ops <command>
+```
+
+The repo also checks in its deploy contract:
+
+- `.env.schema`
+- `deploy/kamal/deploy.yml`
+- `deploy/scripts/`
+- `.github/workflows/*`
+
+`.env.schema` is the single source of truth for required and sensitive deploy vars.
+The shared pilot image tag is `brain-${brainVersion}` end to end.
+When `pilot.yaml.brainVersion` changes and you push, CI rebuilds the shared tag, refreshes generated user env files, and redeploys affected users.
+When a push changes only deploy contract files, CI prints `No affected user configs; skipping deploy.` and stops before Kamal.
+
+## Commands
+
+- `brains-ops init <repo>`
+- `brains-ops render <repo>`
+- `brains-ops onboard <repo> <handle>`
+- `brains-ops reconcile-cohort <repo> <cohort>`
+- `brains-ops reconcile-all <repo>`

package/templates/rover-pilot/cohorts/cohort-1.yaml

@@ -0,0 +1,2 @@
+members:
+  - alice

package/templates/rover-pilot/deploy/Dockerfile

@@ -0,0 +1,15 @@
+ARG BUN_VERSION=1.3.10
+FROM oven/bun:${BUN_VERSION}-slim
+
+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
+
+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
+
+CMD ["sh", "-c", "exec ./node_modules/.bin/brain start"]

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

@@ -0,0 +1,39 @@
+service: rover
+image: <%= ENV['IMAGE_REPOSITORY'] %>
+
+servers:
+  mcp:
+    hosts:
+      - <%= ENV['SERVER_IP'] %>
+
+proxy:
+  ssl:
+    certificate_pem: CERTIFICATE_PEM
+    private_key_pem: PRIVATE_KEY_PEM
+  hosts:
+    - <%= ENV['BRAIN_DOMAIN'] %>
+  app_port: 3333
+  healthcheck:
+    path: /health
+
+registry:
+  server: ghcr.io
+  username: <%= ENV['REGISTRY_USERNAME'] %>
+  password:
+    - KAMAL_REGISTRY_PASSWORD
+
+builder:
+  arch: amd64
+
+env:
+  clear:
+    NODE_ENV: production
+  secret:
+    - AI_API_KEY
+    - GIT_SYNC_TOKEN
+    - MCP_AUTH_TOKEN
+    - DISCORD_BOT_TOKEN
+
+volumes:
+  - /opt/brain-data:/app/brain-data
+  - /opt/brain.yaml:/app/brain.yaml

package/templates/rover-pilot/deploy/scripts/helpers.ts

@@ -0,0 +1,10 @@
+export {
+  readJsonResponse,
+  parseEnvFile,
+  parseEnvSchema,
+  parseEnvSchemaFile,
+  requireEnv,
+  writeGitHubOutput,
+  writeGitHubEnv,
+} from "@rizom/ops/deploy";
+export type { EnvSchemaEntry } from "@rizom/ops/deploy";

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

@@ -0,0 +1,59 @@
+import { execFileSync } from "node:child_process";
+import { requireEnv, writeGitHubOutput } from "./helpers";
+
+const eventName = requireEnv("GITHUB_EVENT_NAME");
+
+if (eventName === "workflow_dispatch") {
+  const handle = requireEnv("HANDLE_INPUT");
+  writeGitHubOutput("handles_json", JSON.stringify([handle]));
+  process.exit(0);
+}
+
+if (eventName !== "push") {
+  throw new Error(`Unsupported GITHUB_EVENT_NAME: ${eventName}`);
+}
+
+const beforeSha = requireEnv("BEFORE_SHA");
+const currentSha = requireEnv("GITHUB_SHA");
+
+if (!isUsableGitRevision(beforeSha) || !isUsableGitRevision(currentSha)) {
+  writeGitHubOutput("handles_json", JSON.stringify([]));
+  process.exit(0);
+}
+
+const diffOutput = execFileSync(
+  "git",
+  ["diff", "--name-only", beforeSha, currentSha],
+  { encoding: "utf8" },
+);
+
+const handles = [
+  ...new Set(
+    diffOutput
+      .split(/\r?\n/)
+      .map((path) => {
+        const match = path.match(/^users\/([^/]+)\/(?:\.env|brain\.yaml)$/);
+        return match?.[1] ?? null;
+      })
+      .filter((handle): handle is string => handle !== null)
+      .sort((left, right) => left.localeCompare(right)),
+  ),
+];
+
+writeGitHubOutput("handles_json", JSON.stringify(handles));
+
+function isUsableGitRevision(revision: string): boolean {
+  if (!revision || /^0+$/.test(revision)) {
+    return false;
+  }
+
+  try {
+    execFileSync("git", ["rev-parse", "--verify", revision], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,49 @@
+import { readFileSync } from "node:fs";
+import { parseEnvFile, requireEnv, writeGitHubOutput } from "./helpers";
+
+const handle = requireEnv("HANDLE");
+const envPath = `users/${handle}/.env`;
+const brainYamlPath = `users/${handle}/brain.yaml`;
+
+const envEntries = parseEnvFile(envPath);
+const repository = process.env["GITHUB_REPOSITORY"] ?? "";
+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 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,
+  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",
+];
+for (const key of required) {
+  if (!outputs[key]) {
+    throw new Error(`Missing ${key} (derived from ${envPath})`);
+  }
+}
+
+for (const [key, value] of Object.entries(outputs)) {
+  writeGitHubOutput(key, value);
+}

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

@@ -0,0 +1,10 @@
+# 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 onboard <repo> <handle>`.
+7. 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.
+8. Hand the MCP connection details to the user.

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

@@ -0,0 +1,47 @@
+# Operator Playbook
+
+## Deploy contract files
+
+Treat these as checked-in deploy artifacts in the pilot repo:
+
+- `.env.schema`
+- `deploy/kamal/deploy.yml`
+- `deploy/scripts/`
+- `.github/workflows/build.yml`
+- `.github/workflows/deploy.yml`
+- `.github/workflows/reconcile.yml`
+
+`.env.schema` is the single source of truth for required and sensitive deploy vars.
+The deploy scripts and workflows should read from that contract instead of inventing a second list.
+
+The shared pilot image tag is `brain-${brainVersion}`:
+
+- build publishes `brain-${brainVersion}`
+- generated `users/<handle>/.env` carries `BRAIN_VERSION=<brainVersion>`
+- deploy sets `VERSION=brain-${brainVersion}`
+
+## Version bump flow
+
+When `pilot.yaml.brainVersion` changes and you push:
+
+1. build publishes the new shared image tag
+2. reconcile refreshes generated `users/<handle>/.env`
+3. deploy runs for handles whose generated config changed
+4. generated file commits happen once in a final aggregation step after the deploy matrix finishes
+
+When a push changes only deploy contract files and no generated `users/<handle>/.env` or `users/<handle>/brain.yaml` files, the deploy workflow exits through its explicit no-op path and prints `No affected user configs; skipping deploy.`
+
+They are scaffolded from `@rizom/ops`, then versioned in this repo like any other deploy contract.
+
+## Upgrading operator behavior
+
+When `@rizom/ops` changes the scaffolded deploy contract:
+
+1. bump `@rizom/ops` in `package.json`
+2. rerun the relevant scaffold/reconcile flow
+3. review the resulting changes to `.env.schema`, `deploy/scripts/`, and workflows in git
+4. commit the updated deploy artifacts together
+
+## Recovery notes
+
+Document known failure modes, recovery steps, and operator notes here.

package/templates/rover-pilot/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "rover-pilot",
+  "private": true,
+  "type": "module",
+  "packageManager": "bun@__BUN_VERSION__",
+  "devDependencies": {
+    "@rizom/ops": "__BRAINS_OPS_VERSION__"
+  }
+}

package/templates/rover-pilot/pilot.yaml

@@ -0,0 +1,8 @@
+schemaVersion: 1
+brainVersion: 0.1.1-alpha.14
+model: rover
+githubOrg: <github-org>
+contentRepoPrefix: rover-
+domainSuffix: .rizom.ai
+preset: core
+aiApiKey: AI_API_KEY

package/templates/rover-pilot/users/alice.yaml

@@ -0,0 +1,3 @@
+handle: alice
+discord:
+  enabled: false