@todoforai/tfa-memory 0.1.0

package/dist/cli.js

@@ -0,0 +1,715 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+import { readFileSync as readFileSync4 } from "node:fs";
+
+// node_modules/@todoforai/tfa-subagent/dist/auth.js
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir, platform } from "node:os";
+var DEFAULT_API_URL = "https://api.todofor.ai";
+function normalizeApiUrl(url) {
+  if (url.startsWith("localhost"))
+    return `http://${url}`;
+  if (!url.startsWith("http://") && !url.startsWith("https://"))
+    return `https://${url}`;
+  return url.replace(/\/+$/, "");
+}
+function credentialsPath() {
+  return platform() === "win32" ? join(homedir(), "AppData", "Roaming", "todoforai", "credentials.json") : platform() === "darwin" ? join(homedir(), "Library", "Application Support", "todoforai", "credentials.json") : join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "todoforai", "credentials.json");
+}
+function credentialsPaths() {
+  return [credentialsPath()];
+}
+function writeSecure(p, data) {
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 384 });
+  try {
+    chmodSync(p, 384);
+  } catch {}
+}
+function readStoredAuth(apiUrl) {
+  for (const p of credentialsPaths()) {
+    try {
+      const c = JSON.parse(readFileSync(p, "utf-8"));
+      const apiToken = c[apiUrl] || c.apiToken || c.apiKey || "";
+      const host = c.backendHost || "";
+      const storedApiUrl = typeof c.apiUrl === "string" && c.apiUrl ? c.apiUrl : host ? `${host === "localhost" || host === "127.0.0.1" ? "http" : "https"}://${host}` : undefined;
+      return {
+        apiToken,
+        apiUrl: storedApiUrl,
+        deviceId: typeof c.deviceId === "string" ? c.deviceId : undefined,
+        deviceSecret: typeof c.deviceSecret === "string" ? c.deviceSecret : undefined
+      };
+    } catch {}
+  }
+  return { apiToken: "" };
+}
+function persistApiToken(token) {
+  for (const p of credentialsPaths()) {
+    try {
+      const c = JSON.parse(readFileSync(p, "utf-8"));
+      c.apiToken = token;
+      writeSecure(p, c);
+      return;
+    } catch {}
+  }
+}
+async function refreshDeviceToken(opts = {}) {
+  const envUrl = process.env.TODOFORAI_API_URL || process.env.API_URL;
+  const initialApiUrl = normalizeApiUrl(opts.apiUrl || envUrl || DEFAULT_API_URL);
+  const stored = readStoredAuth(initialApiUrl);
+  const apiUrl = normalizeApiUrl(opts.apiUrl || envUrl || stored.apiUrl || DEFAULT_API_URL);
+  if (!stored.deviceId || !stored.deviceSecret)
+    return "";
+  try {
+    const res = await fetch(`${apiUrl}/api/v1/cli/device/token`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ deviceId: stored.deviceId, secret: stored.deviceSecret })
+    });
+    if (!res.ok)
+      return "";
+    const data = await res.json();
+    if (!data.token)
+      return "";
+    persistApiToken(data.token);
+    return data.token;
+  } catch {
+    return "";
+  }
+}
+async function fetchWithRenew(url, init, opts) {
+  const header = opts.header ?? "x-api-key";
+  const renewOn = opts.renewOn ?? [401];
+  const send = (token) => fetch(url, { ...init, headers: { ...init.headers, [header]: token } });
+  let res = await send(opts.token);
+  if (renewOn.includes(res.status) && opts.token.startsWith("dst_")) {
+    const fresh = await refreshDeviceToken({ apiUrl: opts.apiUrl });
+    if (fresh && fresh !== opts.token)
+      return { res: await send(fresh), token: fresh };
+  }
+  return { res, token: opts.token };
+}
+function resolveToken(opts = {}) {
+  const envUrl = process.env.TODOFORAI_API_URL || process.env.API_URL;
+  const initialApiUrl = normalizeApiUrl(opts.apiUrl || envUrl || DEFAULT_API_URL);
+  const stored = readStoredAuth(initialApiUrl);
+  const apiUrl = normalizeApiUrl(opts.apiUrl || envUrl || stored.apiUrl || DEFAULT_API_URL);
+  const apiToken = opts.apiToken || process.env.TODOFORAI_API_TOKEN || stored.apiToken || "";
+  if (!apiToken)
+    throw new Error("TODOFORAI_API_TOKEN not set and no apiToken found in ~/.config/todoforai/credentials.json (run `<cli> login` or `todoforai-bridge login`, or pass --api-token)");
+  return { apiUrl, apiToken };
+}
+
+// node_modules/@todoforai/tfa-subagent/dist/login.js
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, chmodSync as chmodSync2 } from "node:fs";
+import { join as join2, dirname as dirname2 } from "node:path";
+import { homedir as homedir2, platform as platform2 } from "node:os";
+import { spawn } from "node:child_process";
+import { platform as platform22, hostname } from "node:os";
+var DEFAULT_API_URL2 = "https://api.todofor.ai";
+function normalizeApiUrl2(url) {
+  if (url.startsWith("localhost"))
+    return `http://${url}`;
+  if (!url.startsWith("http://") && !url.startsWith("https://"))
+    return `https://${url}`;
+  return url.replace(/\/+$/, "");
+}
+function credentialsPath2() {
+  return platform2() === "win32" ? join2(homedir2(), "AppData", "Roaming", "todoforai", "credentials.json") : platform2() === "darwin" ? join2(homedir2(), "Library", "Application Support", "todoforai", "credentials.json") : join2(process.env.XDG_CONFIG_HOME || join2(homedir2(), ".config"), "todoforai", "credentials.json");
+}
+function credentialsPaths2() {
+  return [credentialsPath2()];
+}
+function writeSecure2(p, data) {
+  mkdirSync2(dirname2(p), { recursive: true });
+  writeFileSync2(p, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 384 });
+  try {
+    chmodSync2(p, 384);
+  } catch {}
+}
+function writeCredentials(fields) {
+  const p = credentialsPath2();
+  let existing = {};
+  try {
+    existing = JSON.parse(readFileSync2(p, "utf-8"));
+  } catch {}
+  writeSecure2(p, { ...existing, ...fields });
+}
+function readStoredAuth2(apiUrl) {
+  for (const p of credentialsPaths2()) {
+    try {
+      const c = JSON.parse(readFileSync2(p, "utf-8"));
+      const apiToken = c[apiUrl] || c.apiToken || c.apiKey || "";
+      const host = c.backendHost || "";
+      const storedApiUrl = typeof c.apiUrl === "string" && c.apiUrl ? c.apiUrl : host ? `${host === "localhost" || host === "127.0.0.1" ? "http" : "https"}://${host}` : undefined;
+      return {
+        apiToken,
+        apiUrl: storedApiUrl,
+        deviceId: typeof c.deviceId === "string" ? c.deviceId : undefined,
+        deviceSecret: typeof c.deviceSecret === "string" ? c.deviceSecret : undefined
+      };
+    } catch {}
+  }
+  return { apiToken: "" };
+}
+function persistApiToken2(token) {
+  for (const p of credentialsPaths2()) {
+    try {
+      const c = JSON.parse(readFileSync2(p, "utf-8"));
+      c.apiToken = token;
+      writeSecure2(p, c);
+      return;
+    } catch {}
+  }
+}
+async function refreshDeviceToken2(opts = {}) {
+  const envUrl = process.env.TODOFORAI_API_URL || process.env.API_URL;
+  const initialApiUrl = normalizeApiUrl2(opts.apiUrl || envUrl || DEFAULT_API_URL2);
+  const stored = readStoredAuth2(initialApiUrl);
+  const apiUrl = normalizeApiUrl2(opts.apiUrl || envUrl || stored.apiUrl || DEFAULT_API_URL2);
+  if (!stored.deviceId || !stored.deviceSecret)
+    return "";
+  try {
+    const res = await fetch(`${apiUrl}/api/v1/cli/device/token`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ deviceId: stored.deviceId, secret: stored.deviceSecret })
+    });
+    if (!res.ok)
+      return "";
+    const data = await res.json();
+    if (!data.token)
+      return "";
+    persistApiToken2(data.token);
+    return data.token;
+  } catch {
+    return "";
+  }
+}
+function defaultDeviceName() {
+  const n = hostname().replace(/[^a-zA-Z0-9_-]/g, "-").replace(/^[-_]+/, "").slice(0, 64);
+  return n || undefined;
+}
+var POLL_INTERVAL_MS = 2000;
+function openBrowser(url) {
+  const cmd = platform22() === "darwin" ? "open" : platform22() === "win32" ? "cmd" : "xdg-open";
+  const args = platform22() === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {}
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function login(opts) {
+  const apiUrl = normalizeApiUrl2(opts.apiUrl || process.env.TODOFORAI_API_URL || process.env.API_URL || DEFAULT_API_URL2);
+  let init;
+  try {
+    const res = await fetch(`${apiUrl}/api/v1/cli/login/init`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ clientName: "cli", deviceName: opts.deviceName || defaultDeviceName() })
+    });
+    if (!res.ok) {
+      console.error(`${opts.binName}: login init failed (HTTP ${res.status})`);
+      return 1;
+    }
+    init = await res.json();
+  } catch (e) {
+    console.error(`${opts.binName}: login init failed: ${e?.message ?? e}`);
+    return 1;
+  }
+  console.log(`
+To authenticate, open this URL and approve:
+
+  ${init.url}
+`);
+  openBrowser(init.url);
+  console.log("Waiting for approval…");
+  const deadline = Date.now() + init.expiresIn * 1000;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    let poll;
+    try {
+      const res = await fetch(`${apiUrl}/api/v1/cli/login/poll?code=${encodeURIComponent(init.code)}`, {
+        headers: { "content-type": "application/json" }
+      });
+      if (!res.ok)
+        continue;
+      poll = await res.json();
+    } catch {
+      continue;
+    }
+    if (poll.status === "pending")
+      continue;
+    if (poll.status === "expired") {
+      console.error(`${opts.binName}: login code expired — run login again`);
+      return 1;
+    }
+    if (!poll.device) {
+      console.error(`${opts.binName}: login completed without device credentials`);
+      return 1;
+    }
+    writeCredentials({
+      deviceId: poll.device.id,
+      deviceSecret: poll.device.secret,
+      deviceName: poll.device.name,
+      apiUrl,
+      backendHost: new URL(apiUrl).hostname,
+      ...poll.apiToken ? { apiToken: poll.apiToken } : {},
+      ...poll.user ? { userId: poll.user.id, userEmail: poll.user.email, ...poll.user.name ? { userName: poll.user.name } : {} } : {}
+    });
+    if (!poll.apiToken) {
+      const minted = await refreshDeviceToken2({ apiUrl });
+      if (!minted) {
+        console.error(`${opts.binName}: approved, but failed to mint a session token — try again`);
+        return 1;
+      }
+    }
+    console.log(`
+${opts.binName}: authenticated as ${poll.user?.email ?? poll.user?.id ?? "(unknown)"} (device ${poll.device.name})`);
+    return 0;
+  }
+  console.error(`${opts.binName}: timed out waiting for approval`);
+  return 1;
+}
+async function handleLogin(argv, binName) {
+  if (argv[0] !== "login")
+    return false;
+  const rest = argv.slice(1);
+  const get = (flag) => {
+    const i = rest.indexOf(flag);
+    return i >= 0 ? rest[i + 1] : undefined;
+  };
+  process.exit(await login({ binName, deviceName: get("--device-name"), apiUrl: get("--api-url") }));
+}
+
+// node_modules/@todoforai/tfa-subagent/dist/whoami.js
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, chmodSync as chmodSync3 } from "node:fs";
+import { join as join3, dirname as dirname3 } from "node:path";
+import { homedir as homedir3, platform as platform3 } from "node:os";
+var DEFAULT_API_URL3 = "https://api.todofor.ai";
+function normalizeApiUrl3(url) {
+  if (url.startsWith("localhost"))
+    return `http://${url}`;
+  if (!url.startsWith("http://") && !url.startsWith("https://"))
+    return `https://${url}`;
+  return url.replace(/\/+$/, "");
+}
+function credentialsPath3() {
+  return platform3() === "win32" ? join3(homedir3(), "AppData", "Roaming", "todoforai", "credentials.json") : platform3() === "darwin" ? join3(homedir3(), "Library", "Application Support", "todoforai", "credentials.json") : join3(process.env.XDG_CONFIG_HOME || join3(homedir3(), ".config"), "todoforai", "credentials.json");
+}
+function credentialsPaths3() {
+  return [credentialsPath3()];
+}
+function writeSecure3(p, data) {
+  mkdirSync3(dirname3(p), { recursive: true });
+  writeFileSync3(p, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 384 });
+  try {
+    chmodSync3(p, 384);
+  } catch {}
+}
+function readStoredAuth3(apiUrl) {
+  for (const p of credentialsPaths3()) {
+    try {
+      const c = JSON.parse(readFileSync3(p, "utf-8"));
+      const apiToken = c[apiUrl] || c.apiToken || c.apiKey || "";
+      const host = c.backendHost || "";
+      const storedApiUrl = typeof c.apiUrl === "string" && c.apiUrl ? c.apiUrl : host ? `${host === "localhost" || host === "127.0.0.1" ? "http" : "https"}://${host}` : undefined;
+      return {
+        apiToken,
+        apiUrl: storedApiUrl,
+        deviceId: typeof c.deviceId === "string" ? c.deviceId : undefined,
+        deviceSecret: typeof c.deviceSecret === "string" ? c.deviceSecret : undefined
+      };
+    } catch {}
+  }
+  return { apiToken: "" };
+}
+function persistApiToken3(token) {
+  for (const p of credentialsPaths3()) {
+    try {
+      const c = JSON.parse(readFileSync3(p, "utf-8"));
+      c.apiToken = token;
+      writeSecure3(p, c);
+      return;
+    } catch {}
+  }
+}
+async function refreshDeviceToken3(opts = {}) {
+  const envUrl = process.env.TODOFORAI_API_URL || process.env.API_URL;
+  const initialApiUrl = normalizeApiUrl3(opts.apiUrl || envUrl || DEFAULT_API_URL3);
+  const stored = readStoredAuth3(initialApiUrl);
+  const apiUrl = normalizeApiUrl3(opts.apiUrl || envUrl || stored.apiUrl || DEFAULT_API_URL3);
+  if (!stored.deviceId || !stored.deviceSecret)
+    return "";
+  try {
+    const res = await fetch(`${apiUrl}/api/v1/cli/device/token`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ deviceId: stored.deviceId, secret: stored.deviceSecret })
+    });
+    if (!res.ok)
+      return "";
+    const data = await res.json();
+    if (!data.token)
+      return "";
+    persistApiToken3(data.token);
+    return data.token;
+  } catch {
+    return "";
+  }
+}
+async function fetchWithRenew2(url, init, opts) {
+  const header = opts.header ?? "x-api-key";
+  const renewOn = opts.renewOn ?? [401];
+  const send = (token) => fetch(url, { ...init, headers: { ...init.headers, [header]: token } });
+  let res = await send(opts.token);
+  if (renewOn.includes(res.status) && opts.token.startsWith("dst_")) {
+    const fresh = await refreshDeviceToken3({ apiUrl: opts.apiUrl });
+    if (fresh && fresh !== opts.token)
+      return { res: await send(fresh), token: fresh };
+  }
+  return { res, token: opts.token };
+}
+function resolveToken2(opts = {}) {
+  const envUrl = process.env.TODOFORAI_API_URL || process.env.API_URL;
+  const initialApiUrl = normalizeApiUrl3(opts.apiUrl || envUrl || DEFAULT_API_URL3);
+  const stored = readStoredAuth3(initialApiUrl);
+  const apiUrl = normalizeApiUrl3(opts.apiUrl || envUrl || stored.apiUrl || DEFAULT_API_URL3);
+  const apiToken = opts.apiToken || process.env.TODOFORAI_API_TOKEN || stored.apiToken || "";
+  if (!apiToken)
+    throw new Error("TODOFORAI_API_TOKEN not set and no apiToken found in ~/.config/todoforai/credentials.json (run `<cli> login` or `todoforai-bridge login`, or pass --api-token)");
+  return { apiUrl, apiToken };
+}
+async function whoami(opts) {
+  let apiUrl;
+  let apiToken;
+  try {
+    ({ apiUrl, apiToken } = resolveToken2({ apiUrl: opts.apiUrl, apiToken: opts.apiToken }));
+  } catch {
+    console.log(`${opts.binName}: not authenticated`);
+    return 1;
+  }
+  try {
+    const { res } = await fetchWithRenew2(`${apiUrl}/dst/v1/users/profile`, {}, { apiUrl, token: apiToken });
+    if (!res.ok) {
+      console.log(`${opts.binName}: not authenticated`);
+      return 1;
+    }
+    const body = await res.json();
+    console.log(`${opts.binName}: authenticated as ${body.user?.id ?? "(unknown)"}`);
+    return 0;
+  } catch {
+    console.log(`${opts.binName}: not authenticated`);
+    return 1;
+  }
+}
+
+// node_modules/@todoforai/tfa-subagent/dist/update-notifier.js
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+function isLinkedInstall() {
+  try {
+    return !fs.realpathSync(process.argv[1] || "").includes(`${path.sep}node_modules${path.sep}`);
+  } catch {
+    return false;
+  }
+}
+var TTL_MS = 24 * 60 * 60 * 1000;
+var CACHE_DIR = path.join(os.homedir(), ".config", "todoforai");
+function cmpVer(a, b) {
+  const pa = a.split("-")[0].split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split("-")[0].split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0;i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d)
+      return d;
+  }
+  return 0;
+}
+function checkForUpdates(pkg) {
+  if (!process.stderr.isTTY || process.env.CI || process.env.NO_UPDATE_NOTIFIER || isLinkedInstall())
+    return;
+  const cacheFile = path.join(CACHE_DIR, `notifier-${encodeURIComponent(pkg.name)}.json`);
+  let cache = {};
+  try {
+    cache = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+  } catch {}
+  if (cache.latest && cmpVer(cache.latest, pkg.version) > 0) {
+    process.stderr.write(`
+\x1B[33m  Update available: \x1B[2m${pkg.version}\x1B[22m → \x1B[1m${cache.latest}\x1B[0m
+` + `\x1B[33m  Run:\x1B[0m npm i -g ${pkg.name}
+
+`);
+  }
+  if (Date.now() - (cache.ts ?? 0) > TTL_MS) {
+    try {
+      fs.mkdirSync(CACHE_DIR, { recursive: true });
+      fs.writeFileSync(cacheFile, JSON.stringify({ ...cache, ts: Date.now() }));
+    } catch {}
+    fetch(`https://registry.npmjs.org/${pkg.name}/latest`, { signal: AbortSignal.timeout(3000) }).then((r) => r.ok ? r.json() : null).then((j) => {
+      if (!j?.version)
+        return;
+      fs.writeFileSync(cacheFile, JSON.stringify({ ts: Date.now(), latest: j.version }));
+    }).catch(() => {});
+  }
+}
+// package.json
+var package_default = {
+  name: "@todoforai/tfa-memory",
+  version: "0.1.0",
+  description: "Zero-config TODOforAI memory CLI — add/search/ls/get/rm text memory rows addressed as source/ref, with full-text and semantic search. Reuses bridge credentials.",
+  type: "module",
+  bin: {
+    "tfa-memory": "dist/cli.js"
+  },
+  scripts: {
+    build: "bun build src/cli.ts --outdir dist --target node --format esm",
+    dev: "bun run src/cli.ts",
+    prepublishOnly: "bun run build"
+  },
+  devDependencies: {
+    "@todoforai/tfa-subagent": "^0.1.9",
+    "@types/node": "^20.11.0"
+  },
+  keywords: [
+    "cli",
+    "memory",
+    "search",
+    "todoforai"
+  ],
+  author: "TODO for AI",
+  license: "MIT",
+  files: [
+    "dist"
+  ]
+};
+
+// src/cli.ts
+var isEntrypoint = __require.main == __require.module === true || !!process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+function printHelp() {
+  console.log(`tfa-memory — TODOforAI memory CLI (addressable, searchable text rows).
+
+Every row's address is \`source/ref\` — sources are directories, refs are
+filenames. A source exists once the first row names it. Re-adding the same
+address updates in place; identical content is skipped (no re-embed).
+
+Usage:
+  tfa-memory <command> [options] [args...]
+
+Commands:
+  add [source/ref] <text|->     Save a row. Without an address → manual/<timestamp>.
+                                "-" reads stdin.
+  search <query>                Full-text search (newest first)
+  ls                            List rows, newest first
+  get <source/ref>              Print full content of one row
+  rm <source/ref>               Delete one row
+  rm --source <name>            Delete every row in a source
+  sources                       List sources with counts and last write
+  login                         Device login — mint & persist credentials
+  whoami                        Print resolved auth context
+
+Options:
+  -s, --source <a,b>            Restrict search/ls to sources (comma-separated)
+      --semantic                Embedding KNN search (meaning, not keywords)
+  -n, --limit <n>               Max rows (default 10, max 50)
+  -j, --json                    Machine-readable output
+  --api-token <token>           Override API token
+  --api-url <url>               Override backend URL
+  -h, --help                    Show this help
+  -v, --version                 Show version
+
+Examples:
+  tfa-memory add "postgres prod runs on hetzner-3, failover is manual"
+  tfa-memory add deploy-notes/rollback "run scripts/rollback.sh, then verify /health"
+  cat docs/auth.md | tfa-memory add acme/docs/auth.md -
+  tfa-memory search "rollback procedure"
+  tfa-memory search "how do we deploy" --semantic
+  tfa-memory ls --source deploy-notes
+  tfa-memory get deploy-notes/rollback
+  tfa-memory rm deploy-notes/rollback
+  tfa-memory rm --source acme
+  tfa-memory sources
+`);
+}
+function die(msg, code = 1) {
+  console.error(`Error: ${msg}`);
+  process.exit(code);
+}
+function splitAddr(addr) {
+  const i = addr.indexOf("/");
+  if (i < 1 || i === addr.length - 1)
+    die(`invalid address "${addr}" — expected source/ref`);
+  return [addr.slice(0, i), addr.slice(i + 1)];
+}
+async function api(ctx, method, path2, body) {
+  const init = {
+    method,
+    headers: body !== undefined ? { "content-type": "application/json" } : {},
+    body: body !== undefined ? JSON.stringify(body) : undefined
+  };
+  const { res, token } = await fetchWithRenew(`${ctx.apiUrl}/dst/v1${path2}`, init, { apiUrl: ctx.apiUrl, token: ctx.token });
+  ctx.token = token;
+  if (!res.ok) {
+    const text = await res.text();
+    let msg = text;
+    try {
+      msg = JSON.parse(text)?.message ?? text;
+    } catch {}
+    die(`HTTP ${res.status}: ${msg}`);
+  }
+  return res.status === 204 ? null : await res.json();
+}
+function printRows(rows, json, snippet = 120) {
+  if (json)
+    return console.log(JSON.stringify(rows, null, 2));
+  if (!rows.length)
+    return console.log("(no results)");
+  for (const r of rows) {
+    const oneline = r.content.replace(/\s+/g, " ").slice(0, snippet);
+    console.log(`${r.address}	${new Date(r.createdAt).toISOString().slice(0, 16)}	${oneline}`);
+  }
+}
+var qs = (params) => {
+  const p = new URLSearchParams;
+  for (const [k, v] of Object.entries(params))
+    if (v !== undefined)
+      p.set(k, String(v));
+  const s = p.toString();
+  return s ? `?${s}` : "";
+};
+async function main() {
+  await handleLogin(process.argv.slice(2), "tfa-memory");
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      source: { type: "string", short: "s" },
+      semantic: { type: "boolean", default: false },
+      limit: { type: "string", short: "n" },
+      json: { type: "boolean", short: "j", default: false },
+      "api-token": { type: "string" },
+      "api-url": { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false }
+    },
+    allowPositionals: true,
+    strict: false
+  });
+  if (values.help) {
+    printHelp();
+    return;
+  }
+  if (values.version) {
+    console.log(`tfa-memory ${VERSION}`);
+    return;
+  }
+  const [cmd, ...rest] = positionals;
+  if (!cmd) {
+    printHelp();
+    process.exit(2);
+  }
+  if (cmd === "whoami")
+    process.exit(await whoami({
+      binName: "tfa-memory",
+      apiUrl: values["api-url"],
+      apiToken: values["api-token"]
+    }));
+  let ctx;
+  try {
+    const { apiUrl, apiToken } = resolveToken({
+      apiUrl: values["api-url"],
+      apiToken: values["api-token"]
+    });
+    ctx = { apiUrl, token: apiToken };
+  } catch (e) {
+    die(e?.message ?? String(e));
+  }
+  const json = values.json;
+  const limit = values.limit !== undefined ? Number(values.limit) : undefined;
+  if (limit !== undefined && (!Number.isInteger(limit) || limit < 1))
+    die(`--limit must be a positive integer`, 2);
+  const sources = values.source;
+  switch (cmd) {
+    case "add": {
+      let source = "manual", ref = new Date().toISOString().slice(0, 19), text;
+      if (rest.length >= 2 && rest[0].includes("/")) {
+        [source, ref] = splitAddr(rest[0]);
+        text = rest[1];
+      } else if (rest.length === 1) {
+        text = rest[0];
+      } else
+        die(`usage: tfa-memory add [source/ref] "text" | -`, 2);
+      if (text === "-")
+        text = readFileSync4(0, "utf8");
+      text = text.trim();
+      if (!text)
+        die("empty content");
+      const res = await api(ctx, "POST", "/memory", { source, ref, content: text });
+      console.log(json ? JSON.stringify(res) : `${res.status} ${res.address}`);
+      break;
+    }
+    case "search": {
+      const query = rest[0] ?? die(`usage: tfa-memory search "query"`, 2);
+      const res = await api(ctx, "GET", `/memory/search${qs({ query, semantic: values.semantic ? true : undefined, sources, limit })}`);
+      printRows(res.rows, json, 200);
+      break;
+    }
+    case "ls": {
+      const res = await api(ctx, "GET", `/memory${qs({ sources, limit })}`);
+      printRows(res.rows, json);
+      break;
+    }
+    case "get": {
+      const [source, ref] = splitAddr(rest[0] ?? die("address required (source/ref)", 2));
+      const res = await api(ctx, "GET", `/memory/get${qs({ source, ref })}`);
+      if (json)
+        console.log(JSON.stringify(res, null, 2));
+      else
+        process.stdout.write(res.content + `
+`);
+      break;
+    }
+    case "rm":
+    case "delete":
+    case "del": {
+      let body;
+      if (rest[0]) {
+        const [source, ref] = splitAddr(rest[0]);
+        body = { source, ref };
+      } else if (sources && !sources.includes(","))
+        body = { source: sources };
+      else
+        die("usage: tfa-memory rm <source/ref> | tfa-memory rm --source <name>", 2);
+      const res = await api(ctx, "POST", "/memory/remove", body);
+      console.log(json ? JSON.stringify(res) : `removed ${res.removed}`);
+      break;
+    }
+    case "sources": {
+      const res = await api(ctx, "GET", "/memory/sources");
+      if (json) {
+        console.log(JSON.stringify(res.sources, null, 2));
+        break;
+      }
+      if (!res.sources.length) {
+        console.log("(no sources)");
+        break;
+      }
+      const w = Math.max(...res.sources.map((s) => s.source.length));
+      for (const s of res.sources.sort((a, b) => b.lastWrite - a.lastWrite))
+        console.log(`${s.source.padEnd(w)}  ${String(s.count).padStart(4)}  ${new Date(s.lastWrite).toISOString().slice(0, 16)}`);
+      break;
+    }
+    default:
+      die(`unknown command: ${cmd} (try 'tfa-memory --help')`, 2);
+  }
+}
+var VERSION = package_default.version;
+if (isEntrypoint) {
+  checkForUpdates({ name: package_default.name, version: package_default.version });
+  main();
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@todoforai/tfa-memory",
+  "version": "0.1.0",
+  "description": "Zero-config TODOforAI memory CLI \u2014 add/search/ls/get/rm text memory rows addressed as source/ref, with full-text and semantic search. Reuses bridge credentials.",
+  "type": "module",
+  "bin": {
+    "tfa-memory": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "bun build src/cli.ts --outdir dist --target node --format esm",
+    "dev": "bun run src/cli.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@todoforai/tfa-subagent": "^0.1.9",
+    "@types/node": "^20.11.0"
+  },
+  "keywords": [
+    "cli",
+    "memory",
+    "search",
+    "todoforai"
+  ],
+  "author": "TODO for AI",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ]
+}