@botdocs/cli 0.12.2 → 0.14.0

package/dist/lib/config.d.ts

@@ -10,10 +10,44 @@ interface AuthConfig {
     username: string;
     displayName: string;
     syncLibrary?: boolean;
+    /** Stable per-install device identity (a v4 UUID) sent to the API as
+     * `X-Device-Id` on every authenticated request. Generated once by
+     * `getOrCreateDeviceId` and NEVER rotated — the free-tier device/session
+     * caps key off it, so rotating would register a phantom new device. CI
+     * runners override it via the `BOTDOCS_DEVICE_ID` env var (see
+     * `getOrCreateDeviceId`) so they don't blow the cap across ephemeral
+     * machines. Optional for backward-compat: auth.json files written before
+     * this field existed lazily gain one on the next `getOrCreateDeviceId`. */
+    deviceId?: string;
+    /** Last server-acknowledged library generation counter (the `version`
+     * returned by POST /api/library/lockfile-sync). The CLI sends it back as
+     * `baseVersion` on the next sync so the server can detect that ANOTHER
+     * device changed the shelf in between and return a 409 `library_conflict`
+     * instead of silently clobbering. Absent until the first successful sync;
+     * a missing value is treated as "no base" (the server force-writes and
+     * stamps a fresh version). */
+    libraryVersion?: number;
 }
 export declare function saveAuth(config: AuthConfig): void;
 export declare function loadAuth(): AuthConfig | null;
 export declare function clearAuth(): void;
