busa-cli 0.96.0 → 0.97.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as checkForUpdate, n as pkgVersion, r as runCli } from "./run-B3hHU9aE.js";
+import { i as checkForUpdate, n as pkgVersion, r as runCli } from "./run-C7tO-SDN.js";
 //#region src/flush-stdio.ts
 /**
 * Wait for stdout/stderr to reach the other side before the process is torn down.

package/dist/index.js

@@ -1,3 +1,3 @@
-import { a as render, i as checkForUpdate, n as pkgVersion, r as runCli, t as HELP } from "./run-B3hHU9aE.js";
+import { a as render, i as checkForUpdate, n as pkgVersion, r as runCli, t as HELP } from "./run-C7tO-SDN.js";
 import { DEFAULT_BASE_URL, createBusabaseClient, normalizeBaseUrl } from "busabase-sdk";
 export { DEFAULT_BASE_URL, HELP, checkForUpdate, createBusabaseClient, normalizeBaseUrl, pkgVersion, render, runCli };

package/dist/{run-B3hHU9aE.js → run-C7tO-SDN.js}

@@ -158,15 +158,15 @@ const utf8ByteLength = (value) => new TextEncoder().encode(value).length;
 const customPromptLabelSchema = iStringSchema.refine((value) => iStringLocaleValues(value).every((v) => v.length <= CUSTOM_AGENT_PROMPT_LIMITS.maxLabelChars), { message: `label must be at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxLabelChars} characters per locale` });
 const customPromptBodySchema = iStringSchema.refine((value) => iStringLocaleValues(value).every((v) => utf8ByteLength(v) <= CUSTOM_AGENT_PROMPT_LIMITS.maxBodyBytes), { message: `body must be at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxBodyBytes} bytes (UTF-8) per locale` });
 /**
-* One custom scenario prompt. `body`'s `{target}` placeholder is substituted at
-* render time with the same target string `PromptDef.body(target)` receives
-* today (see `node-agent-prompts.ts`) — this schema does not interpolate it.
+* One custom scenario prompt. `body` is only the task: every rendered prompt
+* opens with the node's target line, the same one a built-in prompt opens with
+* (see `node-agent-prompts.ts`), so authors never place it and this schema
+* interpolates nothing.
 *
-* The placeholder is OPTIONAL and chooses placement only: a `body` that never
-* mentions `{target}` gets the target line prepended as its first paragraph, so
-* a custom prompt can never reach an agent without naming the node it acts on.
-* That is why the schema does not require it — forgetting it is not an error to
-* reject, it is a default to supply.
+* `{target}` is a retired placeholder that is still accepted, because bodies
+* saved before the target line became fixed contain it: a line that is only
+* `{target}` is dropped (the target already opens the prompt), and one inside a
+* sentence reads as the node's name. Rejecting it would break those prompts.
 */
 const customPromptDefSchema = z.object({
 	/** Stable id, unique within this node's custom list. */
@@ -178,7 +178,7 @@ const customPromptDefSchema = z.object({
 	intent: customPromptIntentSchema.optional(),
 	/** Short title shown in the dialog's left list. */
 	label: customPromptLabelSchema,
-	/** Template text; "{target}" is substituted with the rendered target line. */
+	/** The task. The node's target line is added ahead of it when the prompt renders. */
 	body: customPromptBodySchema
 });
 /**
@@ -246,14 +246,15 @@ const PlaybookMatchFieldSchema = z.enum([
 	"body"
 ]);
 const localeSchema = z.string().trim().min(1).max(20).describe("Locale for prompt labels and the rendered prompt body, e.g. \"en\" or \"zh-CN\". Falls back to English, then to whatever locale the prompt has.");
-z.object({
+const playbookSearchInputShape = {
 	queries: z.array(z.string().max(PLAYBOOK_SEARCH_LIMITS.maxQueryChars)).max(PLAYBOOK_SEARCH_LIMITS.maxQueries).default([]).describe("2–5 phrasings of what the user wants, in the user's language AND in English (e.g. [\"记录客户拜访\", \"log customer visit\", \"visit\"]). Each is matched as a case-insensitive substring; an item hit by more phrasings ranks higher. Empty = browse: every playbook, nearest first (at most 30)."),
 	kinds: z.array(PlaybookKindSchema).optional().describe("Restrict to \"skill\" and/or \"prompt\". Default: both."),
 	nearNodeId: z.string().trim().min(1).optional().describe("The node the user is on. Playbooks on that node rank first, then its folder, then ancestor folders (closest first)."),
 	inNodeId: z.string().trim().min(1).optional().describe("Only return playbooks on this node or inside its subtree."),
 	limit: z.coerce.number().int().min(1).max(PLAYBOOK_SEARCH_LIMITS.maxLimit).optional().describe("Max items (1–50). Default 10 for a search; 30 for a browse."),
 	locale: localeSchema.optional()
-});
+};
+z.strictObject(playbookSearchInputShape, { error: (issue) => issue.code === "unrecognized_keys" ? `Unknown key${issue.keys.length === 1 ? "" : "s"} ${issue.keys.map((key) => `"${key}"`).join(", ")}. playbooks search accepts: ${Object.keys(playbookSearchInputShape).join(", ")}${issue.keys.includes("query") ? " (did you mean \"queries\", an array of phrasings?)" : ""}.` : void 0 });
 /** Fields shared by a search item and a get result: where the playbook lives. */
 const playbookLocationShape = {
 	kind: PlaybookKindSchema,
@@ -1883,6 +1884,7 @@ const rejectMismatchedPayload = (input) => {
 	const type = input.type;
 	const wrong = [];
 	if (input.fields !== void 0 && type !== "base") wrong.push("fields");
+	if (input.skipDefaultView !== void 0 && type !== "base") wrong.push("skipDefaultView");
 	if (input.body !== void 0 && type !== "doc") wrong.push("body");
 	if (input.assetId !== void 0 && type !== "file") wrong.push("assetId");
 	if ((input.files !== void 0 || input.mergeMode !== void 0) && !FILE_TREE_TYPES.has(type)) wrong.push(input.files !== void 0 ? "files" : "mergeMode");
@@ -2012,7 +2014,8 @@ const createNode = async (client, input) => {
 	if (type === "base") {
 		const payload = {
 			...common,
-			fields: asFieldArray(input.fields) ?? []
+			fields: asFieldArray(input.fields) ?? [],
+			...input.skipDefaultView ? { defaultView: false } : {}
 		};
 		return client.bases.create(payload);
 	}
@@ -2135,6 +2138,15 @@ const nodeCreateTask = {
 				parser: "fieldSpecs"
 			}
 		},
+		{
+			name: "skipDefaultView",
+			appliesWhen: {
+				param: "type",
+				values: ["base"]
+			},
+			kind: "boolean",
+			description: "Base only. Create the Base WITHOUT its default \"Grid view\" (a table of every record and field). Only when you add your own views right after with view_change_request — a Base must keep at least one view, and the first one is what it opens on."
+		},
 		{
 			name: "body",
 			kind: "string",
@@ -2225,7 +2237,7 @@ const nodeCreateTask = {
 		{
 			name: "agentPrompts",
 			kind: "json",
-			description: "Scenario prompts shown when someone opens this node and asks an agent for something: [{\"key\":\"log-visit\",\"label\":\"Log a customer visit\",\"body\":\"{target}\\n\\nAdd a visit record with today's date, the contact I name, and a one-line summary.\",\"intent\":\"change\"}]. Write what the PERSON wants in their own words (\"Log a customer visit\"), not the operation (\"Create a record in Visits\") — the node type already covers the operations. These REPLACE the node type's default scenario prompts, so 2-5 real recurring jobs help and a generic pair is worse than none: omit this when you cannot name one. `{target}` expands to a complete sentence naming the node and space, so give it its own line. Stored in a second call after the node exists, so they are skipped (and reported) when this call proposes a ChangeRequest instead of creating the node; add them afterwards with `nodes set-agent-prompts`."
+			description: "Scenario prompts shown when someone opens this node and asks an agent for something: [{\"key\":\"log-visit\",\"label\":\"Log a customer visit\",\"body\":\"Add a visit record with today's date, the contact I name, and a one-line summary.\",\"intent\":\"change\"}]. Write what the PERSON wants in their own words (\"Log a customer visit\"), not the operation (\"Create a record in Visits\") — the node type already covers the operations. These are added after the node type's built-in scenario prompts, so 2-5 real recurring jobs help and a generic pair only repeats the defaults: omit this when you cannot name one. Write only the task: Busabase opens every prompt with a line naming the node and space, so do not write `{target}`. Stored in a second call after the node exists, so they are skipped (and reported) when this call proposes a ChangeRequest instead of creating the node; add them afterwards with `nodes set-agent-prompts`."
 		}
 	],
 	examples: [
@@ -2570,7 +2582,7 @@ const viewChangeTask = {
 	name: "view_change_request",
 	cliPath: ["views", "change-request"],
 	summary: "Propose a Base view change (create / update / delete / restore)",
-	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 — check the response's `materialized` field to see which happened. Pass requireReview to always propose instead of merging. Views are structure, not content — 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 — 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 — check the response's `materialized` field to see which happened. Pass requireReview to always propose instead of merging. Views are structure, not content — 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 — the endpoint split follows whichever id identifies the target, which this task handles for you. View order is shared by everyone: a new view joins the end, `update` with `position` moves one (0 = leftmost), and the leftmost view is what the Base opens on. Every Base keeps at least one view, so deleting its last one is rejected — create the replacement first. A new Base already starts with a default \"Grid view\" (every record and field): when you are about to add your own views, create the Base with `node_create` `skipDefaultView` (REST `defaultView: false`) so your first view is the one it opens on.",
 	annotations: {
 		readOnly: false,
 		destructive: false
@@ -2641,6 +2653,16 @@ const viewChangeTask = {
 			},
 			description: "Changes to apply to the view (update only)."
 		},
+		{
+			name: "position",
+			kind: "number",
+			min: 0,
+			appliesWhen: {
+				param: "action",
+				values: ["update"]
+			},
+			description: "Move the view to this 0-based index among the Base's views (update only); the others shift to make room. 0 makes it the view the Base opens on."
+		},
 		{
 			name: "message",
 			kind: "string",
@@ -2665,6 +2687,7 @@ const viewChangeTask = {
 	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 update --view-id viw_1 --position 0",
 		"busabase-cli views change-request --action delete --view-id viw_1"
 	],
 	execute: async (client, input) => {
@@ -2690,11 +2713,12 @@ const viewChangeTask = {
 			...meta
 		};
 		if (input.action === "update") {
-			if (!input.patch) throw new Error("action \"update\" requires patch.");
+			if (!input.patch && input.position === void 0) throw new Error("action \"update\" requires patch or position.");
 			return client.views.changeRequest({
 				operation: "update",
 				...target,
-				...input.patch
+				...input.patch ?? {},
+				...input.position !== void 0 ? { position: input.position } : {}
 			});
 		}
 		if (input.action === "delete") return client.views.changeRequest({
@@ -6546,6 +6570,7 @@ z.object({
 		required: z.boolean().default(false),
 		options: fieldOptionsSchema.optional().default({})
 	})).default([]),
+	defaultView: z.boolean().optional().describe("Whether the new Base gets its default \"Grid view\" (a table view showing every record and field). Defaults to true. Pass false only when you add your own views right away — a Base must always keep at least one view, and the leftmost one is what it opens on."),
 	autoMerge: z.boolean().optional()
 });
 const createBaseFieldInputSchema = z.object({
@@ -6805,9 +6830,9 @@ z.object({
 	createdAt: z.string()
 });
 z.object({
-	parentId: z.string().nullable().optional().describe("Node to start from. Omit or null to start from the space root."),
-	depth: z.coerce.number().int().min(1).max(5).optional().describe("How many levels beneath the start point to eagerly include (default 2 once either field is set). Capped at 5."),
-	status: z.enum(["active", "archived"]).optional().default("active").describe("`active` walks the live TREE. `archived` returns a FLAT list of soft-archived nodes (the Trash view) with no parent/depth walk — so the response shape you can rely on differs between the two, not just the rows."),
+	parentId: z.string().nullable().optional().describe("Folder to start from: a node id or a folder slug. Omit or null to start from the space root. An unknown ref is a 404 and a node that is not a folder is a 400 — never an empty list. With `types`, scopes the flat list to this folder's subtree."),
+	depth: z.coerce.number().int().min(1).max(5).optional().describe("How many levels beneath the start point to eagerly include (default 2 once either field is set). Capped at 5. With `types` and `parentId`, how many levels of the folder's subtree to search (default: all of it)."),
+	status: z.enum(["active", "archived"]).optional().default("active").describe("`active` walks the live TREE. `archived` returns a FLAT list of soft-archived nodes (the Trash view) with no parent/depth walk — so the response shape you can rely on differs between the two, not just the rows. `parentId` with `archived` is a 400."),
 	/**
 	* Narrow to specific node types and return a FLAT list of lightweight node
 	* summaries (`children: []`) instead of walking the tree. This is what
@@ -6831,7 +6856,7 @@ z.object({
 	* bare string, not a 1-element array — only a REPEATED occurrence
 	* (`?types=doc&types=file`) becomes an array. Accept both and normalize.
 	*/
-	types: z.union([z.array(z.enum(NODE_TYPES)), z.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}.")
+	types: z.union([z.array(z.enum(NODE_TYPES)), z.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 — across the space, or within `parentId`'s subtree when given. Read one node's full detail with GET /nodes/{nodeId}.")
 }).optional();
 z.object({
 	nodeId: z.string().describe("The node walked UPWARDS from — the possible descendant."),
@@ -7135,6 +7160,7 @@ const changeRequestSchema = z.object({
 	operationCount: z.number(),
 	reviews: z.array(reviewSchema)
 });
+changeRequestSchema.extend({ materialized: z.literal(false) });
 z.object({
 	changeRequest: changeRequestSchema,
 	trigger: z.enum(["changes_requested", "ai_mention"]),
@@ -7359,7 +7385,7 @@ z.object({
 	autoMerge: destructiveAutoMerge("Archiving is reversible: the record leaves every listing but is restored intact by `operation: \"restore\"`.")
 });
 z.object({
-	fields: z.record(z.string(), z.unknown()).describe("Updated field values keyed by field slug. If you set the base's PRIMARY field (its first field), keep it a short human-readable name — it is the record's display title everywhere."),
+	fields: z.record(z.string(), z.unknown()).describe("Updated field values keyed by field slug. A field id or its exact display name (any language, unambiguous) is mapped to the slug; a write in which no key names a field of the Base is a 400 listing the valid slugs. If you set the base's PRIMARY field (its first field), keep it a short human-readable name — it is the record's display title everywhere."),
 	message: z.string().optional().default("Revise operation").describe("Explanation shown to the human reviewer. Write a conventional-commit style subject — imperative verb + what + why, e.g. \"Update deal stage to qualified — demo booked for July 8\"."),
 	author: z.string().optional().default("local-producer"),
 	baseCommitId: z.string().optional()
@@ -7615,6 +7641,7 @@ z.object({
 	type: viewTypeSchema,
 	config: viewConfigSchema,
 	status: z.enum(["active", "archived"]),
+	position: z.number().int(),
 	createdBy: z.string(),
 	createdByUser: userRefSchema.nullable().optional().default(null),
 	archivedAt: z.string().nullable(),
@@ -7648,6 +7675,7 @@ const updateViewInputSchema = z.object({
 	message: z.string().optional().default("Update view"),
 	name: z.string().min(1).optional(),
 	type: viewTypeSchema.optional(),
+	position: z.number().int().min(0).optional().describe("Move the view to this 0-based index among the Base's active views; the others shift to make room. The order is shared by everyone, and the leftmost view (0) is the one the Base opens on. Out-of-range values clamp to the end."),
 	submittedBy: z.string().optional().default("local-producer"),
 	autoMerge: autoMergeSchema
 });
@@ -9802,6 +9830,7 @@ const createBase = async (client, node, parentNodeId, options, state, bases, fie
 		name: node.name,
 		description: node.description,
 		fields: immediateFields,
+		...node.base.views.length > 0 ? { defaultView: false } : {},
 		autoMerge: true
 	});
 	if (!result.materialized) throw new Error(`Base "${node.slug}" was requested immediately but the server returned a pending change request; install cannot attach its views or records to it.`);
@@ -10329,7 +10358,10 @@ const collectBase = async (client, source, common, options) => {
 	const base = await client.bases.get({ baseId });
 	if (!base) throw new Error(`Base node "${source.slug}" has no Base behind it (looked up ${baseId}). The space may be mid-migration; re-run export.`);
 	const allViews = await client.bases.listViews({ baseId: base.id });
-	const views = allViews.filter((view) => view.slug.length > 0);
+	const views = allViews.filter((view) => view.slug.length > 0).map((view, index) => ({
+		view,
+		index
+	})).sort((left, right) => (left.view.position ?? 0) - (right.view.position ?? 0) || left.index - right.index).map(({ view }) => view);
 	if (views.length !== allViews.length) options.warn(`Base "${common.slug}" has ${allViews.length - views.length} view(s) with no slug — they were dropped (predates the slug requirement; rename it in the UI to keep it).`);
 	const { baseSlugById, fieldSlugById } = await buildIndexes(client, options.baseResourceKeys ?? /* @__PURE__ */ new Map());
 	const fields = [...base.fields].sort((a, b) => a.position - b.position).map((field) => toPackageField(field, {
@@ -12634,6 +12666,7 @@ Quick reference — every path is relative to the base URL above; worked example
 | Bulk create records CR | \`POST /api/v1/bases/:baseId/records/bulk-change-request\` | propose many records (≤1000) as ONE CR |
 | Bulk update records CR | \`POST /api/v1/bases/:baseId/records/bulk-update-change-request\` | partially update many existing records (≤1000) as ONE atomic CR |
 | Create node CR | \`POST /api/v1/nodes/change-requests\` | propose folder / Skill structure changes (supports in-CR \`ref\`/\`parentNodeRef\`) |
+| View CR | \`POST /api/v1/views/change-requests\` | create / update / delete / restore a Base view. Order is shared: \`update\` with \`position\` reorders, the leftmost view is what the Base opens on, and a Base's last view can't be deleted. A new Base starts with a "Grid view" unless created with \`"defaultView": false\` |
 | Read Skill files | \`GET /api/v1/file-trees/:nodeId/files/:filePath\` | read a Skill file (same route for Drives and AirApps) |
 | Create Skill file CR | \`POST /api/v1/file-trees/:nodeId/change-requests\` | propose a Skill file edit |
 | Request asset upload | \`POST /api/v1/assets/upload-urls\` | request an upload target for attachment-field files |
@@ -12984,7 +13017,9 @@ curl ${base}/api/v1/openapi.json
 \`\`\`
 
 It is large — **do not load the whole file into context.** Pull out only the path you need
-(e.g. \`curl ${base}/api/v1/openapi.json | jq '.paths["/api/v1/records"]'\`), or browse the
+(e.g. \`curl ${base}/api/v1/openapi.json | jq '.paths["/api/v1/records"]'\`); shared types such as
+\`ChangeRequest\`, \`Base\`, and \`Record\` are \`$ref\`s into \`.components.schemas\` (e.g.
+\`jq '.components.schemas.ChangeRequest'\`). Or browse the
 interactive docs at \`${base}/api/v1/doc\`. MCP-capable agents can skip docs entirely and
 connect to \`${base}/api/mcp\` (Streamable HTTP) — the most context-efficient path.
 
@@ -13077,9 +13112,9 @@ ${authLine}  -H 'content-type: application/json' \\
   --data '{
     "agentPrompts": [
       { "key": "log-visit", "label": "Log a customer visit",
-        "body": "{target}\\n\\nAdd a visit record with the date I give, the contact I name, and a one-line summary." },
+        "body": "Add a visit record with the date I give, the contact I name, and a one-line summary." },
       { "key": "quarter-recap", "intent": "read-only", "label": "What did we discuss this quarter",
-        "body": "{target}\\n\\nSummarize every visit to the account I name since the quarter started." }
+        "body": "Summarize every visit to the account I name since the quarter started." }
     ]
   }'
 \`\`\`
@@ -13094,8 +13129,8 @@ Four rules, each of which is a way this goes wrong:
    write nothing — the defaults already cover the generic work.
 3. **Only write them when you know the job.** You usually do — the user just told you why they
    wanted this node. A scratch table, a one-off Doc, a folder that only groups things: no prompts.
-4. **\`{target}\` expands to a full sentence** naming the node and space, so give it its own line.
-   Dropped mid-sentence it reads as a run-on with two full stops.
+4. **Write only the task.** Busabase opens every prompt with a line naming the node and space, so
+   do not write \`{target}\` — the target is no longer yours to place.
 
 Prompts are addressed by node id, so they are a second call after the node exists. When your
 create was proposed for review instead of merged, there is no node id yet — say so, and write
@@ -15444,10 +15479,11 @@ function buildProgram(state = {}) {
 Answers "what do I send, and what comes back" without fetching anything. The
 contract is compiled into this CLI, so \`schema\` works offline and unauthenticated.
 
-Prefer it over \`busabase-cli openapi\`: that returns the WHOLE document — 936 KB
-across 103 endpoints as of 2026-09-04, with every type inlined per endpoint — so
-reading one endpoint's arguments out of it costs roughly 234k tokens. One
-endpoint through \`schema\` is a few KB.
+Prefer it over \`busabase-cli openapi\`: that returns the WHOLE document — about
+240 KB across 106 endpoints as of 2026-10-20, with shared types behind \`$ref\`s
+into \`components.schemas\` — so reading one endpoint's arguments out of it costs
+tens of thousands of tokens plus chasing references. One endpoint through
+\`schema\` is a few KB and self-contained.
 
   busabase-cli schema                                 # every endpoint: id, method, path
   busabase-cli schema ${sampleEndpointId()}                       # input + output schema
@@ -15678,8 +15714,8 @@ Each entry: { key: string (unique per node), intent?: "read-only" | "change",
 label: string | { <locale>: string }, body: string | { <locale>: string } }.
 Locale keys (when using the object form): en, zh-CN, zh-TW, ja, ko, de, fr, es,
 pt — anything else fails validation as "Invalid input" on that field.
-"body" may contain a literal "{target}" placeholder, substituted at render time
-with the same node/space description every built-in prompt uses. At most 50
+"body" is only the task: every prompt opens with the same node/space line the
+built-in prompts use, added for you, so do not write "{target}". At most 50
 entries per node, 80 characters per localized label, 8 KiB per localized body.
 
 The file is validated against this exact schema BEFORE any network request —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-cli",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "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.96.0",
+    "busabase-sdk": "0.97.0",
     "commander": "^14.0.0",
     "qrcode": "^1.5.4",
     "tar-stream": "^3.1.7",