@aiaiai-pt/martha-cli 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
 
+## [0.5.0] — 2026-05-20
+
+### Added — #372 PR4 collection-hierarchy CLI parity
+- `documents collections --tree` renders the parent → child hierarchy as ASCII, mirroring the admin tree UX from #372 PR3.
+- `documents create-collection --parent <slug-or-id>` creates a sub-collection under the named parent. Same slug/name/UUID resolution the agent uses.
+- `documents move-collection <id> --parent <slug-or-id> | --root` moves a collection atomically. Cycle prevention is server-side; CLI rejects self-as-parent eagerly.
+- `clients grant <c> function <fn> --collection <slug-or-id>` and the matching `clients revoke ... --collection`. Scoped grants only apply to functions (#372 PR2 cascade); passing `--collection` to a workflow or agent grant is a clean Validation error.
+- `agents add-function <a> <fn> --collection <slug-or-id>` and `agents remove-function <a> <fn> --collection` likewise. Omit the flag to target the root grant (`collection_id IS NULL` per the allowlist semantics).
+- Shared `lib/collections.ts:resolveCollectionIdForGrant` resolves UUID, slug, or name with a single `GET /api/admin/collections` round-trip.
+
 ## [0.3.0] — 2026-05-10
 
 First-run UX for third-party developers and agent runtimes.

package/dist/index.js

@@ -13218,6 +13218,27 @@ var workflowsConfig = {
 
 // src/commands/agents.ts
 init_errors();
+
+// src/lib/collections.ts
+init_errors();
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function resolveCollectionIdForGrant(ctx, ref) {
+  if (UUID_RE.test(ref)) {
+    return ref;
+  }
+  const all = await ctx.api.get("/api/admin/collections", {
+    params: { active_only: "false" }
+  });
+  const bySlug = all.find((c) => c.slug === ref);
+  if (bySlug)
+    return bySlug.id;
+  const byName = all.find((c) => c.name === ref);
+  if (byName)
+    return byName.id;
+  throw new CLIError(`Collection '${ref}' not found (tried UUID, slug, and name).`, 3 /* NotFound */, "Run `martha documents collections --tree` to see available collections.");
+}
+
+// src/commands/agents.ts
 function parseSetFlags(items) {
   const result = {};
   for (const item of items) {
@@ -13375,7 +13396,7 @@ var agentsConfig = {
       console.log(`  Updated:     ${agent.updated_at}`);
   },
   extraCommands: (parentCmd, getCtx, isJson) => {
-    parentCmd.command("add-function <agent> <functionName>").description("Add a function to an agent").option("--set <items...>", "Config overrides (key=value)").action(async (agent, functionName, opts) => {
+    parentCmd.command("add-function <agent> <functionName>").description("Add a function to an agent").option("--set <items...>", "Config overrides (key=value)").option("--collection <slug-or-id>", "Scope the grant to one collection (#372 PR2). " + "Server rejects with 400 if the function is collection-agnostic.").action(async (agent, functionName, opts) => {
       const ctx = getCtx();
       const body = {
         function_name: functionName
@@ -13383,25 +13404,36 @@ var agentsConfig = {
       if (opts.set) {
         body.config_overrides = parseSetFlags(opts.set);
       }
+      if (opts.collection) {
+        body.collection_id = await resolveCollectionIdForGrant(ctx, opts.collection);
+      }
       const result = await ctx.api.post(`${API_PATH}/${encodeURIComponent(agent)}/functions`, body);
       if (isJson()) {
         console.log(JSON.stringify(result, null, 2));
         return;
       }
-      console.log(`Added function '${functionName}' to agent '${agent}'`);
+      const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
+      console.log(`Added function '${functionName}' to agent '${agent}'${scopeLabel}`);
     });
-    parentCmd.command("remove-function <agent> <functionName>").description("Remove a function from an agent").action(async (agent, functionName) => {
+    parentCmd.command("remove-function <agent> <functionName>").description("Remove a function from an agent").option("--collection <slug-or-id>", "Revoke just the given collection scope (#372 PR2). " + "Omit to revoke the root grant (collection_id IS NULL).").action(async (agent, functionName, opts) => {
       const ctx = getCtx();
-      await ctx.api.del(`${API_PATH}/${encodeURIComponent(agent)}/functions/${encodeURIComponent(functionName)}`);
+      let endpoint = `${API_PATH}/${encodeURIComponent(agent)}/functions/${encodeURIComponent(functionName)}`;
+      if (opts.collection) {
+        const collId = await resolveCollectionIdForGrant(ctx, opts.collection);
+        endpoint += `?collection_id=${encodeURIComponent(collId)}`;
+      }
+      await ctx.api.del(endpoint);
       if (isJson()) {
         console.log(JSON.stringify({
           agent,
           function_name: functionName,
+          collection: opts.collection ?? null,
           removed: true
         }));
         return;
       }
-      console.log(`Removed function '${functionName}' from agent '${agent}'`);
+      const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
+      console.log(`Removed function '${functionName}' from agent '${agent}'${scopeLabel}`);
     });
     parentCmd.command("provision-auth <agent>").description("Provision, switch, or rotate agent auth credentials").requiredOption("--method <method>", "Auth method: service-account or api-key").action(async (agent, opts) => {
       const ctx = getCtx();
@@ -13507,6 +13539,32 @@ function formatBytes(bytes) {
     return `${(bytes / 1024).toFixed(1)} KB`;
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
+function renderCollectionTree(items) {
+  const byParent = new Map;
+  const ids = new Set(items.map((c) => c.id));
+  for (const c of items) {
+    const key = c.parent_collection_id && ids.has(c.parent_collection_id) ? c.parent_collection_id : null;
+    const list = byParent.get(key);
+    if (list)
+      list.push(c);
+    else
+      byParent.set(key, [c]);
+  }
+  const byName = (a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
+  for (const list of byParent.values())
+    list.sort(byName);
+  const roots = byParent.get(null) ?? [];
+  function walk(node, prefix, isLast) {
+    const connector = isLast ? "└── " : "├── ";
+    const count = node.document_count ?? 0;
+    const status = node.is_active === false ? source_default.dim(" [inactive]") : "";
+    console.log(`${prefix}${connector}${node.name}${source_default.dim(` (${count})`)}${status}`);
+    const children = byParent.get(node.id) ?? [];
+    const nextPrefix = prefix + (isLast ? "    " : "│   ");
+    children.forEach((child, idx) => walk(child, nextPrefix, idx === children.length - 1));
+  }
+  roots.forEach((root, idx) => walk(root, "", idx === roots.length - 1));
+}
 var STATUS_COLORS2 = {
   ready: source_default.green,
   active: source_default.green,
@@ -13626,7 +13684,25 @@ function registerDocumentCommands(program2) {
   function isJson() {
     return !!program2.opts().json;
   }
-  cmd.command("collections").description("List document collections").option("--inactive", "Include inactive collections").option("--limit <n>", "Max results", "50").action(async (opts) => {
+  async function resolveCollection(ctx, ref) {
+    const looksLikeUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(ref);
+    if (looksLikeUuid) {
+      try {
+        return await ctx.api.get(`/api/admin/collections/${encodeURIComponent(ref)}`);
+      } catch {}
+    }
+    const all = await ctx.api.get("/api/admin/collections", {
+      params: { active_only: "false" }
+    });
+    const bySlug = all.find((c) => c.slug === ref);
+    if (bySlug)
+      return bySlug;
+    const byName = all.find((c) => c.name === ref);
+    if (byName)
+      return byName;
+    throw new CLIError(`Collection '${ref}' not found (tried UUID, slug, and name).`, 3 /* NotFound */);
+  }
+  cmd.command("collections").description("List document collections").option("--inactive", "Include inactive collections").option("--limit <n>", "Max results", "50").option("--tree", "Render the hierarchy as ASCII (--limit ignored in tree mode)").action(async (opts) => {
     const ctx = getCtx();
     const limitN = parseInt(opts.limit ?? "50", 10);
     if (isNaN(limitN) || limitN < 1) {
@@ -13635,13 +13711,17 @@ function registerDocumentCommands(program2) {
     const params = {};
     if (!opts.inactive)
       params.active_only = "true";
-    const items = await ctx.api.get("/api/admin/collections", {
-      params
-    });
+    const items = await ctx.api.get("/api/admin/collections", { params });
     if (isJson()) {
       console.log(JSON.stringify(items, null, 2));
       return;
     }
+    if (opts.tree) {
+      renderCollectionTree(items);
+      console.log(source_default.dim(`
+${items.length} collections`));
+      return;
+    }
     const columns = [
       { header: "NAME", accessor: (i) => i.name },
       {
@@ -13693,7 +13773,7 @@ ${items.length} collections`));
     if (col.updated_at)
       console.log(`  Updated:   ${col.updated_at}`);
   });
-  cmd.command("create-collection").description("Create a new document collection").requiredOption("--name <name>", "Collection name").option("--description <text>", "Collection description").action(async (opts) => {
+  cmd.command("create-collection").description("Create a new document collection").requiredOption("--name <name>", "Collection name").option("--description <text>", "Collection description").option("--parent <slug-or-id>", "Create as a sub-collection of the given collection (#372 PR1)").action(async (opts) => {
     const ctx = getCtx();
     const tenantId = await ctx.getTenantId();
     const body = {
@@ -13702,12 +13782,41 @@ ${items.length} collections`));
     };
     if (opts.description)
       body.description = opts.description;
+    if (opts.parent) {
+      const parent = await resolveCollection(ctx, opts.parent);
+      body.parent_collection_id = parent.id;
+    }
     const result = await ctx.api.post("/api/admin/collections", body);
     if (isJson()) {
       console.log(JSON.stringify(result, null, 2));
       return;
     }
-    console.log(`Created collection '${result.name}' (${result.id})`);
+    const parentLabel = opts.parent ? ` under '${opts.parent}'` : "";
+    console.log(`Created collection '${result.name}' (${result.id})${parentLabel}`);
+  });
+  cmd.command("move-collection <id>").description("Move a collection to a new parent or to the root (#372 PR1)").option("--parent <slug-or-id>", "New parent collection (mutually exclusive with --root)").option("--root", "Move to the top level (no parent)").action(async (id, opts) => {
+    if (!!opts.parent === !!opts.root) {
+      throw new CLIError("Pass exactly one of --parent <slug-or-id> or --root", 4 /* Validation */);
+    }
+    const ctx = getCtx();
+    const moving = await resolveCollection(ctx, id);
+    let newParentId;
+    if (opts.root) {
+      newParentId = null;
+    } else {
+      const parent = await resolveCollection(ctx, opts.parent);
+      if (parent.id === moving.id) {
+        throw new CLIError("Cannot move a collection into itself.", 4 /* Validation */);
+      }
+      newParentId = parent.id;
+    }
+    const result = await ctx.api.put(`/api/admin/collections/${encodeURIComponent(moving.id)}`, { parent_collection_id: newParentId });
+    if (isJson()) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const target = newParentId ? `under '${opts.parent}'` : "to root (top-level)";
+    console.log(`Moved collection '${moving.name}' ${target}`);
   });
   cmd.command("upload <collection-id> <file>").description("Upload a document to a collection").option("--wait", "Wait for ingestion to complete").option("--follow", "Follow ingestion progress in real time").action(async (collectionId, filePath, opts) => {
     const ctx = getCtx();
@@ -16137,7 +16246,7 @@ ${clients.length} client(s)`));
     }
     console.log(`Deleted client '${nameOrId}'`);
   });
-  cmd.command("grant <clientNameOrId> <type> <defName>").description("Grant a client access to a function, workflow, or agent").option("--config <items...>", "Config overrides (key=value, functions/agents only)").action(async (clientNameOrId, type, defName, opts) => {
+  cmd.command("grant <clientNameOrId> <type> <defName>").description("Grant a client access to a function, workflow, or agent").option("--config <items...>", "Config overrides (key=value, functions/agents only)").option("--collection <slug-or-id>", "Scope the grant to one collection (function grants only; #372 PR2)").action(async (clientNameOrId, type, defName, opts) => {
     if (!VALID_TYPES.has(type)) {
       throw new CLIError(`Invalid type: '${type}'. Must be function, workflow, or agent.`, 4 /* Validation */);
     }
@@ -16165,20 +16274,30 @@ ${clients.length} client(s)`));
       }
       body.config_overrides = parseSetFlags(opts.config);
     }
+    if (opts.collection) {
+      if (accessType !== "function") {
+        throw new CLIError("--collection only applies to function grants (#372 PR2).", 4 /* Validation */);
+      }
+      body.collection_id = await resolveCollectionIdForGrant(ctx, opts.collection);
+    }
     const result = await ctx.api.post(endpoint, body);
     if (isJson()) {
       console.log(JSON.stringify(result, null, 2));
       return;
     }
-    console.log(`Granted ${accessType} '${defName}' to client '${clientNameOrId}'`);
+    const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
+    console.log(`Granted ${accessType} '${defName}' to client '${clientNameOrId}'${scopeLabel}`);
   });
-  cmd.command("revoke <clientNameOrId> <type> <defName>").description("Revoke a client's access to a function, workflow, or agent").action(async (clientNameOrId, type, defName) => {
+  cmd.command("revoke <clientNameOrId> <type> <defName>").description("Revoke a client's access to a function, workflow, or agent").option("--collection <slug-or-id>", "Revoke just the given collection scope (function grants only; #372 PR2). " + "Omit to revoke the root grant (collection_id IS NULL).").action(async (clientNameOrId, type, defName, opts) => {
     if (!VALID_TYPES.has(type)) {
       throw new CLIError(`Invalid type: '${type}'. Must be function, workflow, or agent.`, 4 /* Validation */);
     }
     const accessType = type;
     const ctx = getCtx();
     const clientId = await resolveClientId(ctx, clientNameOrId);
+    if (opts.collection && accessType !== "function") {
+      throw new CLIError("--collection only applies to function grants (#372 PR2).", 4 /* Validation */);
+    }
     let endpoint;
     if (accessType === "agent") {
       endpoint = `${DEFS_API}/clients/${clientId}/agents/${encodeURIComponent(defName)}`;
@@ -16186,6 +16305,10 @@ ${clients.length} client(s)`));
       const defId = await resolveDefinitionId(ctx, accessType, defName);
       const typePlural = `${accessType}s`;
       endpoint = `${DEFS_API}/clients/${clientId}/${typePlural}/${encodeURIComponent(defId)}`;
+      if (opts.collection) {
+        const collId = await resolveCollectionIdForGrant(ctx, opts.collection);
+        endpoint += `?collection_id=${encodeURIComponent(collId)}`;
+      }
     }
     await ctx.api.del(endpoint);
     if (isJson()) {
@@ -16193,11 +16316,13 @@ ${clients.length} client(s)`));
         client: clientNameOrId,
         type: accessType,
         name: defName,
+        collection: opts.collection ?? null,
         revoked: true
       }));
       return;
     }
-    console.log(`Revoked ${accessType} '${defName}' from client '${clientNameOrId}'`);
+    const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
+    console.log(`Revoked ${accessType} '${defName}' from client '${clientNameOrId}'${scopeLabel}`);
   });
   const embed = cmd.command("embed").description("Create, configure, and test embeddable chat clients");
   function addEmbedConfigOptions(command) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {

package/skills/martha-cli/SKILL.md

@@ -272,11 +272,13 @@ martha agents generate-key <agent>
 **Function grants:**
 
 ```bash
-martha agents add-function <agent> <function> [--set key=value]    # config_overrides
-martha agents remove-function <agent> <function>
+martha agents add-function <agent> <function> [--set key=value] [--collection <slug-or-id>]
+martha agents remove-function <agent> <function> [--collection <slug-or-id>]
 martha agents functions <agent>                                     # List granted functions
 ```
 
+`--collection` scopes the grant to one collection per the #372 PR2 cascade. Omit it to grant at the root (tenant-wide); pass it on `remove-function` to revoke just that scope. Server returns 400 if the function is collection-agnostic (e.g. `recall`).
+
 ---
 
 ## Tasks: queue + executor lifecycle
@@ -579,9 +581,10 @@ Document collections are tenant-scoped containers that ingest files (PDF, DOCX,
 
 ```bash
 # Collections
-martha documents collections [--inactive] [--limit 50]
+martha documents collections [--inactive] [--limit 50] [--tree]      # --tree renders the parent/child hierarchy as ASCII (#372)
 martha documents collection <id>               # Stats, ingestion status, total size
-martha documents create-collection --name "My Docs" [--description "..."]
+martha documents create-collection --name "My Docs" [--description "..."] [--parent <slug-or-id>]
+martha documents move-collection <id> --parent <slug-or-id> | --root  # Atomic move; server rejects cycles
 
 # Document lifecycle
 martha documents upload <collection-id> <file> [--wait] [--follow]   # --follow streams ingestion progress
@@ -653,11 +656,13 @@ martha clients update <name-or-id> [--name <n>] [--system-prompts '...']
 martha clients delete <name-or-id> [--force] [--yes]                  # --force drops sessions
 
 # Access grants — what definitions this client's sessions can use
-martha clients grant <client> function|workflow|agent <def-name> [--config key=value]
-martha clients revoke <client> function|workflow|agent <def-name>
+martha clients grant <client> function|workflow|agent <def-name> [--config key=value] [--collection <slug-or-id>]
+martha clients revoke <client> function|workflow|agent <def-name> [--collection <slug-or-id>]
 martha clients access <name-or-id>                                    # All grants for this client
 ```
 
+`--collection` is only valid on `function` grants (#372 PR2). The same UUID, slug, or name accepted by `documents move-collection` works here. Granting a scope on a collection-agnostic function (like `recall`) returns 400.
+
 ---
 
 ## Sessions + Chat
@@ -859,6 +864,35 @@ martha integrations specs --json | jq -r '.[] | select(.name == "linear") | .id'
 done
 ```
 
+### Collection hierarchy + scoped grants (#372)
+
+```bash
+# See the tree
+martha documents collections --tree
+
+# Build a hierarchy
+martha documents create-collection --name "Reports"
+martha documents create-collection --name "2026 Reports" --parent reports
+martha documents create-collection --name "Q1 2026" --parent 2026-reports
+
+# Reorganize
+martha documents move-collection q1-2026 --parent reports        # promote a level
+martha documents move-collection 2026-reports --root             # back to top-level
+
+# Scoped grants. Agent only sees docs in /Reports and descendants.
+martha agents add-function planner list_docs --collection reports
+martha agents add-function planner read_doc --collection reports
+
+# Most-specific ancestor wins: an additional grant on a child
+# collection overrides config_overrides for that subtree only.
+martha agents add-function planner list_docs --collection q1-2026 --set max_results=50
+
+# Revoke just one scope; the parent root grant (if any) survives.
+martha agents remove-function planner list_docs --collection q1-2026
+```
+
+`--collection` accepts UUID, slug, or name — same identifier the agent uses. Resolution mirrors the backend.
+
 ---
 
 ## Troubleshooting