@botdocs/cli 0.12.2 → 0.14.0

package/dist/commands/propose.js

@@ -0,0 +1,202 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ApiError, apiFetch, fetchRawContent, friendlyApiErrorDetail, getApiUrl } from '../lib/api.js';
+import { loadAuth } from '../lib/config.js';
+import { parseRef } from '../lib/ref.js';
+import { fileSetHash } from '../lib/proposals.js';
+import { collectFromDirectory, collectFromFile } from './publish.js';
+/** Bail before any file reading if the user isn't logged in. Mirrors
+ * publish.ts's preflight: one friendly line, exit 1. Proposing requires auth
+ * (the server attributes the proposal to the caller). */
+function requireAuth(options) {
+    if (loadAuth())
+        return;
+    if (options.json) {
+        console.log(JSON.stringify({ ok: false, error: 'not logged in', hint: 'Run `botdocs login` first.' }));
+    }
+    else {
+        console.error('\n  ✗ Not logged in. Run `botdocs login` first.\n');
+    }
+    process.exit(1);
+}
+/** True when the logged-in user owns this ref. A skill ref's username IS the
+ * author's username (the registry resolves `@user/slug` by the author's
+ * handle), so ownership is a case-insensitive username match. Used only to
+ * tailor the success copy — the server is the authority on what the proposal
+ * actually does (an owner proposing still gets a proposal row, not a publish).
+ */
+function isOwnRef(username) {
+    const me = loadAuth()?.username;
+    if (!me)
+        return false;
+    return me.toLowerCase() === username.toLowerCase();
+}
+/** Pull the live published file set (filename + content) so we can compute the
+ * canonical basedFileHash the server uses for drift detection. The manifest
+ * lists files by rawUrl; we fetch each body. Returns null on a non-SKILL
+ * manifest (proposals only apply to skills). */
+async function fetchLiveFileSet(username, slug) {
+    const manifest = await apiFetch(`/api/skills/${username}/${slug}/manifest`);
+    if (manifest.type !== 'SKILL' || !manifest.files)
+        return null;
+    const files = await Promise.all(manifest.files.map(async (f) => ({
+        filename: f.filename,
+        content: await fetchRawContent(f.rawUrl),
+    })));
+    return files;
+}
+/**
+ * `botdocs propose @user/slug [path]` — queue a change to a skill for the
+ * author to review, instead of publishing directly.
+ *
+ * Collects the local files (directory or single markdown file, default cwd),
+ * computes `basedFileHash` over the skill's CURRENT live file set (the base
+ * the author will diff against), and POSTs the proposal. The author reviews +
+ * accepts/rejects from the Proposals tab or `botdocs proposals accept`.
+ */
+export async function propose(rawRef, pathArg, options) {
+    requireAuth(options);
+    let ref;
+    try {
+        ref = parseRef(rawRef);
+    }
+    catch (err) {
+        console.error(`\n  ✗ ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+    const refStr = `@${ref.username}/${ref.slug}`;
+    // Collect the proposed files from the local path (default: cwd).
+    const source = pathArg ?? '.';
+    const resolved = path.resolve(source);
+    if (!fs.existsSync(resolved)) {
+        console.error(`\n  ✗ Source not found: ${source}\n`);
+        process.exit(1);
+    }
+    let files;
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        files = collectFromDirectory(resolved);
+    }
+    else {
+        files = collectFromFile(resolved);
+    }
+    if (files.length === 0) {
+        console.error('\n  ✗ No markdown files found to propose.\n');
+        process.exit(1);
+    }
+    if (!files.some((f) => f.filename.endsWith('.md') || f.filename.endsWith('.mdc'))) {
+        console.error('\n  ✗ A proposal needs at least one markdown file (.md or .mdc).\n');
+        process.exit(1);
+    }
+    // Fetch the live file set so basedFileHash anchors the proposal to the exact
+    // base the author will see. A drift between this and what the server stores
+    // becomes the "skill moved while you reviewed" guard on accept.
+    let liveFiles;
+    try {
+        liveFiles = await fetchLiveFileSet(ref.username, ref.slug);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+            console.error(`\n  ✗ Skill not found: ${refStr}\n`);
+            process.exit(1);
+        }
+        if (err instanceof ApiError) {
+            console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    if (liveFiles === null) {
+        console.error('\n  ✗ Proposals only apply to skills (not bundles).\n');
+        process.exit(1);
+    }
+    const basedFileHash = fileSetHash(liveFiles);
+    let result;
+    try {
+        result = await apiFetch(`/api/skills/${ref.username}/${ref.slug}/proposals`, {
+            method: 'POST',
+            auth: true,
+            body: {
+                files: files.map((f) => ({
+                    filename: f.filename,
+                    content: f.content,
+                    sortOrder: f.sortOrder,
+                })),
+                changelog: options.message,
+                agentLabel: options.agentLabel,
+                basedFileHash,
+            },
+        });
+    }
+    catch (err) {
+        handleProposeError(err, refStr, options);
+        return;
+    }
+    const own = isOwnRef(ref.username);
+    // The #proposals deep link only renders for the author, so we only print it
+    // when the proposer owns the skill. A non-author operator gets the plain
+    // "queued for review" line with no dead link.
+    const reviewUrl = own
+        ? `${getApiUrl()}/${refStr}#proposals`
+        : `${getApiUrl()}/${refStr}`;
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            ref: refStr,
+            proposalId: result.proposalId,
+            status: result.status,
+            baseVersion: result.baseVersion,
+            url: reviewUrl,
+        }));
+        return;
+    }
+    console.log(`\n  ✓ Proposal queued for ${refStr} (id ${result.proposalId}).`);
+    if (own) {
+        console.log(`    Review it at ${reviewUrl}\n`);
+    }
+    else {
+        console.log(`    The skill author will review it. ${reviewUrl}\n`);
+    }
+}
+/** Map a propose API error to a friendly, actionable CLI message.
+ *
+ * 404 — skill not found (or unreadable; the server collapses both to 404).
+ * 413 — proposal too large.
+ * 429 — per-skill OPEN cap or per-proposer/day cap; the server sends a
+ *       structured `{ error, message }` we surface.
+ * Everything else routes through the shared helper. */
+function handleProposeError(err, refStr, options) {
+    if (!(err instanceof ApiError)) {
+        throw err;
+    }
+    const body = err.body;
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: false,
+            ref: refStr,
+            status: err.status,
+            error: err.message,
+            message: body?.message ?? null,
+        }));
+        process.exit(1);
+    }
+    if (err.status === 404) {
+        console.error(`\n  ✗ Skill not found: ${refStr}\n`);
+    }
+    else if (err.status === 413) {
+        console.error(`\n  ✗ Proposal too large for ${refStr}. Trim the files and try again.\n`);
+    }
+    else if (err.status === 429) {
+        // The review queue is full or you've hit the per-day proposal limit. The
+        // server's structured message is the most specific; fall back to a generic
+        // line.
+        console.error(`\n  ✗ ${body?.message ?? 'Proposal rate limit reached — try again later.'}\n`);
+    }
+    else if (err.status === 401) {
+        console.error(`\n  ✗ ${err.message}\n`);
+    }
+    else {
+        console.error(`\n  ✗ ${refStr}: ${friendlyApiErrorDetail(err, refStr)}\n`);
+    }
+    process.exit(1);
+}

