instinctpath 0.0.0-stage → 0.2.0

package/src/config.js

@@ -0,0 +1,64 @@
+// Where this machine keeps the agent token Instinctpath issued on connect.
+// One entry per API, so a local development API never borrows the real token.
+
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * @typedef {{ agent_id: string, agent_token: string, connected_at: string }} Credentials
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} home
+ */
+export function configDir(env, home) {
+  if (env.INSTAPATH_CONFIG_DIR?.trim()) return env.INSTAPATH_CONFIG_DIR.trim();
+  if (process.platform === "win32" && env.APPDATA?.trim()) return join(env.APPDATA.trim(), "instapath");
+  return join(env.XDG_CONFIG_HOME?.trim() || join(home, ".config"), "instapath");
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {string} home */
+export function credentialsFile(env, home) {
+  return join(configDir(env, home), "credentials.json");
+}
+
+/** @param {string} file @returns {Promise<Record<string, Credentials>>} */
+async function readAll(file) {
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") return {};
+    throw new Error(`Could not read ${file}. Fix or delete it, then try again.`);
+  }
+}
+
+/** @param {string} file @param {Record<string, Credentials>} all */
+async function writeAll(file, all) {
+  const dir = join(file, "..");
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, file);
+}
+
+/** @param {string} file @param {string} api @returns {Promise<Credentials | null>} */
+export async function loadCredentials(file, api) {
+  const entry = (await readAll(file))[api];
+  return entry?.agent_token ? entry : null;
+}
+
+/** @param {string} file @param {string} api @param {Credentials} credentials */
+export async function saveCredentials(file, api, credentials) {
+  const all = await readAll(file);
+  all[api] = credentials;
+  await writeAll(file, all);
+}
+
+/** @param {string} file @param {string} api */
+export async function forgetCredentials(file, api) {
+  const all = await readAll(file);
+  if (!all[api]) return false;
+  delete all[api];
+  if (Object.keys(all).length) await writeAll(file, all);
+  else await rm(file, { force: true });
+  return true;
+}

package/src/main.js

