@hraness/wordcell 0.22.4 → 0.23.0

package/src/cli-style.ts

@@ -0,0 +1,132 @@
+/**
+ * Terminal style for human CLI output: status symbols with ASCII fallbacks,
+ * symbol-only color, and the shared audience rule.
+ *
+ * TODO(df-0.8): use detectAudience and cli-style from @hraness/desktop-foundation
+ * once 0.8.0 is released. This file copies the Hraness CLI style contract
+ * (SPEC § C and § D6) verbatim so the output already matches it.
+ */
+
+export type TerminalEnvironment = Readonly<Record<string, string | undefined>>;
+
+export type CliSymbol = "ok" | "fail" | "warn" | "next" | "on" | "off" | "skip" | "progress" | "notice";
+
+const UNICODE_SYMBOLS: Readonly<Record<CliSymbol, string>> = {
+  ok: "✓",
+  fail: "✗",
+  warn: "⚠",
+  next: "→",
+  on: "●",
+  off: "○",
+  skip: "–",
+  progress: "↻",
+  notice: "🔐",
+};
+
+const ASCII_SYMBOLS: Readonly<Record<CliSymbol, string>> = {
+  ok: "OK",
+  fail: "FAIL",
+  warn: "WARN",
+  next: "->",
+  on: "*",
+  off: "o",
+  skip: "-",
+  progress: "...",
+  notice: "NOTE",
+};
+
+const SYMBOL_COLORS: Readonly<Partial<Record<CliSymbol, string>>> = {
+  ok: "32",
+  fail: "31",
+  warn: "33",
+  next: "2",
+  on: "32",
+  skip: "2",
+};
+
+export type TerminalStyle = {
+  readonly ascii: boolean;
+  readonly color: boolean;
+};
+
+function nonEmpty(value: string | undefined): value is string {
+  return value !== undefined && value !== "";
+}
+
+/** ASCII fallbacks apply for `TERM=dumb`, `HRANESS_ASCII=1`, or a locale that does not name UTF-8. */
+export function prefersAscii(env: TerminalEnvironment): boolean {
+  if (env.TERM === "dumb" || env.HRANESS_ASCII === "1") return true;
+  const locale = [env.LC_ALL, env.LC_CTYPE, env.LANG].find(nonEmpty);
+  return locale === undefined || !/utf-?8/iu.test(locale);
+}
+
+/** Color only on a terminal that is not `dumb` and when `NO_COLOR` is unset or empty; `FORCE_COLOR=1` forces it. */
+export function prefersColor(env: TerminalEnvironment, isTTY: boolean): boolean {
+  if (env.FORCE_COLOR === "1") return true;
+  if (nonEmpty(env.NO_COLOR)) return false;
+  return isTTY && env.TERM !== "dumb";
+}
+
+export function terminalStyle(env: TerminalEnvironment, isTTY: boolean): TerminalStyle {
+  return { ascii: prefersAscii(env), color: prefersColor(env, isTTY) };
+}
+
+/** One status symbol. Only the symbol is ever colored, never the sentence. */
+export function symbol(name: CliSymbol, style: TerminalStyle): string {
+  const glyph = style.ascii ? ASCII_SYMBOLS[name] : UNICODE_SYMBOLS[name];
+  const color = SYMBOL_COLORS[name];
+  return style.color && color !== undefined ? `\u001b[${color}m${glyph}\u001b[0m` : glyph;
+}
+
+export type Audience = "human" | "agent" | "quiet";
+
+const AGENT_MARKERS = [
+  "AI_AGENT",
+  "CLAUDECODE",
+  "CODEX_SANDBOX",
+  "CODEX_SANDBOX_NETWORK_DISABLED",
+  "CURSOR_AGENT",
+  "GEMINI_CLI",
+] as const;
+
+/**
+ * Who reads stderr: `HRANESS_AUDIENCE` wins, then exact agent markers, then a
+ * terminal on stderr means a person, and anything else stays quiet.
+ */
+export function detectAudience(env: TerminalEnvironment, stderrIsTTY: boolean): Audience {
+  const explicit = env.HRANESS_AUDIENCE;
+  if (explicit === "human" || explicit === "agent" || explicit === "quiet") return explicit;
+  if (explicit === "off") return "quiet";
+  if (AGENT_MARKERS.some((marker) => nonEmpty(env[marker]))) return "agent";
+  return stderrIsTTY ? "human" : "quiet";
+}
+
+/** The two-line human error: what happened, then exactly one next command. */
+export function renderFailure(text: string, next: string, style: TerminalStyle): string {
+  return `${symbol("fail", style)} ${text}\n${symbol("next", style)} ${next}\n`;
+}
+
+/** A parser message as one sentence: capitalized unless it starts with a flag, with a final period. */
+export function sentence(message: string): string {
+  const trimmed = message.trim();
+  const capitalized = /^[a-z]/u.test(trimmed) ? `${trimmed[0]?.toUpperCase() ?? ""}${trimmed.slice(1)}` : trimmed;
+  return /[.!?]$/u.test(capitalized) ? capitalized : `${capitalized}.`;
+}
+
+const terminalOutputs = new WeakSet<object>();
+
+/** Mark an output object as the process's real stdout and stderr. */
+export function terminalOutput<T extends object>(output: T): T {
+  terminalOutputs.add(output);
+  return output;
+}
+
+/** Style for an error written to `output`: color only when it is the real terminal stderr. */
+export function stderrStyle(env: TerminalEnvironment, output: object): TerminalStyle {
+  return terminalStyle(env, terminalOutputs.has(output) && process.stderr.isTTY === true);
+}
+
+/** True when `output` writes to the process's real stderr and that stderr is a terminal. */
+export function writesToTerminal(output: object): boolean {
+  return terminalOutputs.has(output) && process.stderr.isTTY === true;
+}