package/dist/commands/publish.d.ts

@@ -6,32 +6,32 @@ interface PublishOptions {
     license?: string;
     json?: boolean;
     noCompile?: boolean;
-    /** Skip the pre-POST y/N confirmation prompt. First-time authors don't
-     * always realize `publish` is immediate, so the path-form publish asks
-     * "Publish to public registry as @<user>/<slug>? [y/N]" by default.
-     * `--yes` bypasses it for scripted runs; `--json` skips it implicitly
-     * because JSON mode is for non-interactive consumers. */
+    /** Skip the pre-POST y/N confirmation prompt. The path-form publish asks
+     * "Add @<user>/<slug> to your library? [y/N]" by default so first-time
+     * authors realize it uploads immediately. `--yes` bypasses it for scripted
+     * runs; `--json` skips it implicitly because JSON mode is non-interactive. */
     yes?: boolean;
     /** Build the payload, print what would be published, exit 0 without POSTing.
      * Lets authors preview title/description/file list + total size before they
-     * commit to publishing. Skipped entirely on ref-form publish (toggling a
-     * draft → published flag is already cheap and reversible via `unpublish`). */
+     * commit to uploading. Skipped entirely on ref-form publish (flipping a
+     * skill's CLI-discoverable flag is already cheap and reversible via
+     * `unpublish`). */
     dryRun?: boolean;
 }
