takibibase 1.0.0 → 1.0.2

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,9 +19,9 @@ 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).
 
 ## Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takibibase",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Thin CLI for the Takibi API: ask, search, tasks, docs. Single file, zero dependencies.",
   "type": "module",
   "bin": {

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.
@@ -26,11 +27,11 @@ 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 BAKED_VERSION = '1.0.2';
 const CLI_VERSION = (() => {
   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 pkg.version;
   } catch {
     // Single-file download: no package.json travels with takibi.mjs.
   }
@@ -126,11 +127,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 +178,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 +271,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 +291,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 +446,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 +460,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 +485,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 +521,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 +534,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 +549,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 +559,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 +585,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 +610,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 +637,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 +701,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,7 +752,7 @@ async function cmdVersion(globals) {
 async function main(argv) {
   const { globals, rest } = parseArgv(argv);
   if (globals.version) {
-    out(`takibibase ${CLI_VERSION}`);
+    out(`takibi ${CLI_VERSION}`);
     return;
   }
   const [cmd, ...tokens] = rest;