package/src/clip/acquire.ts

@@ -16,6 +16,13 @@ import { getCookies, type BrowserName, type GetCookiesOptions } from "@steipete/
 
 import { captureUrl, type CaptureArguments } from "./args.js";
 import { readBoundedByteStream } from "./bounded-byte-buffer.js";
+import {
+  announceCookiePermissions,
+  classifyCookieProviderWarnings,
+  cookiePermissionNeed,
+  cookiePermissionRecovery,
+  reportCookiePermissionFailure,
+} from "./cookie-permission.js";
 import {
   filterCookieProviderResult,
   readCookieFile,
@@ -1210,6 +1217,13 @@ export function createCookieRecordReader(reader: CookieStoreReader): CookieRecor
             ...(options.cookieSources.includes("safari") ? { safariCookiesFile: options.cookieProfile } : {}),
           }),
     };
+    const needs = options.cookieSources.flatMap((source) => {
+      const need = cookiePermissionNeed(source);
+      return need === undefined ? [] : [need];
+    });
+    if (!await announceCookiePermissions(needs)) {
+      throw new Error("reading browser cookies was skipped; pass --cookies-file <path> to use exported cookies instead");
+    }
     let provided: unknown;
     try {
       provided = await reader(cookieOptions);
@@ -1219,6 +1233,12 @@ export function createCookieRecordReader(reader: CookieStoreReader): CookieRecor
     const filtered = filterCookieProviderResult(provided, url);
     if (!filtered.validShape) throw new Error("the selected browser cookie provider returned malformed data");
     if (filtered.cookies.length === 0) {
+      // A keychain denial or missing Full Disk Access is never "no matching cookies".
+      const permission = classifyCookieProviderWarnings((provided as { readonly warnings?: unknown }).warnings);
+      if (permission !== undefined) {
+        reportCookiePermissionFailure(permission);
+        throw new Error(cookiePermissionRecovery(permission, process.env).message);
+      }
       throw new Error(filtered.rejected === 0
         ? "no matching cookies were found in the explicitly selected browser"
         : `no usable origin-scoped cookies were found; rejected ${filtered.rejected} malformed, expired, or out-of-scope record(s)`);

package/src/clip/args.ts

@@ -400,9 +400,12 @@ Capture options:
   --scope auto|page|thread|comments Content scope (default: platform-aware)
   --html <path|->                  Parse saved/rendered HTML; - reads stdin
   --browser-profile <name|path>    Use a signed-in or persistent Chrome profile
+                                   (downloads read its cookies from the keychain)
   --browser-live                   Attach to a live Chrome session
   --cdp <loopback-port>            Attach to a local CDP-capable browser
   --cookie-source <browser>        chrome|arc|brave|chromium|edge|firefox|safari
+                                   On a Mac, Chromium browsers ask for keychain
+                                   access; Safari needs Full Disk Access
   --cookie-profile <name|path>     Browser profile; Safari expects a Cookies.binarycookies path
   --cookies-file <path>            Cookie-Editor JSON/base64, Netscape, Cookie header, or cURL input
   --media none|images|all          Localize images or all supported media

package/src/clip/cli.ts

@@ -9,6 +9,15 @@ import {
   renderDoctorReport,
 } from "./doctor.js";
 import { redactSensitiveText } from "./persist.js";
+import { detectAudience, renderFailure, sentence, stderrStyle, terminalOutput, writesToTerminal } from "../cli-style.js";
+import {
+  CONFIRM_LINE,
+  cookiePermissionRecovery,
+  renderCookiePermissionNotice,
+  renderCookiePermissionRecovery,
+  setCookiePermissionReporter,
+  type CookiePermissionFailure,
+} from "./cookie-permission.js";
 import { sanitizeTerminalLine, sanitizeTerminalText } from "./terminal.js";
 
 type Output = {
@@ -16,10 +25,10 @@ type Output = {
   readonly stderr: (value: string) => void;
 };
 
-const defaultOutput: Output = {
+const defaultOutput: Output = terminalOutput({
   stdout: (value) => process.stdout.write(value),
   stderr: (value) => process.stderr.write(value),
-};
+});
 
 function line(value: string): string {
   return value.endsWith("\n") ? value : `${value}\n`;
@@ -44,8 +53,34 @@ function terminalSafeJson(value: unknown): string {
 type CliDependencies = {
   readonly runCapture?: typeof runCapture;
   readonly inspectClipEnvironment?: typeof inspectClipEnvironment;
+  /** Ask whether to continue past a permission notice; present only when stdin and stderr are terminals. */
+  readonly confirmPermission?: () => Promise<"continue" | "skip">;
+  /** Whether the person is at a terminal on stderr; defaults to the real stderr. */
+  readonly stderrIsTerminal?: boolean;
 };
 
+const CONFIRM_TIMEOUT_MS = 120_000;
+
+/** Read one line from a terminal: Enter continues, `s` skips, and silence skips after two minutes. */
+async function confirmFromTerminal(): Promise<"continue" | "skip"> {
+  const reader = Bun.stdin.stream().getReader();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeout = new Promise<"skip">((resolve) => {
+      timer = setTimeout(() => resolve("skip"), CONFIRM_TIMEOUT_MS);
+    });
+    const answer = reader.read().then(({ value }) => {
+      const text = value === undefined ? "" : new TextDecoder().decode(value).trim().toLowerCase();
+      return text === "s" || text === "skip" ? "skip" as const : "continue" as const;
+    });
+    return await Promise.race([answer, timeout]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    // A read still pending after the timeout must not keep stdin open.
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
 export type ClipRuntimeOptions = {
   /** Trusted embedding hint; never parsed from public CLI arguments. */
   readonly ownedBrowserProfile?: {
@@ -111,7 +146,9 @@ export async function main(
 ): Promise<number> {
   const parsed = parseArguments(rawArguments, environment);
   if (!parsed.ok) {
-    output.stderr(`error: ${safe(parsed.message)}\n\n${sanitizeTerminalText(usage)}`);
+    const first = rawArguments[0];
+    const next = first === "doctor" || first === "adapters" || first === "inspect" ? `wordcell ${first} --help` : "wordcell clip --help";
+    output.stderr(renderFailure(sentence(safe(parsed.message)), next, stderrStyle(environment, output)));
     return 2;
   }
   const arguments_ = parsed.value;
@@ -129,6 +166,24 @@ export async function main(
     return 0;
   }
 
+  const onTerminal = dependencies.stderrIsTerminal ?? writesToTerminal(output);
+  const human = !arguments_.json && detectAudience(environment, onTerminal) === "human";
+  let permissionFailure: CookiePermissionFailure | undefined;
+  setCookiePermissionReporter({
+    notice: async (need) => {
+      if (!human || arguments_.quiet) return "continue";
+      output.stderr(renderCookiePermissionNotice(need, environment, stderrStyle(environment, output)));
+      const confirm = dependencies.confirmPermission
+        ?? (onTerminal && process.stdin.isTTY === true ? confirmFromTerminal : undefined);
+      if (confirm === undefined) return "continue";
+      output.stderr(CONFIRM_LINE);
+      return await confirm();
+    },
+    failure: (failure) => {
+      permissionFailure ??= failure;
+    },
+  });
+
   if (!arguments_.quiet && !arguments_.json) {
     const target = arguments_.currentTab ? "the current browser tab" : safe(arguments_.url?.href ?? "current");
     output.stderr(`Capturing ${target} (${arguments_.mode}, ${arguments_.scope}) ...\n`);
@@ -171,10 +226,32 @@ export async function main(
     }
     return captureExitCode(outcome);
   } catch (error) {
-    const message = safe(error instanceof Error ? error.message : String(error));
+    const raw = error instanceof Error ? error.message : String(error);
+    const recovery = permissionFailure === undefined
+      ? undefined
+      : cookiePermissionRecovery(permissionFailure, environment);
+    // Use the permission copy only when the capture failed because of it: the
+    // cookie reader's own message is in the failure. Any other error wins.
+    if (recovery !== undefined && raw.includes(recovery.message)) {
+      if (arguments_.json) {
+        output.stdout(terminalSafeJson({
+          ok: false,
+          error: recovery.message,
+          code: recovery.code,
+          next: recovery.next,
+          permission: recovery.permission,
+        }));
+      } else {
+        output.stderr(renderCookiePermissionRecovery(recovery, stderrStyle(environment, output)));
+      }
+      return 1;
+    }
+    const message = safe(raw);
     if (arguments_.json) output.stdout(terminalSafeJson({ ok: false, error: message }));
-    else output.stderr(`error: ${message}\n`);
+    else output.stderr(renderFailure(message, "wordcell doctor", stderrStyle(environment, output)));
     return 1;
+  } finally {
+    setCookiePermissionReporter(undefined);
   }
 }
 

package/src/clip/cookie-permission.ts

@@ -0,0 +1,241 @@
+/**
+ * What a person sees before and after macOS guards a browser cookie source:
+ * the keychain prompt for Chromium browsers' "Safe Storage" key, and Full
+ * Disk Access for Safari's cookie file.
+ *
+ * TODO(df-0.8): use CHROME_SAFE_STORAGE, renderNotice, and renderRecovery from
+ * @hraness/desktop-foundation's permissions kit once 0.8.0 is released. The
+ * copy below follows that kit's templates (SPEC § D, "Copy templates").
+ */
+
+import { symbol, type TerminalEnvironment, type TerminalStyle } from "../cli-style.js";
+
+export const PRODUCT = "Wordcell";
+export const KEYCHAIN_REQUESTER = "security";
+export const FULL_DISK_ACCESS_PATH = "System Settings › Privacy & Security › Full Disk Access";
+export const FULL_DISK_ACCESS_URL = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles";
+
+/** The Chromium browsers whose cookie key lives in the macOS keychain, by keychain label. */
+const KEYCHAIN_BROWSERS = ["Chrome", "Brave", "Arc", "Chromium", "Dia", "Microsoft Edge"] as const;
+export type KeychainBrowser = (typeof KEYCHAIN_BROWSERS)[number];
+
+export type CookiePermissionNeed =
+  | { readonly kind: "keychain"; readonly browser: KeychainBrowser }
+  | { readonly kind: "full-disk-access"; readonly browser: "Safari" };
+
+export type CookiePermissionState = "denied" | "unknown" | "missing";
+
+export type CookiePermissionFailure = CookiePermissionNeed & {
+  readonly state: CookiePermissionState;
+  /** Keychain only: the login keychain is locked, so macOS could not ask. */
+  readonly locked?: boolean;
+};
+
+/** Map a `--cookie-source` value to the browser whose keychain key it reads. */
+export function keychainBrowserFor(source: string): KeychainBrowser | undefined {
+  switch (source) {
+    case "chrome": return "Chrome";
+    case "brave": return "Brave";
+    case "arc": return "Arc";
+    case "chromium": return "Chromium";
+    case "edge": return "Microsoft Edge";
+    default: return undefined;
+  }
+}
+
+/** The permission a cookie source needs on macOS, if any. */
+export function cookiePermissionNeed(source: string, platform: string = process.platform): CookiePermissionNeed | undefined {
+  if (platform !== "darwin") return undefined;
+  if (source === "safari") return { kind: "full-disk-access", browser: "Safari" };
+  const browser = keychainBrowserFor(source);
+  return browser === undefined ? undefined : { kind: "keychain", browser };
+}
+
+const KEYCHAIN_WARNING = /^Failed to read macOS Keychain \(([A-Za-z ]{1,40}) Safe Storage\): ([\s\S]{0,2000})$/u;
+const SAFARI_WARNING = /^Failed to read Safari cookies: ([\s\S]{0,2000})$/u;
+
+/**
+ * Classify a cookie provider's warnings as a permission failure. Only fixed
+ * facts leave this function: the browser comes from a closed list and the
+ * warning text itself is never retained.
+ */
+export function classifyCookieProviderWarnings(warnings: unknown): CookiePermissionFailure | undefined {
+  if (!Array.isArray(warnings)) return undefined;
+  for (const warning of warnings.slice(0, 64)) {
+    if (typeof warning !== "string") continue;
+    const keychain = KEYCHAIN_WARNING.exec(warning);
+    if (keychain !== null) {
+      const browser = KEYCHAIN_BROWSERS.find((name) => name === keychain[1]);
+      if (browser === undefined) continue;
+      return { kind: "keychain", browser, ...keychainState(keychain[2] ?? "") };
+    }
+    const safari = SAFARI_WARNING.exec(warning);
+    if (safari !== null && /\b(?:EPERM|EACCES)\b|operation not permitted|permission denied/iu.test(safari[1] ?? "")) {
+      return { kind: "full-disk-access", browser: "Safari", state: "denied" };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * `security find-generic-password` failures: a cancel (-128) or a wrong
+ * password (-25293) is a denial, a locked keychain with no UI (-25308) is
+ * unknown, and a missing item (-25300) means the browser never made its key.
+ */
+function keychainState(detail: string): { readonly state: CookiePermissionState; readonly locked?: boolean } {
+  if (/-25300\b|could not be found/iu.test(detail)) return { state: "missing" };
+  if (/-25308\b|interaction is not allowed/iu.test(detail)) return { state: "unknown", locked: true };
+  // Sweet Cookie's stderr-less fallback ("permission denied / keychain locked /
+  // entry missing.") names three causes, so only a specific status is a denial.
+  if (/-128\b|-25293\b|canceled|cancelled|passphrase you entered is not correct/iu.test(detail)) {
+    return { state: "denied" };
+  }
+  return { state: "unknown" };
+}
+
+/** The terminal app that asks for Full Disk Access on the person's behalf. */
+export function terminalAppName(env: TerminalEnvironment): string {
+  switch (env.TERM_PROGRAM) {
+    case "Apple_Terminal": return "Terminal";
+    case "iTerm.app": return "iTerm";
+    case "vscode": return "Visual Studio Code";
+    case "WezTerm": return "WezTerm";
+    case "ghostty": return "Ghostty";
+    case "WarpTerminal": return "Warp";
+    case "zed": return "Zed";
+    default: return "your terminal app";
+  }
+}
+
+function keychainAsk(browser: KeychainBrowser): string {
+  return `use "${browser} Safe Storage" from your keychain`;
+}
+
+/**
+ * The pre-prompt printed before Wordcell reads a guarded cookie source. The
+ * confirm line is added by the caller only when stdin and stderr are terminals.
+ */
+export function renderCookiePermissionNotice(
+  need: CookiePermissionNeed,
+  env: TerminalEnvironment,
+  style: TerminalStyle,
+): string {
+  const icon = symbol("notice", style);
+  if (need.kind === "keychain") {
+    return `${icon} macOS will ask to let ${KEYCHAIN_REQUESTER} ${keychainAsk(need.browser)} for ${PRODUCT}.\n`
+      + `   ${PRODUCT} uses it to read the ${need.browser} sign-in you already have and never stores it. `
+      + "Enter your Mac password if asked, then choose Always Allow so macOS doesn't ask again.\n";
+  }
+  const requester = terminalAppName(env);
+  return `${icon} ${PRODUCT} needs Full Disk Access to read your Safari cookies.\n`
+    + `   macOS doesn't ask for this. Turn on ${requester} in ${FULL_DISK_ACCESS_PATH}. `
+    + `${PRODUCT} reads only the cookies for the page you capture and never stores them.\n`;
+}
+
+export const CONFIRM_LINE = "   Press Enter to continue · s to skip\n";
+
+export type CookiePermissionRecovery = {
+  /** The first line after the failure symbol. */
+  readonly message: string;
+  /** The indented line that says how to fix it. */
+  readonly detail: string;
+  /** Exactly one next command. */
+  readonly next: string;
+  readonly code: "permission-denied" | "permission-unknown" | "permission-missing";
+  readonly permission: { readonly kind: CookiePermissionNeed["kind"]; readonly settingsUrl?: string };
+};
+
+const COOKIES_FILE_NEXT = "wordcell clip <url> --cookies-file <path>";
+
+/** Recovery copy for a failed guarded cookie read. */
+export function cookiePermissionRecovery(
+  failure: CookiePermissionFailure,
+  env: TerminalEnvironment,
+): CookiePermissionRecovery {
+  if (failure.kind === "full-disk-access") {
+    const requester = terminalAppName(env);
+    return {
+      message: `${PRODUCT} can't read your Safari cookies: macOS access is off for ${requester}.`,
+      detail: `Turn on ${requester} in ${FULL_DISK_ACCESS_PATH}, then run it again.`,
+      next: `open "${FULL_DISK_ACCESS_URL}"`,
+      code: "permission-denied",
+      permission: { kind: "full-disk-access", settingsUrl: FULL_DISK_ACCESS_URL },
+    };
+  }
+  const ask = keychainAsk(failure.browser);
+  switch (failure.state) {
+    case "denied":
+      return {
+        message: `${PRODUCT} can't ${ask}: the keychain request was denied.`,
+        detail: "Run it again and choose Always Allow when macOS asks, or pass a cookie file exported from the browser.",
+        next: COOKIES_FILE_NEXT,
+        code: "permission-denied",
+        permission: { kind: "keychain" },
+      };
+    case "missing":
+      return {
+        message: `${PRODUCT} can't find "${failure.browser} Safe Storage" in your keychain.`,
+        detail: `Open ${failure.browser} and sign in to the site once, or pass a cookie file exported from the browser.`,
+        next: COOKIES_FILE_NEXT,
+        code: "permission-missing",
+        permission: { kind: "keychain" },
+      };
+    case "unknown":
+      return {
+        message: `${PRODUCT} couldn't ${ask}. macOS may be blocking ${KEYCHAIN_REQUESTER}.`,
+        detail: failure.locked === true
+          ? "Unlock your login keychain, then run it again."
+          : "Check the key in Keychain Access, then run it again.",
+        next: COOKIES_FILE_NEXT,
+        code: "permission-unknown",
+        permission: { kind: "keychain" },
+      };
+  }
+}
+
+/** The three-line human recovery: what happened, how to fix it, one next command. */
+export function renderCookiePermissionRecovery(recovery: CookiePermissionRecovery, style: TerminalStyle): string {
+  return `${symbol("fail", style)} ${recovery.message}\n  ${recovery.detail}\n${symbol("next", style)} ${recovery.next}\n`;
+}
+
+/**
+ * What the CLI registers so library capture stays quiet: `notice` runs once
+ * per need before the guarded read and may decline it; `failure` records a
+ * classified failure for the final error.
+ */
+export type CookiePermissionReporter = {
+  readonly notice: (need: CookiePermissionNeed) => Promise<"continue" | "skip">;
+  readonly failure: (failure: CookiePermissionFailure) => void;
+};
+
+let reporter: CookiePermissionReporter | undefined;
+const answers = new Map<string, Promise<"continue" | "skip">>();
+
+export function setCookiePermissionReporter(next: CookiePermissionReporter | undefined): void {
+  reporter = next;
+  answers.clear();
+}
+
+/**
+ * Show the pre-prompt for each need once per run. Capture lanes read cookies
+ * concurrently, so every caller waits on the same answer and a skip stops them
+ * all. Resolves false when the person skipped.
+ */
+export async function announceCookiePermissions(needs: readonly CookiePermissionNeed[]): Promise<boolean> {
+  const current = reporter;
+  if (current === undefined) return true;
+  for (const need of needs) {
+    const key = `${need.kind}:${need.browser}`;
+    let answer = answers.get(key);
+    if (answer === undefined) {
+      answer = current.notice(need);
+      answers.set(key, answer);
+    }
+    if (await answer === "skip") return false;
+  }
+  return true;
+}
+
+export function reportCookiePermissionFailure(failure: CookiePermissionFailure): void {
+  reporter?.failure(failure);
+}

package/src/clip/url-metadata-cli.ts

@@ -11,7 +11,8 @@ import {
   runMetadataSearchTool,
   type MetadataSearchToolAction,
 } from "./metadata-search-tool/runner.js";
-import { sanitizeTerminalText } from "./terminal.js";
+import { renderFailure, sentence, stderrStyle, terminalOutput } from "../cli-style.js";
+import { sanitizeTerminalLine, sanitizeTerminalText } from "./terminal.js";
 
 export const urlMetadataUsage = `wordcell url-metadata — backfill bounded metadata for saved URLs
 
@@ -31,10 +32,10 @@ type Output = {
   readonly stderr: (value: string) => void;
 };
 
-const defaultOutput: Output = {
+const defaultOutput: Output = terminalOutput({
   stdout: (value) => process.stdout.write(value),
   stderr: (value) => process.stderr.write(value),
-};
+});
 
 type ParsedUrlMetadataArguments =
   | { readonly kind: "help" }
@@ -203,7 +204,7 @@ export async function main(
   const parsed = parseUrlMetadataArguments(rawArguments, environment);
   if (!parsed.ok) {
     if (parsed.json) output.stdout(terminalJson({ ok: false, error: parsed.message }));
-    else output.stderr(`error: ${sanitizeTerminalText(parsed.message)}\n\n${urlMetadataUsage}`);
+    else output.stderr(renderFailure(sentence(sanitizeTerminalLine(parsed.message)), "wordcell url-metadata --help", stderrStyle(environment, output)));
     return 2;
   }
   if (parsed.value.kind === "help") {
@@ -243,7 +244,7 @@ export async function main(
     if (parsed.value.kind === "backfill" && parsed.value.json) {
       output.stdout(terminalJson({ ok: false, error: message }));
     }
-    else output.stderr(`error: ${sanitizeTerminalText(message)}\n`);
+    else output.stderr(renderFailure(sanitizeTerminalLine(message), "wordcell url-metadata tool check", stderrStyle(environment, output)));
     return 1;
   }
 }

package/src/clip/url-metadata.ts

@@ -808,6 +808,20 @@ function absoluteSource(value: unknown, label: string, allowLocalPdf: boolean):
   return normalizedPublicUrl(value, label);
 }
 
+/**
+ * Why `url-metadata` would refuse `value` as the `source` of a saved article
+ * note, or `undefined` when it accepts it. Other writers of `source` use this
+ * so the saved-URL inventory keeps working.
+ */
+export function savedSourceProblem(value: string): string | undefined {
+  try {
+    absoluteSource(value, "source", false);
+    return undefined;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
 function confined(root: string, path: string, label: string): void {
   const pathFromRoot = relative(root, path);
   if (pathFromRoot === "" || pathFromRoot === ".." || pathFromRoot.startsWith(`..${sep}`) || pathFromRoot.includes(`\0`)) {