-interface FileEntry {
+export interface FileEntry {
     filename: string;
     content: string;
     sortOrder: number;
 }
 export declare function publish(source: string, options: PublishOptions): Promise<void>;
 /**
- * Toggle an existing BotDoc from draft → published via the API.
+ * Make an existing skill discoverable from the CLI (install/pull/list) via the
+ * API — sets `cli_discoverable = true` server-side. The inverse of `unpublish`.
  *
  * Called from `publish()` when the source argument looks like a ref
- * (`@user/slug` or `user/slug`) instead of a local path. Strips the
- * `draft` and `ingest:<id>` tags server-side. No prompt — moving from
- * draft to published is the natural progression, and unpublishing a
- * mistake is one CLI call away.
+ * (`@user/slug` or `user/slug`) instead of a local path. No prompt — exposing
+ * your own skill to your own CLI is harmless, and `unpublish` hides it again in
+ * one call. Skills are never public; this only controls CLI reach.
  */
 declare function publishRef(rawRef: string, options: PublishOptions): Promise<void>;
 /**
@@ -49,6 +49,8 @@ declare function publishRef(rawRef: string, options: PublishOptions): Promise<vo
  */
 declare function handlePublishToggleError(err: unknown, refLabel: string, options: PublishOptions): void;
 export { publishRef, handlePublishToggleError };
+export declare function collectFromFile(filePath: string): FileEntry[];
+export declare function collectFromDirectory(dirPath: string): FileEntry[];
 /**
  * Recursively collect publishable markdown files under `currentDir`.
  *

package/dist/commands/publish.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import AdmZip from 'adm-zip';
 import * as p from '@clack/prompts';
-import { ApiError, apiFetch, getApiUrl, friendlyApiErrorDetail } from '../lib/api.js';
+import { ApiError, apiFetch, getApiUrl, friendlyApiErrorDetail, friendlyFreeTierError } from '../lib/api.js';
 import { parseManifest } from '../lib/manifest.js';
 import { compile } from './compile.js';
 import { ecosystemDestination } from '../lib/canonical.js';
@@ -60,9 +60,9 @@ export async function publish(source, options) {
     // user isn't logged in. The 401 would otherwise only surface after the POST,
     // making large publishes feel slow and confusing.
     requireAuth(options);
-    // Ref-form (e.g. "@user/slug" or "user/slug") → toggle the published
-    // flag via the API. Path-form continues to the existing upload flow
-    // below. Overloading by argument shape (rather than introducing
+    // Ref-form (e.g. "@user/slug" or "user/slug") → make that existing skill
+    // discoverable from the CLI via the API. Path-form continues to the upload
+    // flow below. Overloading by argument shape (rather than introducing
     // `botdocs publish-ref` or a `--ref` flag) keeps the verb intuitive:
     // a user typing `botdocs publish @me/foo` doesn't have to know it's a
     // different code path under the hood.
@@ -160,11 +160,11 @@ export async function publish(source, options) {
         console.error('Description is required. Use --description "..." or set "description" in botdocs.json.');
         process.exit(1);
     }
-    // Pre-POST confirmation. Publish is immediate and pushes the skill to the
-    // public registry — first-time authors don't always know that, so we ask
-    // y/N (defaulting to N) before sending. Skipped under --yes (scripted
-    // runs that opt in) and --json (non-interactive consumers, which also
-    // gives back-compat for callers that don't have a TTY).
+    // Pre-POST confirmation. The upload is immediate (the skill lands in your
+    // library, private, discoverable from the CLI) — first-time authors don't
+    // always know that, so we ask y/N (defaulting to N) before sending. Skipped
+    // under --yes (scripted runs that opt in) and --json (non-interactive
+    // consumers, which also gives back-compat for callers that don't have a TTY).
     if (!options.yes && !options.json) {
         const auth = loadAuth();
         // requireAuth() ran first, so auth is non-null here. The fallback is
@@ -172,11 +172,11 @@ export async function publish(source, options) {
         const username = auth?.username ?? 'me';
         const slugGuess = derivePublishSlug(source);
         const confirmed = await p.confirm({
-            message: `Publish to public registry as @${username}/${slugGuess}?`,
+            message: `Add @${username}/${slugGuess} to your library? (private — discoverable from your CLI)`,
             initialValue: false,
         });
         if (p.isCancel(confirmed) || confirmed !== true) {
-            console.log('  Publish cancelled.');
+            console.log('  Cancelled.');
             return;
         }
     }
@@ -211,7 +211,7 @@ export async function publish(source, options) {
         console.log(JSON.stringify({ ...result, url: absoluteUrl }));
     }
     else {
-        console.log(`\nPublished: ${absoluteUrl}`);
+        console.log(`\nAdded to your library: ${absoluteUrl}`);
     }
 }
 /** Translate path-publish API errors into actionable CLI messages.
@@ -284,10 +284,14 @@ function handlePathPublishError(err, options) {
         console.error(`\n  ✗ ${err.message}\n`);
     }
     else {
-        // Generic 403/429/5xx — route through the shared helper so the
-        // wording matches sync/install/edit instead of leaking ApiError's raw
-        // `message` (which is often the server's error string verbatim).
-        console.error(`\n  ✗ ${friendlyApiErrorDetail(err)}\n`);
+        // Free-tier frictions (e.g. 403 skill_cap_exceeded) get an HONEST CTA
+        // from the shared mapper before the generic 403/429/5xx wording. The
+        // mapper returns null for anything it doesn't recognize, so the
+        // friendlyApiErrorDetail fallback still covers "permission denied" /
+        // "rate-limited" / server errors. Keeps the cap message identical to
+        // the one ingest/install render.
+        const friendly = friendlyFreeTierError(err);
+        console.error(`\n  ✗ ${friendly ?? friendlyApiErrorDetail(err)}\n`);
     }
     process.exit(1);
 }
@@ -302,13 +306,13 @@ function extractDetailMessage(detail) {
     return undefined;
 }
 /**
- * Toggle an existing BotDoc from draft → published via the API.
+ * Make an existing skill discoverable from the CLI (install/pull/list) via the
+ * API — sets `cli_discoverable = true` server-side. The inverse of `unpublish`.
  *
  * Called from `publish()` when the source argument looks like a ref
- * (`@user/slug` or `user/slug`) instead of a local path. Strips the
- * `draft` and `ingest:<id>` tags server-side. No prompt — moving from
- * draft to published is the natural progression, and unpublishing a
- * mistake is one CLI call away.
+ * (`@user/slug` or `user/slug`) instead of a local path. No prompt — exposing
+ * your own skill to your own CLI is harmless, and `unpublish` hides it again in
+ * one call. Skills are never public; this only controls CLI reach.
  */
 async function publishRef(rawRef, options) {
     // Preflight: same as the path-form publish. publish() already called
@@ -337,10 +341,10 @@ async function publishRef(rawRef, options) {
         return;
     }
     if (options.json) {
-        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'published' }));
+        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'cli-visible' }));
     }
     else {
-        console.log(`✓ Published ${refLabel} — visible at https://botdocs.ai/${refLabel}`);
+        console.log(`✓ ${refLabel} is now discoverable from the CLI.`);
     }
 }
 /**
@@ -460,12 +464,12 @@ function derivePublishSlug(source) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
-function collectFromFile(filePath) {
+export function collectFromFile(filePath) {
     const content = fs.readFileSync(filePath, 'utf-8');
     const filename = path.basename(filePath);
     return [{ filename, content, sortOrder: 0 }];
 }
-function collectFromDirectory(dirPath) {
+export function collectFromDirectory(dirPath) {
     const files = [];
     walkDirectory(dirPath, dirPath, files);
     files.sort((a, b) => a.sortOrder - b.sortOrder);

package/dist/commands/unpublish.d.ts

@@ -3,14 +3,14 @@ interface UnpublishOptions {
     json?: boolean;
 }
 /**
- * Set the `draft` flag back on a published BotDoc, hiding it from
- * `/explore` and 404ing the public URL for everyone except the author.
+ * Hide a skill from the CLI (sets `cli_discoverable = false` server-side): it
+ * stays in the author's web library, but `botdocs install`/`pull`/`list` can
+ * no longer see it. The inverse of `publish @user/slug`.
  *
- * Idempotent server-side — calling unpublish on something already a
- * draft is a no-op. Prompts for confirmation by default because the
- * effect is visible to anyone who had the URL bookmarked; skip with
- * `--yes` for scripting/CI. `--json` implies `--yes` so machine-driven
- * callers don't deadlock on the prompt.
+ * Idempotent server-side — hiding an already-hidden skill is a no-op. Prompts
+ * for confirmation by default (so a stray `unpublish` doesn't quietly pull a
+ * skill out of your agents); skip with `--yes` for scripting/CI. `--json`
+ * implies `--yes` so machine-driven callers don't deadlock on the prompt.
  */
 export declare function unpublish(rawRef: string, options: UnpublishOptions): Promise<void>;
 export {};

