takibibase 1.0.0 → 1.0.3

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2026, Takibi (also known as Takibi Base, takibibase.com).
+Copyright (c) 2026, Deian Isac (operating as Takibi / Takibi Base, takibibase.com).
 All rights reserved.
 
 This software is proprietary to Takibi. You may install and run it

package/README.md

@@ -9,11 +9,12 @@ Needs Node.js 22+. This directory is also the npm package source:
 `takibi.mjs` stays a single zero-dependency file so the
 `/downloads/takibi.mjs` copy and the published package never drift.
 
-Thin client-side enablement for agents. Zero changes to `apps/api`,
-`apps/web`, schema, or grants — this directory is the whole feature.
+Thin client-side enablement for agents. Its only server pairing is
+`GET /v1/projects`, which lists a key's granted collections — everything
+else lives in this directory.
 
 - `takibi.mjs` — the CLI. Single-file Node ≥ 22, zero dependencies.
-  Run it as `node tools/takibi/takibi.mjs …`, or alias it:
+  Run it from a checkout as `node tools/takibi/takibi.mjs …`, or alias it:
   `alias takibi='node <checkout>/tools/takibi/takibi.mjs'`.
 - `SKILL.md` — the `takibi-use` skill. Short on purpose; the CLI carries
   the contract. Install it into your harness's skills dir, or paste it
@@ -28,10 +29,11 @@ Thin client-side enablement for agents. Zero changes to `apps/api`,
 3. Optional: one base-URL line in `~/.takibi/config` (default
    `http://localhost:3849`). Env overrides: `$TAKIBI_KEY_FILE`,
    `$TAKIBI_BASE_URL`.
-4. `takibi projects --add <name> <uuid>` per project (UUIDs are in
-   Settings → Projects). `GET /v1/projects` is account-only, so names
-   live in `~/.takibi/projects` as `name=uuid` lines; UUIDs also work
-   directly in `--project`, and single-grant keys may omit it.
+4. `takibi projects` — lists the projects this key can reach, straight
+   from the API. Names resolve in `--project` (UUIDs work too, from
+   Settings → Projects); single-grant keys may omit it. Only for offline
+   use: `takibi projects --add <name> <uuid>` keeps local aliases in
+   `~/.takibi/projects`.
 5. `takibi version` — probes the API without needing the key.
 
 ## Give an agent

package/SKILL.md

@@ -19,10 +19,14 @@ error hints.
   committed. If a command says the key is missing, stop and ask.
 - Base URL defaults to `http://localhost:3849` (local boot). Override with
   `$TAKIBI_BASE_URL` or one URL line in `~/.takibi/config`.
-- Projects: `takibi projects` lists saved names. `--project` takes a name
-  or a UUID; single-grant keys may omit it. New name? Ask the founder for
-  the UUID once, then `takibi projects --add <name> <uuid>`.
+- Projects: `takibi projects` lists what this key can reach. `--project`
+  takes a name or a UUID; single-grant keys may omit it.
+  `takibi projects --add <name> <uuid>` keeps local aliases for offline use.
 - First probe: `takibi version` (needs no key; shows build + `jev` status).
