@crvouga/personal 0.0.0-stage → 0.1.0

package/probe.mjs

@@ -0,0 +1,479 @@
+// packages/fleet/src/errors.ts
+class FleetUsageError extends Error {
+}
+
+// packages/fleet/src/config.ts
+var CAPABILITIES = [
+  "github",
+  "vault",
+  "t3",
+  "vscode",
+  "toolchain"
+];
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function fields(value, allowed) {
+  if (Object.keys(value).some((key) => !allowed.includes(key))) {
+    throw new FleetUsageError("Unknown configuration field. Run fleet schema.");
+  }
+}
+function absolutePath(value) {
+  return typeof value === "string" && value.startsWith("/") && value.length <= 4096 && !/[\x00-\x1f\x7f]/.test(value);
+}
+function parseNode(value) {
+  if (!record(value))
+    throw new FleetUsageError("Each node must be an object.");
+  fields(value, ["id", "ssh", "workspace", "runtime", "required"]);
+  const names = nodeNames(value);
+  if (!absolutePath(value["workspace"]))
+    throw new FleetUsageError("workspace must be an absolute POSIX path.");
+  if (value["runtime"] !== undefined && !absolutePath(value["runtime"])) {
+    throw new FleetUsageError("runtime must be an absolute POSIX path to Node or Bun.");
+  }
+  return {
+    ...names,
+    workspace: value["workspace"],
+    ...typeof value["runtime"] === "string" ? { runtime: value["runtime"] } : {},
+    required: requiredCapabilities(value["required"])
+  };
+}
+function nodeNames(value) {
+  if (typeof value["id"] !== "string" || !/^[a-z][a-z0-9-]{0,62}$/.test(value["id"])) {
+    throw new FleetUsageError("Node IDs must be lowercase names (1–63 characters).");
+  }
+  if (typeof value["ssh"] !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$/.test(value["ssh"])) {
+    throw new FleetUsageError("ssh must be a plain SSH alias or hostname, not options or user@host.");
+  }
+  return { id: value["id"], ssh: value["ssh"] };
+}
+function requiredCapabilities(value) {
+  const required = value === undefined ? ["github", "vault", "t3", "toolchain"] : value;
+  if (!Array.isArray(required) || required.some((item) => !CAPABILITIES.includes(item))) {
+    throw new FleetUsageError("required must contain only capability names from fleet schema.");
+  }
+  if (new Set(required).size !== required.length)
+    throw new FleetUsageError("required capabilities must be unique.");
+  return required;
+}
+function parseConfig(value) {
+  if (!record(value))
+    throw new FleetUsageError("Fleet configuration must be an object.");
+  fields(value, ["$schema", "version", "nodes"]);
+  if (value["$schema"] !== undefined && typeof value["$schema"] !== "string")
+    throw new FleetUsageError("$schema must be a string.");
+  if (value["version"] !== 1 || !Array.isArray(value["nodes"])) {
+    throw new FleetUsageError("Expected version 1 and a nodes array.");
+  }
+  if (value["nodes"].length < 1 || value["nodes"].length > 64) {
+    throw new FleetUsageError("Configure between 1 and 64 developer nodes.");
+  }
+  const nodes = value["nodes"].map(parseNode);
+  if (new Set(nodes.map((node) => node.id)).size !== nodes.length) {
+    throw new FleetUsageError("Node IDs must be unique.");
+  }
+  return { version: 1, nodes };
+}
+
+// packages/fleet/src/fingerprint.ts
+import { readFile as readFile2, mkdir, writeFile } from "node:fs/promises";
+import { join as join2 } from "node:path";
+
+// packages/fleet/src/input-hashes.ts
+import { createHash } from "node:crypto";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+var INPUT_FILES = [
+  "package.json",
+  "bun.lock",
+  "mise.toml",
+  "mise.lock"
+];
+var FINGERPRINT_FILES = [
+  ...INPUT_FILES,
+  "workspace-manifests",
+  "mise-sidecars"
+];
+async function fileHash(path) {
+  try {
+    return digest(await readFile(path));
+  } catch {
+    return null;
+  }
+}
+async function manifestHash(root) {
+  try {
+    const entries = await readdir(join(root, "packages"), {
+      withFileTypes: true
+    });
+    const hashes = [];
+    for (const entry of entries.filter((item) => item.isDirectory()).sort((left, right) => left.name.localeCompare(right.name, "en"))) {
+      hashes.push(`${entry.name}:${await fileHash(join(root, "packages", entry.name, "package.json"))}`);
+    }
+    return digest(hashes.join(`
+`));
+  } catch {
+    return null;
+  }
+}
+async function sidecarHash(root) {
+  try {
+    const files = await readdir(join(root, ".mise/locks"), {
+      recursive: true,
+      withFileTypes: true
+    });
+    if (files.length > 4096 || files.some((entry) => entry.isSymbolicLink()))
+      return null;
+    const hashes = [];
+    const paths = files.filter((entry) => entry.isFile()).map((entry) => join(entry.parentPath, entry.name)).sort();
+    for (const path of paths) {
+      const hash = await fileHash(path);
+      if (hash === null)
+        return null;
+      const relative = path.slice(join(root, ".mise/locks").length).replaceAll("\\", "/");
+      hashes.push(`${relative}:${hash}`);
+    }
+    return digest(hashes.join(`
+`));
+  } catch {
+    return null;
+  }
+}
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+// packages/fleet/src/fingerprint.ts
+var RECEIPT = "node_modules/.fleet-sync.json";
+async function fingerprint(root, run) {
+  const files = {};
+  for (const name of INPUT_FILES)
+    files[name] = await fileHash(join2(root, name));
+  files["workspace-manifests"] = await manifestHash(root);
+  files["mise-sidecars"] = await sidecarHash(root);
+  const head = await run(["git", "rev-parse", "HEAD"], { cwd: root });
+  return {
+    head: head.ok && /^[a-f0-9]{40,64}\s*$/.test(head.stdout) ? head.stdout.trim() : null,
+    files
+  };
+}
+async function dependencyCheck(root, current) {
+  const remedy = {
+    action: "Review fleet sync, then explicitly apply a frozen toolchain/dependency sync."
+  };
+  try {
+    const receipt = JSON.parse(await readFile2(join2(root, RECEIPT), "utf8"));
+    const matches = record(receipt) && receipt["version"] === 1 && JSON.stringify(receipt["files"]) === JSON.stringify(current.files);
+    return {
+      id: "dependencies",
+      status: matches ? "pass" : "fail",
+      summary: matches ? "Last successful frozen sync matches input hashes; not a full integrity audit." : "Dependency sync receipt is stale or invalid.",
+      ...matches ? {} : { remedy }
+    };
+  } catch {
+    return {
+      id: "dependencies",
+      status: "warn",
+      summary: "No frozen-sync receipt; installed dependencies are unverified.",
+      remedy
+    };
+  }
+}
+async function writeReceipt(root, current) {
+  await mkdir(join2(root, "node_modules"), { recursive: true });
+  await writeFile(join2(root, RECEIPT), JSON.stringify({ version: 1, files: current.files }), { mode: 384 });
+}
+
+// packages/fleet/src/auth-checks.ts
+import { join as join3 } from "node:path";
+async function authCheck(capability, run, root) {
+  if (capability === "t3")
+    return t3Checks(run);
+  const spec = {
+    github: {
+      command: ["gh", "auth", "status", "--active"],
+      action: "Authenticate on this node with gh auth login, then gh auth setup-git."
+    },
+    vault: {
+      command: ["vault", "token", "lookup", "-format=json"],
+      action: "Authenticate to the configured Vault on this node. Do not copy a token from another computer."
+    },
+    vscode: {
+      command: ["code", "--list-extensions"],
+      action: "Install the VS Code CLI on PATH and ms-vscode-remote.remote-ssh in the local editor profile."
+    },
+    toolchain: {
+      command: ["bun", join3(root, "scripts/dev/doctor.ts"), "--json"],
+      action: "Run ws tools check --json; use the shared mise setup to reconcile tools."
+    }
+  }[capability];
+  const result = await run(spec.command, {
+    cwd: root,
+    timeoutMs: capability === "toolchain" ? 90000 : 15000
+  });
+  const extensions = result.stdout.toLowerCase().split(/\s+/);
+  const ok = result.ok && (capability !== "vscode" || extensions.includes("ms-vscode-remote.remote-ssh"));
+  return [
+    {
+      id: `auth:${capability}`,
+      status: ok ? "pass" : "fail",
+      summary: ok ? `${capability} check succeeded in this process context.` : `${capability} check failed (${result.reason}); no credential output retained.`,
+      ...ok ? {} : { remedy: { action: spec.action } }
+    }
+  ];
+}
+async function t3Checks(run) {
+  const config = await run(["t3", "status", "--json"]);
+  const checks = [t3Settings(config)];
+  const live = await run(["t3", "environment", "list", "--json"]);
+  checks.push({
+    id: "t3:api",
+    status: live.ok ? "pass" : "fail",
+    summary: live.ok ? "Local T3 API answered a read-only environment listing; peer connectivity is not inferred." : "Local T3 API did not answer the environment listing.",
+    ...!live.ok ? {
+      remedy: {
+        action: "Check t3 service status and t3 status. Inspect linked peers in T3 Settings → Connections; relink only with operator approval."
+      }
+    } : {}
+  });
+  checks.push({
+    id: "t3:end-to-end",
+    status: "skip",
+    summary: "Relay traversal and remote peer authorization require an operator connection test; local settings are not proof."
+  });
+  return checks;
+}
+function t3Settings(config) {
+  const fallback = {
+    id: "t3:settings",
+    status: "fail",
+    summary: "T3 settings unavailable or unsupported CLI response.",
+    remedy: {
+      action: "Run t3 status --json on this node. Complete t3 up --connect as its operator if needed."
+    }
+  };
+  try {
+    const data = JSON.parse(config.stdout);
+    if (config.ok && record(data) && record(data["connect"])) {
+      const enabled = data["connect"]["enabled"] === true && data["connect"]["revoked"] === false;
+      return {
+        id: "t3:settings",
+        status: enabled ? "pass" : "fail",
+        summary: enabled ? "T3 Connect enabled and not marked revoked (settings only)." : "T3 Connect disabled, revoked, or unknown.",
+        ...!enabled ? {
+          remedy: {
+            action: "Review t3 status, then complete t3 up --connect as the operator. Never share pairing tokens."
+          }
+        } : {}
+      };
+    }
+  } catch {}
+  return fallback;
+}
+
+// packages/fleet/src/probe.ts
+async function probe(root, required, run) {
+  const current = await fingerprint(root, run);
+  const checks = [
+    {
+      id: "workspace",
+      status: Object.values(current.files).every(Boolean) && current.head ? "pass" : "fail",
+      summary: "Checkout revision and shared dependency/toolchain input availability."
+    }
+  ];
+  const dirty = await run(["git", "status", "--porcelain"], { cwd: root });
+  checks.push({
+    id: "git:clean",
+    status: dirty.ok ? dirty.stdout.trim() ? "warn" : "pass" : "fail",
+    summary: dirty.ok && !dirty.stdout.trim() ? "Working tree is clean." : "Working tree is dirty or unreadable; sync --pull will refuse."
+  });
+  checks.push(await dependencyCheck(root, current));
+  for (const capability of [
+    "github",
+    "vault",
+    "t3",
+    "vscode",
+    "toolchain"
+  ]) {
+    if (required.includes(capability))
+      checks.push(...await authCheck(capability, run, root));
+    else
+      checks.push({
+        id: `auth:${capability}`,
+        status: "skip",
+        summary: "Not required by this node configuration."
+      });
+  }
+  return {
+    version: 1,
+    platform: process.platform,
+    fingerprint: current,
+    checks
+  };
+}
+
+// packages/fleet/src/runner.ts
+import { spawn } from "node:child_process";
+var MAX_OUTPUT_BYTES = 1024 * 1024;
+function terminate(child) {
+  try {
+    if (process.platform !== "win32" && child.pid)
+      process.kill(-child.pid, "SIGKILL");
+    else
+      child.kill("SIGKILL");
+  } catch {}
+}
+function runCommand(command, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command[0], command.slice(1), {
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        ...options.env,
+        GIT_TERMINAL_PROMPT: "0",
+        CI: "1"
+      },
+      stdio: "pipe",
+      windowsHide: true,
+      detached: process.platform !== "win32"
+    });
+    let stdout = "";
+    let stderr = "";
+    let bytes = 0;
+    let finished = false;
+    let reason = "exit";
+    const finish = (ok) => {
+      if (finished)
+        return;
+      finished = true;
+      clearTimeout(timer);
+      child.stdin.destroy();
+      child.stdout.destroy();
+      child.stderr.destroy();
+      resolve({ ok, stdout, stderr, reason });
+    };
+    const abort = (cause) => {
+      reason = cause;
+      terminate(child);
+      finish(false);
+    };
+    const timer = setTimeout(() => {
+      abort("timeout");
+    }, options.timeoutMs ?? 15000);
+    const capture = (stream, chunk) => {
+      if (finished)
+        return;
+      bytes += Buffer.byteLength(chunk);
+      if (bytes > MAX_OUTPUT_BYTES) {
+        abort("overflow");
+        return;
+      }
+      if (stream === "stdout")
+        stdout += chunk;
+      else
+        stderr += chunk;
+    };
+    child.stdout.setEncoding("utf8").on("data", (chunk) => capture("stdout", chunk));
+    child.stderr.setEncoding("utf8").on("data", (chunk) => capture("stderr", chunk));
+    child.stdin.on("error", () => {
+      return;
+    });
+    child.on("error", () => {
+      abort("missing");
+    });
+    child.on("close", (code) => {
+      finish(code === 0 && reason === "exit");
+    });
+    child.stdin.end(options.input);
+  });
+}
+
+// packages/fleet/src/sync.ts
+import { unlink } from "node:fs/promises";
+import { join as join4 } from "node:path";
+async function syncWorkspace(root, pull, run) {
+  const before = await fingerprint(root, run);
+  if (!completeFingerprint(before)) {
+    return failed("Not a complete workspace checkout. Follow fleet onboard first.");
+  }
+  if (pull) {
+    const dirty = await run(["git", "status", "--porcelain"], { cwd: root });
+    const branch = await run(["git", "symbolic-ref", "--quiet", "HEAD"], {
+      cwd: root
+    });
+    if (!dirty.ok || dirty.stdout.trim() || !branch.ok)
+      return failed("Refusing pull: dirty, detached, or unreadable checkout. Reconcile manually.");
+  }
+  await unlink(join4(root, "node_modules/.fleet-sync.json")).catch(() => {
+    return;
+  });
+  if (pull) {
+    const result = await run(["git", "pull", "--ff-only"], {
+      cwd: root,
+      timeoutMs: 120000
+    });
+    if (!result.ok)
+      return failed("Fast-forward pull failed. Inspect upstream/network/auth manually; nothing was reset.");
+  }
+  const expected = await fingerprint(root, run);
+  const result = await run([
+    "mise",
+    "exec",
+    "--locked",
+    "bun",
+    "--",
+    "bun",
+    "scripts/dev/setup.ts",
+    "--non-interactive"
+  ], { cwd: root, timeoutMs: 1200000 });
+  if (!result.ok)
+    return failed(`Shared toolchain/dependency sync failed (${result.reason}). Inspect setup locally; partial installs are possible.`);
+  const after = await fingerprint(root, run);
+  if (JSON.stringify(expected) !== JSON.stringify(after))
+    return failed("Checkout inputs changed during sync. Retry from a stable checkout.");
+  await writeReceipt(root, after);
+  return [
+    {
+      id: "sync",
+      status: "pass",
+      summary: "Shared setup succeeded; frozen-sync receipt recorded. Auth and live connectivity still need doctor checks."
+    }
+  ];
+}
+function failed(summary) {
+  return [
+    {
+      id: "sync",
+      status: "fail",
+      summary,
+      remedy: {
+        action: "Resolve locally using scripts/dev/README.md, then review and retry fleet sync."
+      }
+    }
+  ];
+}
+function completeFingerprint(value) {
+  return value.head !== null && Object.values(value.files).every(Boolean);
+}
+
+// packages/fleet/src/remote-entry.ts
+async function main() {
+  const raw = JSON.parse(Buffer.from(process.argv.at(-1) ?? "", "base64").toString());
+  if (!record(raw) || raw["action"] !== "probe" && raw["action"] !== "sync")
+    throw new Error("Invalid request.");
+  const node = parseConfig({ version: 1, nodes: [raw["node"]] }).nodes[0];
+  if (raw["action"] === "sync") {
+    if (raw["apply"] !== true)
+      throw new Error("Sync requires explicit authorization.");
+    const checks = await syncWorkspace(node.workspace, raw["pull"] === true, runCommand);
+    process.stdout.write(JSON.stringify({ version: 1, checks }));
+  } else
+    process.stdout.write(JSON.stringify(await probe(node.workspace, node.required, runCommand)));
+}
+await main().catch(() => {
+  process.stdout.write(JSON.stringify({
+    version: 1,
+    error: "Remote operation failed; inspect node locally."
+  }));
+  process.exitCode = 1;
+});

