@rizom/ops 0.2.0-alpha.45 → 0.2.0-alpha.450

package/templates/rover-pilot/deploy/scripts/update-dns.ts

@@ -13,23 +13,81 @@ const baseUrl = "https://api.cloudflare.com/client/v4";
 
 interface CloudflareResult {
   success: boolean;
+}
+
+interface CloudflareRecordList extends CloudflareResult {
   result?: Array<{ id: string }>;
 }
 
-async function upsertRecord(name: string): Promise<void> {
-  const lookupUrl = `${baseUrl}/zones/${zoneId}/dns_records?type=A&name=${encodeURIComponent(name)}`;
+/**
+ * Copied verbatim into generated projects, so this stays dependency-free and
+ * checks the payload by hand. readJsonResponse returns unknown; asserting a
+ * response type onto it would let malformed error bodies pass silently.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readCloudflareSuccess(payload: unknown): boolean | undefined {
+  if (!isRecord(payload)) return undefined;
+  const success = payload["success"];
+  return typeof success === "boolean" ? success : undefined;
+}
+
+function readCloudflareRecordList(
+  payload: unknown,
+): CloudflareRecordList | undefined {
+  const success = readCloudflareSuccess(payload);
+  if (success === undefined) return undefined;
+  if (!success) return { success };
+  if (!isRecord(payload)) return undefined;
+  const result = payload["result"];
+  if (
+    !Array.isArray(result) ||
+    !result.every(
+      (entry): entry is { id: string } =>
+        isRecord(entry) && typeof entry["id"] === "string",
+    )
+  ) {
+    return undefined;
+  }
+  return { success, result };
+}
+
+function readCloudflareMutation(
+  payload: unknown,
+): CloudflareResult | undefined {
+  const success = readCloudflareSuccess(payload);
+  if (success === undefined) return undefined;
+  if (!success) return { success };
+  if (!isRecord(payload)) return undefined;
+  const result = payload["result"];
+  if (!isRecord(result) || typeof result["id"] !== "string") return undefined;
+  return { success };
+}
+
+async function findRecordId(
+  name: string,
+  type: "A" | "CNAME",
+): Promise<string | undefined> {
+  const lookupUrl = `${baseUrl}/zones/${zoneId}/dns_records?type=${type}&name=${encodeURIComponent(name)}`;
   const lookup = await fetch(lookupUrl, { headers });
-  const payload = (await readJsonResponse(
-    lookup,
-    "Cloudflare DNS lookup",
-  )) as CloudflareResult;
-  if (!lookup.ok || !payload.success) {
-    throw new Error(`Cloudflare DNS lookup failed: ${JSON.stringify(payload)}`);
+  const raw = await readJsonResponse(lookup, "Cloudflare DNS lookup");
+  const payload = readCloudflareRecordList(raw);
+  if (!lookup.ok || !payload?.success) {
+    throw new Error(`Cloudflare DNS lookup failed: ${JSON.stringify(raw)}`);
   }
 
-  const existing = payload.result?.[0];
+  return payload.result?.[0]?.id;
+}
+
+async function upsertRecord(name: string): Promise<void> {
+  // Prefer an existing A record. If the hostname currently has a CNAME,
+  // replace that CNAME in-place so deploys can claim legacy www aliases.
+  const existing =
+    (await findRecordId(name, "A")) ?? (await findRecordId(name, "CNAME"));
   const url = existing
-    ? `${baseUrl}/zones/${zoneId}/dns_records/${existing.id}`
+    ? `${baseUrl}/zones/${zoneId}/dns_records/${existing}`
     : `${baseUrl}/zones/${zoneId}/dns_records`;
 
   const response = await fetch(url, {
@@ -43,12 +101,10 @@ async function upsertRecord(name: string): Promise<void> {
       proxied: true,
     }),
   });
-  const result = (await readJsonResponse(
-    response,
-    "Cloudflare DNS upsert",
-  )) as CloudflareResult;
-  if (!response.ok || !result.success) {
-    throw new Error(`Cloudflare DNS upsert failed: ${JSON.stringify(result)}`);
+  const raw = await readJsonResponse(response, "Cloudflare DNS upsert");
+  const result = readCloudflareMutation(raw);
+  if (!response.ok || !result?.success) {
+    throw new Error(`Cloudflare DNS upsert failed: ${JSON.stringify(raw)}`);
   }
 }
 

package/templates/rover-pilot/deploy/scripts/validate-secrets.ts

@@ -4,7 +4,7 @@ import { parseEnvSchema } from "./helpers";
 const envSchemaPath = ".env.schema";
 const schema = parseEnvSchema(readFileSync(envSchemaPath, "utf8"));
 const requiredKeys = schema
-  .filter((entry) => entry.required)
+  .filter((entry) => entry.required && entry.key !== "BWS_ACCESS_TOKEN")
   .map((entry) => entry.key);
 
 const missing: string[] = [];
@@ -14,6 +14,17 @@ for (const key of requiredKeys) {
   }
 }
 
+const discordKeys = [
+  "DISCORD_BOT_TOKEN",
+  "DISCORD_PUBLIC_KEY",
+  "DISCORD_APPLICATION_ID",
+];
+if (discordKeys.some((key) => process.env[key])) {
+  for (const key of discordKeys) {
+    if (!process.env[key]) missing.push(key);
+  }
+}
+
 if (missing.length > 0) {
   throw new Error(`Missing required secrets: ${missing.join(", ")}`);
 }

package/templates/rover-pilot/deploy/scripts/verify-runtime-image.ts

@@ -0,0 +1,18 @@
+import { loadPilotRegistry } from "@rizom/ops";
+import {
+  requireEnv,
+  runtimeImageTag,
+  sitePackagesFor,
+  verifyRuntimeImage,
+} from "@rizom/ops/deploy";
+
+const handle = requireEnv("HANDLE");
+const registry = await loadPilotRegistry(process.cwd());
+const user = registry.users.find((entry) => entry.handle === handle);
+if (!user) throw new Error(`Unknown fleet handle: ${handle}`);
+
+await verifyRuntimeImage(`ghcr.io/${requireEnv("GITHUB_REPOSITORY")}`, {
+  tag: runtimeImageTag(user.brainVersion),
+  brainVersion: user.brainVersion,
+  sitePackages: sitePackagesFor(user.siteOverride),
+});

package/templates/rover-pilot/docs/canonical-crossover-record.md

@@ -0,0 +1,107 @@
+# Canonical Crossover Approval Record
+
+> Draft evidence record only. Completing this file does not authorize a merge, publish, reconcile, or deployment.
+
+Do not include secret values, private keys, access tokens, or decrypted user configuration.
+
+## Authorization and freeze
+
+- Operator:
+- Approval reference:
+- Approved window:
+- Freeze start:
+- Build workflow disabled and idle:
+- Reconcile workflow disabled and idle:
+- Deploy workflow disabled and idle:
+
+## Reviewed inputs
+
+- `brains` crossover commit:
+- Private-pilot source commit used for staging:
+- Canonical review commit:
+- Secret-free review diff SHA-256:
+- Identity-review evidence SHA-256:
+- Reviewed source-to-target bundle manifest SHA-256:
+- Reviewed hosted-site pin manifest SHA-256:
+- Source and review worktrees clean:
+
+## Hosted site and theme pins
+
+List every hosted site. External site and theme package versions must be exact and must
+match the staged user desired state; do not infer them from the brain or from each other.
+
+| Handle | Site package | Exact site version | Theme package | Exact theme version | Package/image evidence |
+| ------ | ------------ | ------------------ | ------------- | ------------------- | ---------------------- |
+|        |              |                    |               |                     |                        |
+
+## Forward artifact pins
+
+| Artifact               | Exact version | Registry integrity or digest | Verified installable |
+| ---------------------- | ------------- | ---------------------------- | -------------------- |
+| `@rizom/brain`         |               |                              |                      |
+| `@rizom/ops`           |               |                              |                      |
+| private-pilot lockfile | n/a           |                              |                      |
+
+Record every image. Tags alone are not immutable evidence.
+
+| Cohort/handle | Config commit | Image repository | Image tag | Image digest |
+| ------------- | ------------- | ---------------- | --------- | ------------ |
+|               |               |                  |           |              |
+
+## Rollback pair
+
+- Prior private-pilot commit:
+- Prior `@rizom/ops` version and registry integrity:
+
+| Cohort/handle | Prior config commit | Prior image repository | Prior image tag | Prior image digest |
+| ------------- | ------------------- | ---------------------- | --------------- | ------------------ |
+|               |                     |                        |                 |                    |
+
+## Identity review
+
+- Repository and image names unchanged or explicitly approved:
+- GitHub organization and content repository identities unchanged:
+- Server, domain, Cloudflare zone, and ATProto identities unchanged:
+- Secret selector names and encrypted secret artifacts unchanged:
+- Per-user runtime-version and site-package tag inputs reviewed:
+- No plaintext source secrets copied into the review artifact:
+- Every generated config declares `bundleContract: capability-bundles-v1`:
+- Pilot and explicit cohort source selections exactly matched the reviewed manifest:
+- No removed model, preset, or old-format schema discriminator remains:
+- Every external hosted site and theme package has an exact reviewed pin:
+
+## Offline convergence
+
+Command:
+
+```sh
+bunx brains-ops reconcile-all <canonical-review-copy> --dry-run
+```
+
+- First-pass reconciler-owned changed files:
+- Second-pass reconciler-owned changed files (must be zero):
+- Observational `views/users.md` unchanged by reconciliation:
+- Review copy unchanged:
+- External content-repository access blocked:
+
+## Pre-window validation
+
+- Package tests, typecheck, lint, build, and packed-consumer startup:
+- Architecture and dependency boundaries:
+- Environment-schema and workspace checks:
+- Crossover migration and comment preservation:
+- Canary-first order and health checks reviewed:
+- Paired rollback reviewed:
+
+## Execution record
+
+Complete only inside the explicitly approved maintenance window.
+
+- Unified packages published and verified:
+- Canonical desired state committed while automation remained frozen:
+- Image digest set matched this record:
+- First reconcile reviewed:
+- Per-instance health, MCP authorization, identity, content, and site checks:
+- Second reconcile produced zero reconciler-owned drift and no deploy work:
+- Freeze lifted:
+- One-week soak start:

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

@@ -4,14 +4,18 @@
 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`, `contentRepoAdminToken`, and `mcpAuthToken`
+   - confirm shared selectors for `aiApiKey`, `gitSyncToken`, and `contentRepoAdminToken`
    - use different tokens for `contentRepoAdminToken` and `gitSyncToken`: admin creates/checks content repos; sync is used by runtime directory-sync
    - confirm `agePublicKey`
 4. Run `bunx brains-ops user:add <repo> <handle> --cohort <cohort>`.
-   - Discord is enabled by default for pilot users.
-   - if the user should be an anchor there, add `--anchor-id <discord-user-id>`.
+   - Web chat is the primary interface; it needs no per-user setup beyond the passkey.
+   - `user:add` currently writes `discord: enabled: true`; set it to `false` unless the user's cohort actually uses Discord.
+   - if the user should be an anchor on Discord, add `--anchor-id <discord-user-id>`.
    - the command creates `users/<handle>.yaml`, `users/<handle>.secrets.yaml`, and the cohort membership without duplicating existing entries.
 5. Edit the generated user file if the anchor profile needs richer metadata.
+   - Set `setup.delivery: email` and `setup.email` so the user gets the passkey setup email — this is the default onboarding path.
+   - For ATProto publishing, add `atproto.identifier` to the user file; put only `atprotoAppPassword` in the per-user secrets file.
+   - Ensure `SETUP_EMAIL_API_KEY` and `SETUP_EMAIL_FROM` exist as GitHub Secrets before deploying any email-setup user.
 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`.
@@ -19,15 +23,20 @@
 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:
+13. Verify the deployed canonical contract:
+    - `https://<handle>.rizom.ai/health/operate` returns `200`
+    - `https://<handle>.rizom.ai/chat` loads the web chat and accepts passkey sign-in
+    - unauthenticated `POST https://<handle>.rizom.ai/mcp` returns the expected auth failure
+    - content repo exists and runtime sync is healthy
+    - background jobs are not repeatedly failing, except for expected missing optional integrations
+    - when `site` is selected, the browser/Studio surfaces load and the initial app-managed site build completes
+14. For fleet upgrades, edit `pilot.yaml.brainVersion` and push once; CI rebuilds the required default/site image tags, refreshes generated user env files, and redeploys affected users. Every external site and theme package keeps its own required exact version pin and never follows the brain version implicitly.
+15. Confirm the user received the setup email, registered their passkey, and can sign in to web chat at `https://<handle>.rizom.ai/chat`. That completes the default onboarding; everything below is per-cohort extras.
+16. Hand over the browser surfaces:
+    - Chat (primary): `https://<handle>.rizom.ai/chat`
     - 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.
+    - Studio: `https://<handle>.rizom.ai/studio`, plus GitHub token guidance if Studio editing is part of their cohort
+17. For Discord-enabled cohorts, hand the Discord setup details to the user as a secondary chat surface.
+18. If they need direct client access (MCP), use OAuth/passkey-capable clients where possible.
+19. 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.
+20. Send `docs/user-onboarding.md` to the user as the pilot handoff guide.