@rizom/ops 0.2.0-alpha.397 → 0.2.0-alpha.398

package/dist/run-command.d.ts

@@ -4,6 +4,7 @@ import type { LoadPilotRegistryOptions } from "./load-registry";
 import { type LookupHost } from "./observed-status";
 import { type RunCommand as OpsRunCommand } from "./run-subprocess";
 import { type SshKeygen } from "./ssh-key-bootstrap";
+import type { PilotOffboardDriver } from "./user-offboard";
 import type { UserRunner } from "./user-runner";
 import type { cleanupDirectorySyncStress, runDeployedDirectorySyncStress, verifyDirectorySyncStressAccess } from "./directory-sync-stress-system";
 import type { cleanupHealthWatchdogSmoke, runHealthWatchdogSmoke } from "./health-watchdog-smoke";
@@ -29,6 +30,7 @@ export interface CommandDependencies extends LoadPilotRegistryOptions {
     healthWatchdogSmokeRunner?: typeof runHealthWatchdogSmoke | undefined;
     healthWatchdogSmokeCleanupRunner?: typeof cleanupHealthWatchdogSmoke | undefined;
     legacyProjectionJobRecoveryRunner?: typeof retireLegacyProjectionJob | undefined;
+    pilotOffboardDriver?: PilotOffboardDriver | undefined;
 }
 export declare const globalFlags: FlagDefinitions;
 export declare const commands: readonly CommandDefinition<CommandDependencies, CommandResult>[];

package/dist/user-offboard.d.ts

@@ -0,0 +1,61 @@
+import type { FetchLike } from "@brains/utils/fetch-like";
+export interface OffboardPilotUsersOptions {
+    handles: string[];
+    confirmation?: string | undefined;
+    dryRun?: boolean | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    fetchImpl?: FetchLike | undefined;
+    logger?: ((message: string) => void) | undefined;
+    sleep?: ((delayMs: number) => Promise<void>) | undefined;
+    driver?: PilotOffboardDriver | undefined;
+}
+export interface PilotOffboardTarget {
+    handle: string;
+    instanceName: string;
+    domain: string;
+    previewDomain: string;
+    wwwDomain?: string | undefined;
+    contentRepo: string;
+    cloudflareZoneId: string;
+}
+export interface PilotOffboardServer {
+    id: number;
+    name: string;
+    ip?: string | undefined;
+}
+export interface PilotOffboardDnsRecord {
+    id: string;
+    name: string;
+    type: "A" | "CNAME";
+    content: string;
+}
+export interface PilotOffboardInspection {
+    server?: PilotOffboardServer | undefined;
+    dnsRecords: PilotOffboardDnsRecord[];
+    contentRepoArchived: boolean;
+}
+export interface PilotOffboardDriver {
+    inspect(target: PilotOffboardTarget): Promise<PilotOffboardInspection>;
+    archiveContentRepo(target: PilotOffboardTarget): Promise<void>;
+    deleteDnsRecord(target: PilotOffboardTarget, record: PilotOffboardDnsRecord): Promise<void>;
+    deleteServer(target: PilotOffboardTarget, server: PilotOffboardServer): Promise<void>;
+}
+export interface OffboardPilotUserPlan {
+    target: PilotOffboardTarget;
+    inspection: PilotOffboardInspection;
+}
+export interface OffboardPilotUsersResult {
+    dryRun: boolean;
+    handles: string[];
+    confirmation: string;
+    plans: OffboardPilotUserPlan[];
+}
+export declare function offboardPilotUsers(rootDir: string, options: OffboardPilotUsersOptions): Promise<OffboardPilotUsersResult>;
+interface DefaultDriverOptions {
+    env: NodeJS.ProcessEnv;
+    fetchImpl?: FetchLike | undefined;
+    contentRepoTokenName: string;
+}
+export declare function createPilotOffboardDriver(options: DefaultDriverOptions): PilotOffboardDriver;
+export declare function assertPilotUsersRemoved(rootDir: string, handles: string[]): Promise<void>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rizom/ops",
-  "version": "0.2.0-alpha.397",
+  "version": "0.2.0-alpha.398",
   "description": "Operator CLI for managing private brain fleet registry repos",
   "keywords": [
     "brains",

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

@@ -0,0 +1,107 @@
+name: Offboard
+
+on:
+  workflow_dispatch:
+    inputs:
+      handles:
+        description: Comma-separated pilot handles
+        required: true
+        type: string
+      confirm:
+        description: Exact confirmation (sunset:<sorted-comma-separated-handles>)
+        required: true
+        type: string
+      apply:
+        description: Archive content repos and destroy DNS, servers, and desired state
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+
+concurrency:
+  group: offboard-pilot-users
+  cancel-in-progress: false
+
+jobs:
+  offboard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install operator tooling
+        run: bun install
+
+      - name: Load provider credentials
+        uses: ./.github/actions/varlock-env
+        env:
+          BWS_ACCESS_TOKEN: ${{ secrets.BWS_ACCESS_TOKEN }}
+
+      - name: Resolve handles
+        id: handles
+        env:
+          OFFBOARD_HANDLES: ${{ inputs.handles }}
+        run: |
+          node <<'NODE'
+          const handles = [...new Set(process.env.OFFBOARD_HANDLES
+            .split(',')
+            .map((handle) => handle.trim())
+            .filter(Boolean))]
+            .sort((left, right) => left.localeCompare(right));
+          if (handles.length === 0 || handles.some((handle) => !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(handle))) {
+            throw new Error('Invalid offboarding handle list');
+          }
+          const output = process.env.GITHUB_OUTPUT;
+          require('node:fs').appendFileSync(output, `json=${JSON.stringify(handles)}\n`);
+          NODE
+
+      - name: Preview offboarding plan
+        env:
+          OFFBOARD_HANDLES_JSON: ${{ steps.handles.outputs.json }}
+        run: |
+          mapfile -t handles < <(node -e 'for (const handle of JSON.parse(process.env.OFFBOARD_HANDLES_JSON)) console.log(handle)')
+          bunx brains-ops user:offboard "$GITHUB_WORKSPACE" "${handles[@]}"
+
+      - name: Apply offboarding plan
+        if: inputs.apply
+        env:
+          OFFBOARD_CONFIRM: ${{ inputs.confirm }}
+          OFFBOARD_HANDLES_JSON: ${{ steps.handles.outputs.json }}
+        run: |
+          mapfile -t handles < <(node -e 'for (const handle of JSON.parse(process.env.OFFBOARD_HANDLES_JSON)) console.log(handle)')
+          bunx brains-ops user:offboard "$GITHUB_WORKSPACE" "${handles[@]}" \
+            --apply --confirm "$OFFBOARD_CONFIRM"
+
+      - name: Validate changed paths
+        if: inputs.apply
+        run: |
+          unexpected="$(git status --short | awk '{print $2}' | grep -Ev '^(cohorts/|users/|views/users\.md$)' || true)"
+          if [ -n "$unexpected" ]; then
+            echo "Offboarding changed unexpected paths:" >&2
+            echo "$unexpected" >&2
+            exit 1
+          fi
+
+      - name: Commit desired-state removal
+        if: inputs.apply
+        env:
+          OFFBOARD_HANDLES: ${{ inputs.handles }}
+        run: |
+          git add --all -- cohorts users views/users.md
+          if git diff --cached --quiet; then
+            echo "No desired-state changes remain to commit."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "chore(ops): sunset pilot brains" \
+            -m "Retired handles: $OFFBOARD_HANDLES"
+          git pull --rebase origin main
+          git push origin HEAD:main

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

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import { requireEnv, writeGitHubOutput } from "./helpers";
 
 const eventName = requireEnv("GITHUB_EVENT_NAME");
@@ -47,6 +48,9 @@ const handles = [
         return match?.[1] ?? null;
       })
       .filter((handle): handle is string => handle !== null)