package/dist/commands/unpublish.js

@@ -3,14 +3,14 @@ import { apiFetch } from '../lib/api.js';
 import { parseRef } from '../lib/ref.js';
 import { handlePublishToggleError } from './publish.js';
 /**
- * Set the `draft` flag back on a published BotDoc, hiding it from
- * `/explore` and 404ing the public URL for everyone except the author.
+ * Hide a skill from the CLI (sets `cli_discoverable = false` server-side): it
+ * stays in the author's web library, but `botdocs install`/`pull`/`list` can
+ * no longer see it. The inverse of `publish @user/slug`.
  *
- * Idempotent server-side — calling unpublish on something already a
- * draft is a no-op. Prompts for confirmation by default because the
- * effect is visible to anyone who had the URL bookmarked; skip with
- * `--yes` for scripting/CI. `--json` implies `--yes` so machine-driven
- * callers don't deadlock on the prompt.
+ * Idempotent server-side — hiding an already-hidden skill is a no-op. Prompts
+ * for confirmation by default (so a stray `unpublish` doesn't quietly pull a
+ * skill out of your agents); skip with `--yes` for scripting/CI. `--json`
+ * implies `--yes` so machine-driven callers don't deadlock on the prompt.
  */
 export async function unpublish(rawRef, options) {
     let parsed;
@@ -25,8 +25,8 @@ export async function unpublish(rawRef, options) {
     const refLabel = `@${username}/${slug}`;
     if (!options.yes && !options.json) {
         const confirmed = await p.confirm({
-            message: `Unpublish ${refLabel}? It will be hidden from /explore and the public URL ` +
-                `will 404 for everyone except you.`,
+            message: `Hide ${refLabel} from the CLI? It stays in your web library, but ` +
+                `the CLI won't be able to install, pull, or list it.`,
             initialValue: false,
         });
         if (p.isCancel(confirmed) || !confirmed) {
@@ -45,9 +45,9 @@ export async function unpublish(rawRef, options) {
         return;
     }
     if (options.json) {
-        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'draft' }));
+        console.log(JSON.stringify({ ok: true, ref: refLabel, status: 'cli-hidden' }));
     }
     else {
-        console.log(`✓ Unpublished ${refLabel} — now hidden from /explore.`);
+        console.log(`✓ ${refLabel} is now hidden from the CLI (still in your web library).`);
     }
 }

