busa-cli 0.10.3 → 0.11.2

package/bin/busabase-cli.mjs

@@ -1,11 +1,8 @@
 #!/usr/bin/env node
 import { existsSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 
-const here = dirname(fileURLToPath(import.meta.url));
-const pkgRoot = resolve(here, "..");
-const builtCli = resolve(pkgRoot, "dist/cli.js");
+const builtCli = new URL("../dist/cli.js", import.meta.url);
+const programmaticEntry = new URL("../dist/index.js", import.meta.url);
 const delegatedArgvJson = process.env.BUSABASE_CLI_DELEGATED_ARGV;
 
 if (!existsSync(builtCli)) {
@@ -22,14 +19,14 @@ if (!existsSync(builtCli)) {
 try {
   if (delegatedArgvJson) {
     delete process.env.BUSABASE_CLI_DELEGATED_ARGV;
-    const { runCli } = await import(resolve(pkgRoot, "dist/index.js"));
+    const { runCli } = await import(programmaticEntry.href);
     const delegatedArgv = JSON.parse(delegatedArgvJson);
     if (!Array.isArray(delegatedArgv) || delegatedArgv.some((arg) => typeof arg !== "string")) {
       throw new Error("BUSABASE_CLI_DELEGATED_ARGV must be a JSON string array.");
     }
     process.exit(await runCli(delegatedArgv));
   }
-  await import(builtCli);
+  await import(builtCli.href);
 } catch (error) {
   const message = error instanceof Error ? error.message : String(error);
   if (message.includes("busabase-sdk") && message.includes("dist/index.js")) {

package/dist/{chunk-MLTXEKPL.js → chunk-S3KRMKDU.js}

@@ -284,6 +284,10 @@ var baseFieldChangeTask = {
 
 // ../../packages/busabase-contract/src/tasks/change-request.ts
 var REVIEW_GUIDANCE = "This records a HUMAN decision. Never call it unless the user explicitly asked for this specific verdict on these specific change requests. Summarising a change request for the user is not permission to approve it.";
+var singleItemError = (result) => Object.assign(new Error(result?.error ?? "Change request action returned no result"), {
+  ...result?.code ? { code: result.code } : {},
+  ...result?.data === void 0 ? {} : { data: result.data }
+});
 var changeRequestQueryTask = {
   name: "change_request_query",
   cliPath: ["change-requests", "query"],
@@ -363,18 +367,15 @@ var changeRequestReviewTask = {
       throw new Error("changeRequestIds must contain at least one id.");
     }
     const verdict = input.verdict;
-    if (ids.length === 1) {
-      return client.changeRequests.review({
-        changeRequestId: ids[0],
-        verdict,
-        ...input.reason ? { reason: input.reason } : {}
-      });
-    }
-    return client.changeRequests.reviewMany({
+    const response = await client.changeRequests.review({
       changeRequestIds: ids,
       verdict,
       ...input.reason ? { reason: input.reason } : {}
     });
+    if (ids.length !== 1) return response;
+    const result = response.results[0];
+    if (!result?.ok) throw singleItemError(result);
+    return result.changeRequest;
   }
 };
 var changeRequestMergeTask = {
@@ -401,8 +402,15 @@ var changeRequestMergeTask = {
     if (!Array.isArray(ids) || ids.length === 0) {
       throw new Error("changeRequestIds must contain at least one id.");
     }
-    if (ids.length === 1) return client.changeRequests.merge({ changeRequestId: ids[0] });
-    return client.changeRequests.mergeMany({ changeRequestIds: ids });
+    const response = await client.changeRequests.merge({ changeRequestIds: ids });
+    if (ids.length !== 1) return response;
+    const result = response.results[0];
+    if (!result?.ok) throw singleItemError(result);
+    return {
+      changeRequest: result.changeRequest,
+      record: result.record,
+      view: result.view
+    };
   }
 };
 
@@ -434,25 +442,25 @@ var nodeListTask = {
     {
       path: ["skills", "list"],
       preset: { kind: "skill" },
-      summary: "List Skill nodes with their file trees"
+      summary: "List Skill nodes (summaries; use `skills get` for one node's files)"
     },
     {
       path: ["drives", "list"],
       preset: { kind: "drive" },
-      summary: "List Drive nodes with their file trees"
+      summary: "List Drive nodes (summaries; use `drives get` for one node's files)"
     },
     {
       path: ["airapps", "list"],
       preset: { kind: "airapp" },
-      summary: "List AirApp nodes with their file trees"
+      summary: "List AirApp nodes (summaries; use `airapps get` for one node's files)"
     }
   ],
-  summary: "List Skill, Drive, or AirApp nodes with their file trees",
-  guidance: "Returns every node of the given kind together with its Asset-backed file list. For the workspace tree across all node types, use `nodes_list` instead.",
+  summary: "List Skill, Drive, or AirApp nodes",
+  guidance: "Returns a lightweight summary row for every node of the given kind \u2014 id, name, slug, type, and metadata, but NOT the node's file list. Follow up with `node_get_file_tree` for one node's files, or `node_files_list` for just the file inventory. For the workspace tree across all node types, use `nodes_list` instead.",
   annotations: { readOnly: true, destructive: false },
   params: [kindParam],
   examples: ["busabase-cli nodes list-file-trees --kind skill"],
-  execute: async (client, input) => client.fileTrees.list({ type: resolveKind(input.kind) })
+  execute: async (client, input) => client.nodes.list({ types: [resolveKind(input.kind)] })
 };
 var nodeGetTask = {
   name: "node_get_file_tree",
@@ -478,7 +486,10 @@ var nodeGetTask = {
   annotations: { readOnly: true, destructive: false },
   params: [kindParam, nodeIdParam],
   examples: ["busabase-cli nodes get-file-tree --kind airapp --node-id nod_123"],
-  execute: async (client, input) => client.fileTrees.get({ nodeId: input.nodeId, type: resolveKind(input.kind) })
+  // Reads through the unified Node detail route. The payload is unchanged apart
+  // from the `type` discriminator the union carries, so a caller still gets
+  // `{ node, entryFile, visibility, version, files }`.
+  execute: async (client, input) => client.nodes.get({ nodeId: input.nodeId, type: resolveKind(input.kind) })
 };
 var nodeListFilesTask = {
   name: "node_files_list",
@@ -567,7 +578,7 @@ var nodeFilesChangeRequestTask = {
     }
   ],
   summary: "Propose file changes inside a Skill, Drive, or AirApp node",
-  guidance: "Approval-first: this proposes a ChangeRequest for a human to review, it does not write directly. Each operation is one of create / update / delete / metadata_update. Include `baseContentHash` (from `node_file_read`) on an update so a concurrent edit is caught.",
+  guidance: 'Approval-first: this proposes a ChangeRequest for a human to review, it does not write directly. Each operation is one of create / update / delete / metadata_update. Include `baseContentHash` (from `node_file_read`) on an update so a concurrent edit is caught. For kind "airapp", keep the project runnable by `npm run dev` \u2014 editing package.json must leave a "dev" script starting a plain Node server, not a bundler dev server.',
   annotations: { readOnly: false, destructive: false },
   params: [
     kindParam,
@@ -1189,7 +1200,7 @@ var nodeCreateTask = {
       name: "files",
       appliesWhen: { param: "type", values: ["skill", "drive", "airapp"] },
       kind: "json",
-      description: 'Seed files for a Skill/Drive/AirApp: [{"path":"SKILL.md","content":"..."}]. Layered over the default scaffold unless mergeMode is "replace".'
+      description: 'Seed files for a Skill/Drive/AirApp: [{"path":"SKILL.md","content":"..."}]. Layered over the default scaffold unless mergeMode is "replace" \u2014 a path you supply REPLACES the scaffold\'s file at that path. For --type airapp the project MUST be runnable by `npm run dev`: give package.json a "dev" script running a plain Node server (`node server.js`, Hono or node:http). A bundler dev server (Vite/webpack/Next) and any native-binary dependency CANNOT boot in the AirApp runtime, and browser files must need no build step.'
     },
     {
       name: "mergeMode",
@@ -1285,11 +1296,16 @@ var nodeCreateTask = {
 
 // ../../packages/busabase-contract/src/tasks/record-change.ts
 var OPERATIONS2 = ["update", "delete", "restore"];
+var mergeIntent2 = (input) => {
+  if (input.requireReview) return { autoMerge: false };
+  if (input.autoMerge) return { autoMerge: true };
+  return {};
+};
 var recordChangeTask = {
   name: "record_change_request",
   cliPath: ["records", "change-request"],
   summary: "Propose a change to an existing record (update / delete / restore)",
-  guidance: "Approval-first: proposes a ChangeRequest for a human, it does not write directly. `delete` ARCHIVES the record \u2014 it is reversible with `restore`, not an erase. For update, `fields` is keyed by field slug and only needs the fields you are changing; if you set the Base's PRIMARY (first) field, keep it a short human-readable title.",
+  guidance: "Review is permission-aware, decided server-side: `update` merges immediately when your key has write access on the Base's node and lands as a pending ChangeRequest otherwise \u2014 check the response's `materialized` field to see which happened. Pass explicit `autoMerge: false` to force review even when you could write directly. `delete` and `restore` are always review-first regardless of permission, by design. `delete` ARCHIVES the record \u2014 it is reversible with `restore`, not an erase. For update, `fields` is keyed by field slug and only needs the fields you are changing; if you set the Base's PRIMARY (first) field, keep it a short human-readable title.",
   annotations: { readOnly: false, destructive: false },
   params: [
     { name: "recordId", kind: "string", required: true, description: "Record to change." },
@@ -1311,10 +1327,23 @@ var recordChangeTask = {
       kind: "string",
       description: 'Explanation for the reviewer \u2014 imperative verb + what + why, e.g. "Update deal stage to qualified \u2014 demo booked".'
     },
-    { name: "submittedBy", kind: "string", description: "Producer label recorded on the change." }
+    { name: "submittedBy", kind: "string", description: "Producer label recorded on the change." },
+    {
+      name: "autoMerge",
+      kind: "boolean",
+      appliesWhen: { param: "operation", values: ["update"] },
+      description: "Skip review and apply the update immediately if you have write access. Not a permission override \u2014 a changeRequest-level key still gets a pending CR. Default is permission-aware: merge when you can, otherwise propose."
+    },
+    {
+      name: "requireReview",
+      kind: "boolean",
+      appliesWhen: { param: "operation", values: ["update"] },
+      description: "Always propose a pending ChangeRequest for this update, even with write access. delete/restore are review-first regardless."
+    }
   ],
   examples: [
     `busabase-cli records change-request --record-id rec_1 --operation update --fields-json '{"status":"published"}'`,
+    `busabase-cli records change-request --record-id rec_1 --operation update --fields-json '{"status":"published"}' --require-review`,
     "busabase-cli records change-request --record-id rec_1 --operation delete"
   ],
   execute: async (client, input) => {
@@ -1330,7 +1359,10 @@ var recordChangeTask = {
       return client.records.changeRequest({
         ...common,
         operation: "update",
-        fields: input.fields
+        fields: input.fields,
+        // Only `update` carries the merge intent — the endpoint's delete/restore
+        // branches have no `autoMerge` in their schema at all, by design.
+        ...mergeIntent2(input)
       });
     }
     if (input.operation === "delete") {
@@ -1433,11 +1465,16 @@ var recordQueryTask = {
 
 // ../../packages/busabase-contract/src/tasks/view-change.ts
 var ACTIONS = ["create", "update", "delete", "restore"];
+var mergeIntent3 = (input) => {
+  if (input.requireReview) return { autoMerge: false };
+  if (input.autoMerge) return { autoMerge: true };
+  return {};
+};
 var viewChangeTask = {
   name: "view_change_request",
   cliPath: ["views", "change-request"],
   summary: "Propose a Base view change (create / update / delete / restore)",
-  guidance: "Approval-first: proposes a ChangeRequest, it does not change the view directly. `create` needs the BASE id; update / delete / restore need the VIEW id \u2014 the endpoint split follows whichever id identifies the target, which this task handles for you.",
+  guidance: "Review is permission-aware, decided server-side: the change merges immediately when your key has write access on the Base's node and lands as a pending ChangeRequest otherwise \u2014 check the response's `materialized` field to see which happened. Pass requireReview to always propose instead of merging. Views are structure, not content \u2014 when you are building starter structure (a Base plus the views that make it usable) let it merge so the workspace is not left half-built behind a review queue, exactly as you would for `node_create` and `POST /bases`. `create` needs the BASE id; update / delete / restore need the VIEW id \u2014 the endpoint split follows whichever id identifies the target, which this task handles for you.",
   annotations: { readOnly: false, destructive: false },
   params: [
     {
@@ -1484,16 +1521,30 @@ var viewChangeTask = {
       description: "Changes to apply to the view (update only)."
     },
     { name: "message", kind: "string", description: "Explanation for the reviewer." },
-    { name: "submittedBy", kind: "string", description: "Producer label recorded on the change." }
+    { name: "submittedBy", kind: "string", description: "Producer label recorded on the change." },
+    {
+      name: "autoMerge",
+      kind: "boolean",
+      description: "Skip review and apply the change immediately if you have write access. Not a permission override \u2014 a changeRequest-level key still gets a pending CR. Default is permission-aware: merge when you can, otherwise propose."
+    },
+    {
+      name: "requireReview",
+      kind: "boolean",
+      description: "Always propose a pending ChangeRequest, even with write access."
+    }
   ],
   examples: [
     'busabase-cli views change-request --action create --base-id bas_1 --name "Published" --type table',
+    'busabase-cli views change-request --action create --base-id bas_1 --name "Published" --require-review',
     "busabase-cli views change-request --action delete --view-id viw_1"
   ],
   execute: async (client, input) => {
     const meta = {
       ...input.message ? { message: input.message } : {},
-      ...input.submittedBy ? { submittedBy: input.submittedBy } : {}
+      ...input.submittedBy ? { submittedBy: input.submittedBy } : {},
+      // Tri-state, like node_create's: omitted keeps the endpoint's
+      // permission-aware default, explicit true/false forces the branch.
+      ...mergeIntent3(input)
     };
     if (input.action === "create") {
       if (!input.baseId || !input.name) {
@@ -2243,8 +2294,11 @@ async function exportFull(options) {
   let docBodyCount = 0;
   for (const node of docNodes) {
     const nodeId = node.id;
-    const doc = await client.docs.get({ nodeId });
-    await writer.addBuffer(`docs/${nodeId}.md`, doc.body ?? "");
+    const detail = await client.nodes.get({ nodeId, type: "doc" });
+    if (detail.type !== "doc") {
+      throw new Error(`Expected a doc node for ${nodeId}, got "${detail.type}"`);
+    }
+    await writer.addBuffer(`docs/${nodeId}.md`, detail.body ?? "");
     docBodyCount += 1;
   }
   log(`exported ${docBodyCount} doc bodies`);
@@ -2659,9 +2713,15 @@ async function ask2(question) {
 function openBrowser(url) {
   const platform = process.platform;
   const [command, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  const reportFailure = () => {
+    say2("Could not open a browser automatically. Open the URL above manually.");
+  };
   try {
-    spawn(command, args, { stdio: "ignore", detached: true }).unref();
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.once("error", reportFailure);
+    child.unref();
   } catch {
+    reportFailure();
   }
 }
 async function verifyAuth(baseUrl, token) {
@@ -3408,6 +3468,10 @@ var fieldChangeRequestInputSchema = z6.discriminatedUnion("operation", [
   reorderFieldsChangeRequestInputSchema.extend({ operation: z6.literal("reorder"), ...withBaseId }),
   restoreFieldChangeRequestInputSchema.extend({ operation: z6.literal("restore"), ...withBaseId })
 ]);
+var baseLifecycleChangeRequestInputSchema = z6.discriminatedUnion("operation", [
+  archiveBaseInputSchema.extend({ operation: z6.literal("archive"), ...withBaseId }),
+  restoreBaseInputSchema.extend({ operation: z6.literal("restore"), ...withBaseId })
+]);
 
 // ../../packages/busabase-contract/src/domains/base/contract/view-schemas.ts
 import { z as z8 } from "zod";
@@ -3465,7 +3529,33 @@ var listNodesInputSchema = z7.object({
    * soft-archived nodes for the Trash view — no `parentId`/`depth` walk, since
    * archived nodes are shown as a list, not a tree.
    */
-  status: z7.enum(["active", "archived"]).optional().default("active")
+  status: z7.enum(["active", "archived"]).optional().default("active"),
+  /**
+   * Narrow to specific node types and return a FLAT list of lightweight node
+   * summaries (`children: []`) instead of walking the tree. This is what
+   * replaced the four retired narrow listings (`GET /docs`, `/files`,
+   * `/folders`, `/file-trees`); file-trees are selected with their real
+   * discriminators `skill` / `drive` / `airapp`, since there is no synthetic
+   * "file-tree" node type.
+   *
+   * Omitting `types` leaves every existing caller on exactly today's
+   * behaviour (full tree, or a `parentId`/`depth`-bounded walk, or the
+   * archived flat list) — the two modes never interfere.
+   *
+   * NOTE — no `projection` parameter, deliberately. The consolidation roadmap
+   * sketched `?projection=summary`, but it also rules out adding
+   * `projection=detail` in this batch (the retired detail lists were the
+   * N+1 payloads this change exists to remove). That would leave a parameter
+   * with exactly one legal value, which is noise in OpenAPI/MCP/CLI rather
+   * than a decision a caller gets to make. Detail is `GET /nodes/{nodeId}`.
+   *
+   * A GET query param that occurs exactly once (`?types=doc`) arrives as a
+   * bare string, not a 1-element array — only a REPEATED occurrence
+   * (`?types=doc&types=file`) becomes an array. Accept both and normalize.
+   */
+  types: z7.union([z7.array(z7.enum(NODE_TYPES)), z7.enum(NODE_TYPES)]).transform((value) => Array.isArray(value) ? value : [value]).optional().describe(
+    "Return a flat list of lightweight summaries for these node types instead of the tree. Read one node's full detail with GET /nodes/{nodeId}."
+  )
 }).optional();
 var isDescendantInputSchema = z7.object({
   nodeId: z7.string(),
@@ -3633,11 +3723,19 @@ var liveEventSchema = z7.object({
     // via the audit funnel, but nothing needs reviewing). Consumed by
     // `use-live-sync.ts` to pop a desktop Notification, and by
     // busabase-cloud's host hook to persist an inbox notification row.
-    "change_request.pending_review"
+    "change_request.pending_review",
+    // A node's metadata was written directly, outside the change-request flow
+    // (`PATCH /api/v1/nodes/{nodeId}/metadata` — agents, the SDK, an MCP tool,
+    // and every rich-node editor's own Save). Carries the touched node in
+    // `nodeIds` so open dashboards refetch the node tree instead of showing a
+    // stale whiteboard/workflow/HTML document until the next reload.
+    "node.metadata_updated"
   ]),
   spaceId: z7.string(),
   actorId: z7.string(),
-  changeRequestId: z7.string(),
+  // Null for events that aren't about a change request at all
+  // (`node.metadata_updated`), which is every direct, auto-audited write.
+  changeRequestId: z7.string().nullable(),
   baseId: z7.string().nullable(),
   nodeIds: z7.array(z7.string()),
   recordIds: z7.array(z7.string()),
@@ -3808,6 +3906,19 @@ var listChangeRequestsResponseSchema = z7.object({
   changeRequests: z7.array(changeRequestSchema),
   nextCursor: z7.string().nullable()
 });
+var listChangeRequestsPageInputSchema = z7.object({
+  page: z7.coerce.number().int().min(1).optional().default(1),
+  pageSize: z7.coerce.number().int().min(1).max(100).optional().default(50),
+  status: z7.array(changeRequestStatusSchema).optional(),
+  mine: z7.boolean().optional()
+}).optional().default({ page: 1, pageSize: 50 });
+var listChangeRequestsPageResponseSchema = z7.object({
+  changeRequests: z7.array(changeRequestSchema),
+  total: z7.number().int().nonnegative(),
+  totalPages: z7.number().int().nonnegative(),
+  page: z7.number().int().min(1),
+  pageSize: z7.number().int().min(1).max(100)
+});
 var changeRequestCountsSchema = z7.object({
   review: z7.number().int().nonnegative(),
   changes: z7.number().int().nonnegative(),
@@ -3948,6 +4059,9 @@ var viewSchema = z8.object({
   createdAt: z8.string(),
   updatedAt: z8.string()
 });
+var autoMergeSchema = z8.boolean().optional().describe(
+  "Whether to approve and merge this view change immediately. Omitted defaults to merging immediately if the actor has write access on the Base's node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access."
+);
 var createViewInputSchema = z8.object({
   config: viewConfigSchema.optional().default({ filters: [], sorts: [] }),
   description: z8.string().optional().default(""),
@@ -3955,7 +4069,8 @@ var createViewInputSchema = z8.object({
   name: z8.string().min(1),
   type: viewTypeSchema.optional().default("table"),
   slug: z8.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
-  submittedBy: z8.string().optional().default("local-producer")
+  submittedBy: z8.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var updateViewInputSchema = z8.object({
   config: viewConfigSchema.optional(),
@@ -3963,15 +4078,18 @@ var updateViewInputSchema = z8.object({
   message: z8.string().optional().default("Update view"),
   name: z8.string().min(1).optional(),
   type: viewTypeSchema.optional(),
-  submittedBy: z8.string().optional().default("local-producer")
+  submittedBy: z8.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var deleteViewInputSchema = z8.object({
   message: z8.string().optional().default("Delete view"),
-  submittedBy: z8.string().optional().default("local-producer")
+  submittedBy: z8.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var restoreViewInputSchema = z8.object({
   message: z8.string().optional().default("Restore view"),
-  submittedBy: z8.string().optional().default("local-producer")
+  submittedBy: z8.string().optional().default("local-producer"),
+  autoMerge: autoMergeSchema
 });
 var viewChangeRequestInputSchema = z8.discriminatedUnion("operation", [
   createViewInputSchema.extend({
@@ -4486,16 +4604,25 @@ var createBase = async (client, node, parentNodeId, options, state, bases, field
   bases.push({ node, baseId: result.id });
   indexFields(fieldIds, node.slug, result.fields);
   for (const view of node.base.views) {
-    const changeRequest = await client.views.changeRequest({
+    const created = await client.views.changeRequest({
       operation: "create",
       baseId: result.id,
       slug: view.slug,
       name: view.name,
       description: view.description,
       config: view.config,
-      submittedBy: options.submittedBy
+      submittedBy: options.submittedBy,
+      // Structure, exactly like the Base above — so ask for it outright instead
+      // of proposing it and immediately approving+merging our own proposal,
+      // which is what this loop used to do only because the endpoint had no
+      // `autoMerge`.
+      autoMerge: true
     });
-    await approveAndMerge(client, changeRequest.id);
+    if (!created.materialized) {
+      throw new Error(
+        `View "${view.slug}" was requested immediately but the server returned a pending change request; install cannot leave a Base's views behind in review.`
+      );
+    }
     state.created.views++;
   }
 };
@@ -4718,8 +4845,32 @@ var toKeyArray = (value) => {
   return [];
 };
 var approveAndMerge = async (client, changeRequestId) => {
-  await client.changeRequests.review({ changeRequestId, verdict: "approved" });
-  return client.changeRequests.merge({ changeRequestId });
+  const reviewed = await client.changeRequests.review({
+    changeRequestIds: [changeRequestId],
+    verdict: "approved"
+  });
+  const reviewResult = reviewed.results[0];
+  if (!reviewResult?.ok) {
+    throw Object.assign(
+      new Error(reviewResult?.error ?? "Change request review returned no result"),
+      {
+        code: reviewResult?.code,
+        data: reviewResult?.data
+      }
+    );
+  }
+  const merged = await client.changeRequests.merge({ changeRequestIds: [changeRequestId] });
+  const mergeResult = merged.results[0];
+  if (!mergeResult?.ok) {
+    throw Object.assign(
+      new Error(mergeResult?.error ?? "Change request merge returned no result"),
+      {
+        code: mergeResult?.code,
+        data: mergeResult?.data
+      }
+    );
+  }
+  return mergeResult;
 };
 
 // ../../packages/busabase-package/src/collect.ts
@@ -4766,7 +4917,10 @@ var collectNode = async (client, source, options) => {
         children: await collectNodes(client, source.children ?? [], options)
       };
     case "doc": {
-      const doc = await client.docs.get({ nodeId: source.id });
+      const doc = await client.nodes.get({ nodeId: source.id, type: "doc" });
+      if (doc.type !== "doc") {
+        throw new Error(`Expected a doc node for "${source.slug}", got "${doc.type}".`);
+      }
       return { ...common, type: "doc", body: doc.body };
     }
     case "base":
@@ -4950,7 +5104,10 @@ var collectFileTree = async (client, source, type, common, options) => {
   };
 };
 var collectFile = async (client, source, common, options) => {
-  const fileNode = await client.files.get({ nodeId: source.id });
+  const fileNode = await client.nodes.get({ nodeId: source.id, type: "file" });
+  if (fileNode.type !== "file") {
+    throw new Error(`Expected a file node for "${source.slug}", got "${fileNode.type}".`);
+  }
   const asset = fileNode.asset;
   if (!asset?.url) {
     options.warn(`Skipped file node "${source.slug}": it has no downloadable asset.`);
@@ -6488,12 +6645,17 @@ var GENERATED_SKIP = /* @__PURE__ */ new Set([
   // The `/file-trees` group is exposed by the task layer as `nodes
   // list-file-trees` / `get-file-tree` / `files` / `read-file` /
   // `files-change-request`, each taking `--kind` (see tasks/file-tree.ts).
-  "fileTrees.list",
+  // `fileTrees.list`/`fileTrees.get` are absent because the procedures are: the
+  // two tasks that used to call them now call `nodes.list({ types })` /
+  // `nodes.get`, so there is nothing left for the generator to skip.
   "fileTrees.create",
-  "fileTrees.get",
   "fileTrees.listFiles",
   "fileTrees.readFile",
   "fileTrees.createChangeRequest"
+  // `nodes get` is the curated `docs|files|folders get` facade's underlying
+  // route, but it stays generated too: it is the ONE command that reads a node
+  // of any type without knowing the type first, which is the whole point of the
+  // consolidation.
 ]);
 function registerGeneratedCommands(program, state) {
   const getGroup = (displayName, tag) => program.commands.find((c2) => c2.name() === displayName) ?? program.command(displayName).description(tag ?? `${displayName} endpoints`);
@@ -7150,6 +7312,44 @@ To add content to a space that is already in use, use \`busabase-cli install\` i
       );
     })
   );
+  for (const facade of [
+    {
+      group: "docs",
+      type: "doc",
+      label: "Doc",
+      detail: "body included",
+      omitted: "no bodies"
+    },
+    {
+      group: "files",
+      type: "file",
+      label: "File",
+      detail: "backing Asset included",
+      omitted: "no Asset detail"
+    },
+    {
+      group: "folders",
+      type: "folder",
+      label: "Folder",
+      detail: "direct children included",
+      omitted: "no children"
+    }
+  ]) {
+    const group = program.commands.find((c2) => c2.name() === facade.group) ?? program.command(facade.group).description(`${facade.label} nodes`);
+    addGlobalFlags(group.command("list")).description(`List ${facade.label} nodes \u2014 summaries only (${facade.omitted})`).addHelpText(
+      "after",
+      `
+OpenAPI: GET /nodes?types=${facade.type}
+  Follow up with \`${facade.group} get --node-id <id>\` for one node's full detail.`
+    ).action(runAction(state, (client) => client.nodes.list({ types: [facade.type] })));
+    addGlobalFlags(group.command("get")).description(`Get one ${facade.label} node (${facade.detail})`).requiredOption("--node-id <id>", `${facade.label} node id, or a slug unique to this type`).addHelpText("after", `
+OpenAPI: GET /nodes/{nodeId}?type=${facade.type}`).action(
+      runAction(
+        state,
+        (client, opts) => client.nodes.get({ nodeId: opts.nodeId, type: facade.type })
+      )
+    );
+  }
   registerTaskCommands(program, BUSABASE_TASKS, {
     addGlobalFlags,
     parseFieldSpecs,

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunk-MLTXEKPL.js";
+} from "./chunk-S3KRMKDU.js";
 
 // src/cli.ts
 process.exit(await runCli(process.argv.slice(2)));

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   HELP,
   render,
   runCli
-} from "./chunk-MLTXEKPL.js";
+} from "./chunk-S3KRMKDU.js";
 
 // src/index.ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-cli",
-  "version": "0.10.3",
+  "version": "0.11.2",
   "description": "Command-line client for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server`. Short-name alias for busabase-cli.",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-cli",
@@ -33,7 +33,7 @@
   "dependencies": {
     "@zip.js/zip.js": "^2.8.20",
     "busabase-package": "workspace:*",
-    "busabase-sdk": "0.10.3",
+    "busabase-sdk": "0.11.2",
     "commander": "^14.0.0",
     "tar-stream": "^3.1.7",
     "yaml": "^2.9.0",