+- Update notice: the CLI polls the npm registry once a day and nudges on
+  stderr when behind (never on `--json`). Silence it with
+  `TAKIBI_NO_UPDATE_CHECK=1`; point it at a mirror with
+  `TAKIBI_REGISTRY_URL`.
 
 ## Commands
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "takibibase",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Thin CLI for the Takibi API: ask, search, tasks, docs. Single file, zero dependencies.",
   "type": "module",
   "bin": {
-    "takibi": "./takibi.mjs"
+    "takibi": "takibi.mjs"
   },
   "files": [
     "takibi.mjs",

package/takibi.mjs

@@ -11,9 +11,10 @@
  * - Base URL: $TAKIBI_BASE_URL or ~/.takibi/config, else localhost:3849.
  *
  * Pure-client deviations the server forces (no apps/api changes allowed):
- * - GET /v1/projects is account-only, so `projects` reads a LOCAL map
- *   (~/.takibi/projects, `name=uuid` lines) and --project resolves names
- *   through it. UUIDs pass straight through.
+ * - Keys list their own granted scope via GET /v1/projects, so `projects`
+ *   reads the API first and --project resolves names through it. A LOCAL
+ *   map (~/.takibi/projects, `name=uuid` lines) remains as the offline
+ *   fallback and for custom aliases. UUIDs pass straight through.
  * - There is no GET /v1/tasks/:id, so `tasks get` lists and filters.
  * - Account-only routes (doc download, uploads, deletes) answer 401, not
  *   403, to Bearer callers; `doc download` refuses client-side with a hint.
@@ -21,21 +22,24 @@
  * Exit codes: 0 ok (honest abstains included), 1 transport/API error,
  * 2 usage error.
  */
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 /** Baked fallback; the published package re-reads package.json next door. */
-const BAKED_VERSION = '1.0.0';
-const CLI_VERSION = (() => {
+const BAKED_VERSION = '1.0.3';
+const CLI_INFO = (() => {
   try {
     const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
-    if (typeof pkg.version === 'string' && pkg.version.length > 0) return pkg.version;
+    if (pkg.name === 'takibibase' && typeof pkg.version === 'string' && pkg.version.length > 0) {
+      return { version: pkg.version, singleFile: false };
+    }
   } catch {
     // Single-file download: no package.json travels with takibi.mjs.
   }
-  return BAKED_VERSION;
+  return { version: BAKED_VERSION, singleFile: true };
 })();
+const CLI_VERSION = CLI_INFO.version;
 const DEFAULT_BASE_URL = 'http://localhost:3849';
 const REQUEST_TIMEOUT_MS = 90_000;
 const USER_AGENT = `takibibase/${CLI_VERSION}`;
@@ -65,6 +69,78 @@ const usageError = (message) => new CliError(message, { exitCode: 2 });
 
 const takibiDir = () => join(homedir(), '.takibi');
 
+const UPDATE_CHECK_TTL_MS = 86_400_000;
+const REGISTRY_URL = (process.env.TAKIBI_REGISTRY_URL ?? '').trim().replace(/\/+$/, '') || 'https://registry.npmjs.org';
+
+/** Numeric dotted-version compare; false on anything unparseable. */
+function versionBehind(current, latest) {
+  const parts = (v) => String(v ?? '').trim().split('.');
+  const c = parts(current);
+  const l = parts(latest);
+  for (let i = 0; i < Math.max(c.length, l.length); i++) {
+    const a = i < c.length ? Number(c[i]) : 0;
+    const b = i < l.length ? Number(l[i]) : 0;
+    if (!Number.isInteger(a) || !Number.isInteger(b)) return false;
+    if (b > a) return true;
+    if (a > b) return false;
+  }
+  return false;
+}
+
+/** Once-a-day latest-version poll. Stderr only (stdout stays clean),
+ * best-effort, never fails the command. Failures are cached too, so an
+ * unreachable registry costs one slow run a day, not every invocation.
+ * Skipped for --json (errors there are a single JSON object), in CI, and
+ * with TAKIBI_NO_UPDATE_CHECK=1. */
+async function maybeNotifyUpdate({ json = false } = {}) {
+  try {
+    if (json || process.env.CI || process.env.TAKIBI_NO_UPDATE_CHECK === '1') return;
+    const path = join(takibiDir(), 'update-check');
+    let cached = null;
+    try {
+      cached = JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+      // First run: no cache yet.
+    }
+    const fresh = cached && typeof cached.at === 'number' && Date.now() - cached.at < UPDATE_CHECK_TTL_MS;
+    let latest = null;
+    if (fresh) {
+      if (typeof cached.latest !== 'string' || !cached.latest) return;
+      latest = cached.latest;
+    } else {
+      try {
+        const res = await fetch(`${REGISTRY_URL}/takibibase/latest`, { signal: AbortSignal.timeout(1200) });
+        const v = res.ok ? (await res.json())?.version : null;
+        if (typeof v === 'string' && v) latest = v;
+      } catch {
+        // Offline: fall through below.
+      }
+      if (!latest && cached && typeof cached.latest === 'string' && cached.latest) {
+        // Failed refresh keeps the last known version: a timeout or 5xx must
+        // not delete a nudge we already knew about. The fresh timestamp still
+        // stops us hammering the registry.
+        latest = cached.latest;
+      }
+      try {
+        mkdirSync(takibiDir(), { recursive: true });
+        writeFileSync(path, JSON.stringify({ at: Date.now(), latest }));
+      } catch {
+        // Read-only home: notifying still works, caching just retries daily.
+      }
+      if (!latest) return;
+    }
+    if (!versionBehind(CLI_VERSION, latest)) return;
+    err(`takibi: ${latest} is available (you have ${CLI_VERSION}).`);
+    err(
+      CLI_INFO.singleFile
+        ? 'hint: download the latest takibi.mjs from https://takibibase.com/downloads/takibi.mjs'
+        : 'hint: `npm i -g takibibase@latest`, or `npx takibibase@latest` for one-shot runs.',
+    );
+  } catch {
+    // Offline, broken cache, slow registry: stay silent, run the command.
+  }
+}
+
 /** First non-blank, non-comment line of a file, or null when missing. */
 function firstLine(path) {
   if (!existsSync(path)) return null;
@@ -126,11 +202,50 @@ function loadProjectMap() {
   return { map, warnings, path };
 }
 
-/** --project value → uuid-or-undefined. Names resolve via the local map. */
-function resolveProjectFlag(value) {
+/** Failures that mean "answer from the local map instead": old servers that
+ * still gate the list account-only, and an unreachable API when a key is on
+ * disk (offline mode). Config errors — bad base URL, malformed key file —
+ * are the truth and rethrow. */
+function isListFallbackable(e) {
+  if (!(e instanceof CliError)) return false;
+  if (e.status === 401 && /login required/i.test(e.message)) return true;
+  return e.status == null && /^Cannot reach the API at /.test(e.message);
+}
+
+/** --project value → uuid-or-undefined. Names resolve via the API list first, then the local map. */
+async function resolveProjectFlag(value, ctx) {
   if (value === undefined || value === null || value === '') return undefined;
   const v = String(value).trim();
   if (UUID_RE.test(v)) return v;
+  if (ctx?.key && ctx?.baseUrl) {
+    let data;
+    try {
+      data = await api('GET', '/v1/projects', { baseUrl: ctx.baseUrl, key: ctx.key, verbose: ctx.verbose, label: 'projects' });
+    } catch (e) {
+      if (!isListFallbackable(e)) throw e;
+      const { map } = loadProjectMap();
+      const hit = map.get(v);
+      if (hit) return hit;
+      throw e; // Offline and unmapped: the reachability error beats "Unknown project".
+    }
+    // Collection names are not unique: duplicates must not silently resolve.
+    const matches = (data?.projects ?? []).filter((p) => p.name === v);
+    if (matches.length > 1) {
+      throw new CliError(`More than one project is named ${JSON.stringify(v)}.`, {
+        hint: 'Pass --project <uuid> instead; `takibi projects` lists ids.',
+      });
+    }
+    if (matches[0]?.id) return matches[0].id;
+    // Online but unnamed in the grant list: local aliases still apply, and the
+    // server gates the resolved id on the real call.
+    const { map } = loadProjectMap();
+    const alias = map.get(v);
+    if (alias) return alias;
+    const serverNames = (data?.projects ?? []).map((p) => p.name).filter(Boolean);
+    throw new CliError(`Unknown project ${JSON.stringify(v)}.`, {
+      hint: serverNames.length > 0 ? `This key reaches: ${serverNames.join(', ')}.` : 'This key reaches no projects.',
+    });
+  }
   const { map } = loadProjectMap();
   const hit = map.get(v);
   if (hit) return hit;
@@ -138,8 +253,8 @@ function resolveProjectFlag(value) {
   throw new CliError(`Unknown project ${JSON.stringify(v)}.`, {
     hint:
       known.length > 0
-        ? `Known names: ${known.join(', ')}. Pass a project UUID, or ask the account owner for this one.`
-        : 'Pass a project UUID, or ask the account owner to add names via `takibi projects --add <name> <uuid>`.',
+        ? `Known names: ${known.join(', ')}. Run \`takibi projects\` to see what this key can reach, or pass a project UUID.`
+        : 'Run `takibi projects` to see what this key can reach, or pass a project UUID.',
   });
 }
 
@@ -231,12 +346,13 @@ Commands:
   doc list                Documents (metadata)
   doc get <id>            One document's metadata
   doc text <id>           Converted text of one document
-  projects                Saved project names (-> uuids for --project)
+  projects                Granted projects (names -> uuids for --project)
   version                 What build is serving + jev wired|unwired (no key needed)
 
 Global options (accepted before or after the command):
-  --project <name-or-uuid>   Project scope. Names resolve via ~/.takibi/projects;
-                             single-grant keys may omit it entirely.
+  --project <name-or-uuid>   Project scope. Names resolve via the API list,
+                             then ~/.takibi/projects; single-grant keys
+                             may omit it entirely.
   --folder <uuid>            Folder scope (ask, search, doc list only).
   --json                     Raw server JSON instead of human-readable output.
   --verbose                  Log method + URL + status to stderr (never the key).
@@ -250,9 +366,10 @@ Per-command options:
   projects: --add <name> <uuid>
 
 Setup: save the owner-provided key (one <publicId>.<secret> line) to
-~/.takibi/key (chmod 600), optional base URL line to ~/.takibi/config,
-project names via \`takibi projects --add\`. Env overrides: $TAKIBI_KEY_FILE,
-$TAKIBI_BASE_URL. Then \`takibi version\` to probe the API.
+~/.takibi/key (chmod 600), optional base URL line to ~/.takibi/config.
+Env overrides: $TAKIBI_KEY_FILE, $TAKIBI_BASE_URL. Then \`takibi version\`
+to probe the API and \`takibi projects\` to see this key's scope
+(\`projects --add\` keeps local aliases for offline use).
 
 Reads are free. Task claim/status/artifact writes need owner approval in
 conversation. Account-only routes (upload, delete, retry, download originals,
@@ -404,10 +521,10 @@ function renderDoc(d) {
 }
 
 /** Shared context: baseUrl always; key for every command except version/help. */
-function ctxFor(globals, { needKey }) {
+async function ctxFor(globals, { needKey }) {
   const baseUrl = resolveBaseUrl();
   const key = needKey ? resolveKey() : null;
-  const projectId = resolveProjectFlag(globals.project);
+  const projectId = await resolveProjectFlag(globals.project, { baseUrl, key, verbose: globals.verbose });
   const { warnings } = loadProjectMap();
   for (const w of warnings) err(`warning: ${w}`);
   if (globals.folder !== undefined && globals.folder !== null && globals.folder !== '' && !UUID_RE.test(globals.folder)) {
@@ -418,7 +535,7 @@ function ctxFor(globals, { needKey }) {
 
 async function cmdAsk(tokens, globals) {
   const { q, k } = parseQueryArgs(tokens, { kMin: 1, kMax: 12 });
-  const ctx = ctxFor(globals, { needKey: true });
+  const ctx = await ctxFor(globals, { needKey: true });
   // GET carries the contract; POST only when q outgrows a sane URL.
   const data =
     q.length > 1500
@@ -443,7 +560,7 @@ async function cmdAsk(tokens, globals) {
 
 async function cmdSearch(tokens, globals) {
   const { q, k } = parseQueryArgs(tokens, { kMin: 1, kMax: 20 });
-  const ctx = ctxFor(globals, { needKey: true });
+  const ctx = await ctxFor(globals, { needKey: true });
   const data = await api('GET', '/v1/search', {
     ...ctx,
     query: qparams([
@@ -479,7 +596,7 @@ async function cmdTasks(tokens, globals) {
       if (t === '--all') includeArchived = true;
       else throw usageError(`Unexpected ${JSON.stringify(t)}. Usage: takibi tasks list [--all]`);
     }
-    const ctx = ctxFor(globals, { needKey: true });
+    const ctx = await ctxFor(globals, { needKey: true });
     const tasks = await listTasks(ctx, includeArchived);
     if (ctx.json) {
       out(JSON.stringify({ tasks }, null, 2));
@@ -492,7 +609,7 @@ async function cmdTasks(tokens, globals) {
   if (sub === 'get') {
     const [id, extra] = rest;
     if (!id || extra) throw usageError('Usage: takibi tasks get <id>');
-    const ctx = ctxFor(globals, { needKey: true });
+    const ctx = await ctxFor(globals, { needKey: true });
     let tasks = await listTasks(ctx, false);
     let found = tasks.find((t) => t.id === id);
     if (!found) {
@@ -507,7 +624,7 @@ async function cmdTasks(tokens, globals) {
   if (sub === 'claim') {
     const [id, extra] = rest;
     if (!id || extra) throw usageError('Usage: takibi tasks claim <id>');
-    const ctx = ctxFor(globals, { needKey: true });
+    const ctx = await ctxFor(globals, { needKey: true });
     const data = await api('POST', `/v1/tasks/${id}/claim`, { ...ctx, query: qparams([['projectId', ctx.projectId]]), label: 'tasks claim' });
     if (ctx.json) out(JSON.stringify(data, null, 2));
     else renderTask(data.task);
@@ -517,7 +634,7 @@ async function cmdTasks(tokens, globals) {
     const [id, to, extra] = rest;
     if (!id || !to || extra) throw usageError('Usage: takibi tasks status <id> <todo|in_progress|review|done>');
     if (!TASK_STATUSES.includes(to)) throw usageError(`Status is one of ${TASK_STATUSES.join(' | ')}, not ${JSON.stringify(to)}.`);
-    const ctx = ctxFor(globals, { needKey: true });
+    const ctx = await ctxFor(globals, { needKey: true });
     const data = await api('PATCH', `/v1/tasks/${id}`, {
       ...ctx,
       query: qparams([['projectId', ctx.projectId]]),
@@ -543,7 +660,7 @@ async function cmdTasks(tokens, globals) {
       if (!Number.isInteger(n) || n < 0) throw usageError('--size takes an integer >= 0 (asserted bytes).');
       flags.size = n;
     }
-    const ctx = ctxFor(globals, { needKey: true });
+    const ctx = await ctxFor(globals, { needKey: true });
     const data = await api('POST', `/v1/tasks/${taskId}/artifacts`, {
       ...ctx,
       query: qparams([['projectId', ctx.projectId]]),
@@ -568,7 +685,7 @@ async function cmdDoc(tokens, globals) {
       if (rest[i] === '--limit') limit = rest[++i];
       else throw usageError(`Unexpected ${JSON.stringify(rest[i])}. Usage: takibi doc list [--limit <n>]`);
     }
-    const ctx = ctxFor(globals, { needKey: true });
+    const ctx = await ctxFor(globals, { needKey: true });
     const data = await api('GET', '/v1/documents', {
       ...ctx,
       query: qparams([
@@ -595,7 +712,7 @@ async function cmdDoc(tokens, globals) {
       if (sub === 'text' && flagTokens[i] === '--max-chars') maxChars = flagTokens[++i];
       else throw usageError(`Unexpected ${JSON.stringify(flagTokens[i])}. Usage: takibi doc ${sub} <id>${sub === 'text' ? ' [--max-chars <n>]' : ''}`);
     }
-    const ctx = ctxFor(globals, { needKey: true });
+    const ctx = await ctxFor(globals, { needKey: true });
     if (sub === 'get') {
       const data = await api('GET', `/v1/documents/${id}`, { ...ctx, query: qparams([['projectId', ctx.projectId]]), label: 'doc get' });
       if (ctx.json) out(JSON.stringify(data, null, 2));
@@ -659,14 +776,42 @@ async function cmdProjects(tokens, globals) {
     return;
   }
   if (tokens.length > 0) throw usageError(`Unexpected ${JSON.stringify(tokens[0])}. Usage: takibi projects [--add <name> <uuid>]`);
-  const entries = [...map.entries()].map(([name, id]) => ({ name, id }));
+  let entries = null;
+  try {
+    const key = resolveKey();
+    const data = await api('GET', '/v1/projects', { baseUrl: resolveBaseUrl(), key, verbose: globals.verbose, label: 'projects' });
+    const seen = new Set();
+    entries = [];
+    for (const p of data?.projects ?? []) {
+      if (p?.id && !seen.has(p.id)) {
+        seen.add(p.id);
+        entries.push({ name: p.name, id: p.id });
+      }
+    }
+    // Local aliases stay visible alongside the server list.
+    for (const [name, id] of map.entries()) {
+      if (!seen.has(id)) {
+        seen.add(id);
+        entries.push({ name, id });
+      }
+    }
+  } catch (e) {
+    if (e instanceof CliError && /No API key file/.test(e.message)) {
+      entries = null; // Keyless: answer from the map below, like before.
+    } else if (isListFallbackable(e)) {
+      entries = null;
+    } else {
+      throw e;
+    }
+  }
+  if (entries === null) entries = [...map.entries()].map(([name, id]) => ({ name, id }));
   if (globals.json) {
     out(JSON.stringify({ projects: entries }, null, 2));
     return;
   }
   if (!entries.length) {
-    out('No project names saved.');
-    err(`(GET /v1/projects is account-only, so names live in ${path} as name=uuid lines.\nAdd them with \`takibi projects --add <name> <uuid>\` (ask the account owner for UUIDs),\nor pass --project <uuid> directly. Single-grant keys may omit --project.)`);
+    out('No projects found.');
+    err(`(This key sees no granted projects, or the API is unreachable and ${path} is empty.\nAdd names with \`takibi projects --add <name> <uuid>\`, or pass --project <uuid> directly. Single-grant keys may omit --project.)`);
     return;
   }
   for (const { name, id } of entries) out(`${name} → ${id}`);
@@ -682,9 +827,11 @@ async function cmdVersion(globals) {
 async function main(argv) {
   const { globals, rest } = parseArgv(argv);
   if (globals.version) {
-    out(`takibibase ${CLI_VERSION}`);
+    out(`takibi ${CLI_VERSION}`);
+    await maybeNotifyUpdate({ json: globals.json });
     return;
   }
+  await maybeNotifyUpdate({ json: globals.json });
   const [cmd, ...tokens] = rest;
   if (globals.help || !cmd) {
     out(HELP);