package/dist/index.js

@@ -126,6 +126,8 @@ import { ingest, SUPPORTED_TOOLS as INGEST_SUPPORTED_TOOLS } from './commands/in
 import { checkUpdates } from './commands/check-updates.js';
 import { compile } from './commands/compile.js';
 import { edit } from './commands/edit.js';
+import { propose } from './commands/propose.js';
+import { registerProposalsCommands } from './commands/proposals.js';
 import { registerTeamCommands } from './commands/team.js';
 import { registerBackupCommands } from './commands/backups.js';
 import { undo } from './commands/undo.js';
@@ -180,7 +182,7 @@ program
 });
 program
     .command('publish <source>')
-    .description('Publish a BotDoc — pass a local path to upload, or @user/slug to mark an existing draft live')
+    .description('Add a skill to your library — pass a local path to upload, or @user/slug to make an existing skill discoverable from the CLI')
     .option('--title <title>', 'BotDoc title')
     .option('--description <description>', 'BotDoc description')
     .option('--category <category>', 'Category (knowledge_management, dev_workflow, automation, agent_config, project_scaffold, other)')
@@ -194,14 +196,14 @@ program
 });
 program
     .command('unpublish <ref>')
-    .description('Hide a published BotDoc from /explore (sets the draft flag back)')
+    .description('Hide a skill from the CLI (it stays in your web library)')
     .option('--yes', 'Skip the confirmation prompt')
     .action(async (ref, options) => {
     await unpublish(ref, { ...options, json: program.opts().json });
 });
 program
     .command('delete <ref>')