+/**
+ * Get the stable device identity for this CLI install, creating it if needed.
+ *
+ * Resolution order:
+ *   1. `BOTDOCS_DEVICE_ID` env var (CI/automation escape hatch) — wins when
+ *      set and non-blank; not persisted.
+ *   2. The `deviceId` already saved in ~/.botdocs/auth.json.
+ *   3. A freshly generated v4 UUID, persisted back into auth.json (when an
+ *      auth config exists) so it's stable across runs.
+ *
+ * The id is NEVER rotated once persisted — the server's device/session caps
+ * key off it. If there's no auth.json yet (user not logged in) we still return
+ * a generated id for the current process but can't persist it; `login` calls
+ * this AFTER saving auth so the id lands in the file. Returns `null` only when
+ * generation itself is impossible (never, in practice).
+ */
+export declare function getOrCreateDeviceId(): string;
 /** One-time startup migration check. If auth.json exists and was created by
  * a pre-P1-G CLI (mode 0644 / world-readable), tighten it in place AND
  * warn the user — the token may have been read by another local user, so

package/dist/lib/config.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { randomUUID } from 'node:crypto';
 // POSIX modes used for the CLI's credential storage. The token lives in
 // auth.json and is the bearer for every authenticated API call — a default
 // umask of 022 leaves the file at 0644 (world-readable) on shared dev
@@ -78,6 +79,45 @@ export function clearAuth() {
         fs.unlinkSync(file);
     }
 }
+/** Env var that pins a stable device identity, overriding the persisted one.
+ * Documented escape hatch for CI/automation: a fleet of ephemeral runners can
+ * export the same `BOTDOCS_DEVICE_ID` so they all present as one device and
+ * don't blow the free-tier device/concurrent-session caps. When set (and
+ * non-blank) it ALWAYS wins and is never persisted. */
+const DEVICE_ID_ENV = 'BOTDOCS_DEVICE_ID';
+/**
+ * Get the stable device identity for this CLI install, creating it if needed.
+ *
+ * Resolution order:
+ *   1. `BOTDOCS_DEVICE_ID` env var (CI/automation escape hatch) — wins when
+ *      set and non-blank; not persisted.
+ *   2. The `deviceId` already saved in ~/.botdocs/auth.json.
+ *   3. A freshly generated v4 UUID, persisted back into auth.json (when an
+ *      auth config exists) so it's stable across runs.
+ *
+ * The id is NEVER rotated once persisted — the server's device/session caps
+ * key off it. If there's no auth.json yet (user not logged in) we still return
+ * a generated id for the current process but can't persist it; `login` calls
+ * this AFTER saving auth so the id lands in the file. Returns `null` only when
+ * generation itself is impossible (never, in practice).
+ */
+export function getOrCreateDeviceId() {
+    const fromEnv = process.env[DEVICE_ID_ENV]?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const config = loadAuth();
+    if (config?.deviceId && config.deviceId.trim().length > 0) {
+        return config.deviceId;
+    }
+    const generated = randomUUID();
+    // Persist back onto the existing auth config so the id is stable across
+    // runs. If there's no auth.json (not logged in), we can't persist — return
+    // the generated id for this process; `login` persists it once auth exists.
+    if (config) {
+        saveAuth({ ...config, deviceId: generated });
+    }
+    return generated;
+}
 export function checkAuthFilePerms() {
     if (process.platform === 'win32')
         return { changed: false };

package/dist/lib/library-sync.d.ts

@@ -3,6 +3,12 @@
  * - file contents (lockfile never contained them, but the route also rejects them)
  * - install destinations (private to the user's machine)
  * - fingerprints (not useful server-side; minimize what we send)
- * Only refs + versions + types remain. Failures are silent so install
- * and sync flows never break on telemetry hiccups. */
+ * Only refs + versions + types remain.
+ *
+ * Sends the last server-acknowledged generation counter as `baseVersion` so
+ * the server can detect a concurrent change from another device and reply 409
+ * `library_conflict` instead of clobbering. On success we persist the new
+ * `version`. On conflict we surface a single honest notice (keep-local +
+ * advise `botdocs sync`). All OTHER failures stay silent so install/sync
+ * flows never break on a telemetry hiccup. */
 export declare function syncLibrary(): Promise<void>;

package/dist/lib/library-sync.js

@@ -1,13 +1,49 @@
-import { apiFetch } from './api.js';
+import { ApiError, apiFetch } from './api.js';
 import { loadLockfile } from './lockfile.js';
-import { loadAuth } from './config.js';
+import { loadAuth, saveAuth } from './config.js';
+/** Narrow an ApiError body to the standard `library_conflict` 409 shape. The
+ * server sends `conflictingDevice` (the device that last touched the shelf);
+ * it may be null when the device name isn't known. */
+function asLibraryConflict(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    if (body.error !== 'library_conflict')
+        return null;
+    return body;
+}
+/** Module-scoped guard so a single CLI invocation (which may call syncLibrary
+ * several times — e.g. install loops) prints the conflict notice at most once.
+ * Reset is unnecessary: the process is short-lived. */
+let conflictNoticePrinted = false;
+/** Print the honest library-conflict CTA to stderr exactly once per process.
+ *
+ * MVP policy (no auto-merge): we KEEP the local shelf untouched — the server
+ * already refused the write, so there's nothing to roll back here — and advise
+ * the user to pull the latest with `botdocs sync` before retrying. Per-member
+ * shelves are mentioned as a coming team feature (honest: no fake purchase).
+ * Goes to stderr so it never disturbs a command's stdout-rendered output. */
+function printConflictNotice(conflictingDevice) {
+    if (conflictNoticePrinted)
+        return;
+    conflictNoticePrinted = true;
+    const who = conflictingDevice ? ` from "${conflictingDevice}"` : '';
+    process.stderr.write(`\n  ⚠ Your library changed on another device${who} since this one last synced.\n` +
+        `    Kept your local copy as-is. Run \`botdocs sync\` to pull the latest, then retry.\n` +
+        `    (Per-member shelves are a coming team feature.)\n`);
+}
 /** Posts a sanitized snapshot of the lockfile to BotDocs if the user has
  * opted-in via `botdocs login --sync-library`. Sanitization strips:
  * - file contents (lockfile never contained them, but the route also rejects them)
  * - install destinations (private to the user's machine)
  * - fingerprints (not useful server-side; minimize what we send)
- * Only refs + versions + types remain. Failures are silent so install
- * and sync flows never break on telemetry hiccups. */
+ * Only refs + versions + types remain.
+ *
+ * Sends the last server-acknowledged generation counter as `baseVersion` so
+ * the server can detect a concurrent change from another device and reply 409
+ * `library_conflict` instead of clobbering. On success we persist the new
+ * `version`. On conflict we surface a single honest notice (keep-local +
+ * advise `botdocs sync`). All OTHER failures stay silent so install/sync
+ * flows never break on a telemetry hiccup. */
 export async function syncLibrary() {
     const auth = loadAuth();
     if (!auth?.syncLibrary)
@@ -15,16 +51,39 @@ export async function syncLibrary() {
     const lf = loadLockfile();
     const sanitized = {
         version: 1,
+        // Generation counter the server last acked. Separate axis from the
+        // lockfile-FORMAT `version: 1` above — this is "which revision of the
+        // shelf did I base this write on". Omitted when we've never synced.
+        baseVersion: auth.libraryVersion,
         installs: lf.installs.map((i) => ({ ref: i.ref, type: i.type, version: i.version })),
     };
     try {
-        await apiFetch('/api/library/lockfile-sync', {
+        const result = await apiFetch('/api/library/lockfile-sync', {
             method: 'POST',
             auth: true,
             body: sanitized,
         });
+        // Persist the new generation counter so the next sync sends it as
+        // baseVersion. Re-load auth in case it changed under us; guard the write
+        // so we don't resurrect a logged-out config.
+        if (typeof result.version === 'number') {
+            const current = loadAuth();
+            if (current)
+                saveAuth({ ...current, libraryVersion: result.version });
+        }
     }
-    catch {
-        // Silent — never break user flows
+    catch (err) {
+        // 409 library_conflict is the ONE telemetry failure worth surfacing — it's
+        // user-actionable (another device moved the shelf). Everything else
+        // (network blips, 5xx, the launch-day waitlist 403) stays silent so the
+        // foreground command isn't disrupted by a background sync.
+        if (err instanceof ApiError && err.status === 409) {
+            const conflict = asLibraryConflict(err.body);
+            if (conflict) {
+                printConflictNotice(conflict.conflictingDevice);
+                return;
+            }
+        }
+        // Silent — never break user flows.
     }
 }

package/dist/lib/proposals.d.ts

@@ -0,0 +1,37 @@
+/** A file for hashing — ONLY filename + content participate. */
+export interface HashableFile {
+    filename: string;
+    content: string;
+}
+/**
+ * Canonical file-set hash. Mirrors the server's `fileSetHash` exactly so the
+ * `basedFileHash` the CLI sends matches what the server would compute over the
+ * same live file set. Sort is by filename ascending using the same comparison
+ * the server uses (`<` / `>` on the raw filename string).
+ */
+export declare function fileSetHash(files: ReadonlyArray<HashableFile>): string;
+/**
+ * Canonical SYNTHESIS idempotency hash. DISTINCT from {@link fileSetHash}
+ * (which is the drift anchor / `basedFileHash`). The server keys the
+ * partial-unique index `botdoc_proposals_synthesis_hash_uq` on this value so
+ * the same OPEN synthesis (same sources + same merged content) can't be
+ * created twice — the CLI computes it before POSTing only so the value is
+ * stable client-side; the server recomputes + enforces it.
+ *
+ * MUST match `apps/web/src/lib/proposals.ts#sourceHash` byte-for-byte:
+ *
+ *   sha256-hex( JSON.stringify({
+ *     sources: [...new Set(synthesizedFrom)].sort(),
+ *     files:   [...mergedFiles]
+ *                .sort by filename ascending (same `<`/`>` compare as fileSetHash)
+ *                .map(f => [f.filename, sha256hex(f.content)]),
+ *   }) )
+ *
+ * Notes (identical exclusions to fileSetHash):
+ *   - `sources` is deduplicated + lexicographically sorted, so source-id
+ *     ordering / duplicates don't change the hash.
+ *   - `files` pairs each filename with the sha256 of its content (not the raw
+ *     body) to keep the JSON small.
+ *   - `mode`/`sortOrder` are NOT part of the hash.
+ */
+export declare function sourceHash(synthesizedFrom: ReadonlyArray<string>, mergedFiles: ReadonlyArray<HashableFile>): string;

package/dist/lib/proposals.js

@@ -0,0 +1,72 @@
+/**
+ * proposals.ts — shared helpers for the CLI proposal lane.
+ *
+ * The load-bearing piece here is {@link fileSetHash}: the canonical file-set
+ * hash that the server computes in `apps/web/src/lib/proposals.ts#fileSetHash`.
+ * The two MUST agree byte-for-byte — the server uses it as the drift anchor
+ * (`basedFileHash`) the CLI sends on every `propose`. Any divergence (sort
+ * order, framing byte, included fields) would make the server reject or
+ * mis-detect drift for every proposal.
+ *
+ * Canonical spec (identical on both sides):
+ *   - sha256, hex digest
+ *   - over each file sorted by filename ascending (JS default string compare)
+ *   - of:  filename + "\u0000" + content + "\u0000"
+ *   - `mode` and `sortOrder` are NOT part of the hash.
+ */
+import { createHash } from 'node:crypto';
+/** NUL framing byte between/after each (filename, content) pair. Defined once
+ * so the intent is obvious and it can never be mistaken for a space. */
+const NUL = '\u0000';
+/**
+ * Canonical file-set hash. Mirrors the server's `fileSetHash` exactly so the
+ * `basedFileHash` the CLI sends matches what the server would compute over the
+ * same live file set. Sort is by filename ascending using the same comparison
+ * the server uses (`<` / `>` on the raw filename string).
+ */
+export function fileSetHash(files) {
+    const sorted = [...files].sort((a, b) => a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0);
+    const hash = createHash('sha256');
+    for (const f of sorted) {
+        hash.update(f.filename);
+        hash.update(NUL);
+        hash.update(f.content);
+        hash.update(NUL);
+    }
+    return hash.digest('hex');
+}
+/** sha256-hex of a single string (a file's content). Helper for {@link sourceHash}. */
+function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+/**
+ * Canonical SYNTHESIS idempotency hash. DISTINCT from {@link fileSetHash}
+ * (which is the drift anchor / `basedFileHash`). The server keys the
+ * partial-unique index `botdoc_proposals_synthesis_hash_uq` on this value so
+ * the same OPEN synthesis (same sources + same merged content) can't be
+ * created twice — the CLI computes it before POSTing only so the value is
+ * stable client-side; the server recomputes + enforces it.
+ *
+ * MUST match `apps/web/src/lib/proposals.ts#sourceHash` byte-for-byte:
+ *
+ *   sha256-hex( JSON.stringify({
+ *     sources: [...new Set(synthesizedFrom)].sort(),
+ *     files:   [...mergedFiles]
+ *                .sort by filename ascending (same `<`/`>` compare as fileSetHash)
+ *                .map(f => [f.filename, sha256hex(f.content)]),
+ *   }) )
+ *
+ * Notes (identical exclusions to fileSetHash):
+ *   - `sources` is deduplicated + lexicographically sorted, so source-id
+ *     ordering / duplicates don't change the hash.
+ *   - `files` pairs each filename with the sha256 of its content (not the raw
+ *     body) to keep the JSON small.
+ *   - `mode`/`sortOrder` are NOT part of the hash.
+ */
+export function sourceHash(synthesizedFrom, mergedFiles) {
+    const sources = [...new Set(synthesizedFrom)].sort();
+    const files = [...mergedFiles]
+        .sort((a, b) => (a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0))
+        .map((f) => [f.filename, sha256Hex(f.content)]);
+    return sha256Hex(JSON.stringify({ sources, files }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botdocs/cli",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "CLI for BotDocs — author, publish, install, and sync agent skills across Claude, Claude Code, Cursor, Codex, ChatGPT, Windsurf, Copilot, Gemini, Antigravity, and OpenCode.",
   "keywords": [
     "botdocs",