skillrepo 3.1.5 → 3.2.0

package/README.md

@@ -24,19 +24,26 @@ Requires Node.js 18 or later.
 
 ## Quick start
 
-1. **Create an access key** at [skillrepo.dev/app/settings](https://skillrepo.dev/app/settings)
-   (Settings → Access Keys).
-2. **Run `init`** inside your project directory:
+1. **Run `init`** inside your project directory:
    ```sh
    npx skillrepo init
    ```
-3. **Your library is now on disk.** The CLI wrote skills into
+   When no key is configured, `init` opens
+   [skillrepo.dev/cli/auth](https://skillrepo.dev/cli/auth) in your default
+   browser. Sign in, click **Issue CLI key**, and paste the key back into
+   the terminal. The page works headless too — copy the key from any
+   browser if your terminal can't auto-launch one.
+2. **Your library is now on disk.** The CLI wrote skills into
    `.claude/skills/` (project) and registered the MCP server with every IDE
    it detected (`.claude/`, `.cursor/`, `.vscode/`, `~/.codeium/windsurf/`).
-4. **From now on**, use `skillrepo update` to pull new versions,
+3. **From now on**, use `skillrepo update` to pull new versions,
    `skillrepo add` to add skills to your library, and `skillrepo list` to
    see what you have.
 
+> If you'd rather provision the key yourself, create one at
+> [skillrepo.dev/app/settings](https://skillrepo.dev/app/settings)
+> (Settings → Access Keys) and pass `--key <sk_live_...>` to `init`.
+
 ## Commands
 
 ### `init` — first-run setup
@@ -63,7 +70,12 @@ below), and runs the first library sync.
 `init` is idempotent: re-running with a valid existing config re-runs
 detection + MCP merge + first sync without re-prompting for a key. If the
 stored key has been revoked (401 from `/auth/validate`), the CLI falls back
-to the interactive prompt automatically.
+to the interactive prompt automatically — including opening
+[skillrepo.dev/cli/auth](https://skillrepo.dev/cli/auth) so you can mint a
+fresh key without leaving the terminal.
+
+When stdin is not a TTY (CI, piped input), `init` skips the browser launch
+and just prints the URL — paste the key via the upstream pipe.
 
 **Headless / CI:** if you run from a directory with no IDE markers, init
 will refuse and print a copy-pasteable MCP config for manual wiring. To

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "3.1.5",
+  "version": "3.2.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/init.mjs

@@ -56,6 +56,7 @@ import { installSessionSyncHook } from "./init-session-sync.mjs";
 import { resolveKeyFromEnvFiles } from "../lib/resolve-key.mjs";
 import {
   promptSecret,
+  promptWithBrowserOpen,
   confirm,
 } from "../lib/prompt.mjs";
 import {
@@ -64,6 +65,7 @@ import {
   validationError,
   EXIT_AUTH,
 } from "../lib/errors.mjs";
+import { cliAuthUrl } from "../lib/constants.mjs";
 
 // Local print helpers that use the INJECTED stdout/stderr streams.
 // The prompt.mjs `print*` helpers write to process.stdout directly,
@@ -204,7 +206,10 @@ export async function runInit(argv, io = {}, deps = {}) {
         hint: "Pass --key sk_live_... or set SKILLREPO_ACCESS_KEY.",
       });
     }
-    apiKey = await promptSecret("Enter your access key (sk_live_...)");
+    apiKey = await promptWithBrowserOpen(
+      cliAuthUrl(serverUrl),
+      "Enter your access key (sk_live_...)",
+    );
   }
 
   // Trim whitespace from the key before validating. Pasting an API
@@ -241,7 +246,12 @@ export async function runInit(argv, io = {}, deps = {}) {
       !yes
     ) {
       p.warning("Existing config has an invalid key. Re-prompting for a new one.");
-      apiKey = (await promptSecret("Enter your access key (sk_live_...)")).trim();
+      apiKey = (
+        await promptWithBrowserOpen(
+          cliAuthUrl(serverUrl),
+          "Enter your access key (sk_live_...)",
+        )
+      ).trim();
       if (!apiKey || !apiKey.startsWith("sk_live_")) {
         throw validationError("Invalid access key format.");
       }

package/src/lib/browser-open.mjs

@@ -0,0 +1,136 @@
+/**
+ * Cross-platform "open URL in the user's default browser" helper
+ * (epic #1214, Phase 2 #1217).
+ *
+ * Used by the inline auth flow (`promptWithBrowserOpen` in
+ * `prompt.mjs`) so any command that needs an access key can take the
+ * user to `https://skillrepo.dev/cli/auth` and have them paste the
+ * issued key back into the terminal.
+ *
+ * Design rules:
+ *
+ *   • Zero non-Node dependencies. Uses `child_process.spawn` with
+ *     `detached: true` + `unref()` so the spawned browser does not
+ *     keep the CLI process alive.
+ *   • Platform-specific commands are explicit, not shelled out.
+ *     `spawn(command, [url])` passes the URL as argv directly with no
+ *     shell interpolation, so URL contents (e.g., query strings with
+ *     `&`) cannot become shell metacharacters.
+ *   • Returns `true` when the spawn call succeeded synchronously,
+ *     `false` for synchronous failures (unsupported platform, URL
+ *     rejected, spawn throws). Note: when the OS reports the binary
+ *     is missing asynchronously (ENOENT via the child's `error` event
+ *     — common on minimal Linux containers without `xdg-open`), this
+ *     function still returns `true`. The `error` handler swallows the
+ *     event so it doesn't crash the CLI, but the browser window never
+ *     actually opens. Callers must always print the URL alongside the
+ *     spawn so the user has a copy/paste path that works regardless
+ *     of the async outcome.
+ *   • The URL is validated to be http(s) before launch. The constant
+ *     in `constants.mjs` is trusted, but this gate stops a future
+ *     caller from accidentally launching a `file://` or `javascript:`
+ *     URI through an OS-level handler.
+ *
+ * The `platform` and `spawnFn` parameters are injection points for
+ * tests — production callers omit them and the defaults
+ * (`process.platform` and `child_process.spawn`) take effect.
+ */
+
+import { spawn as nodeSpawn } from "node:child_process";
+
+/**
+ * Attempt to open `url` in the user's default browser.
+ *
+ * @param {string} url - HTTP(S) URL to open.
+ * @param {object} [options]
+ * @param {NodeJS.Platform} [options.platform] - Override for tests.
+ * @param {typeof nodeSpawn} [options.spawnFn] - Override for tests.
+ * @returns {boolean} `true` if a browser process was spawned,
+ *   `false` if the platform is unsupported, the URL is rejected,
+ *   or the spawn failed.
+ */
+export function openBrowser(url, { platform, spawnFn } = {}) {
+  if (!isLaunchableUrl(url)) return false;
+
+  const plat = platform ?? process.platform;
+  const spawnImpl = spawnFn ?? nodeSpawn;
+
+  const launch = resolveLaunchCommand(plat, url);
+  if (!launch) return false;
+
+  try {
+    const child = spawnImpl(launch.command, launch.args, {
+      detached: true,
+      stdio: "ignore",
+    });
+    // If the command is missing entirely (ENOENT), Node emits an
+    // `error` event asynchronously. Swallow it so it doesn't bubble
+    // up as an unhandled exception — the caller already chose to
+    // treat openBrowser failure as a soft signal.
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reject anything that isn't a normal http(s) URL. The auth flow
+ * only ever passes the SkillRepo cloud URL, but defensive validation
+ * here means a future regression that points this helper at a
+ * `javascript:` or `file:` URL doesn't silently launch through the
+ * OS handler.
+ *
+ * @param {string} url
+ * @returns {boolean}
+ */
+function isLaunchableUrl(url) {
+  if (typeof url !== "string" || url.length === 0) return false;
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Map a Node platform string to the OS command that opens a URL.
+ * Returns `null` for unsupported platforms (the caller falls back to
+ * printing the URL).
+ *
+ * @param {NodeJS.Platform} platform
+ * @param {string} url
+ * @returns {{ command: string, args: string[] } | null}
+ */
+function resolveLaunchCommand(platform, url) {
+  if (platform === "darwin") {
+    return { command: "open", args: [url] };
+  }
+  if (platform === "win32") {
+    // `start` is a cmd.exe builtin, not a real binary. The empty-string
+    // first argument becomes the window title — without it, a URL
+    // wrapped in quotes would be consumed as the title and never
+    // launched. We pass an EMPTY JS string `""` (zero characters)
+    // rather than the literal two-character `'""'`: with `shell: false`,
+    // Node's argv→command-line conversion emits an empty string as the
+    // four-char sequence `""` on the wire, which is what `start`
+    // expects. Passing the literal two-quote string round-trips through
+    // CRT escaping as `\"\"` and confuses `start`'s argument parser.
+    // This matches the canonical pattern used by the `open` npm package.
+    return { command: "cmd.exe", args: ["/c", "start", "", url] };
+  }
+  // linux, freebsd, openbsd, sunos, ... → xdg-open is the freedesktop
+  // standard. If it's missing, the spawn-error path returns false.
+  if (
+    platform === "linux" ||
+    platform === "freebsd" ||
+    platform === "openbsd" ||
+    platform === "sunos" ||
+    platform === "aix"
+  ) {
+    return { command: "xdg-open", args: [url] };
+  }
+  return null;
+}

package/src/lib/constants.mjs

@@ -0,0 +1,69 @@
+/**
+ * Cross-cutting CLI constants. Single source of truth for URLs and
+ * other values that would otherwise drift across modules.
+ *
+ * Keep this file dependency-free — modules at every layer import from
+ * here, so a transitive dependency would risk import cycles.
+ */
+
+/**
+ * The browser-assisted CLI auth page (epic #1214, Phases 1 #1216 +
+ * 3 #1218).
+ *
+ * The CLI is cloud-only today, so the production default URL is
+ * baked in. But users running against staging (or any non-default
+ * --url) should see a hint URL pointing at the matching host —
+ * otherwise a 401 hint that says "open https://skillrepo.dev/cli/auth"
+ * is wrong when they're actually authed against staging.skillrepo.dev.
+ *
+ * `cliAuthUrl(serverUrl)` derives the auth URL from a server URL,
+ * preserving the host. Callers that already have the active
+ * serverUrl in scope (every public http.mjs function does) should
+ * use the helper. Callers without context fall back to
+ * `DEFAULT_CLI_AUTH_URL`.
+ *
+ * Query params (Phase 3, #1218):
+ *
+ *   • `source=cli` — distinguishes CLI-driven traffic from manual
+ *     browser visits. The page uses this to gate the auto-mint
+ *     behavior; without it, the page renders the deliberate
+ *     "Issue CLI key" button.
+ *   • `new=1` — the CLI's signal that it has no working key locally.
+ *     The page reads this to immediately attempt a mint on load
+ *     (rather than waiting for a click). On `quota_exceeded` the
+ *     page falls into the rotate flow.
+ *
+ * Both params are advisory — the page is server-side authenticated
+ * and authorized regardless. Spoofing the params just affects UX
+ * immediacy, not authorization.
+ */
+const DEFAULT_CLI_AUTH_HOST = "https://skillrepo.dev";
+const CLI_AUTH_PATH = "/cli/auth";
+const CLI_AUTH_QUERY = "?source=cli&new=1";
+
+/**
+ * Derive the auth URL for the given server URL. Preserves the
+ * server's host so the hint tells users "open <the server you're
+ * actually using>/cli/auth" rather than always pointing at prod.
+ *
+ * @param {string | null | undefined} serverUrl
+ *   Server URL the CLI is authenticated against. Trailing slashes
+ *   are stripped. `null` / `undefined` / empty string fall back to
+ *   the production host.
+ * @returns {string} Full auth URL with the auto-mint hint params.
+ */
+export function cliAuthUrl(serverUrl) {
+  const base =
+    typeof serverUrl === "string" && serverUrl.trim() !== ""
+      ? serverUrl.replace(/\/+$/, "")
+      : DEFAULT_CLI_AUTH_HOST;
+  return `${base}${CLI_AUTH_PATH}${CLI_AUTH_QUERY}`;
+}
+
+/**
+ * Default auth URL pointing at production. Used in error paths that
+ * have no serverUrl context (e.g. the `authHeaders` no-key guard
+ * before any flag has been resolved). Prefer `cliAuthUrl(serverUrl)`
+ * everywhere a serverUrl is in scope.
+ */
+export const DEFAULT_CLI_AUTH_URL = cliAuthUrl(DEFAULT_CLI_AUTH_HOST);

package/src/lib/http.mjs

@@ -29,6 +29,7 @@ import {
   validationError,
   withRetry,
 } from "./errors.mjs";
+import { cliAuthUrl, DEFAULT_CLI_AUTH_URL } from "./constants.mjs";
 
 const DEFAULT_URL = "https://skillrepo.dev";
 
@@ -117,13 +118,13 @@ async function authHeaders(apiKey) {
   // path through authHeaders produces a clean Bearer header.
   if (typeof apiKey !== "string") {
     throw authError("No access key configured.", {
-      hint: "Run `skillrepo init` or pass --key <sk_live_...>.",
+      hint: `Run \`skillrepo init\`, pass --key <sk_live_...>, or open ${DEFAULT_CLI_AUTH_URL} to mint a new access key.`,
     });
   }
   const trimmed = apiKey.trim();
   if (trimmed === "") {
     throw authError("No access key configured.", {
-      hint: "Run `skillrepo init` or pass --key <sk_live_...>.",
+      hint: `Run \`skillrepo init\`, pass --key <sk_live_...>, or open ${DEFAULT_CLI_AUTH_URL} to mint a new access key.`,
     });
   }
   return {
@@ -302,8 +303,21 @@ async function mapErrorResponse(res, url) {
   const code = body.code;
 
   if (res.status === 401) {
+    // Derive the auth URL from the request URL's origin so users
+    // running against staging see a staging hint, not a prod hint.
+    // `url` here is the full request URL (e.g.
+    // https://staging.skillrepo.dev/api/v1/library); `new URL(...).origin`
+    // gives us "https://staging.skillrepo.dev" which is what
+    // `cliAuthUrl` expects.
+    let authUrl = DEFAULT_CLI_AUTH_URL;
+    try {
+      authUrl = cliAuthUrl(new URL(url).origin);
+    } catch {
+      // URL parse failure shouldn't happen — `safeFetch` already
+      // validated. Fall back to the prod default.
+    }
     return authError(message, {
-      hint: "Run `skillrepo init` to refresh your access key.",
+      hint: `Run \`skillrepo init\` or open ${authUrl} in your browser to get a new access key.`,
     });
   }
   if (res.status === 403) {

package/src/lib/prompt.mjs

@@ -1,6 +1,11 @@
 /**
- * Interactive prompts using Node's built-in readline.
- * Zero dependencies. Supports TTY detection and NO_COLOR.
+ * Interactive prompts using Node's built-in readline. Supports TTY
+ * detection and NO_COLOR.
+ *
+ * Dependencies: `node:readline` and `./browser-open.mjs` (used by
+ * `promptWithBrowserOpen` to spawn the system browser).
+ * `browser-open.mjs` itself depends only on `node:child_process`, so
+ * the full transitive surface remains node-builtins-only.
  *
  * v3.0.0 cleanup (PR4 cross-review): the old v2.0.0 print helpers
  * (printHeader, printStep, printSuccess, printWarning, printError,
@@ -9,13 +14,16 @@
  * the stream-injection pattern every v3.0.0 command uses for
  * testability. `init.mjs` defines its own `makePrinter` helper that
  * ties into the injected io.stdout/io.stderr streams; every other
- * command uses the same pattern. This module now only exports the
- * three interactive primitives (`promptText`, `promptSecret`,
- * `confirm`) that still need direct stdin/stdout access.
+ * command uses the same pattern. This module exports the interactive
+ * primitives (`promptText`, `promptSecret`, `confirm`) that need
+ * direct stdin/stdout access, plus `promptWithBrowserOpen` (epic
+ * #1214 Phase 2 #1217) for the browser-assisted auth flow.
  */
 
 import { createInterface } from "node:readline";
 
+import { openBrowser } from "./browser-open.mjs";
+
 const isTTY = process.stdout.isTTY && !process.env.NO_COLOR;
 const dim = (s) => (isTTY ? `\x1b[2m${s}\x1b[0m` : s);
 
@@ -89,6 +97,74 @@ export function promptSecret(question) {
   });
 }
 
+/**
+ * Browser-assisted variant of `promptSecret` (epic #1214 Phase 2,
+ * issue #1217). Opens the user's default browser to `url` so they can
+ * sign in, mint a CLI key, and paste it back into the terminal.
+ *
+ * Behavior:
+ *
+ *   • Always prints the URL on its own line first. The browser-open
+ *     attempt is a convenience — the URL print is the contract, so the
+ *     user can copy/paste even when the spawn silently fails (sandboxed
+ *     containers, SSH sessions without `xdg-open`, etc.).
+ *   • Skips the browser launch when `process.stdin.isTTY` is false.
+ *     A pipe/CI invocation that hits this prompt has no human to read
+ *     the spawned browser, and `start` / `xdg-open` would fail or
+ *     produce noise. The pasted-token capture below still works for
+ *     piped stdin via `promptSecret`'s non-TTY branch.
+ *   • Delegates to `promptSecret(label)` for capture so the existing
+ *     no-echo / Ctrl-C / backspace UX is preserved.
+ *
+ * The `openBrowserFn`, `isInteractive`, `stdout`, and `promptSecretFn`
+ * parameters are injection points for tests — production callers omit
+ * them.
+ *
+ * @param {string} url - HTTP(S) URL to open in the browser.
+ * @param {string} label - Prompt label for `promptSecret`.
+ * @param {object} [options]
+ * @param {(url: string) => boolean} [options.openBrowserFn] - Override for tests.
+ * @param {() => boolean} [options.isInteractive] - Override for tests.
+ * @param {NodeJS.WritableStream} [options.stdout] - Output stream
+ *   (defaults to `process.stdout`). Tests inject a buffer here.
+ * @param {(label: string) => Promise<string>} [options.promptSecretFn] -
+ *   Override for tests so the secret-capture path can be exercised
+ *   without driving `process.stdin`.
+ * @returns {Promise<string>} The pasted access key.
+ */
+export async function promptWithBrowserOpen(
+  url,
+  label,
+  {
+    openBrowserFn = openBrowser,
+    isInteractive = () => Boolean(process.stdin.isTTY),
+    stdout = process.stdout,
+    promptSecretFn = promptSecret,
+  } = {},
+) {
+  // Fail loudly on a bad URL rather than silently rendering "undefined"
+  // to the terminal. The only production caller passes the constant
+  // from `constants.mjs`, but a future caller (or a typo) shouldn't
+  // produce a confusing UI line.
+  if (typeof url !== "string" || url.length === 0) {
+    throw new TypeError("promptWithBrowserOpen: `url` must be a non-empty string");
+  }
+  stdout.write(`  Opening browser for authentication:\n  ${url}\n`);
+  if (isInteractive()) {
+    const opened = openBrowserFn(url);
+    if (!opened) {
+      stdout.write(
+        "  Could not open the browser automatically — open the URL above manually.\n",
+      );
+    }
+  } else {
+    stdout.write(
+      "  Non-interactive session — open the URL above in a browser to mint a key.\n",
+    );
+  }
+  return promptSecretFn(label);
+}
+
 /**
  * y/n confirmation.
  */

package/src/test/lib/browser-open.test.mjs

@@ -0,0 +1,187 @@
+/**
+ * Unit tests for src/lib/browser-open.mjs (epic #1214 Phase 2 #1217).
+ *
+ * No real browsers spawn here — every test injects a `spawnFn` stub
+ * and asserts on the recorded command/args. The injected `platform`
+ * argument lets a single host (CI runs on macOS) cover the win32 and
+ * linux branches deterministically.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { openBrowser } from "../../lib/browser-open.mjs";
+
+/**
+ * Build a stub spawnFn that records every call and returns a fake
+ * child-process handle. The handle implements only the surface
+ * `openBrowser` actually uses: `on(event, handler)` and `unref()`.
+ */
+function makeSpawnStub({ throwOnSpawn = false, emitError = false } = {}) {
+  const calls = [];
+  const handlers = [];
+  function spawnFn(command, args, options) {
+    calls.push({ command, args, options });
+    if (throwOnSpawn) {
+      throw new Error("spawn ENOENT");
+    }
+    const child = {
+      on(event, handler) {
+        handlers.push({ event, handler });
+        if (emitError && event === "error") {
+          // emit synchronously so the test sees it before the
+          // openBrowser call returns
+          handler(new Error("ENOENT"));
+        }
+      },
+      unref() {},
+    };
+    return child;
+  }
+  return { spawnFn, calls, handlers };
+}
+
+describe("openBrowser", () => {
+  it("uses `open` on darwin", () => {
+    const { spawnFn, calls } = makeSpawnStub();
+    const result = openBrowser("https://skillrepo.dev/cli/auth", {
+      platform: "darwin",
+      spawnFn,
+    });
+    assert.equal(result, true);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].command, "open");
+    assert.deepEqual(calls[0].args, ["https://skillrepo.dev/cli/auth"]);
+    assert.equal(calls[0].options.detached, true);
+    assert.equal(calls[0].options.stdio, "ignore");
+  });
+
+  it("uses `xdg-open` on linux", () => {
+    const { spawnFn, calls } = makeSpawnStub();
+    const result = openBrowser("https://skillrepo.dev/cli/auth", {
+      platform: "linux",
+      spawnFn,
+    });
+    assert.equal(result, true);
+    assert.equal(calls[0].command, "xdg-open");
+    assert.deepEqual(calls[0].args, ["https://skillrepo.dev/cli/auth"]);
+  });
+
+  it("uses `cmd.exe /c start` on win32 with EMPTY-string title arg", () => {
+    // The third arg MUST be the empty JS string `""` (zero chars), NOT
+    // the literal two-quote `'""'`. Node's argv→cmdline CRT escaping
+    // emits an empty string as `""` on the wire, which is what cmd.exe
+    // `start` expects. Passing `'""'` would round-trip as `\"\"` and
+    // break `start`'s argument parser. Pin the exact zero-length char
+    // so a future regression is caught.
+    const { spawnFn, calls } = makeSpawnStub();
+    const result = openBrowser("https://skillrepo.dev/cli/auth", {
+      platform: "win32",
+      spawnFn,
+    });
+    assert.equal(result, true);
+    assert.equal(calls[0].command, "cmd.exe");
+    assert.deepEqual(calls[0].args, [
+      "/c",
+      "start",
+      "",
+      "https://skillrepo.dev/cli/auth",
+    ]);
+    assert.equal(calls[0].args[2].length, 0, "title arg must be zero-length");
+  });
+
+  it("uses xdg-open on freebsd / openbsd / sunos / aix", () => {
+    for (const platform of ["freebsd", "openbsd", "sunos", "aix"]) {
+      const { spawnFn, calls } = makeSpawnStub();
+      const result = openBrowser("https://skillrepo.dev/cli/auth", {
+        platform,
+        spawnFn,
+      });
+      assert.equal(result, true, `${platform} should spawn`);
+      assert.equal(calls[0].command, "xdg-open");
+    }
+  });
+
+  it("returns false on unsupported platforms without spawning", () => {
+    const { spawnFn, calls } = makeSpawnStub();
+    const result = openBrowser("https://skillrepo.dev/cli/auth", {
+      platform: "haiku",
+      spawnFn,
+    });
+    assert.equal(result, false);
+    assert.equal(calls.length, 0);
+  });
+
+  it("returns false when spawn throws", () => {
+    const { spawnFn, calls } = makeSpawnStub({ throwOnSpawn: true });
+    const result = openBrowser("https://skillrepo.dev/cli/auth", {
+      platform: "darwin",
+      spawnFn,
+    });
+    assert.equal(result, false);
+    assert.equal(calls.length, 1);
+  });
+
+  it("registers an error handler so post-spawn ENOENT is swallowed", () => {
+    // The spawn returns a child but the OS reports the binary is
+    // missing asynchronously via an `error` event. Without a
+    // registered handler this would crash the CLI.
+    const { spawnFn, handlers } = makeSpawnStub({ emitError: true });
+    const result = openBrowser("https://skillrepo.dev/cli/auth", {
+      platform: "linux",
+      spawnFn,
+    });
+    // Spawn succeeded → returns true; the error event was registered
+    // and silently absorbed.
+    assert.equal(result, true);
+    const errorHandlers = handlers.filter((h) => h.event === "error");
+    assert.equal(errorHandlers.length, 1);
+  });
+
+  it("rejects non-string url", () => {
+    const { spawnFn, calls } = makeSpawnStub();
+    for (const bogus of [undefined, null, 42, {}, ""]) {
+      const result = openBrowser(bogus, { platform: "darwin", spawnFn });
+      assert.equal(result, false, `should reject ${JSON.stringify(bogus)}`);
+    }
+    assert.equal(calls.length, 0);
+  });
+
+  it("rejects javascript: and file: URIs to prevent OS-handler abuse", () => {
+    const { spawnFn, calls } = makeSpawnStub();
+    for (const url of [
+      "javascript:alert(1)",
+      "file:///etc/passwd",
+      "data:text/html,<script>alert(1)</script>",
+      "ftp://example.com",
+      "not-a-url",
+    ]) {
+      const result = openBrowser(url, { platform: "darwin", spawnFn });
+      assert.equal(result, false, `should reject ${url}`);
+    }
+    assert.equal(calls.length, 0);
+  });
+
+  it("accepts http:// URLs", () => {
+    const { spawnFn, calls } = makeSpawnStub();
+    const result = openBrowser("http://localhost:3000/cli/auth", {
+      platform: "darwin",
+      spawnFn,
+    });
+    assert.equal(result, true);
+    assert.equal(calls[0].args[0], "http://localhost:3000/cli/auth");
+  });
+
+  it("does not set `shell` (URL must not be shell-interpreted)", () => {
+    // Stronger than `notEqual(shell, true)`: `shell` must be absent.
+    // If a future refactor sets `shell: false` (still safe) the test
+    // passes; if it sets `shell: "/bin/bash"` (unsafe — re-parses URL)
+    // this catches it.
+    const { spawnFn, calls } = makeSpawnStub();
+    openBrowser("https://skillrepo.dev/cli/auth?a=1&b=2", {
+      platform: "darwin",
+      spawnFn,
+    });
+    assert.equal(calls[0].options.shell, undefined);
+  });
+});

package/src/test/lib/constants.test.mjs

@@ -0,0 +1,93 @@
+/**
+ * Unit tests for src/lib/constants.mjs (epic #1214 Phase 3 #1218
+ * follow-up).
+ *
+ * The `cliAuthUrl(serverUrl)` helper has three distinct branches —
+ * production fallback, normal-host pass-through, and trailing-slash
+ * stripping. Coverage was previously indirect via http.mjs tests;
+ * this file pins each branch directly so a refactor of `cliAuthUrl`
+ * can't silently regress without surfacing here.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  cliAuthUrl,
+  DEFAULT_CLI_AUTH_URL,
+} from "../../lib/constants.mjs";
+
+describe("cliAuthUrl", () => {
+  it("returns the production-default URL when serverUrl is null", () => {
+    assert.equal(cliAuthUrl(null), DEFAULT_CLI_AUTH_URL);
+  });
+
+  it("returns the production-default URL when serverUrl is undefined", () => {
+    assert.equal(cliAuthUrl(undefined), DEFAULT_CLI_AUTH_URL);
+  });
+
+  it("returns the production-default URL when serverUrl is empty string", () => {
+    assert.equal(cliAuthUrl(""), DEFAULT_CLI_AUTH_URL);
+  });
+
+  it("returns the production-default URL when serverUrl is whitespace-only", () => {
+    // Whitespace-only is not a meaningful server URL; the helper
+    // should fall back to prod rather than producing
+    // "  /cli/auth?source=cli&new=1".
+    assert.equal(cliAuthUrl("   "), DEFAULT_CLI_AUTH_URL);
+  });
+
+  it("preserves the host when serverUrl is a normal URL", () => {
+    assert.equal(
+      cliAuthUrl("https://staging.skillrepo.dev"),
+      "https://staging.skillrepo.dev/cli/auth?source=cli&new=1",
+    );
+  });
+
+  it("strips a single trailing slash", () => {
+    assert.equal(
+      cliAuthUrl("https://staging.skillrepo.dev/"),
+      "https://staging.skillrepo.dev/cli/auth?source=cli&new=1",
+    );
+  });
+
+  it("strips multiple trailing slashes", () => {
+    assert.equal(
+      cliAuthUrl("https://staging.skillrepo.dev///"),
+      "https://staging.skillrepo.dev/cli/auth?source=cli&new=1",
+    );
+  });
+
+  it("preserves an explicit port", () => {
+    assert.equal(
+      cliAuthUrl("http://localhost:3000"),
+      "http://localhost:3000/cli/auth?source=cli&new=1",
+    );
+  });
+
+  it("includes the auto-mint hint params (source=cli&new=1)", () => {
+    // Pin the exact param shape — both the page and the CLI
+    // depend on this contract. If either side changes, both must
+    // agree. This test catches drift if `cliAuthUrl` ever stops
+    // emitting one of the params.
+    const url = cliAuthUrl("https://example.com");
+    const parsed = new URL(url);
+    assert.equal(parsed.searchParams.get("source"), "cli");
+    assert.equal(parsed.searchParams.get("new"), "1");
+    assert.equal(parsed.pathname, "/cli/auth");
+  });
+});
+
+describe("DEFAULT_CLI_AUTH_URL", () => {
+  it("points at the production host", () => {
+    const parsed = new URL(DEFAULT_CLI_AUTH_URL);
+    assert.equal(parsed.host, "skillrepo.dev");
+    assert.equal(parsed.protocol, "https:");
+  });
+
+  it("includes the auto-mint hint params", () => {
+    const parsed = new URL(DEFAULT_CLI_AUTH_URL);
+    assert.equal(parsed.searchParams.get("source"), "cli");
+    assert.equal(parsed.searchParams.get("new"), "1");
+  });
+});

package/src/test/lib/http.test.mjs

@@ -375,6 +375,69 @@ describe("validateAccessKey", () => {
     );
   });
 
+  it("hint on missing apiKey points users at the /cli/auth browser flow (#1217)", async () => {
+    // Phase 2 of the API Access Integrity v2 epic added an inline
+    // browser-assisted auth path. The upfront-no-key error must
+    // surface that path so users get unstuck without running
+    // `skillrepo init` first.
+    await assert.rejects(
+      () => validateAccessKey("http://127.0.0.1:1", ""),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_AUTH &&
+        typeof err.hint === "string" &&
+        err.hint.includes("https://skillrepo.dev/cli/auth"),
+    );
+  });
+
+  it("401 hint points users at the /cli/auth browser flow (#1217)", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 401, { error: "Invalid access key" }),
+    );
+    try {
+      await assert.rejects(
+        () => validateAccessKey(srv.url, VALID_KEY),
+        (err) =>
+          err instanceof CliError &&
+          err.exitCode === EXIT_AUTH &&
+          typeof err.hint === "string" &&
+          err.hint.includes("/cli/auth?source=cli&new=1"),
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  // Phase 3 follow-up (verification on staging): the 401 hint URL
+  // should reflect the SERVER the CLI is talking to, not always the
+  // production host. A user authed against staging.skillrepo.dev who
+  // hits 401 should see "open https://staging.skillrepo.dev/cli/auth"
+  // — pointing them to the prod auth page would make them mint a
+  // prod key against the wrong account.
+  it("401 hint URL host matches the request URL host (not always prod)", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 401, { error: "x" }),
+    );
+    try {
+      await assert.rejects(
+        () => validateAccessKey(srv.url, VALID_KEY),
+        (err) => {
+          if (!(err instanceof CliError) || err.exitCode !== EXIT_AUTH) {
+            return false;
+          }
+          if (typeof err.hint !== "string") return false;
+          // Test server is at http://127.0.0.1:<port>; the hint
+          // should derive its auth URL from THAT host, not from the
+          // hardcoded prod default.
+          const expectedAuthUrl = `${srv.url}/cli/auth?source=cli&new=1`;
+          return err.hint.includes(expectedAuthUrl);
+        },
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
   it("rejects empty serverUrl with validationError", async () => {
     await assert.rejects(
       () => validateAccessKey("", VALID_KEY),

package/src/test/lib/prompt.test.mjs

@@ -0,0 +1,154 @@
+/**
+ * Unit tests for `promptWithBrowserOpen` in src/lib/prompt.mjs
+ * (epic #1214 Phase 2 #1217).
+ *
+ * The pre-existing `promptSecret`/`promptText`/`confirm` helpers are
+ * not covered here — they drive `process.stdin` in raw mode and
+ * already have indirect coverage via the dispatcher tests. This file
+ * is scoped to the new browser-assisted helper, which is fully
+ * testable through dependency injection.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { promptWithBrowserOpen } from "../../lib/prompt.mjs";
+
+/**
+ * Build a writable-stream stub that captures every chunk as a string.
+ */
+function makeStdoutStub() {
+  const chunks = [];
+  return {
+    stream: {
+      write(chunk) {
+        chunks.push(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+        return true;
+      },
+    },
+    get text() {
+      return chunks.join("");
+    },
+  };
+}
+
+describe("promptWithBrowserOpen", () => {
+  it("prints the URL on its own line before prompting", async () => {
+    const stdout = makeStdoutStub();
+    await promptWithBrowserOpen("https://skillrepo.dev/cli/auth", "Key", {
+      openBrowserFn: () => true,
+      isInteractive: () => true,
+      stdout: stdout.stream,
+      promptSecretFn: () => Promise.resolve("sk_live_token"),
+    });
+    assert.match(stdout.text, /Opening browser for authentication:/);
+    assert.match(stdout.text, /https:\/\/skillrepo\.dev\/cli\/auth/);
+  });
+
+  it("returns the pasted token from promptSecretFn", async () => {
+    const stdout = makeStdoutStub();
+    const token = await promptWithBrowserOpen(
+      "https://skillrepo.dev/cli/auth",
+      "Enter key",
+      {
+        openBrowserFn: () => true,
+        isInteractive: () => true,
+        stdout: stdout.stream,
+        promptSecretFn: () => Promise.resolve("sk_live_pasted_value"),
+      },
+    );
+    assert.equal(token, "sk_live_pasted_value");
+  });
+
+  it("forwards the label to promptSecretFn", async () => {
+    const stdout = makeStdoutStub();
+    let receivedLabel = null;
+    await promptWithBrowserOpen("https://skillrepo.dev/cli/auth", "MY-LABEL", {
+      openBrowserFn: () => true,
+      isInteractive: () => true,
+      stdout: stdout.stream,
+      promptSecretFn: (label) => {
+        receivedLabel = label;
+        return Promise.resolve("");
+      },
+    });
+    assert.equal(receivedLabel, "MY-LABEL");
+  });
+
+  it("calls openBrowserFn when stdin is a TTY", async () => {
+    const stdout = makeStdoutStub();
+    let openCalls = 0;
+    let receivedUrl = null;
+    await promptWithBrowserOpen("https://skillrepo.dev/cli/auth", "Key", {
+      openBrowserFn: (url) => {
+        openCalls++;
+        receivedUrl = url;
+        return true;
+      },
+      isInteractive: () => true,
+      stdout: stdout.stream,
+      promptSecretFn: () => Promise.resolve(""),
+    });
+    assert.equal(openCalls, 1);
+    assert.equal(receivedUrl, "https://skillrepo.dev/cli/auth");
+  });
+
+  it("skips openBrowserFn entirely when stdin is NOT a TTY (CI/pipe)", async () => {
+    const stdout = makeStdoutStub();
+    let openCalls = 0;
+    await promptWithBrowserOpen("https://skillrepo.dev/cli/auth", "Key", {
+      openBrowserFn: () => {
+        openCalls++;
+        return true;
+      },
+      isInteractive: () => false,
+      stdout: stdout.stream,
+      promptSecretFn: () => Promise.resolve(""),
+    });
+    assert.equal(openCalls, 0, "openBrowser must not be called in non-TTY");
+    assert.match(stdout.text, /Non-interactive session/);
+  });
+
+  it("prints a graceful fallback when openBrowserFn returns false", async () => {
+    const stdout = makeStdoutStub();
+    await promptWithBrowserOpen("https://skillrepo.dev/cli/auth", "Key", {
+      openBrowserFn: () => false,
+      isInteractive: () => true,
+      stdout: stdout.stream,
+      promptSecretFn: () => Promise.resolve(""),
+    });
+    assert.match(stdout.text, /Could not open the browser automatically/);
+    // The URL is still printed first, so the user has something to copy.
+    assert.match(stdout.text, /https:\/\/skillrepo\.dev\/cli\/auth/);
+  });
+
+  it("rejects with TypeError on a bogus url (fails loudly, no `undefined` in UI)", async () => {
+    const stdout = makeStdoutStub();
+    for (const bogus of [undefined, null, 0, {}, "", false]) {
+      await assert.rejects(
+        () =>
+          promptWithBrowserOpen(bogus, "Key", {
+            openBrowserFn: () => true,
+            isInteractive: () => true,
+            stdout: stdout.stream,
+            promptSecretFn: () => Promise.resolve(""),
+          }),
+        TypeError,
+        `should reject ${JSON.stringify(bogus)}`,
+      );
+    }
+    // Nothing should have been written — the guard fires before any I/O.
+    assert.equal(stdout.text, "");
+  });
+
+  it("does NOT print the fallback message when openBrowser succeeds", async () => {
+    const stdout = makeStdoutStub();
+    await promptWithBrowserOpen("https://skillrepo.dev/cli/auth", "Key", {
+      openBrowserFn: () => true,
+      isInteractive: () => true,
+      stdout: stdout.stream,
+      promptSecretFn: () => Promise.resolve(""),
+    });
+    assert.doesNotMatch(stdout.text, /Could not open the browser automatically/);
+  });
+});