-    .description('Delete a BotDoc — drafts are hard-deleted with cascade; published BotDocs are soft-deleted (hidden, version history preserved)')
+    .description('Delete a skill — fresh skills (no installs/history) are hard-deleted with cascade; ones with history are soft-deleted (hidden, version history preserved)')
     .option('--yes', 'Skip the confirmation prompt')
     .action(async (ref, options) => {
     await deleteCmd(ref, { ...options, json: program.opts().json });
@@ -325,6 +327,19 @@ program
     .action(async (ref, opts) => {
     await edit(ref, { ...opts, json: program.opts().json });
 });
+program
+    .command('propose <ref> [path]')
+    .description('Queue a change to a skill for its author to review (instead of publishing directly)')
+    .option('--message <message>', 'Changelog describing the proposed change')
+    .option('--agent-label <label>', 'Self-reported agent identity (e.g. hermes-v2); shown to the author as unverified')
+    .action(async (ref, pathArg, opts) => {
+    await propose(ref, pathArg, { ...opts, json: program.opts().json });
+});
+// `proposals` (list, default) + its `accept` subcommand. Registered via a
+// helper (like team/backups) so the nested `accept` lives in proposals.ts —
+// `botdocs proposals @user/slug` lists; `botdocs proposals accept @user/slug
+// --id X` accepts.
+registerProposalsCommands(program);
 registerTeamCommands(program);
 registerBackupCommands(program);
 program

package/dist/lib/api.d.ts

@@ -105,4 +105,23 @@ export declare function fetchRawContent(rawUrl: string, options?: {
  * stale-token cases are 401, which is handled upstream as "Authentication
  * failed"). */
 export declare function friendlyApiErrorDetail(err: ApiError, ref?: string): string;
+/** The free-tier friction error codes the server returns in the JSON body's
+ * `error` field. Commands branch on these to print a consistent, HONEST CTA
+ * (no fake purchase flow — all accounts are free today). Kept as a union so a
+ * server-side rename breaks the mapping exactly once, here. */
+export type FreeTierErrorCode = 'device_cap_exceeded' | 'session_limit_exceeded' | 'skill_cap_exceeded' | 'library_conflict';
+/**
+ * Map a server error to a friendly, HONEST one-liner for the free-tier
+ * frictions (and the expired-token 401). Returns null when `err` isn't one of
+ * the handled cases, so callers fall back to `friendlyApiErrorDetail`.
+ *
+ * Honesty rule (locked product decision): there is NO purchase/upgrade flow.
+ * Messages communicate the free limit and point at "learn more" docs — they
+ * never promise a working checkout. Higher limits for teams are described as
+ * "coming".
+ *
+ * Centralized here so `install` / `create` / `sync` / `ingest` render the same
+ * vocabulary; a copy tweak is a single edit.
+ */
+export declare function friendlyFreeTierError(err: ApiError): string | null;
 export {};

package/dist/lib/api.js

@@ -1,4 +1,5 @@
-import { loadAuth } from './config.js';
+import os from 'node:os';
+import { loadAuth, getOrCreateDeviceId } from './config.js';
 const DEFAULT_API_URL = 'https://www.botdocs.ai';
 /** Default per-request timeout (ms). Exposed so tests can override without
  * mocking `setTimeout` globally, and so callers can read the value when
@@ -27,6 +28,23 @@ function isLocalhostUrl(u) {
 /** Track whether we've already printed the override-warning so the CLI doesn't
  * spam stderr across every API call in a single process run. */
 let overrideWarnPrinted = false;
+/** Attach the device-identity headers to an authenticated request.
+ *
+ * `X-Device-Id` is the stable per-install id (or the `BOTDOCS_DEVICE_ID`
+ * override); `X-Machine-Name` is a display-only hint the server stores on the
+ * device row. Called from the SAME choke point as the bearer so every
+ * authenticated request carries the device identity — the free-tier
+ * device/session caps depend on it. Best-effort: a failure to resolve the id
+ * (e.g. a read-only home dir) never blocks the request. */
+function attachDeviceHeaders(headers) {
+    try {
+        headers['X-Device-Id'] = getOrCreateDeviceId();
+        headers['X-Machine-Name'] = os.hostname();
+    }
+    catch {
+        // Best-effort — never fail a request because we couldn't stamp a device id.
+    }
+}
 export function getApiUrl() {
     const override = process.env.BOTDOCS_API_URL;
     if (!override)
@@ -148,6 +166,9 @@ export async function apiFetch(path, options = {}) {
         }
         else {
             headers['Authorization'] = `Bearer ${config.token}`;
+            // Same choke point as the bearer: stamp the device identity so the
+            // server's free-tier device/session gates see this request.
+            attachDeviceHeaders(headers);
         }
     }
     // AbortController + setTimeout is the lowest-overhead way to enforce a hard
@@ -245,6 +266,7 @@ export async function fetchRawContent(rawUrl, options = {}) {
     const config = loadAuth();
     if (config?.token) {
         headers['Authorization'] = `Bearer ${config.token}`;
+        attachDeviceHeaders(headers);
     }
     // Same pattern as apiFetch — AbortController + clearTimeout in finally so
     // the timer never outlives the request and blocks process exit.
@@ -302,3 +324,72 @@ export function friendlyApiErrorDetail(err, ref) {
         return err.message;
     return `request failed (${err.status})`;
 }
+/** Narrow an `ApiError.body` to the free-tier error shape when it carries one
+ * of the known codes. Returns null for any other body. */
+function asFreeTierErrorBody(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const code = body.error;
+    if (code === 'device_cap_exceeded' ||
+        code === 'session_limit_exceeded' ||
+        code === 'skill_cap_exceeded' ||
+        code === 'library_conflict') {
+        return { ...body, error: code };
+    }
+    return null;
+}
+/**
+ * Map a server error to a friendly, HONEST one-liner for the free-tier
+ * frictions (and the expired-token 401). Returns null when `err` isn't one of
+ * the handled cases, so callers fall back to `friendlyApiErrorDetail`.
+ *
+ * Honesty rule (locked product decision): there is NO purchase/upgrade flow.
+ * Messages communicate the free limit and point at "learn more" docs — they
+ * never promise a working checkout. Higher limits for teams are described as
+ * "coming".
+ *
+ * Centralized here so `install` / `create` / `sync` / `ingest` render the same
+ * vocabulary; a copy tweak is a single edit.
+ */
+export function friendlyFreeTierError(err) {
+    // Expired-token 401: the server already 401s an expired bearer; surface the
+    // re-login CTA. (Generic 401s are handled upstream in apiFetch with the same
+    // wording; this keeps the mapping in one place for callers that inspect the
+    // raw ApiError.)
+    if (err.status === 401) {
+        return 'Your session has expired. Run `botdocs login` to sign in again.';
+    }
+    const body = asFreeTierErrorBody(err.body);
+    if (!body)
+        return null;
+    switch (body.error) {
+        case 'device_cap_exceeded': {
+            const limit = body.limit;
+            const limitText = typeof limit === 'number' ? `${limit} devices` : 'a limited number of devices';
+            return (`Free accounts are limited to ${limitText}, and you've reached that limit. ` +
+                `Revoke a device you no longer use at https://botdocs.ai/settings, or set ` +
+                `BOTDOCS_DEVICE_ID to reuse one identity in CI. Higher limits for teams are coming — ` +
+                `learn more at https://botdocs.ai/teams.`);
+        }
+        case 'session_limit_exceeded': {
+            const limit = body.limit;
+            const limitText = typeof limit === 'number' ? `${limit} devices` : 'a limited number of devices';
+            return (`Free accounts can be active on ${limitText} at once, and you're over that limit right now. ` +
+                `Wait a few minutes for another device to go idle, or set BOTDOCS_DEVICE_ID to share one ` +
+                `identity in CI. Higher limits for teams are coming — learn more at https://botdocs.ai/teams.`);
+        }
+        case 'skill_cap_exceeded': {
+            const limit = body.limit;
+            const limitText = typeof limit === 'number' ? `${limit} skills` : 'a limited number of skills';
+            return (`Free accounts are limited to ${limitText}, and you've reached that limit. ` +
+                `Remove a skill you no longer need, or learn about higher limits for teams (coming soon) ` +
+                `at https://botdocs.ai/teams.`);
+        }
+        case 'library_conflict': {
+            const device = body.conflictingDevice;
+            const who = device ? ` from "${device}"` : '';
+            return (`Your library was changed by another device${who} since this one last synced. ` +
+                `Run \`botdocs sync\` to pull the latest, then retry.`);
+        }
+    }
+}