+      // Deleted generated files belong to retired users and must not be sent
+      // through the onboarding/deploy path after an offboarding commit.
+      .filter((handle) => existsSync(`users/${handle}.yaml`))
       .sort((left, right) => left.localeCompare(right)),
   ),
 ];

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

@@ -11,6 +11,7 @@ Treat these as checked-in deploy artifacts in the pilot repo:
 - `.github/workflows/deploy.yml`
 - `.github/workflows/directory-sync-stress.yml`
 - `.github/workflows/health-watchdog-smoke.yml`
+- `.github/workflows/offboard.yml`
 - `.github/workflows/reconcile.yml`
 
 `.env.schema` is the single source of truth for required and sensitive deploy vars.
@@ -180,6 +181,38 @@ The shared cert bootstrap writes local cert artifacts under `.brains-ops/certs/s
 
 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.
 
+## Pilot user offboarding
+
+Use the manual **Offboard** workflow for explicit pilot retirement. It is the only
+supported path that removes both checked-in desired state and provider resources.
+Normal reconcile/deploy changes never imply destruction.
+
+1. Enter a comma-separated handle list. The command sorts and deduplicates it.
+2. Run with `apply: false` and review the exact servers, DNS records, and content
+   repositories in the plan.
+3. Enter the canonical confirmation printed by the dry run, for example
+   `sunset:alice,bob`.
+4. Rerun with `apply: true`.
+5. Verify the workflow's bot commit removes user YAML, encrypted secrets, generated
+   user directories, cohort membership, and rows from `views/users.md`.
+
+The apply path archives each private content repository, deletes the user's main and
+preview DNS records, destroys the dedicated Hetzner server, and removes desired state.
+Custom-domain users also lose their managed `www` record. The operation is idempotent,
+but it deliberately creates **no runtime backup**; obtain separate owner approval and
+backup state before apply when retention is required.
+
+The equivalent operator-local commands are:
+
+```sh
+bunx brains-ops user:offboard . alice bob
+bunx brains-ops user:offboard . alice bob \
+  --apply --confirm sunset:alice,bob
+```
+
+The deploy handle resolver ignores deleted users, so the generated-file deletions in
+the offboarding commit cannot route those handles back through onboarding/deploy.
+
 ## Upgrading operator behavior
 
 The pilot repository pins `@rizom/ops` in `package.json`. The scheduled and manually dispatched Upgrade workflow owns routine upgrades to that pin. It refreshes the scaffold on a branch and opens a reviewable PR; it does not change runtime desired state or authorize a deployment.