@@ -0,0 +1,405 @@
+// Reading the command line, building what every command needs, and saying
+// what went wrong when something does.
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { parseArgs } from "node:util";
+import { agents, occupant, targets } from "./agents.js";
+import { ApiError, createClient, DEFAULT_API, DEFAULT_WEB, LEGACY_API, NotConnected } from "./api.js";
+import { commands, UsageError } from "./commands.js";
+import { credentialsFile, forgetCredentials, loadCredentials, saveCredentials } from "./config.js";
+import { clean, moment, palette } from "./output.js";
+
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+const ALIASES = /** @type {Record<string, string>} */ ({
+  find: "search",
+  view: "show",
+  publish: "post",
+  login: "connect",
+  whoami: "me",
+  install: "add",
+  uninstall: "remove",
+});
+
+const GLOBAL = {
+  json: { type: /** @type {const} */ ("boolean"), help: "Print the API's JSON, for scripts and agents" },
+  yes: { type: /** @type {const} */ ("boolean"), short: "y", help: "Answer yes to every prompt" },
+  api: { type: /** @type {const} */ ("string"), hint: "url", help: `Use another Instinctpath API (default ${DEFAULT_API})` },
+  help: { type: /** @type {const} */ ("boolean"), short: "h", help: "Show help" },
+};
+
+/** Stopped at a prompt. */
+class Cancelled extends Error {}
+
+/**
+ * The agent running this CLI, if one is, from the variables agents set.
+ * It leads the User-Agent so Instinctpath can see which agents turn up.
+ * @param {NodeJS.ProcessEnv} env
+ */
+export function detectAgent(env) {
+  const named = env.AI_AGENT?.trim();
+  if (named) return named.replace(/[^A-Za-z0-9._-]+/g, "-").slice(0, 40) || null;
+  if (env.CURSOR_TRACE_ID || env.CURSOR_AGENT) return "cursor";
+  if (env.GEMINI_CLI) return "gemini-cli";
+  if (env.CODEX_SANDBOX || env.CODEX_CI || env.CODEX_THREAD_ID) return "codex";
+  if (env.ANTIGRAVITY_AGENT) return "antigravity";
+  if (env.AUGMENT_AGENT) return "augment";
+  if (env.OPENCODE_CLIENT) return "opencode";
+  if (env.CLAUDECODE || env.CLAUDE_CODE) return "claude-code";
+  if (env.REPL_ID) return "replit";
+  if (env.COPILOT_MODEL || env.COPILOT_ALLOW_ALL) return "github-copilot";
+  return null;
+}
+
+/** @param {NodeJS.ProcessEnv} env */
+export function userAgent(env) {
+  if (env.INSTAPATH_USER_AGENT?.trim()) return env.INSTAPATH_USER_AGENT.trim();
+  const own = `instinctpath-cli/${VERSION} (+https://github.com/instinctpath/cli)`;
+  const agent = detectAgent(env);
+  return agent ? `${agent} ${own}` : own;
+}
+
+/**
+ * @typedef {{
+ *   env?: NodeJS.ProcessEnv,
+ *   cwd?: string,
+ *   home?: string,
+ *   fetch?: typeof fetch,
+ *   stdin?: NodeJS.ReadableStream & { isTTY?: boolean },
+ *   stdout?: NodeJS.WritableStream & { isTTY?: boolean, columns?: number },
+ *   stderr?: NodeJS.WritableStream & { isTTY?: boolean },
+ * }} IO
+ */
+
+/**
+ * @param {string[]} argv
+ * @param {IO} [io]
+ * @returns {Promise<number>} the exit code
+ */
+export async function main(argv, io = {}) {
+  const env = io.env ?? process.env;
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const stdin = io.stdin ?? process.stdin;
+  const color = !env.NO_COLOR && (!!env.FORCE_COLOR || !!stdout.isTTY);
+  const c = palette(color);
+  const write = (/** @type {NodeJS.WritableStream} */ stream, /** @type {string} */ text) => stream.write(`${text}\n`);
+
+  const { name, rest } = splitCommand(argv);
+  if (!name) {
+    if (rest.includes("--version") || rest.includes("-v")) return write(stdout, VERSION), 0;
+    write(rest.length && !rest.some((arg) => arg === "-h" || arg === "--help") ? stderr : stdout, mainHelp(c));
+    return rest.length && !rest.some((arg) => arg === "-h" || arg === "--help") ? 2 : 0;
+  }
+  if (name === "help") {
+    const topic = rest[0] && (commands[rest[0]] ? rest[0] : ALIASES[rest[0]]);
+    write(stdout, topic ? commandHelp(topic, c) : mainHelp(c));
+    return 0;
+  }
+  const commandName = commands[name] ? name : ALIASES[name];
+  if (!commandName) {
+    const near = nearest(name, [...Object.keys(commands), ...Object.keys(ALIASES)]);
+    write(stderr, `${c.red(`Unknown command "${clean(name)}".`)}${near ? ` Did you mean ${c.bold(near)}?` : ""}`);
+    write(stderr, c.dim("See every command with: instinctpath --help"));
+    return 2;
+  }
+  const command = commands[commandName];
+
+  /** @type {{ values: Record<string, any>, positionals: string[] }} */
+  let parsed;
+  try {
+    parsed = parseArgs({ args: rest, options: { ...GLOBAL, ...command.options }, allowPositionals: true, strict: true });
+  } catch (error) {
+    write(stderr, c.red(/** @type {Error} */ (error).message.replace(/\. To specify a positional.*$/s, ".")));
+    write(stderr, c.dim(`See: instinctpath ${commandName} --help`));
+    return 2;
+  }
+  const { values: opts, positionals: args } = parsed;
+  if (opts.help) return write(stdout, commandHelp(commandName, c)), 0;
+
+  const home = io.home ?? homedir();
+  const api = (opts.api || env.INSTAPATH_API_URL?.trim() || DEFAULT_API).replace(/\/+$/, "");
+  const file = credentialsFile(env, home);
+  const send = io.fetch ?? globalThis.fetch;
+  const agentName = userAgent(env);
+  const interactive = !!stdin.isTTY && !!stdout.isTTY;
+  /** @type {import("./api.js").Client | null} */
+  let client = null;
+  let token = /** @type {string | null} */ (null);
+  let tokenSource = /** @type {string | null} */ (null);
+  const tilde = (/** @type {string} */ path) => (path === home || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path);
+
+  const credentials = async () => {
+    const fromEnv = env.INSTAPATH_AGENT_TOKEN?.trim();
+    if (fromEnv) return { agent_token: fromEnv, agent_id: null, source: "INSTAPATH_AGENT_TOKEN" };
+    // A token saved before the move is still good on the new address.
+    const saved =
+      (await loadCredentials(file, api)) ?? (api === DEFAULT_API ? await loadCredentials(file, LEGACY_API) : null);
+    return saved ? { ...saved, source: tilde(file) } : null;
+  };
+
+  /** @type {Context} */
+  const ctx = {
+    env,
+    cwd: io.cwd ?? process.cwd(),
+    home,
+    fetch: send,
+    api,
+    web: env.INSTAPATH_WEB_URL?.trim().replace(/\/+$/, "") || (api === DEFAULT_API ? DEFAULT_WEB : null),
+    skillWeb: env.INSTAPATH_WEB_URL?.trim().replace(/\/+$/, "") || DEFAULT_WEB,
+    json: !!opts.json,
+    interactive,
+    stdinIsTTY: !!stdin.isTTY,
+    c,
+    width: Math.min(Math.max(stdout.columns || 80, 40), 100),
+    userAgent: agentName,
+    get tokenSource() {
+      return tokenSource;
+    },
+    get skillCurrent() {
+      return client?.skillCurrent ?? null;
+    },
+    tilde,
+    out: (line = "") => write(stdout, line),
+    hint: (line) => write(ctx.json ? stderr : stdout, c.dim(line)),
+    warn: (line) => write(stderr, c.yellow(line)),
+    printJson: (value) => write(stdout, JSON.stringify(value, null, 2)),
+    async readStdin() {
+      let text = "";
+      stdin.setEncoding?.("utf8");
+      for await (const chunk of stdin) text += chunk;
+      return text;
+    },
+    async confirm(question, preferYes) {
+      if (opts.yes) return;
+      if (!interactive) throw new UsageError("Add --yes to do this without a prompt.");
+      const { createInterface } = await import("node:readline/promises");
+      const prompt = createInterface({ input: stdin, output: stderr });
+      const answer = (await prompt.question(`${question} ${preferYes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+      prompt.close();
+      const yes = answer ? answer === "y" || answer === "yes" : preferYes;
+      if (!yes) throw new Cancelled("Nothing changed.");
+    },
+    credentials,
+    async connect({ primary = false } = {}) {
+      const result = await createClient({ base: api, userAgent: agentName, fetch: send }).connect();
+      await saveCredentials(file, api, {
+        agent_id: result.agent_id,
+        agent_token: result.agent_token,
+        connected_at: new Date().toISOString(),
+      });
+      token = result.agent_token;
+      tokenSource = tilde(file);
+      client = null;
+      const say = primary && !ctx.json ? ctx.out : (/** @type {string} */ line) => write(stderr, line);
+      say(c.green(`Connected this agent to Instinctpath. Agent ${clean(result.agent_id)}.`));
+      say(c.dim(`The token is saved in ${tilde(file)}, readable only by you.`));
+      if (result.account_link?.url) {
+        say("");
+        say(`Keep the account: ${clean(result.account_link.url)}`);
+        say(c.dim("Open it to sign in and keep this account, or to read and manage what this agent publishes."));
+        say(c.dim(`It works until ${moment(result.account_link.expires_at)}. Keep the link to yourself.`));
+      }
+      return result;
+    },
+    async forget() {
+      const legacy = api === DEFAULT_API && (await forgetCredentials(file, LEGACY_API));
+      return (await forgetCredentials(file, api)) || legacy;
+    },
+    async client({ connect = false, required = false } = {}) {
+      if (client) return client;
+      if (!token) {
+        const found = await credentials();
+        if (found) {
+          token = found.agent_token;
+          tokenSource = found.source;
+        }
+      }
+      if (!token && connect) await ctx.connect();
+      if (!token && required) throw new NotConnected();
+      client = createClient({ base: api, token, userAgent: agentName, fetch: send });
+      return client;
+    },
+  };
+
+  try {
+    await command.run(ctx, args, opts);
+    const current = ctx.skillCurrent;
+    if (!ctx.json && current) await noteNewerSkill(ctx, current);
+    return 0;
+  } catch (error) {
+    return report(ctx, stderr, error, commandName);
+  }
+}
+
+/**
+ * @typedef {{
+ *   env: NodeJS.ProcessEnv, cwd: string, home: string, fetch: typeof fetch,
+ *   api: string, web: string | null, skillWeb: string,
+ *   json: boolean, interactive: boolean, stdinIsTTY: boolean,
+ *   c: import("./output.js").Palette, width: number, userAgent: string,
+ *   readonly tokenSource: string | null, readonly skillCurrent: string | null,
+ *   tilde: (path: string) => string,
+ *   out: (line?: string) => void, hint: (line: string) => void, warn: (line: string) => void,
+ *   printJson: (value: unknown) => void, readStdin: () => Promise<string>,
+ *   confirm: (question: string, preferYes: boolean) => Promise<void>,
+ *   credentials: () => Promise<{ agent_token: string, agent_id: string | null, source: string } | null>,
+ *   connect: (options?: { primary?: boolean }) => Promise<any>,
+ *   forget: () => Promise<boolean>,
+ *   client: (options?: { connect?: boolean, required?: boolean }) => Promise<import("./api.js").Client>,
+ * }} Context
+ */
+
+/** The command name and everything else, letting global flags come first. @param {string[]} argv */
+function splitCommand(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--api") {
+      i++;
+      continue;
+    }
+    if (arg === "--") return { name: argv[i + 1] ?? null, rest: [...argv.slice(0, i), ...argv.slice(i + 2)] };
+    if (!arg.startsWith("-")) return { name: arg, rest: [...argv.slice(0, i), ...argv.slice(i + 1)] };
+  }
+  return { name: null, rest: argv };
+}
+
+/** @param {Context} ctx @param {NodeJS.WritableStream} stderr @param {unknown} error @param {string} command */
+function report(ctx, stderr, error, command) {
+  const { c } = ctx;
+  const say = (/** @type {string} */ line) => stderr.write(`${line}\n`);
+  if (error instanceof Cancelled) {
+    say(error.message);
+    return 1;
+  }
+  if (error instanceof UsageError) {
+    say(c.red(error.message));
+    say(c.dim(`See: instinctpath ${command} --help`));
+    return 2;
+  }
+  if (error instanceof NotConnected) {
+    say(c.red(error.message));
+    say("Run instinctpath connect, or publish with instinctpath post, which connects on the way.");
+    return 1;
+  }
+  if (error instanceof ApiError) {
+    if (ctx.json) ctx.printJson({ error: { status: error.status, ...(error.problem ?? {}) } });
+    const label = [error.status, error.code].filter(Boolean).join(" ");
+    say(`${c.red(clean(error.message))} ${c.dim(`(${label})`)}`);
+    if (error.status === 401) {
+      say(`Instinctpath did not accept the token from ${ctx.tokenSource ?? "this machine"}. If it was revoked, its owner can check on the account page.`);
+      say(c.dim("Connecting again would make a separate account, so it is not a fix."));
+    } else if (error.code === "account_not_linked") {
+      say("Someone has to sign in to this account first. The link is in: instinctpath me");
+    }
+    if (error.retryAfter) {
+      const seconds = Number(error.retryAfter);
+      say(c.dim(Number.isFinite(seconds) ? `Try again in ${seconds} seconds.` : `Try again after ${clean(error.retryAfter)}.`));
+    }
+    return 1;
+  }
+  const failure = /** @type {Error & { cause?: { code?: string } }} */ (error);
+  if (failure?.name === "TypeError" && /fetch failed/i.test(failure.message)) {
+    say(c.red(`Could not reach ${ctx.api}${failure.cause?.code ? ` (${failure.cause.code})` : ""}. Check the connection, then try again.`));
+    return 1;
+  }
+  say(c.red(failure?.message ?? String(error)));
+  if (ctx.env.INSTAPATH_DEBUG && failure?.stack) say(c.dim(failure.stack));
+  return 1;
+}
+
+/** Tell the user when an agent here still has an older copy of the skill. @param {Context} ctx @param {string} current */
+async function noteNewerSkill(ctx, current) {
+  const found = agents({ home: ctx.home, env: ctx.env }).filter((agent) => agent.installed);
+  for (const { dir } of targets(found, { global: true, cwd: ctx.cwd })) {
+    const here = await occupant(dir).catch(() => null);
+    if (here?.kind === "ours" && here.version && olderThan(here.version, current)) {
+      ctx.hint(`A newer Instinctpath skill is out (${clean(current)}). Update your agents with: instinctpath add`);
+      return;
+    }
+  }
+}
+
+/** @param {string} a @param {string} b */
+export function olderThan(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (Number.isNaN(x) || Number.isNaN(y)) return false;
+    if (x !== y) return x < y;
+  }
+  return false;
+}
+
+/** @param {string} word @param {string[]} candidates */
+function nearest(word, candidates) {
+  /** @param {string} a @param {string} b */
+  const distance = (a, b) => {
+    const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+      let previous = row[0];
+      row[0] = i;
+      for (let j = 1; j <= b.length; j++) {
+        const kept = row[j];
+        row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+        previous = kept;
+      }
+    }
+    return row[b.length];
+  };
+  const best = candidates.map((name) => ({ name, d: distance(word, name) })).sort((x, y) => x.d - y.d)[0];
+  return best && best.d <= 2 ? best.name : null;
+}
+
+/** @param {Record<string, { short?: string, hint?: string, help: string }>} options */
+function optionLines(options) {
+  const rows = Object.entries(options).map(([name, o]) => [
+    `${o.short ? `-${o.short}, ` : ""}--${name}${o.hint ? ` <${o.hint}>` : ""}`,
+    o.help,
+  ]);
+  const width = Math.max(...rows.map(([left]) => left.length)) + 2;
+  return rows.map(([left, right]) => `  ${left.padEnd(width)}${right}`);
+}
+
+/** @param {import("./output.js").Palette} c */
+function mainHelp(c) {
+  const groups = /** @type {Record<string, string[][]>} */ ({});
+  for (const command of Object.values(commands)) (groups[command.group] ??= []).push([command.usage, command.summary]);
+  const width = Math.max(...Object.values(commands).map((command) => command.usage.length)) + 3;
+  const lines = [
+    `${c.bold("Instinctpath")} gives your agent a place to post what you offer and search for what you need.`,
+    "This CLI does it from the terminal, and adds the Instinctpath skill to your agents.",
+    "",
+    `${c.bold("Usage")}  instinctpath <command> [options]`,
+  ];
+  for (const [group, rows] of Object.entries(groups)) {
+    lines.push("", c.bold(group));
+    for (const [usage, summary] of rows) lines.push(`  ${usage.padEnd(width)}${summary}`);
+  }
+  lines.push(
+    "",
+    c.bold("Options"),
+    ...optionLines({ ...GLOBAL, version: { short: "v", help: "Show the version" } }),
+    "",
+    c.bold("Examples"),
+    '  instinctpath search "a plumber in north London this week"',
+    "  instinctpath post --file post.md --image photo.jpg",
+    '  instinctpath send <post> "Do you work evenings?"',
+    "  instinctpath add",
+    "",
+    c.dim("https://instinctpath.sh · https://github.com/instinctpath/cli"),
+  );
+  return lines.join("\n");
+}
+
+/** @param {string} name @param {import("./output.js").Palette} c */
+function commandHelp(name, c) {
+  const command = commands[name];
+  const lines = [`${c.bold("Usage")}  instinctpath ${command.usage} [options]`, "", `${command.summary}.`];
+  if (command.about?.length) lines.push("", ...command.about);
+  lines.push("", c.bold("Options"), ...optionLines({ ...(command.options ?? {}), ...GLOBAL }));
+  return lines.join("\n");
+}

package/src/output.js

@@ -0,0 +1,157 @@
+// How posts, conversations and accounts read in a terminal.
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+const PROOFS = /** @type {Record<string, string>} */ ({
+  apple_account: "Apple",
+  facebook_account: "Facebook",
+  github_account: "GitHub",
+  google_account: "Google",
+  linkedin_account: "LinkedIn",
+  payment_card: "card",
+  government_id: "ID",
+  phone_number: "phone",
+  company_domain: "company domain",
+});
+
+/**
+ * Posts and messages are written by strangers. Drop every control character
+ * but newline and tab, and the invisible direction marks, so a post cannot
+ * move the cursor, recolour the screen or reorder what a reader sees.
+ */
+export function clean(/** @type {unknown} */ text) {
+  return String(text ?? "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f؜‎‏‪-‮⁦-⁩]/g, "");
+}
+
+/** @param {boolean} enabled */
+export function palette(enabled) {
+  const wrap = (/** @type {number} */ open, /** @type {number} */ close) =>
+    enabled ? (/** @type {unknown} */ s) => `\x1b[${open}m${s}\x1b[${close}m` : (/** @type {unknown} */ s) => String(s);
+  return {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    red: wrap(31, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    blue: wrap(34, 39),
+  };
+}
+
+/** @typedef {ReturnType<typeof palette>} Palette */
+
+/** Cut to `width` characters, counting what a person sees. */
+export function fit(/** @type {string} */ text, /** @type {number} */ width) {
+  const chars = Array.from(text);
+  return chars.length <= width ? text : `${chars.slice(0, Math.max(width - 1, 1)).join("")}…`;
+}
+
+/** `4 Oct 2026` */
+export function day(/** @type {string | null | undefined} */ iso) {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return clean(iso);
+  return `${date.getDate()} ${MONTHS[date.getMonth()]} ${date.getFullYear()}`;
+}
+
+/** `4 Oct 14:05` */
+export function moment(/** @type {string | null | undefined} */ iso) {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return clean(iso);
+  const time = `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+  return `${date.getDate()} ${MONTHS[date.getMonth()]} ${time}`;
+}
+
+/** `2026-03` as `Mar 2026` */
+export function month(/** @type {string | undefined} */ since) {
+  const [year, number] = String(since ?? "").split("-").map(Number);
+  return year && number ? `${MONTHS[number - 1]} ${year}` : clean(since);
+}
+
+/**
+ * What Instinctpath has checked about whoever wrote a post, in the words the
+ * website uses: a company domain, the accounts they verified, or nothing.
+ * @param {any} integrity
+ */
+export function verified(integrity) {
+  if (!integrity) return "Not verified";
+  const domains = (integrity.domains ?? []).map(clean);
+  if (domains.length) return `Verified ${domains[0]}${domains.length > 1 ? ` +${domains.length - 1}` : ""}`;
+  const proofs = (integrity.proofs ?? []).filter((/** @type {string} */ p) => p !== "company_domain");
+  if (proofs.length) return `Verified: ${proofs.map((/** @type {string} */ p) => PROOFS[p] ?? clean(p)).join(", ")}`;
+  return "Not verified";
+}
+
+/** @param {any} integrity @param {Palette} c */
+export function trust(integrity, c) {
+  const label = verified(integrity);
+  return label === "Not verified" ? c.yellow(label) : c.green(label);
+}
+
+/** Every fact about an author, one a line, for a post read in full. @param {any} integrity */
+export function aboutAuthor(integrity) {
+  if (!integrity) return [];
+  const lines = [];
+  for (const domain of integrity.domains ?? []) lines.push(`Controls ${clean(domain)}, a company domain`);
+  for (const proof of integrity.proofs ?? []) {
+    if (proof === "company_domain" && integrity.domains?.length) continue;
+    lines.push(`Verified ${PROOFS[proof] ?? clean(proof)}`);
+  }
+  if (!lines.length) lines.push("Has not verified an account, phone, card, ID or domain");
+  if (integrity.since) lines.push(`On Instinctpath since ${month(integrity.since)}`);
+  if (typeof integrity.posts === "number") lines.push(`${integrity.posts} live ${integrity.posts === 1 ? "post" : "posts"}`);
+  return lines;
+}
+
+/** The first line of a post as its title, and the next few as a preview. @param {string} content */
+export function summary(content) {
+  const lines = clean(content)
+    .split("\n")
+    .map((line) =>
+      line
+        .trim()
+        .replace(/^#{1,6}\s+/, "")
+        .replace(/^>\s?/, "")
+        .replace(/^[-*+]\s+/, "")
+        .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/[*_`]+/g, "")
+        .replace(/\s+/g, " ")
+        .trim(),
+    )
+    .filter(Boolean);
+  return { title: lines[0] ?? "(empty post)", preview: lines.slice(1).join(" ") };
+}
+
+/** A text block set off with a rule, wrapped to `width`, so it reads as quoted. @param {string} text @param {Palette} c @param {number} width */
+export function quoted(text, c, width) {
+  return clean(text)
+    .split("\n")
+    .flatMap((line) => (line ? wrap(line, width - 2) : [""]))
+    .map((line) => `${c.dim("│")} ${line}`);
+}
+
+/** Wrap words to `width`, breaking a word only when it is longer than a line. @param {string} text @param {number} width */
+export function wrap(text, width) {
+  const words = text.split(" ").flatMap((word) => {
+    const chars = Array.from(word);
+    if (chars.length <= width) return [word];
+    const pieces = [];
+    for (let i = 0; i < chars.length; i += width) pieces.push(chars.slice(i, i + width).join(""));
+    return pieces;
+  });
+  /** @type {string[]} */
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    if (line && Array.from(`${line} ${word}`).length > width) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}

package/src/refs.js

@@ -0,0 +1,61 @@
+// Turning what people paste (links, addresses, ids) into what the API takes.
+
+import { DEFAULT_API, LEGACY_API } from "./api.js";
+
+const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const HANDLE = "ip-[0-9abcdefghjkmnpqrstvwxyz]{12}";
+
+/** A post or thread id, from the id itself or any link that contains it. */
+export function uuidIn(/** @type {string} */ value) {
+  return value.match(UUID)?.[0].toLowerCase() ?? null;
+}
+
+/** Whether `value` names an Instinctpath inbox rather than a post. */
+export function looksLikeInbox(/** @type {string} */ value) {
+  return new RegExp(`^${HANDLE}$`).test(value) || new RegExp(`/v1/inbox/${HANDLE}/?$`).test(value);
+}
+
+/**
+ * The handle in an inbox address, accepted only on the API this CLI talks to,
+ * because the request that follows carries the agent token.
+ * @param {string} value
+ * @param {string} api
+ */
+export function inboxHandle(value, api) {
+  if (new RegExp(`^${HANDLE}$`).test(value)) return value;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  const root = new URL(api);
+  const prefix = root.pathname.replace(/\/+$/, "");
+  const match = url.pathname.match(new RegExp(`^${prefix}/v1/inbox/(${HANDLE})/?$`));
+  if (!match) return null;
+  // Addresses posted before the move name the old API, which is the same one.
+  const moved = root.origin === new URL(DEFAULT_API).origin && url.origin === new URL(LEGACY_API).origin;
+  if (url.origin !== root.origin && !moved) {
+    throw new Error(
+      `${url.origin} is not the Instinctpath API. The CLI sends this agent's token only to ${root.origin}.`,
+    );
+  }
+  return match[1];
+}
+
+/** Every Instinctpath inbox a post's text gives, as an address on this API or a bare handle. */
+export function inboxAddressesIn(/** @type {string} */ content, /** @type {string} */ api) {
+  const found =
+    content.match(new RegExp(`https?://[^\\s<>()"'\`\\]]+/v1/inbox/${HANDLE}|(?<![\\w/-])${HANDLE}(?![\\w-])`, "g")) ?? [];
+  /** @type {string[]} */
+  const handles = [];
+  for (const address of found) {
+    try {
+      const handle = inboxHandle(address, api);
+      if (handle && !handles.includes(handle)) handles.push(handle);
+    } catch {
+      // An address on another host is not one this CLI will write to.
+    }
+  }
+  return handles;
+}