@blocofy/cli 0.9.0 → 0.11.0

package/lib/args.mjs

@@ -7,8 +7,9 @@
 /**
  * Sonraki token'ı değer olarak almayan flag'ler. 0.8.0: `api-key` de boolean'dır — `login --api-key`
  * gizli prompt açar; `--api-key <değer>` sözdizimi bilerek YOKTUR (sır argv'ye ve shell geçmişine girmez).
+ * CF-T1: `--keychain` (login) ve `--adopt` (link) de değersizdir. CF-T3: `--force` (pages push) da; gerekçesi `--reason <text>`.
  */
-const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version", "api-key", "json", "strict", "write"]);
+const BOOLEAN_FLAGS = new Set(["draft", "live", "yes", "confirm", "no-sync", "dry", "dry-run", "validate", "diff", "help", "version", "api-key", "json", "strict", "write", "keychain", "adopt", "force"]);
 
 /**
  * `known`: bu komutun kabul ettiği bayrak adları (Set). Verildiğinde bilinmeyen bir `--x`

package/lib/content-sync.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
@@ -13,6 +14,7 @@ import {
   serializeV2PageFile,
   stagedWrite,
 } from "./page-files.mjs";
+import { fetchWithRetry } from "./http.mjs";
 import { checkRelativePagePath, parsePageFilePath } from "./page-path-codec.mjs";
 
 /**
@@ -20,6 +22,10 @@ import { checkRelativePagePath, parsePageFilePath } from "./page-path-codec.mjs"
  * locale-aware layout (`pages/<locale>/index.json`, `pages/<locale>/routes/…/index.json`); the platform's
  * `/api/dev/content` protocol v2 is required for every page operation. Tema KODU `theme pull/push`'a gider.
  * Güvenlik platformda: push yalnız mevcut sayfayı günceller, yeni oluşturmaz, silmez.
+ *
+ * CF-T3: every request goes through `fetchWithRetry` (lib/http.mjs). Reads are safe to resend; a settings push is an
+ * upsert; a pages push carries one `x-idempotency-key` per push operation, resent unchanged on every retry, and the
+ * server treats a re-sent, already-applied page as `unchanged`.
  */
 
 export const PAGES_PROTOCOL_VERSION = 2;
