@labelbox/recursion-cli 0.0.45 → 0.0.46

package/README.md

@@ -14,19 +14,37 @@ rl synthesizers create --help # list flags
 ## How it works (fully live, zero per-operation code)
 
 The CLI ships **no** baked API reference and has **no** `@labelbox/recursion-sdk` dependency.
-On each run it **fetches a manifest** from `GET /cli/manifest` on whatever server
-`--base-url` points at (production by default, or staging, or `localhost`), validates
-it (`src/manifest.ts`), and builds its entire command tree, `--help`, request/response
-shapes, and docs browse surfaces from it. Dispatch is generic (`src/dispatch.ts`):
+On each run it **revalidates the manifest** from `GET /cli/manifest` when the server
+selected by `--base-url` is reachable (production by default, or staging, or
+`localhost`). If the server is unavailable, it falls back only to a locally cached
+manifest that was previously validated. From that manifest it builds its entire
+command tree, `--help`, request/response shapes, and docs browse surfaces
+(`src/manifest.ts`). Dispatch is generic (`src/dispatch.ts`):
 each request is built straight from the manifest operation's HTTP method + path
 template + params + body — there is no hand-written command per operation and no
 baked client.
 
 The result: **adding or changing a backend endpoint needs zero CLI release** — the
 live CLI reflects it as soon as the backend deploys. The CLI is re-released only when
-its own engine code changes. The manifest is revalidated on every run via a
-conditional fetch (ETag / `If-None-Match`), cached per base-url under
-`~/.cache/rl-gym/`, so it can never serve stale data and never needs manual busting.
+its own engine code changes. When the server is reachable, the manifest is
+revalidated on every run via a conditional fetch (ETag / `If-None-Match`) and cached
+per base-url under `~/.cache/recursion/`. When the server is unreachable, the CLI may
+use the last locally validated copy so commands remain available offline. If only the
+previous `~/.cache/rl-gym/` entry exists, the CLI validates and uses it immediately,
+then adopts it into the Recursion cache non-destructively. The
+old entry is retained unchanged for rollback; new server responses are written only
+to the Recursion cache.
+
+Legacy adoption uses atomic create-if-absent publication: a validated copy is
+hard-linked from a unique same-directory temporary file, so it never replaces a
+canonical entry created concurrently. A valid concurrent canonical entry wins; an
+invalid one is left untouched while that invocation uses the validated legacy value
+in memory. Validated fresh HTTP `200` responses use atomic same-directory rename and
+therefore retain last-network-writer behavior. Replacement preserves an existing
+file's POSIX mode bits, but deliberately publishes a new inode and does not preserve
+its ACLs or extended attributes. Both paths require parent-directory write/search
+permission; if unavailable, the CLI keeps using the validated in-memory result and
+never falls back to a partial direct write.
 
 ### Docs browse surfaces
 
@@ -100,11 +118,13 @@ rl synthesizer-runs trigger --problem-version-id pv_01HX... --from-json ./run.js
 ## The command surface is the live server
 
 There is **nothing to regenerate or commit** for the CLI — the command surface is
