busa-cli 0.52.0 → 0.53.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as runCli, r as pkgVersion, t as checkForUpdate } from "./update-check-CNYcPsfm.js";
+import { i as runCli, r as pkgVersion, t as checkForUpdate } from "./update-check-Rqylvhw0.js";
 //#region src/cli.ts
 const exitCode = await runCli(process.argv.slice(2));
 const notice = await checkForUpdate("busabase-cli", pkgVersion());

package/dist/index.js

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

package/dist/{update-check-CNYcPsfm.js → update-check-Rqylvhw0.js}

@@ -160,12 +160,20 @@ const customPromptBodySchema = iStringSchema.refine((value) => iStringLocaleValu
 * 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.
+*
+* 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.
 */
 const customPromptDefSchema = z.object({
 	/** Stable id, unique within this node's custom list. */
 	key: z.string().trim().min(1, { message: "key must not be empty" }),
 	/** Defaults to `change` (same default the curated prompts use) so a prompt
-	* cannot silently bypass the approval-first policy by omission. */
+	* cannot silently opt out of the change-request path by omission — whether that
+	* path then merges immediately or waits for review is the permission layer's
+	* call, not the prompt's. */
 	intent: customPromptIntentSchema.optional(),
 	/** Short title shown in the dialog's left list. */
 	label: customPromptLabelSchema,
@@ -1236,6 +1244,7 @@ const baseNodeType = {
 	capabilities: {
 		hasDetail: true,
 		creatable: true,
+		commonlyCreated: true,
 		publicAccess: "detail"
 	},
 	operations: [
@@ -1340,6 +1349,7 @@ const docNodeType = {
 	capabilities: {
 		hasDetail: true,
 		creatable: true,
+		commonlyCreated: true,
 		publicAccess: "detail"
 	},
 	operations: [{
@@ -1371,6 +1381,7 @@ const fileNodeType = {
 	capabilities: {
 		hasDetail: true,
 		creatable: true,
+		commonlyCreated: true,
 		publicAccess: "detail"
 	},
 	operations: []
@@ -1386,6 +1397,7 @@ const folderNodeType = {
 	capabilities: {
 		container: true,
 		creatable: true,
+		commonlyCreated: true,
 		hasDetail: true,
 		publicAccess: "detail"
 	},
@@ -1396,9 +1408,10 @@ const folderNodeType = {
 /**
 * Form node: an agent-authored, sandboxed web page bound to a Base via an
 * explicit field-binding contract. A submission does NOT write a record
-* directly — it produces a review-first record-create ChangeRequest on the
-* target Base (so the submitting act reuses the base's `record_create` op, not a
-* form-specific one). The form's own config (bindings/page/share) is owner-
+* directly — it produces a record-create ChangeRequest on the target Base (so
+* the submitting act reuses the base's `record_create` op, not a form-specific
+* one), which then merges immediately or waits for review according to the
+* submitter's permission on that Base. The form's own config (bindings/page/share) is owner-
 * managed and edited directly, so this node contributes no CR operations of its
 * own for now.
 */
@@ -1406,10 +1419,23 @@ const formNodeType = {
 	type: "form",
 	label: "Form",
 	icon: "form",
+	/**
+	* `hidden` until a Form can be created from a create surface at all.
+	*
+	* `busabase_forms.target_base_id` is NOT NULL and `form` registers no
+	* `node_create` materializer, so a Form built through the generic New-item
+	* flow (which only collects name/slug/description) is a node row with no form
+	* config behind it — it opens to a dead end, every time, for everyone. The
+	* type stays fully `creatable` so `forms.create` (which does take a target
+	* Base) and the REST/MCP surface are untouched; it just no longer offers an
+	* entry point that cannot succeed. Drop this once the New-item flow asks for
+	* the target Base and a materializer writes the config row.
+	*/
 	capabilities: {
 		hasDetail: true,
 		creatable: true,
-		publicAccess: "submit"
+		publicAccess: "submit",
+		hidden: true
 	},
 	operations: []
 };
@@ -5703,6 +5729,19 @@ const TemplateManifestSchema = z.object({
 	/** Card/detail screenshots, package-relative (`assets/screenshots/overview.webp`). */
 	screenshots: z.array(z.string()).default([]),
 	/**
+	* Optional demo clip, package-relative (`assets/recordings/busa-crm.mp4`).
+	*
+	* No companion poster field on purpose: the detail page uses
+	* `screenshots[0]`, which the catalog already requires to be the cover. One
+	* declared path instead of two that can disagree with each other.
+	*
+	* Note for anyone adding a sibling field here: this is a plain `z.object`, so
+	* an unrecognized key in `busabase.json` is silently stripped rather than
+	* rejected. A template cannot declare a field ahead of the schema landing —
+	* it just vanishes, with no error from `busabase-cli check`.
+	*/
+	video: z.string().optional(),
+	/**
 	* Ready-made prompts shown after install ("Ask agent" prefills the first).
 	*
 	* They are the difference between a folder of tables and something a user can
@@ -6047,7 +6086,26 @@ const updateFieldChangeRequestInputSchema = z.object({
 	patch: z.object({
 		name: fieldNameSchema.optional(),
 		required: z.boolean().optional(),
-		options: fieldOptionsSchema.optional()
+		options: fieldOptionsSchema.optional(),
+		/**
+		* Not a patch key — rejected on purpose, and the only key here that is.
+		*
+		* `update` cannot change a field's type; `convert` does, after
+		* `previewFieldConversion` has shown what happens to the stored values.
+		* But `patch` is a plain (non-strict) object, so `{ type: "markdown" }`
+		* used to be stripped silently: the request validated, the change request
+		* merged, `ok: true` came back, and the field was still whatever it was.
+		* A caller reaching for the obvious-but-wrong shape got a successful
+		* no-op, which reads exactly like a successful conversion.
+		*
+		* Blanket `.strict()` is not the fix here — see `contract/auto-merge.ts`
+		* on why these schemas stay open: the SDK ships on its own cadence
+		* against self-hosted servers, so a newer client sending a newer optional
+		* key is normal traffic, and strictness would 400 all of them to catch
+		* this one. Naming the single key that will never be legitimate keeps
+		* that forward compatibility intact.
+		*/
+		type: z.never({ message: "A field type cannot be changed with `update`. Use operation: \"convert\" with `newType`, and call `previewFieldConversion` first to see how many stored values survive it." }).optional()
 	}),
 	message: z.string().optional(),
 	submittedBy: z.string().optional().default("local-editor"),
@@ -6321,7 +6379,14 @@ z.object({
 	name: z.string(),
 	slug: z.string(),
 	path: z.string(),
-	updatedAt: z.string()
+	updatedAt: z.string(),
+	/**
+	* The node's own custom avatar, same shape as `NodeVO.icon`. Optional so an
+	* older server that predates this field is still a valid response — a
+	* caller that doesn't know it falls back to the type icon exactly as it
+	* always has.
+	*/
+	icon: NodeIconSchema.nullable().optional()
 });
 const userRefSchema = z.object({
 	id: z.string(),
@@ -7584,6 +7649,8 @@ const auditPackage = (tree, files, options = {}) => {
 	const present = new Set(paths);
 	if (options.directoryName !== void 0 && options.directoryName !== tree.manifest.name) error("package/identity", `Directory is "${options.directoryName}" but busabase.json declares "${tree.manifest.name}". The directory name is the package's identity, not a label beside it.`);
 	for (const screenshot of tree.manifest.template?.screenshots ?? []) if (!present.has(screenshot)) error("package/screenshot-missing", `busabase.json declares screenshot "${screenshot}", which is not in the package. The Template Center card would render a broken image.`);
+	const video = tree.manifest.template?.video;
+	if (video && !present.has(video)) error("package/video-missing", `busabase.json declares video "${video}", which is not in the package. The Template Center detail page would show a play button that leads nowhere.`);
 	for (const relative of paths) {
 		const base = relative.slice(relative.lastIndexOf("/") + 1);
 		if (/^\.env(?!\.example$)(?:\.|$)/.test(base)) error("package/dotenv", `${relative} is part of the package. Credentials belong in Vault, never in something people install.`);
@@ -9317,7 +9384,7 @@ const toCreatableFields = (node, fields, recordIdsByKey) => {
 	return result;
 };
 const createRecords = async (client, base, recordsToCreate, plan, options, state, recordIdsByKey, app) => {
-	const mergeRecords = options.autoMerge || (app?.mergeSampleRecords ?? false);
+	const mergeRecords = app ? app.mergeSampleRecords : options.autoMerge;
 	const records = [...recordsToCreate].sort((a, b) => a.key.localeCompare(b.key, "en"));
 	for (let offset = 0; offset < records.length; offset += 200) {
 		const batch = records.slice(offset, offset + 200);
@@ -10058,12 +10125,17 @@ const hasUnlinkableRelationValues = (node) => {
 };
 const findCollisions = (tree, targetFolderSlug, target) => {
 	const collisions = [];
-	for (const node of walkNodes(tree.nodes)) if (target.existingNodeSlugsByType.get(node.type)?.has(node.slug)) collisions.push({
-		kind: node.type === "base" ? "base" : "node",
-		nodeType: node.type,
-		slug: node.slug,
-		path: `${targetFolderSlug}/…/${node.slug} (${node.type} slugs are unique per space)`
-	});
+	const check = (type, slug) => {
+		if (!target.existingNodeSlugsByType.get(type)?.has(slug)) return;
+		collisions.push({
+			kind: type === "base" ? "base" : "node",
+			nodeType: type,
+			slug,
+			path: `${targetFolderSlug}/…/${slug} (${type} slugs are unique per space)`
+		});
+	};
+	for (const node of walkNodes(tree.nodes)) check(node.type, node.slug);
+	if (tree.rootSkill) check("skill", tree.rootSkill.slug);
 	return collisions;
 };
 const nodeIdentityKey = (node) => `${node.type}\0${node.slug}`;
@@ -10102,7 +10174,22 @@ const applyRenames = (tree, collisions, existingNodeSlugsByType) => {
 	}
 	const nodeRenames = /* @__PURE__ */ new Map();
 	const baseRenames = /* @__PURE__ */ new Map();
+	if (tree.rootSkill) {
+		const taken = takenByType.get("skill") ?? /* @__PURE__ */ new Set();
+		taken.add(tree.rootSkill.slug);
+		takenByType.set("skill", taken);
+	}
+	let rootSkillRename;
 	for (const collision of collisions) {
+		if (tree.rootSkill && collision.nodeType === "skill" && collision.slug === tree.rootSkill.slug) {
+			const taken = takenByType.get("skill") ?? /* @__PURE__ */ new Set();
+			const renamed = nextFreeSlug(collision.slug, taken);
+			taken.add(renamed);
+			takenByType.set("skill", taken);
+			rootSkillRename = renamed;
+			collision.renamedTo = renamed;
+			continue;
+		}
 		const node = [...walkNodes(tree.nodes)].find((candidate) => candidate.type === collision.nodeType && candidate.slug === collision.slug);
 		if (!node) continue;
 		const taken = takenByType.get(node.type) ?? /* @__PURE__ */ new Set();
@@ -10148,7 +10235,11 @@ const applyRenames = (tree, collisions, existingNodeSlugsByType) => {
 	};
 	return {
 		...tree,
-		nodes: tree.nodes.map(rewriteNode)
+		nodes: tree.nodes.map(rewriteNode),
+		...tree.rootSkill && rootSkillRename ? { rootSkill: {
+			...tree.rootSkill,
+			slug: rootSkillRename
+		} } : {}
 	};
 };
 const collectWarnings = (tree, warnings) => {
@@ -10337,6 +10428,7 @@ const discoverPackages = (files) => {
 			...tree.manifest.template?.category ? { category: tree.manifest.template.category } : {},
 			...validation.risk ? { risk: validation.risk } : {},
 			screenshots: tree.manifest.template?.screenshots ?? [],
+			...tree.manifest.template?.video ? { video: tree.manifest.template.video } : {},
 			tags: [.../* @__PURE__ */ new Set([...tree.manifest.tags, ...tree.manifest.template?.tags ?? []])],
 			agentPrompts: tree.manifest.template?.agentPrompts ?? [],
 			...tree.manifest.version ? { version: tree.manifest.version } : {},
@@ -10563,6 +10655,7 @@ const toEntry = (found, airapps) => ({
 	...found.risk ? { risk: found.risk } : {},
 	tags: found.tags ?? [],
 	screenshots: found.screenshots,
+	...found.video ? { video: found.video } : {},
 	agentPrompts: found.agentPrompts ?? [],
 	...found.version ? { version: found.version } : {},
 	...found.author ? { author: found.author } : {},
@@ -11371,6 +11464,7 @@ const PROCEDURE_PERMISSION_POLICY = {
 	"webhooks.testFire": workspace("manage"),
 	"vault.get": workspace("manage"),
 	"vault.update": workspace("manage"),
+	"vault.updatePreviewFileCredential": workspace("manage"),
 	"vault.clear": workspace("manage"),
 	"dump.exportTables": workspace("manage"),
 	"dump.exportAssetText": workspace("manage"),
@@ -11407,6 +11501,8 @@ const PROCEDURE_PERMISSION_POLICY = {
 	"bases.previewFieldConversion": node("read"),
 	"fileTrees.listFiles": node("read"),
 	"fileTrees.readFile": node("read"),
+	"fileTrees.previewConfig": workspace("read"),
+	"fileTrees.preparePreview": node("read"),
 	"airapps.runLocal": node("write"),
 	"airapps.stopLocal": node("write"),
 	"nodes.readLines": node("read"),
@@ -11421,6 +11517,7 @@ const PROCEDURE_PERMISSION_POLICY = {
 	"assets.readTextLines": node("read"),
 	"install.planFromGithub": workspace("read"),
 	"install.fromGithub": workspace("manage"),
+	"install.fromGithubStream": workspace("manage"),
 	"templates.list": workspace("read"),
 	"guides.list": workspace("read"),
 	"guides.read": workspace("read"),
@@ -11430,6 +11527,7 @@ const PROCEDURE_PERMISSION_POLICY = {
 	"agents.sessions.list": workspace("manage"),
 	"agents.sessions.create": workspace("manage"),
 	"agents.sessions.prompt": workspace("manage"),
+	"agents.sessions.setConfigOption": workspace("manage"),
 	"agents.sessions.cancel": workspace("manage"),
 	"agents.sessions.close": workspace("manage"),
 	"agents.sessions.subscribe": workspace("manage"),
@@ -11732,9 +11830,10 @@ const wrapGuidance = (text, width = 78) => {
 /**
 * `--wait`: block until a submitted proposal is actually decided.
 *
-* Review-first is the product's whole point, so the useful unit of work for a
-* caller is not "the change request was filed" — it is "the change request was
-* merged, or it wasn't". Without this every caller writes the same poll loop
+* A write can still land as a pending proposal — a proposal-only credential, no
+* write access on the target, or an explicit `--require-review` — so the useful
+* unit of work for a caller is not "the change request was filed" but "the
+* change request was merged, or it wasn't". Without this every caller writes the same poll loop
 * against `change-requests get`, and an agent that skips it reports a proposal
 * nobody has looked at as a completed task.
 */
@@ -12831,7 +12930,7 @@ Examples:
 			submittedBy: opts.submittedBy
 		});
 	}));
-	addGlobalFlags(bases.command("create-change-request")).description("Propose a new record via a Change Request — review-first by default").requiredOption("--base-id <id>", "target Base id").requiredOption("--fields-json <json|@file>", "record fields as JSON, or @file.json").option("--message <text>", "reviewer-facing Change Request message").option("--submitted-by <name>", "producer label").option("--auto-merge", "skip review and create the record immediately if you have write access (default: merge immediately if you have write access, otherwise propose a pending Change Request)").option("--require-review", "always propose a pending Change Request, even if you have write access").addHelpText("after", `
+	addGlobalFlags(bases.command("create-change-request")).description("Create a record via a Change Request — merged immediately if you have write access, otherwise proposed for review").requiredOption("--base-id <id>", "target Base id").requiredOption("--fields-json <json|@file>", "record fields as JSON, or @file.json").option("--message <text>", "reviewer-facing Change Request message").option("--submitted-by <name>", "producer label").option("--auto-merge", "skip review and create the record immediately if you have write access (default: merge immediately if you have write access, otherwise propose a pending Change Request)").option("--require-review", "always propose a pending Change Request, even if you have write access").addHelpText("after", `
 Examples:
   busabase-cli bases create-change-request --base-id bse_123 --fields-json '{"title":"Hello","status":"draft"}'
   busabase-cli bases create-change-request --base-id bse_123 --fields-json @record.json
@@ -12918,7 +13017,7 @@ Examples:
 		startLine: opts.startLine,
 		endLine: opts.endLine
 	})));
-	addGlobalFlags(program.command("install")).description("Install a Busabase package from a GitHub repo or a local directory into this space").argument("<source>", "GitHub repo URL (optionally /tree/<ref>[/<subdir>]), or a local directory / file:// URL written by `busabase-cli export`").option("--into-folder <name>", "target folder slug (default: the package's manifest name)").option("--dry-run", "print the plan (tree, record counts, collisions) and create nothing").option("--auto-merge", "merge the package's records and docs on the spot instead of leaving them as change requests to review — this TRUSTS THE PACKAGE AUTHOR, since skills and AirApps carry code your agents will run (default: review first)").option("--rename", "install colliding items under suffixed slugs (-2, -3, …) instead of failing").option("--skill <name>", "which package to install when the URL is a repository holding several (e.g. busabase/skills)").option("--no-sample-records", "propose a template's sample rows for review instead of merging them (default: merged, so the app is not empty on first open)").option("--no-rollback", "keep whatever a failed install created (default: it is moved to Trash)").addHelpText("after", `
+	addGlobalFlags(program.command("install")).description("Install a Busabase package from a GitHub repo or a local directory into this space").argument("<source>", "GitHub repo URL (optionally /tree/<ref>[/<subdir>]), or a local directory / file:// URL written by `busabase-cli export`").option("--into-folder <name>", "target folder slug (default: the package's manifest name)").option("--dry-run", "print the plan (tree, record counts, collisions) and create nothing").option("--auto-merge", "merge the package's records and docs on the spot (the default; the flag is kept so scripts that pass it keep working)").option("--require-review", "leave the package's records and docs as change requests for you to approve, instead of merging them").option("--rename", "install colliding items under suffixed slugs (-2, -3, …) instead of failing").option("--skill <name>", "which package to install when the URL is a repository holding several (e.g. busabase/skills)").option("--no-sample-records", "propose a template's sample rows for review instead of merging them (default: merged, so the app is not empty on first open)").option("--no-rollback", "keep whatever a failed install created (default: it is moved to Trash)").addHelpText("after", `
 The URL's git ref is the version pin — a tag installs that tag's content forever,
 even after the branch moves on. GITHUB_TOKEN is honored for private repos.
 
@@ -12931,12 +13030,15 @@ Examples:
   busabase-cli install https://github.com/acme/support-kb-template
   busabase-cli install https://github.com/acme/packages/tree/v1.2.0/skills/pdf-summarizer
   busabase-cli install https://github.com/acme/support-kb-template --dry-run
-  busabase-cli install https://github.com/acme/support-kb-template --into-folder support --auto-merge
+  busabase-cli install https://github.com/acme/support-kb-template --into-folder support --require-review
   busabase-cli install ./support-kb-template --dry-run
 
 Folders, Bases, their fields and their views are structure and are always created
-immediately. Records are content: by default they land as change requests for you
-to review, and --auto-merge merges them on the spot instead.
+immediately. Records, docs and app code are content: they merge on the spot too if
+your credential can write to the space, and --require-review leaves them as change
+requests for you to approve instead. Installing is already restricted to a space
+owner/admin, so choosing to install IS the trust decision — remember that a package
+can carry skills and AirApps, i.e. code your agents will run.
 
 A TEMPLATE (a package that also carries a SKILL.md) installs as an app: its
 manual lands as a Skill node, its nodes are stamped as belonging to that app, its
@@ -12948,13 +13050,13 @@ still wait for your review.
 If the URL is a repository that holds several packages rather than being one,
 install lists them and you pick with --skill <name>.
 
-A package whose records carry relation values requires --auto-merge — a relation
-stores the ids of the records it points at, and those exist only once the records
-are merged, so review-first would install every relation empty. Defining a relation
-field with nothing linked yet does not trigger this.`).action(runArgAction(state, (repoUrl, client, opts, config) => runInstall(client, repoUrl, {
+A package whose records carry relation values cannot be installed with
+--require-review — a relation stores the ids of the records it points at, and those
+exist only once the records are merged, so review would install every relation
+empty. Defining a relation field with nothing linked yet does not trigger this.`).action(runArgAction(state, (repoUrl, client, opts, config) => runInstall(client, repoUrl, {
 		intoFolder: opts.intoFolder,
 		dryRun: Boolean(opts.dryRun),
-		autoMerge: Boolean(opts.autoMerge),
+		autoMerge: opts.requireReview !== true,
 		rename: Boolean(opts.rename),
 		skill: opts.skill,
 		noSampleRecords: opts.sampleRecords === false,

package/package.json

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