@@ -53,9 +59,9 @@ export function readContentFiles(dir, scope) {
  * The server's page capabilities, or `PAGES_SERVER_UPGRADE_REQUIRED`. An old server answers `scope=capabilities`
  * as a full export without `protocol_version`; nothing is written either way.
  */
-export async function probePagesServer({ url, token }) {
-  const res = await fetch(`${baseOf(url)}/api/dev/content?scope=capabilities`, { headers: { authorization: `Bearer ${token}` } });
-  if (!res.ok) throw new Error(await errorText(res));
+export async function probePagesServer({ url, token, onRetry = null }) {
+  const res = await fetchWithRetry(`${baseOf(url)}/api/dev/content?scope=capabilities`, { headers: { authorization: `Bearer ${token}` } }, { onRetry });
+  if (!res.ok) throw Object.assign(new Error(await errorText(res)), { status: res.status });
   const body = await res.json().catch(() => null);
   if (body?.protocol_version !== PAGES_PROTOCOL_VERSION) {
     throw new PagesCliError(
@@ -63,14 +69,19 @@ export async function probePagesServer({ url, token }) {
       "This site's server does not support locale-aware page files yet. Nothing was changed; update the platform or use an older CLI.",
     );
   }
-  return { defaultLocale: body.default_locale, supportedLocales: body.supported_locales ?? [] };
+  return {
+    defaultLocale: body.default_locale,
+    supportedLocales: body.supported_locales ?? [],
+    // CF-T3 — base_revision / expected_plan_hash / force are only sent to a server that says it checks them.
+    revisionCas: body.page_revision_cas === 1 && body.plan_hash === 1,
+  };
 }
 
 /** Site içeriğini diske çek (pull). Pages require protocol v2; every path is contained and staged. */
-export async function pullContent({ dir, url, token, scope, writeFile }) {
-  const res = await fetch(`${baseOf(url)}/api/dev/content?scope=${encodeURIComponent(scope)}`, {
+export async function pullContent({ dir, url, token, scope, writeFile, onRetry = null }) {
+  const res = await fetchWithRetry(`${baseOf(url)}/api/dev/content?scope=${encodeURIComponent(scope)}`, {
     headers: { authorization: `Bearer ${token}` },
-  });
+  }, { onRetry });
   const body = await res.json().catch(() => null);
   if (!res.ok) {
     // Nothing is written on a non-2xx: an incomplete export (PAGES_EXPORT_INCOMPLETE) carries every finding and no files.
@@ -144,25 +155,72 @@ function fsRoot(dir) {
   return collectPageFiles(dir).root;
 }
 
+/** CF-T3 — the most a `--force` reason may be (the platform's FORCE_REASON_MAX). */
+export const FORCE_REASON_MAX = 500;
+
+/** CF-T3 — paths of `forced`, whether the server lists strings or `{path, base_revision, current_revision}` objects. */
+export function forcedPaths(forced) {
+  return (Array.isArray(forced) ? forced : []).map((f) => (typeof f === "string" ? f : f?.path)).filter((p) => typeof p === "string");
+}
+
+function pushRefusal(res, body, fallback) {
+  return new PagesCliError(body?.code ?? "PAGES_PUSH_FAILED", body?.error ?? fallback, {
+    diagnostics: body?.diagnostics ?? [],
+    pages: body?.pages ?? null,
+    status: res.status,
+  });
+}
+
 /**
  * Push. `settings` keeps the v1 body. `pages`: server capability probe → local preflight (nothing is sent on a
  * local error) → `POST {protocol_version: 2, dry_run, files}`. The server preflights the whole batch again and
  * writes nothing unless every file passes.
+ *
+ * CF-T3 (contract C4) — on a server advertising `page_revision_cas` a push is two requests: a dry run (the plan,
+ * handed to `onPlan` before anything is written), then the real push carrying the plan's `expected_plan_hash` and the
+ * push's `x-idempotency-key`. A refused dry run (a stale file, a file without base_revision) throws and nothing else is
+ * sent; a plan that no longer holds at push time is 409 `PAGES_PLAN_STALE`. `force` + `forceReason` travel on both
+ * requests. An older server gets exactly the old single request (no CAS fields); `onServer(server)` lets the caller warn.
  */
-export async function pushContent({ dir, url, token, scope, dryRun = false }) {
+export async function pushContent({ dir, url, token, scope, instance = null, dryRun = false, idempotencyKey = null, onRetry = null, force = false, forceReason = null, onServer = null, onPlan = null }) {
   const base = baseOf(url);
   if (scope === "settings") {
     const files = readContentFiles(dir, scope);
-    const res = await fetch(`${base}/api/dev/content`, {
+    // T10.1 — an older server ignores `instance` and would write the LIVE theme: send it only to a server that says
+    // it honours it (scope=capabilities `settings_instance: 1`); otherwise refuse before anything is sent.
+    if (instance) {
+      const res = await fetchWithRetry(`${base}/api/dev/content?scope=capabilities`, { headers: { authorization: `Bearer ${token}` } }, { onRetry });
+      if (!res.ok) throw Object.assign(new Error(await errorText(res)), { status: res.status });
+      const caps = await res.json().catch(() => null);
+      if (caps?.protocol_version !== PAGES_PROTOCOL_VERSION || caps?.settings_instance !== 1) {
+        throw new PagesCliError(
+          "SETTINGS_INSTANCE_UNSUPPORTED",
+          "This site's server cannot target a theme with `settings push --instance` (it would write the live theme instead). Nothing was sent; update the platform or push with --live.",
+        );
+      }
+    }
+    const res = await fetchWithRetry(`${base}/api/dev/content`, {
       method: "POST",
       headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
-      body: JSON.stringify({ files }),
-    });
-    if (!res.ok) throw new Error(await errorText(res));
+      body: JSON.stringify(instance ? { files, instance } : { files }),
+    }, { onRetry });
+    if (!res.ok) {
+      const text = await res.text();
+      let body = null;
+      try {
+        body = JSON.parse(text);
+      } catch {
+        /* plain-text body */
+      }
+      const error = Object.assign(new Error(body?.error ?? text), { status: res.status });
+      if (typeof body?.code === "string") error.code = body.code;
+      throw error;
+    }
     return { ...(await res.json()), fileCount: Object.keys(files).length };
   }
 
-  const server = await probePagesServer({ url, token });
+  const server = await probePagesServer({ url, token, onRetry });
+  onServer?.(server);
   const { files: local, errors } = collectPageFiles(dir);
   if (errors.length > 0) throw new PagesCliError(errors[0].code, "Local page files cannot be read safely; nothing was sent.", { diagnostics: errors });
   const localDiagnostics = checkLocalBatch(local.map(([p, c]) => classifyPageFile(p, c, server)));
@@ -173,37 +231,78 @@ export async function pushContent({ dir, url, token, scope, dryRun = false }) {
 
   const files = {};
   for (const [path, content] of local) files[path] = content;
-  const res = await fetch(`${base}/api/dev/content`, {
-    method: "POST",
-    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
-    body: JSON.stringify({ protocol_version: PAGES_PROTOCOL_VERSION, dry_run: dryRun, files }),
-  });
+  // One key per push operation: every transport retry resends this exact request (same key, same body).
+  const key = idempotencyKey ?? `cli-${randomUUID()}`;
+  const post = (payload, withKey) =>
+    fetchWithRetry(`${base}/api/dev/content`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}`, ...(withKey ? { "x-idempotency-key": key } : {}) },
+      body: JSON.stringify({ protocol_version: PAGES_PROTOCOL_VERSION, ...payload, files }),
+    }, { onRetry });
+
+  if (!server.revisionCas) {
+    const res = await post({ dry_run: dryRun }, true);
+    const body = await res.json().catch(() => null);
+    if (!res.ok || body?.ok !== true) throw pushRefusal(res, body, `Push failed (HTTP ${res.status}).`);
+    return { ...body, fileCount: local.length, revisionCas: false };
+  }
+
+  const forceFields = force ? { force: true, force_reason: forceReason } : {};
+  const planRes = await post({ dry_run: true, ...forceFields }, false);
+  const plan = await planRes.json().catch(() => null);
+  if (!planRes.ok || plan?.ok !== true) {
+    const error = pushRefusal(planRes, plan, `Push plan failed (HTTP ${planRes.status}); nothing was changed.`);
+    if (error.code === "PAGES_REVISION_CONFLICT" || error.code === "PAGES_BASE_REVISION_REQUIRED") {
+      const stale = error.diagnostics.filter((d) => d.code === "PAGES_REVISION_CONFLICT" || d.code === "PAGES_BASE_REVISION_REQUIRED").length;
+      error.message =
+        `${stale} page file(s) no longer describe the page on the site (changed since you pulled, or no base_revision); nothing was pushed or changed. ` +
+        "Run `blocofy pages pull` to refresh, or `--force --reason <text>` to overwrite.";
+    }
+    throw error;
+  }
+  if (typeof plan.plan_hash !== "string") {
+    throw new PagesCliError("PAGES_PUSH_FAILED", "The server's plan has no plan_hash; nothing was changed.", { status: planRes.status });
+  }
+  onPlan?.(plan);
+  if (dryRun) return { ...plan, fileCount: local.length, revisionCas: true };
+
+  const res = await post({ dry_run: false, expected_plan_hash: plan.plan_hash, ...forceFields }, true);
   const body = await res.json().catch(() => null);
   if (!res.ok || body?.ok !== true) {
-    throw new PagesCliError(body?.code ?? "PAGES_PUSH_FAILED", body?.error ?? `Push failed (HTTP ${res.status}).`, {
-      diagnostics: body?.diagnostics ?? [],
-      pages: body?.pages ?? null,
-      status: res.status,
-    });
+    const error = pushRefusal(res, body, `Push failed (HTTP ${res.status}).`);
+    if (error.code === "PAGES_PLAN_STALE") {
+      error.message = "The site changed between the plan and the push; no pages were changed. Run the push again to review the new plan.";
+    }
+    throw error;
   }
-  return { ...body, fileCount: local.length };
+  return { ...body, fileCount: local.length, revisionCas: true };
 }
 
 /**
  * `pages check`. Offline: path, JSON, format, layout and local duplicates. With `server` credentials it also
  * resolves the default/supported locales and asks the server for a dry-run preflight (targets, documents).
  */
-export async function checkPages({ dir, url, token }) {
+export async function checkPages({ dir, url, token, onRetry = null }) {
   const { files: local, errors } = collectPageFiles(dir);
   const diagnostics = [...errors];
   let server = null;
-  if (url && token) server = await probePagesServer({ url, token });
-  diagnostics.push(...checkLocalBatch(local.map(([p, c]) => classifyPageFile(p, c, server ?? {}))));
+  if (url && token) server = await probePagesServer({ url, token, onRetry });
+  const classified = local.map(([p, c]) => classifyPageFile(p, c, server ?? {}));
+  diagnostics.push(...checkLocalBatch(classified));
+  // CF-T3 — a v2 file without base_revision will be refused by a revision-checking server; say so before the push.
+  // Not on an older server: it never stamps the field, so the warning could never be fixed there.
+  if (!server || server.revisionCas) {
+    for (const c of classified) {
+      if (c.ok && c.layout === "v2" && c.parsed.base_revision == null) {
+        diagnostics.push({ level: "warning", code: "PAGES_BASE_REVISION_MISSING", message: "no base_revision: the site cannot tell whether this page changed since you pulled it, so a push will be refused. Run `blocofy pages pull` to refresh the file (or push with --force --reason <text>).", path: c.path, locale: c.locale, slug: c.slug });
+      }
+    }
+  }
 
   let plan = null;
   if (server && !diagnostics.some((d) => d.level === "error")) {
     try {
-      plan = await pushContent({ dir, url, token, scope: "pages", dryRun: true });
+      plan = await pushContent({ dir, url, token, scope: "pages", dryRun: true, onRetry });
       for (const d of plan.diagnostics ?? []) {
         if (!diagnostics.some((x) => x.code === d.code && x.path === d.path)) diagnostics.push(d);
       }
@@ -220,7 +319,7 @@ export async function checkPages({ dir, url, token }) {
  * whole migration — zero moves — on any error or ambiguity. `write: true` rewrites each file as v2 at its
  * canonical path (contained, staged per file, verified) and only then removes the legacy file.
  */
-export async function migrateLayout({ dir, url, token, write = false }) {
+export async function migrateLayout({ dir, url, token, write = false, onRetry = null }) {
   const { root, files: local, errors } = collectPageFiles(dir);
   const diagnostics = [...errors];
   const needsDefault = local.some(([, c]) => {
@@ -232,7 +331,7 @@ export async function migrateLayout({ dir, url, token, write = false }) {
     }
   });
   let server = null;
-  if (url && token) server = await probePagesServer({ url, token });
+  if (url && token) server = await probePagesServer({ url, token, onRetry });
 
   const classified = local.map(([p, c]) => classifyPageFile(p, c, server ?? {}));
   diagnostics.push(...checkLocalBatch(classified).filter((d) => d.code !== "PAGES_LEGACY_LAYOUT"));

package/lib/credentials.mjs

@@ -1,92 +1,248 @@
-import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, openSync, readFileSync, rmSync, statSync, writeFileSync, writeSync, chmodSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import { SecretStoreError, secretStoreFor, writeJsonAtomic } from "./secret-store.mjs";
+
 /**
- * Blocofy CLI credentials. `blocofy login` writes the platform URL + dev token to
- * `~/.blocofy/credentials.json` (0600); `blocofy theme dev` reads it. Environment
- * variables (BLOCOFY_URL/BLOCOFY_TOKEN) take precedence over the file (CI/agents).
- * The token is stored in plaintext on disk (the usual dev-CLI pattern), so the file
- * is locked down to 0600.
+ * CF-T1 (contract C1) — Blocofy CLI credential store v2.
+ *
+ * `~/.blocofy/credentials.json` (0600, dir 0700, atomic tmp+rename) holds NAMED CONTEXTS and no secrets:
+ *
+ *   { "schema_version": 2, "current_context": "<name>|null",
+ *     "contexts": { "<name>": { platform_origin, site: {id,slug,name,domain}|null,
+ *                               dev: { url, secret: { store } }?, api: { url, secret: { store } }?, verified_at } } }
  *
- * 0.8.0: the same file also holds the v1 API pair `{ apiUrl, apiKey }` written by
- * `blocofy login --api-key`. The two pairs coexist: `saveCredentials(patch)` MERGES the
- * patch into the existing JSON (an unreadable/corrupt file counts as `{}`), so an API login
- * keeps the dev pair and a later dev login keeps the API pair. `loadCredentials()` (dev
- * pair) is unchanged; `loadApiCredentials()` resolves the v1 pair (BLOCOFY_API_KEY +
- * BLOCOFY_API_URL first, then the file).
+ * Secrets live in a secret store (lib/secret-store.mjs): `~/.blocofy/secrets.json` by default, the macOS keychain
+ * on opt-in. A pre-v2 flat file `{ url, token, apiUrl, apiKey }` is migrated losslessly on first read into
+ * `contexts.default` (unverified, `site: null`); the original bytes are kept in `credentials.v1.bak.json`
+ * (rollback: copy it back over credentials.json). A corrupt or half file is never rewritten: CREDENTIALS_CORRUPT.
+ *
+ * Environment variables form an ephemeral "env" context: BLOCOFY_URL+BLOCOFY_TOKEN and/or
+ * BLOCOFY_API_URL+BLOCOFY_API_KEY. A half-set pair is a loud error (never a silent fall-through to the file).
  */
 
-const DIR_NAME = ".blocofy";
-const FILE_NAME = "credentials.json";
+export const SCHEMA_VERSION = 2;
+export const ENV_CONTEXT = "env";
+
+/** A local credential problem (exit 1). Messages carry paths, never file content or secrets. */
+export class CredentialsError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "CredentialsError";
+    this.code = code;
+    this.details = details;
+    this.exitCode = 1;
+  }
+}
+
+// Resolved per call (not at import): tests redirect HOME, and os.homedir() honours $HOME on POSIX.
+const dir = () => join(homedir(), ".blocofy");
+export const credentialsPath = () => join(dir(), "credentials.json");
+export const secretsPath = () => join(dir(), "secrets.json");
+export const backupPath = () => join(dir(), "credentials.v1.bak.json");
+
+const stripSlash = (url) => String(url).replace(/\/+$/, "");
+const isStr = (v) => typeof v === "string" && v.length > 0;
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+export const emptyStore = () => ({ schema_version: SCHEMA_VERSION, current_context: null, contexts: {} });
+
+function corrupt(reason) {
+  return new CredentialsError("CREDENTIALS_CORRUPT", `The credentials file cannot be used (${reason}): ${credentialsPath()}. Nothing was written. Fix or remove it, then run \`blocofy login\`.`, { path: credentialsPath() });
+}
 
-// Resolved per call (not at import): tests redirect HOME to a temp dir, and os.homedir()
-// honours $HOME on POSIX.
-function dir() {
-  return join(homedir(), DIR_NAME);
+function validPair(pair) {
+  return pair === undefined || (isObj(pair) && isStr(pair.url) && isObj(pair.secret) && (pair.secret.store === "file" || pair.secret.store === "keychain"));
 }
 
-export function credentialsPath() {
-  return join(dir(), FILE_NAME);
+function validV2(data) {
+  if (data.schema_version !== SCHEMA_VERSION || !isObj(data.contexts)) return false;
+  if (data.current_context !== null && data.current_context !== undefined && typeof data.current_context !== "string") return false;
+  for (const ctx of Object.values(data.contexts)) {
+    if (!isObj(ctx) || !validPair(ctx.dev) || !validPair(ctx.api)) return false;
+    if (ctx.site !== null && ctx.site !== undefined && !(isObj(ctx.site) && (isStr(ctx.site.id) || Number.isFinite(ctx.site.id)))) return false;
+  }
+  return true;
 }
 
-function readExisting() {
+/**
+ * Read the store (migrating a v1 file). `{ secretStore }` options pass through to the secret adapters (tests).
+ * A missing file is an empty store and is NOT created.
+ */
+export function loadStore(options = {}) {
+  let raw;
+  try {
+    raw = readFileSync(credentialsPath(), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return emptyStore();
+    throw new CredentialsError("CREDENTIALS_UNREADABLE", `Cannot read ${credentialsPath()} (${error?.code ?? "error"}).`, { path: credentialsPath() });
+  }
+  let data;
   try {
-    const data = JSON.parse(readFileSync(credentialsPath(), "utf8"));
-    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+    data = JSON.parse(raw);
   } catch {
-    return {}; // missing/corrupt → start clean
+    throw corrupt("not valid JSON");
   }
+  if (!isObj(data)) throw corrupt("not a JSON object");
+  if ("schema_version" in data) {
+    if (!validV2(data)) throw corrupt("unexpected structure");
+    return { schema_version: SCHEMA_VERSION, current_context: data.current_context ?? null, contexts: data.contexts };
+  }
+  return migrateV1(raw, data, options);
 }
 
-/** Merge `patch` into the credentials file and write it with 0600 permissions. */
-export function saveCredentials(patch) {
+/** v1 `{url, token, apiUrl, apiKey}` → v2 `contexts.default`. Validates EVERYTHING before the first write. */
+function migrateV1(raw, data, options) {
+  const known = ["url", "token", "apiUrl", "apiKey"];
+  if (Object.keys(data).length === 0) return emptyStore();
+  for (const k of known) if (k in data && !isStr(data[k])) throw corrupt(`field "${k}" is not a string`);
+  const hasDev = isStr(data.url) || isStr(data.token);
+  const hasApi = isStr(data.apiUrl) || isStr(data.apiKey);
+  if (hasDev && !(isStr(data.url) && isStr(data.token))) throw corrupt("the dev URL/token pair is incomplete");
+  if (hasApi && !(isStr(data.apiUrl) && isStr(data.apiKey))) throw corrupt("the API URL/key pair is incomplete");
+  if (!hasDev && !hasApi) throw corrupt("no credential pair found");
+
+  const context = { platform_origin: null, site: null, verified_at: null };
+  if (hasDev) context.dev = { url: stripSlash(data.url), secret: { store: "file" } };
+  if (hasApi) context.api = { url: stripSlash(data.apiUrl), secret: { store: "file" } };
+  const store = { schema_version: SCHEMA_VERSION, current_context: "default", contexts: { default: context } };
+
+  // 1) exact-bytes backup (never overwrite an older, different backup)
   mkdirSync(dir(), { recursive: true, mode: 0o700 });
-  const merged = { ...readExisting(), ...patch };
-  writeFileSync(credentialsPath(), JSON.stringify(merged, null, 2) + "\n", { mode: 0o600 });
-  chmodSync(credentialsPath(), 0o600); // create-mode is ignored if the file already exists → enforce it
+  let backup = backupPath();
+  if (existsSync(backup) && readFileSync(backup, "utf8") !== raw) backup = join(dir(), `credentials.v1.bak.${Date.now()}.json`);
+  if (!existsSync(backup)) {
+    writeFileSync(backup, raw, { mode: 0o600 });
+    chmodSync(backup, 0o600);
+  }
+  // 2) secrets, 3) the v2 file (a crash between steps re-runs an idempotent migration from the untouched v1 file)
+  const secrets = secretStoreFor("file", { filePath: secretsPath(), ...options.secretStore });
+  if (hasDev) secrets.set("default", "dev", data.token);
+  if (hasApi) secrets.set("default", "api", data.apiKey);
+  saveStore(store);
+  return store;
 }
 
+const LOCK_STALE_MS = 10000;
+const LOCK_WAIT_MS = 15000;
+export const lockPath = () => join(dir(), ".lock");
+
 /**
- * Resolve credentials: environment first (both vars), then the file. Returns
- * `{ url, token, source }` or null. Trailing slashes are stripped from the URL.
+ * Review M5 — run the synchronous load-modify-save `fn` under an exclusive `~/.blocofy/.lock` (O_EXCL create), so two
+ * concurrent logins/logouts cannot overwrite each other's context or secret. A lock older than 10 s is stale (a
+ * crashed process) and is taken over; waiting longer than 15 s is CREDENTIALS_LOCKED.
  */
-export function loadCredentials() {
-  const envUrl = process.env.BLOCOFY_URL;
-  const envToken = process.env.BLOCOFY_TOKEN;
-  if (envUrl && envToken) {
-    return { url: stripSlash(envUrl), token: envToken, source: "env" };
+export function withStoreLock(fn) {
+  mkdirSync(dir(), { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  const pause = new Int32Array(new SharedArrayBuffer(4));
+  for (;;) {
+    try {
+      const fd = openSync(lockPath(), "wx", 0o600);
+      writeSync(fd, String(process.pid));
+      closeSync(fd);
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+    try {
+      if (Date.now() - statSync(lockPath()).mtimeMs > LOCK_STALE_MS) {
+        rmSync(lockPath(), { force: true });
+        continue;
+      }
+    } catch {
+      continue; // released between the open and the stat
+    }
+    if (Date.now() > deadline) {
+      throw new CredentialsError("CREDENTIALS_LOCKED", `Another blocofy command is updating ${credentialsPath()}. Nothing was written; try again (or remove ${lockPath()} if no blocofy command is running).`, { path: lockPath() });
+    }
+    Atomics.wait(pause, 0, 0, 20);
   }
-  const data = readExisting();
-  if (typeof data.url === "string" && typeof data.token === "string") {
-    return { url: stripSlash(data.url), token: data.token, source: "file" };
+  try {
+    return fn();
+  } finally {
+    rmSync(lockPath(), { force: true });
   }
-  return null;
 }
 
-/**
- * Resolve the v1 API pair: BLOCOFY_API_KEY + BLOCOFY_API_URL (BOTH required — with only one
- * set this throws and does NOT fall through to the file, so a half-configured CI job fails
- * loudly instead of silently using a developer's file), then the file's `{ apiUrl, apiKey }`.
- * Returns `{ apiUrl, apiKey, source }` or null. The thrown message never contains the key.
- */
-export function loadApiCredentials() {
-  const envKey = process.env.BLOCOFY_API_KEY;
-  const envUrl = process.env.BLOCOFY_API_URL;
-  if (envKey && envUrl) {
-    return { apiUrl: stripSlash(envUrl), apiKey: envKey, source: "env" };
+export function saveStore(store) {
+  writeJsonAtomic(credentialsPath(), { schema_version: SCHEMA_VERSION, current_context: store.current_context ?? null, contexts: store.contexts });
+}
+
+/** The secret-store name for NEW secrets: `--keychain` flag or BLOCOFY_SECRET_STORE, default "file". */
+export function defaultSecretStoreName({ keychain = false, env = process.env } = {}) {
+  if (keychain) return "keychain";
+  const v = env.BLOCOFY_SECRET_STORE;
+  if (v === undefined || v === "" || v === "file") return "file";
+  if (v === "keychain") return "keychain";
+  throw new CredentialsError("SECRET_STORE_UNAVAILABLE", `BLOCOFY_SECRET_STORE must be "file" or "keychain".`);
+}
+
+export function openSecretStore(name, options = {}) {
+  try {
+    return secretStoreFor(name, { filePath: secretsPath(), ...options });
+  } catch (error) {
+    throw asCredentialsError(error);
+  }
+}
+
+function asCredentialsError(error) {
+  if (error instanceof SecretStoreError) return new CredentialsError(error.code, error.message);
+  return error;
+}
+
+/** `{ devToken, apiKey }` for a stored context (null where the pair or its secret is absent). */
+export function readSecrets(name, ctx, options = {}) {
+  try {
+    const get = (kind) => (ctx[kind] ? openSecretStore(ctx[kind].secret.store, options).get(name, kind) : null);
+    return { devToken: get("dev"), apiKey: get("api") };
+  } catch (error) {
+    throw asCredentialsError(error);
   }
-  if (envKey || envUrl) {
-    const missing = envKey ? "BLOCOFY_API_URL" : "BLOCOFY_API_KEY";
-    throw new Error(`${missing} is not set — BLOCOFY_API_KEY and BLOCOFY_API_URL must be set together (the credentials file is not consulted while either is set).`);
+}
+
+export function writeSecret(name, kind, storeName, value, options = {}) {
+  try {
+    openSecretStore(storeName, options).set(name, kind, value);
+  } catch (error) {
+    throw asCredentialsError(error);
   }
-  const data = readExisting();
-  if (typeof data.apiUrl === "string" && typeof data.apiKey === "string") {
-    return { apiUrl: stripSlash(data.apiUrl), apiKey: data.apiKey, source: "file" };
+}
+
+export function removeSecrets(name, ctx, options = {}) {
+  for (const kind of ["dev", "api"]) {
+    if (!ctx?.[kind]) continue;
+    try {
+      openSecretStore(ctx[kind].secret.store, options).remove(name, kind);
+    } catch (error) {
+      throw asCredentialsError(error);
+    }
   }
-  return null;
 }
 
-function stripSlash(url) {
-  return url.replace(/\/+$/, "");
+/**
+ * The ephemeral "env" context, or null when no variable is set. Half-set pairs throw (the message names the
+ * missing variable only).
+ */
+export function envContext(env = process.env) {
+  const pair = (urlVar, secretVar) => {
+    const url = env[urlVar];
+    const secret = env[secretVar];
+    if (url && secret) return { url: stripSlash(url), secret };
+    if (url || secret) {
+      const missing = url ? secretVar : urlVar;
+      throw new CredentialsError("ENV_CREDENTIALS_INCOMPLETE", `${missing} is not set — ${urlVar} and ${secretVar} must be set together (the credentials file is not consulted while either is set).`);
+    }
+    return null;
+  };
+  const dev = pair("BLOCOFY_URL", "BLOCOFY_TOKEN");
+  const api = pair("BLOCOFY_API_URL", "BLOCOFY_API_KEY");
+  if (!dev && !api) return null;
+  return {
+    name: ENV_CONTEXT,
+    source: "env",
+    context: { platform_origin: null, site: null, ...(dev ? { dev: { url: dev.url } } : {}), ...(api ? { api: { url: api.url } } : {}) },
+    secrets: { devToken: dev?.secret ?? null, apiKey: api?.secret ?? null },
+  };
 }

package/lib/http.mjs

@@ -0,0 +1,63 @@
+/**
+ * CF-T3 (contract C4, CLI half) — the ONE retry policy for every CLI request that is safe to resend.
+ *
+ * Retried: a thrown fetch (network error, connection reset, per-attempt timeout) and HTTP 429 / 502 / 503 / 504.
+ * NOT retried: 500 and every other status (a 500 may mean the server applied part of the work; a 4xx is a refusal).
+ * At most 3 retries (4 attempts). Wait before retry n: the response's `Retry-After` (delta-seconds or HTTP-date,
+ * capped at 30 s) when present, else 300 ms / 900 ms / 2000 ms. The SAME request is resent: the caller's `init`
+ * (method, headers incl. `x-idempotency-key`, body string) is reused unchanged, so a replay converges on the
+ * server's idempotency handling instead of applying a second, different mutation.
+ *
+ * Callers only route requests here that are safe to replay: reads, upserts, pointer sets, and mutations carrying
+ * an idempotency key. `onRetry({ attempt, retries, reason, waitMs })` fires before every wait (never silent).
+ * `isFinal(response)` (optional, given a clone) marks a retry-status answer that is a verdict, not a transient
+ * failure: it is returned at once instead of being resent.
+ */
+
+export const RETRY_STATUSES = new Set([429, 502, 503, 504]);
+export const DEFAULT_RETRIES = 3;
+export const DEFAULT_BACKOFF_MS = [300, 900, 2000];
+export const MAX_RETRY_WAIT_MS = 30000;
+
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** `Retry-After` → milliseconds (capped), or null when absent/unparseable. */
+export function parseRetryAfter(value, nowMs = Date.now()) {
+  if (typeof value !== "string" || value.trim() === "") return null;
+  const v = value.trim();
+  let ms;
+  if (/^\d+$/.test(v)) ms = Number(v) * 1000;
+  else if (/[A-Za-z]/.test(v)) {
+    const at = Date.parse(v);
+    if (Number.isNaN(at)) return null;
+    ms = at - nowMs;
+  } else return null;
+  return Math.min(Math.max(ms, 0), MAX_RETRY_WAIT_MS);
+}
+
+/**
+ * `fetch` with the retry contract above. Options: `retries`, `backoff` (ms per retry index), `onRetry`,
+ * `fetchImpl` (default: the global fetch at call time), `sleep(ms)`, `now()`, `timeoutMs` (per attempt).
+ */
+export async function fetchWithRetry(input, init = {}, { retries = DEFAULT_RETRIES, backoff = DEFAULT_BACKOFF_MS, onRetry, fetchImpl, sleep = realSleep, now = Date.now, timeoutMs, isFinal } = {}) {
+  const doFetch = fetchImpl ?? globalThis.fetch;
+  for (let attempt = 0; ; attempt += 1) {
+    const attemptInit = timeoutMs ? { ...init, signal: AbortSignal.timeout(timeoutMs) } : init;
+    let res;
+    try {
+      res = await doFetch(input, attemptInit);
+    } catch (error) {
+      if (attempt >= retries) throw error;
+      const waitMs = backoff[attempt] ?? backoff[backoff.length - 1] ?? 0;
+      onRetry?.({ attempt: attempt + 1, retries, reason: error?.name === "TimeoutError" ? "timeout" : error?.message ?? String(error), waitMs });
+      await sleep(waitMs);
+      continue;
+    }
+    if (!RETRY_STATUSES.has(res.status) || attempt >= retries) return res;
+    if (isFinal && (await isFinal(res.clone()))) return res;
+    const waitMs = parseRetryAfter(res.headers.get("retry-after"), now()) ?? backoff[attempt] ?? backoff[backoff.length - 1] ?? 0;
+    await res.arrayBuffer().catch(() => {}); // release the connection before resending
+    onRetry?.({ attempt: attempt + 1, retries, reason: `HTTP ${res.status}`, waitMs });
+    await sleep(waitMs);
+  }
+}