package/releasing.md

@@ -0,0 +1,159 @@
+# Automated npm releases
+
+The source workspace stays private. Only the allowlisted contents of
+`packages/personal-cli/dist` are packed as **`@crvouga/personal`**.
+
+## One-time bootstrap
+
+Node, npm and Bun must be on PATH through the shared mise setup. npm 11.15+ is
+needed for the bootstrap's `npm trust` command. Start with a read-only plan:
+
+```sh
+bash scripts/dev/bootstrap.sh
+exec "$SHELL" -l
+```
+
+The machine bootstrap needs no Bun or npm, installs the shared locked mise
+toolchain and frozen workspace dependencies, and configures persistent shell
+PATH. On native Windows use `& ./scripts/dev/bootstrap.ps1`, then reopen your
+terminal. See [machine setup](../../scripts/dev/README.md) for new/remote nodes.
+After refreshing your terminal, run:
+
+```sh
+bun run personal:release:plan
+bun run personal:publish:bootstrap --apply --yes --npm-login
+```
+
+Release progress on stderr identifies each stage (`npm-version`, `build`,
+`pack`, `consumer-install`, consumer commands and publisher verification).
+Failures name the stage without exposing raw subprocess output or credentials.
+The npm runner supports mise shims, shell launchers and native executables;
+Windows `.cmd` launchers use npm's adjacent JavaScript entry point through Node.
+To validate the complete build/pack/anonymous-consumer path without logging in,
+publishing or changing trusted publishers, run:
+
+```sh
+bun run personal:build
+bun run --cwd packages/personal-cli smoke
+```
+
+The bootstrap builds and installs/tests the exact tarball in an anonymous isolated
+consumer, prints npm's account authorization URL, publishes the package if necessary,
+and configures/verifies its GitHub trusted publisher. Approve npm login and any
+npm account/2FA approval in your own terminal/browser. No npm password, recovery
+code or long-lived publishing token needs to be supplied to this project.
+The trusted publisher is **`crvouga/personal` / `ci.yml`**, with direct publishing
+permission. npm validates the calling workflow for reusable workflows, so this
+must be `ci.yml`, not the reusable `release-personal-cli.yml` filename.
+
+Bootstrap is retryable: if content is already published, it only checks/configures
+the publisher. Existing publishers are preserved; no connection is revoked or
+replaced. npm account authorization uses an isolated temporary 0600 npmrc, which
+is removed with its logs/cache when the command exits. Initial publication also
+inherits your terminal so npm can request its publishing-specific 2FA approval.
+Global npm login/config is
+not changed. A hard process kill can leave a temporary directory; remove any
+abandoned `personal-npm-auth-*` directory in your OS temporary directory.
+
+### Remote Mac / SSH browser approval
+
+Run the bootstrap **on the Mac Mini** in an interactive remote terminal. If you
+connect with SSH, use `ssh -t YOUR_ALIAS` to allocate a terminal. No browser is
+needed on the Mini, and no port forwarding or copying npm credentials is needed.
+
+1. Run `bun run personal:publish:bootstrap --apply --yes --npm-login` on the Mini.
+2. When npm prints its HTTPS login URL, copy/open that **new URL on your MacBook
+   Air**, sign in to npm and complete the account/2FA approval there.
+3. **Leave the Mini's terminal running**. It waits for npm's approval and resumes
+   automatically; no Enter-to-open-browser prompt is used. Ctrl+C cancels login.
+4. Publishing may print another approval URL or ask for a one-time code. Open
+   that URL on the Air too, or enter the requested code in the Mini's terminal.
+
+Browser launch is disabled for the entire isolated npm session, including
+publish-time web 2FA and trusted-publisher setup. npm update notices/progress are
+disabled too; keep npm versions owned by the shared mise lock, not a global
+`npm install -g`. After cancellation or expiry, rerun the command and use its new
+URL, not an earlier session's URL. Treat approval links as private; never paste
+them into reports or shared logs. The browser approval is not proof of publication;
+wait for registry-integrity and trusted-publisher verification to finish.
+
+## Vault username/password login
+
+If a suitable npm publishing token already exists in Vault, use:
+
+```sh
+bun run personal:publish:bootstrap --apply --yes --login
+```
+
+This prompts for **Vault username and password**, not a Vault token. The default
+username is `crvouga`; set `PERSONAL_VAULT_USERNAME` to change it. Login creates a
+temporary in-memory userpass session, reads the requested credential and revokes
+the session immediately afterward. Nothing is written to `~/.vault-token`.
+`PERSONAL_VAULT_PASSWORD_FILE` supports a private secret-delivery file for agents;
+the caller owns deleting that file immediately after use. Never pass passwords as
+command arguments. Noninteractive calls never prompt.
+
+Defaults: Vault `https://vault.chrisvouga.dev`, document
+`secret/data/personal/prd`, field `NPM_TOKEN`. Select an **existing** field/document
+using `PERSONAL_NPM_TOKEN_KEY` / `PERSONAL_NPM_VAULT_PATH`. The token must permit
+creating/publishing `@crvouga/personal` and satisfy npm's unattended-publish/2FA
+policy. Recovery codes are not publishing credentials. Missing fields fail
+clearly; no code guesses another secret, seeds values or changes Vault policy.
+Vault auth, policy and secret changes remain exclusively OpenTofu-owned.
+
+Existing npm `NODE_AUTH_TOKEN` / `NPM_TOKEN` are also supported for automation.
+Local Vault access always uses username/password, never a user-supplied Vault
+token or a saved `~/.vault-token`. `--login` explicitly chooses username/password
+even when an npm credential is already injected. A publishing
+token is passed only in the npm child environment; its temporary npmrc contains
+an environment-variable reference, not the token itself.
+
+## CI: automatic publishing after checks
+
+The main **CI** workflow validates the CLI on Linux/macOS/Windows and Node
+22/24/26, including installing the packed distribution into a clean directory
+with anonymous registry configuration and running it on real Node. The required
+**Check** includes this job. After Check/Fleet pass on main, the reusable
+`release-personal-cli.yml` workflow:
+
+1. Reads the public registry and hashes the release inputs.
+2. Skips publication when the published content hash already matches.
+3. Uses `0.1.0` initially, then automatically increments the current stable patch
+   version. A higher source manifest version deliberately selects a minor/major.
+4. Builds, allowlist-checks, packs and consumer-tests the exact tarball.
+5. Publishes using npm's **GitHub OIDC trusted publishing**, without npm secrets.
+6. Confirms the content hash, SHA-512 integrity and latest tag, with bounded
+   read-only retries for registry propagation. Unconfirmed outcomes fail rather
+   than blindly republish.
+
+Publishing is serialized with non-cancelling concurrency. Dispatch **CI** on main
+to retry. PRs, merge queues, failed checks and non-main dispatches never publish.
+Public-source CI includes npm provenance. Local bootstrap records its revision
+and dirty-checkout status and does not claim CI provenance. Registry versions
+are the checkpoint; no version-bump commits, tags or GitHub write access is needed.
+Atlas and Mockingbird informed the bootstrap/trusted-publisher and exact-consumer
+validation design; their accounts/publishers are never modified.
+
+For an explicitly selected existing Vault-backed npm token instead of OIDC, set
+the **repository variable** `PERSONAL_NPM_TOKEN_KEY` to its field name, never its
+value. CI then uses existing GitHub → Vault OIDC (`jwt` / `github-actions`) to read
+that one field from `secret/data/personal/prd`. No duplicate GitHub secret is
+created. Leave the variable unset for default tokenless npm publishing.
+
+## Recovery and verification
+
+If publication is unconfirmed, rerun the **plan** first. Never guess a new version
+or blindly repeat a publish. Bootstrap can resume publisher setup after a package
+was published successfully. npm account access is a prerequisite for first
+publication; Vault login alone cannot grant npm publishing access.
+
+Verify the released consumer independently:
+
+```sh
+npx --yes @crvouga/personal@latest commands --json
+npx --yes @crvouga/personal@latest fleet doctor --all --json
+```
+
+Do not claim release or green CI based on local checks. Deployment of the CI
+workflow requires these source changes to land on main, and remote fleet coverage
+requires actual locally configured SSH aliases and checkout paths.

package/schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Developer fleet roster (not infrastructure inventory)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "nodes"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "nodes": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "ssh", "workspace"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,62}$" },
+          "ssh": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,252}$"
+          },
+          "workspace": {
+            "type": "string",
+            "maxLength": 4096,
+            "pattern": "^/[^\\u0000-\\u001f\\u007f]*$"
+          },
+          "runtime": {
+            "type": "string",
+            "maxLength": 4096,
+            "pattern": "^/[^\\u0000-\\u001f\\u007f]*$"
+          },
+          "required": {
+            "type": "array",
+            "uniqueItems": true,
+            "default": ["github", "vault", "t3", "toolchain"],
+            "items": {
+              "enum": ["github", "vault", "t3", "vscode", "toolchain"]
+            }
+          }
+        }
+      }
+    }
+  }
+}