-fetched fresh from the target server's `GET /cli/manifest` on every run, so a backend
-change flows through automatically after deploy with no CLI step. The manifest itself
-is assembled by `yarn generate cli:manifest` (included in `yarn generate prerequisites`) from the
-spec-derived reference files and embedded into the backend; to add or change a
-command, change the backend `@SdkRoute` — not this package.
+revalidated against the target server's `GET /cli/manifest` on every run when the
+server is reachable, with a validated local-cache fallback when it is offline. A
+backend change therefore flows through automatically after deploy with no CLI step.
+The manifest itself is assembled by `yarn generate cli:manifest` (included in
+`yarn generate prerequisites`) from the spec-derived reference files and embedded
+into the backend; to add or change a command, change the backend `@SdkRoute` — not
+this package.
 
 The *engine* (manifest fetch + cache + validation, generic dispatch, flag mapping,
 help formatting, the request-body / returns shape trees, and the docs browse

package/dist/manifest.d.ts

@@ -398,13 +398,22 @@ export type Manifest = z.infer<typeof ManifestSchema>;
  * and only a deliberate format bump trips this.
  */
 export declare function parseManifest(value: unknown, source: string): Manifest;
+/**
+ * A filesystem-safe, collision-free slug for a base URL, so each server caches
+ * independently. The readable part is the sanitized URL (handy when eyeballing the
+ * cache dir); a short hash of the *full* URL is appended so two URLs that sanitize
+ * to the same string (e.g. `https://x.com:8080` vs `https://x-com-8080`) still get
+ * distinct cache files rather than silently sharing — and poisoning — one.
+ */
+export declare function hostSlug(baseUrl: string): string;
 /**
  * Fetch the command manifest, revalidating the cache on every run:
  *   - send `If-None-Match` with the cached ETag → `304` means the cache is provably
  *     current (use it); `200` means the surface changed (validate + replace cache).
  *   - a network error (incl. a timeout) falls back to the cached copy with a warning;
  *     with no cache it errors clearly.
- * The cache therefore can never serve stale data and never needs manual busting — a
- * backend redeploy is picked up automatically on the next command.
+ * When the server is reachable, the cache is revalidated and a backend redeploy is
+ * picked up automatically. Offline, the last locally validated copy may be older
+ * than the server but keeps the CLI usable.
  */
 export declare function fetchManifest(baseUrl: string, apiKey: string): Promise<Manifest>;

package/dist/manifest.js

@@ -1,5 +1,5 @@
-import { createHash } from 'node:crypto';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, fchmodSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import process from 'node:process';
@@ -9,8 +9,8 @@ import { z } from 'zod';
 // from `GET /cli/manifest` on whatever server `--base-url` points at, instead of
 // baking a compiled-in `@labelbox/recursion-sdk` reference. This module owns:
 //   1. the manifest's runtime Zod schema + TS types (the validation boundary), and
-//   2. `fetchManifest` — a conditional-fetch cache (ETag / If-None-Match) that can
-//      never serve stale data and needs no manual busting.
+//   2. `fetchManifest` — a conditional-fetch cache (ETag / If-None-Match) that is
+//      revalidated whenever the server is reachable and remains usable offline.
 // The schema lives here, not in sdk-ts: the CLI no longer depends on that package
 // (see the plan's standalone-CLI decision). The backend embeds the same manifest at
 // build time (`dx manifest:generate`); this is the consumer mirror.
@@ -300,12 +300,15 @@ const CacheSchema = z.object({ etag: z.string().optional(), manifest: z.unknown(
  * to the same string (e.g. `https://x.com:8080` vs `https://x-com-8080`) still get
  * distinct cache files rather than silently sharing — and poisoning — one.
  */
-function hostSlug(baseUrl) {
+export function hostSlug(baseUrl) {
     const readable = baseUrl.replace(/[^a-zA-Z0-9]+/gu, '-').replace(/^-+|-+$/gu, '') || 'default';
     const hash = createHash('sha256').update(baseUrl, 'utf8').digest('hex').slice(0, 8);
     return `${readable}-${hash}`;
 }
-function cachePathFor(baseUrl) {
+function canonicalCachePathFor(baseUrl) {
+    return join(homedir(), '.cache', 'recursion', `${hostSlug(baseUrl)}.json`);
+}
+function legacyCachePathFor(baseUrl) {
     return join(homedir(), '.cache', 'rl-gym', `${hostSlug(baseUrl)}.json`);
 }
 function readCache(path) {
@@ -333,21 +336,129 @@ function readCache(path) {
     // arrives). Treating it as cold lets the next fetch pull — and re-cache — a full
     // body, so the CLI self-heals without a manual cache delete.
     try {
-        return { etag: parsed.data.etag, manifest: parseManifest(parsed.data.manifest, 'the cache') };
+        return {
+            etag: parsed.data.etag,
+            manifest: parseManifest(parsed.data.manifest, 'the cache'),
+            raw,
+        };
     }
     catch {
         return undefined;
     }
 }
-function writeCache(path, entry) {
+const CACHE_TEMP_PREFIX = '.rlc-';
+function uniqueCacheTempPath(directory) {
+    return join(directory, `${CACHE_TEMP_PREFIX}${process.pid.toString()}-${randomUUID()}.tmp`);
+}
+/**
+ * Create, populate, close, and publish one exclusively owned same-directory temp.
+ *
+ * Ownership begins immediately after `openSync` succeeds, so every later failure —
+ * including a partial write or close failure — triggers best-effort pathname cleanup.
+ * Descriptor ownership is cleared before the single close attempt: retrying a numeric
+ * descriptor could close an unrelated resource if the operating system reused it.
+ * Publication happens only after close succeeds. The caller reports whether it
+ * transferred the inode (rename) or retained it (hard-link adoption), which determines
+ * final cleanup ownership.
+ */
+function publishFromOwnedTemp(path, raw, prepare, publish) {
+    let tempPath;
+    let descriptor;
+    let ownsTemp = false;
     try {
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, JSON.stringify(entry));
+        const directory = dirname(path);
+        mkdirSync(directory, { recursive: true });
+        tempPath = uniqueCacheTempPath(directory);
+        descriptor = openSync(tempPath, 'wx');
+        ownsTemp = true;
+        const bytes = Buffer.from(raw, 'utf8');
+        let offset = 0;
+        while (offset < bytes.byteLength) {
+            const written = writeSync(descriptor, bytes, offset, bytes.byteLength - offset);
+            if (written === 0)
+                throw new Error('writing the cache temp made no progress');
+            offset += written;
+        }
+        prepare(descriptor);
+        const descriptorToClose = descriptor;
+        descriptor = undefined;
+        closeSync(descriptorToClose);
+        if (publish(tempPath) === 'transferred')
+            ownsTemp = false;
     }
     catch {
-        // A non-writable cache dir is a bandwidth optimization lost, not a failure —
-        // the command still ran off the fetched manifest. Stay silent.
+        // Cache persistence is a bandwidth optimization. The caller already has a
+        // validated in-memory manifest, so publication failures are non-fatal.
     }
+    finally {
+        if (descriptor !== undefined) {
+            const descriptorToClose = descriptor;
+            descriptor = undefined;
+            try {
+                closeSync(descriptorToClose);
+            }
+            catch {
+                // Never retry a numeric descriptor: it may already have been reused.
+            }
+        }
+        if (ownsTemp && tempPath !== undefined) {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch {
+                // Pathname cleanup is best-effort; readers inspect only the final path.
+            }
+        }
+    }
+}
+/**
+ * Replace a cache with a validated HTTP 200 response via same-directory rename.
+ *
+ * Rename deliberately publishes a new inode: an existing destination's POSIX mode
+ * bits are copied to that inode, but its ACLs and xattrs are not. The operation
+ * requires write/search permission on the parent directory; it never falls back to
+ * a partial direct write when temporary-file creation or rename is unavailable.
+ */
+function replaceCacheAtomically(path, raw) {
+    publishFromOwnedTemp(path, raw, (descriptor) => {
+        // Read the mode immediately before publication. Concurrent HTTP 200 writers all
+        // preserve the established mode while rename keeps last-network-writer-wins.
+        const destination = statSync(path, { throwIfNoEntry: false });
+        if (destination !== undefined)
+            fchmodSync(descriptor, destination.mode & 0o7777);
+    }, (tempPath) => {
+        renameSync(tempPath, path);
+        return 'transferred';
+    });
+}
+/**
+ * Publish validated legacy bytes only if the canonical destination is absent.
+ *
+ * The hard link is the no-replace commit point: unlike rename, it fails if any
+ * concurrent invocation has created the destination. Best-effort temporary-path
+ * cleanup is attempted afterward, while a winning canonical path is never overwritten.
+ */
+function publishCacheIfAbsent(path, raw) {
+    publishFromOwnedTemp(path, raw, () => { }, (tempPath) => {
+        linkSync(tempPath, path);
+        return 'retained';
+    });
+}
+/** Prefer canonical cache; otherwise adopt a validated legacy file without mutating it. */
+function selectCache(baseUrl) {
+    const canonicalPath = canonicalCachePathFor(baseUrl);
+    const canonical = readCache(canonicalPath);
+    if (canonical !== undefined)
+        return canonical;
+    const legacy = readCache(legacyCachePathFor(baseUrl));
+    if (legacy === undefined)
+        return undefined;
+    // Copy the validated bytes exactly. Hard-link publication cannot replace a
+    // canonical file that appears after the reads above. Re-read afterward: prefer a
+    // valid concurrent winner, but leave an invalid winner untouched and keep using
+    // the already-validated legacy value in memory.
+    publishCacheIfAbsent(canonicalPath, legacy.raw);
+    return readCache(canonicalPath) ?? legacy;
 }
 // Every `rl` invocation gates on this fetch, so it must be bounded: a server that
 // accepts the connection but never responds (a hung gateway, a stalled captive
@@ -360,13 +471,14 @@ const MANIFEST_FETCH_TIMEOUT_MS = 30_000;
  *     current (use it); `200` means the surface changed (validate + replace cache).
  *   - a network error (incl. a timeout) falls back to the cached copy with a warning;
  *     with no cache it errors clearly.
- * The cache therefore can never serve stale data and never needs manual busting — a
- * backend redeploy is picked up automatically on the next command.
+ * When the server is reachable, the cache is revalidated and a backend redeploy is
+ * picked up automatically. Offline, the last locally validated copy may be older
+ * than the server but keeps the CLI usable.
  */
 export async function fetchManifest(baseUrl, apiKey) {
     const url = supportUrl(baseUrl, '/cli/manifest');
-    const cachePath = cachePathFor(baseUrl);
-    const cached = readCache(cachePath);
+    const canonicalCachePath = canonicalCachePathFor(baseUrl);
+    const cached = selectCache(baseUrl);
     let res;
     try {
         res = await fetch(url, {
@@ -410,6 +522,6 @@ export async function fetchManifest(baseUrl, apiKey) {
             'points at a recursion API (not a login page or proxy).');
     }
     const manifest = parseManifest(json, url);
-    writeCache(cachePath, { etag: res.headers.get('etag') ?? undefined, manifest: json });
+    replaceCacheAtomically(canonicalCachePath, JSON.stringify({ etag: res.headers.get('etag') ?? undefined, manifest: json }));
     return manifest;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@labelbox/recursion-cli",
-  "version": "0.0.45",
+  "version": "0.0.46",
   "type": "module",
   "repository": {
     "type": "git",