busa-cli 0.21.0 → 0.30.1

package/dist/cli.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
-import { n as runCli } from "./run-CG95MbX_.js";
+import { i as runCli, r as pkgVersion, t as checkForUpdate } from "./update-check-DXT4d-yb.js";
 //#region src/cli.ts
-process.exit(await runCli(process.argv.slice(2)));
+const exitCode = await runCli(process.argv.slice(2));
+const notice = await checkForUpdate("busabase-cli", pkgVersion());
+if (notice) console.error(notice);
+process.exit(exitCode);
 //#endregion
 export {};

package/dist/index.js

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

package/dist/{run-CG95MbX_.js → update-check-DXT4d-yb.js}

@@ -17,6 +17,167 @@ import { parse, stringify } from "yaml";
 import { checkAirApp } from "busabase-sdk/airapp-check";
 import { fileURLToPath } from "node:url";
 import { Uint8ArrayReader, ZipReader } from "@zip.js/zip.js";
+const LocaleSchema = z.enum({
+	defaultLocale: "en",
+	locales: [
+		"en",
+		"zh-CN",
+		"zh-TW",
+		"ja",
+		"ko",
+		"de",
+		"fr",
+		"es",
+		"pt"
+	],
+	extendLocales: [
+		"en",
+		"zh-CN",
+		"zh-TW",
+		"ja",
+		"ko",
+		"fr",
+		"de",
+		"es",
+		"ru",
+		"it",
+		"vi",
+		"pt"
+	]
+}.locales);
+//#endregion
+//#region ../../packages/openlib/i18n/i-string.ts
+/**
+* i18n string utilities and types / i18n 字符串工具与类型
+*
+* Purpose / 作用
+* - EN: Provide a lightweight, persistable representation for business strings that may be multilingual.
+*       Values can be plain strings or locale-keyed records, allowing storage and logic usage.
+* - ZH: 为“可持久化且可多语言”的业务字符串提供轻量表示形式；可存纯文本，或按语言分组的对象，
+*       方便在业务逻辑内读取、比较与分支判断。
+*
+* Model (iString) / 模型（iString）
+* - EN: A value is either a string or a record like { en: "Hello", zh: "你好" }.
+* - ZH: 值可以是纯字符串，或形如 { en: "Hello", zh: "你好" } 的按语言分布对象。
+*
+* Validation / 校验
+* - EN: Zod schemas validate both the record shape and the union type.
+* - ZH: 通过 Zod 对记录结构以及联合类型进行校验，Locale 受 ./types 中定义约束。
+*
+* Exports / 导出
+* - iStringRecordSchema: zod schema for { [locale]: string } constrained by supported locales.
+* - iStringSchema: union of string | iStringRecordSchema.
+* - isIString(str):
+*   - EN: Quick check for JSON iString records; returns parsed record or false.
+*   - ZH: 快速检测 JSON 字符串是否为 iString 记录；成功返回解析对象，否则返回 false。
+* - iStringMatch(str, compare, lang?):
+*   - EN: Compare by specified locale or any locale; supports plain string.
+*   - ZH: 支持按指定语言或任一语言进行等值比较；纯字符串直接比较。
+* - iStringParse(str, lang='en'):
+*   - EN: Resolve to a display string with sensible fallback.
+*   - ZH: 解析为用于展示的字符串，包含合理的回退策略。
+* - iStringify(str, lang='en'):
+*   - EN: Wrap a plain string into a record using the given locale.
+*   - ZH: 将纯字符串按给定语言包装为记录对象。
+* - iStringConcat(str):
+*   - EN: Concatenate all locale values for display/debug (order not guaranteed).
+*   - ZH: 拼接所有语言值以便展示/调试（顺序不保证）。
+*
+* Fallback behavior (iStringParse) / 回退策略（iStringParse）
+* - EN: If str is a string, return it. If it is a record: prefer requested locale; else any non-"en"; else "en".
+*       Warn and return empty string if no suitable value exists.
+* - ZH: 若为纯字符串，原样返回；若为记录：优先使用请求的语言；否则使用任一非 "en"；再退回 "en"。
+*       若均不可用，会发出警告并返回空字符串。
+*
+* Examples / 示例
+* - iStringify('Hello') => { en: 'Hello' }
+* - iStringParse({ en: 'Hello', zh: '你好' }, 'zh') => '你好'
+* - iStringMatch({ en: 'Hello' }, 'Hello') => true
+*
+* Notes / 说明
+* - EN: Depends on zod and the Locale/LocaleSchema from ./types to keep locales consistent.
+* - ZH: 依赖 zod 以及 ./types 中的 Locale/LocaleSchema，确保语言键一致与受控。
+* - EN: isIString expects a JSON string that decodes to a locale-keyed object; plain strings return false.
+* - ZH: isIString 接受 JSON 字符串并尝试解析为按语言分布的对象；纯字符串将返回 false。
+*/
+const iStringRecordSchema = z.partialRecord(LocaleSchema, z.string());
+const iStringSchema = z.union([z.string(), iStringRecordSchema]).describe("i18n string");
+//#endregion
+//#region ../../packages/busabase-contract/src/contract/node-agent-prompt-schemas.ts
+/**
+* Per-node custom scenario prompts (`node.metadata.agentPrompts`) — the single
+* schema shared by BOTH write and read paths, per
+* `apps/busabase-cloud/content/spec/node-agent-prompts-v2.md` §7.3:
+*
+* - Write: `busabase-cli nodes set-agent-prompts` validates a file against this
+*   schema client-side, before calling `nodes.updateMetadata` — a malformed file
+*   never reaches the network.
+* - Read: `buildNodeAgentPrompts` (`packages/busabase-core/.../node-agent-prompts.ts`)
+*   `.safeParse`s whatever is stored in `metadata.agentPrompts` and falls back to
+*   the node type's default scenarios on failure, so a bad write (or a manual
+*   jsonb edit) can never crash the Agent Prompts dialog.
+*
+* One schema, one place to edit the limits — do not duplicate this validation on
+* either side.
+*/
+/** Recommended limits from the spec (§7.3) — kept as named constants so a limit
+* change has exactly one place to edit, and so error messages can cite them. */
+const CUSTOM_AGENT_PROMPT_LIMITS = {
+	/** Max custom prompts per node. */
+	maxPrompts: 50,
+	/** Max characters per localized `label` value. */
+	maxLabelChars: 80,
+	/** Max bytes (UTF-8) per localized `body` value. */
+	maxBodyBytes: 8192
+};
+/** Same intent vocabulary `PromptDef.intent` uses — `change` is the router-side
+* default when omitted, matching the existing curated-prompt behavior. */
+const customPromptIntentSchema = z.enum(["read-only", "change"]);
+const iStringLocaleValues = (value) => typeof value === "string" ? [value] : Object.values(value);
+/** UTF-8 byte length — `body` includes CJK/JA text, whose per-character byte
+* cost is not 1, so a character-count limit alone would under-enforce §7.3's
+* "8 KiB per localized body" budget. */
+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.
+*/
+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. */
+	intent: customPromptIntentSchema.optional(),
+	/** Short title shown in the dialog's left list. */
+	label: customPromptLabelSchema,
+	/** Template text; "{target}" is substituted with the rendered target line. */
+	body: customPromptBodySchema
+});
+/**
+* The full `metadata.agentPrompts` array. `.max` bounds the list; the
+* `superRefine` catches duplicate keys with an issue path pointing at the
+* offending entry, so a CLI/server validation error names which entry and
+* which key collided instead of a bare "keys must be unique".
+*/
+const customAgentPromptsSchema = z.array(customPromptDefSchema).max(CUSTOM_AGENT_PROMPT_LIMITS.maxPrompts, { message: `at most ${CUSTOM_AGENT_PROMPT_LIMITS.maxPrompts} custom prompts per node` }).superRefine((prompts, ctx) => {
+	const firstIndexByKey = /* @__PURE__ */ new Map();
+	prompts.forEach((prompt, index) => {
+		const firstIndex = firstIndexByKey.get(prompt.key);
+		if (firstIndex === void 0) {
+			firstIndexByKey.set(prompt.key, index);
+			return;
+		}
+		ctx.addIssue({
+			code: "custom",
+			path: [index, "key"],
+			message: `duplicate key "${prompt.key}" — already used at entry ${firstIndex + 1}`
+		});
+	});
+});
+//#endregion
 //#region ../../packages/busabase-contract/src/tasks/base-field.ts
 /**
 * Changing a Base's schema, as one task with an `operation` instead of six
@@ -4957,91 +5118,6 @@ const auditSkill = (files, options = {}) => {
 	return findings;
 };
 const PACKAGE_SIDECARS = PACKAGE_SKILL_SIDECAR_DIRS.join("|");
-const LocaleSchema = z.enum({
-	defaultLocale: "en",
-	locales: [
-		"en",
-		"zh-CN",
-		"zh-TW",
-		"ja",
-		"ko",
-		"de",
-		"fr",
-		"es",
-		"pt"
-	],
-	extendLocales: [
-		"en",
-		"zh-CN",
-		"zh-TW",
-		"ja",
-		"ko",
-		"fr",
-		"de",
-		"es",
-		"ru",
-		"it",
-		"vi",
-		"pt"
-	]
-}.locales);
-//#endregion
-//#region ../../packages/openlib/i18n/i-string.ts
-/**
-* i18n string utilities and types / i18n 字符串工具与类型
-*
-* Purpose / 作用
-* - EN: Provide a lightweight, persistable representation for business strings that may be multilingual.
-*       Values can be plain strings or locale-keyed records, allowing storage and logic usage.
-* - ZH: 为“可持久化且可多语言”的业务字符串提供轻量表示形式；可存纯文本，或按语言分组的对象，
-*       方便在业务逻辑内读取、比较与分支判断。
-*
-* Model (iString) / 模型（iString）
-* - EN: A value is either a string or a record like { en: "Hello", zh: "你好" }.
-* - ZH: 值可以是纯字符串，或形如 { en: "Hello", zh: "你好" } 的按语言分布对象。
-*
-* Validation / 校验
-* - EN: Zod schemas validate both the record shape and the union type.
-* - ZH: 通过 Zod 对记录结构以及联合类型进行校验，Locale 受 ./types 中定义约束。
-*
-* Exports / 导出
-* - iStringRecordSchema: zod schema for { [locale]: string } constrained by supported locales.
-* - iStringSchema: union of string | iStringRecordSchema.
-* - isIString(str):
-*   - EN: Quick check for JSON iString records; returns parsed record or false.
-*   - ZH: 快速检测 JSON 字符串是否为 iString 记录；成功返回解析对象，否则返回 false。
-* - iStringMatch(str, compare, lang?):
-*   - EN: Compare by specified locale or any locale; supports plain string.
-*   - ZH: 支持按指定语言或任一语言进行等值比较；纯字符串直接比较。
-* - iStringParse(str, lang='en'):
-*   - EN: Resolve to a display string with sensible fallback.
-*   - ZH: 解析为用于展示的字符串，包含合理的回退策略。
-* - iStringify(str, lang='en'):
-*   - EN: Wrap a plain string into a record using the given locale.
-*   - ZH: 将纯字符串按给定语言包装为记录对象。
-* - iStringConcat(str):
-*   - EN: Concatenate all locale values for display/debug (order not guaranteed).
-*   - ZH: 拼接所有语言值以便展示/调试（顺序不保证）。
-*
-* Fallback behavior (iStringParse) / 回退策略（iStringParse）
-* - EN: If str is a string, return it. If it is a record: prefer requested locale; else any non-"en"; else "en".
-*       Warn and return empty string if no suitable value exists.
-* - ZH: 若为纯字符串，原样返回；若为记录：优先使用请求的语言；否则使用任一非 "en"；再退回 "en"。
-*       若均不可用，会发出警告并返回空字符串。
-*
-* Examples / 示例
-* - iStringify('Hello') => { en: 'Hello' }
-* - iStringParse({ en: 'Hello', zh: '你好' }, 'zh') => '你好'
-* - iStringMatch({ en: 'Hello' }, 'Hello') => true
-*
-* Notes / 说明
-* - EN: Depends on zod and the Locale/LocaleSchema from ./types to keep locales consistent.
-* - ZH: 依赖 zod 以及 ./types 中的 Locale/LocaleSchema，确保语言键一致与受控。
-* - EN: isIString expects a JSON string that decodes to a locale-keyed object; plain strings return false.
-* - ZH: isIString 接受 JSON 字符串并尝试解析为按语言分布的对象；纯字符串将返回 false。
-*/
-const iStringRecordSchema = z.partialRecord(LocaleSchema, z.string());
-z.union([z.string(), iStringRecordSchema]).describe("i18n string");
 //#endregion
 //#region ../../packages/busabase-contract/src/contract/auto-merge.ts
 /**
@@ -5187,7 +5263,8 @@ const baseSchema = z.object({
 		requiredApprovals: z.number()
 	}),
 	createdAt: z.string(),
-	fields: z.array(baseFieldSchema)
+	fields: z.array(baseFieldSchema),
+	metadata: z.record(z.string(), z.unknown()).default({})
 });
 z.object({
 	parentNodeId: z.string().optional().describe("Parent node id. Must be a folder or the space root; container-incapable node types (Base, Doc, AirApp, etc.) cannot hold children."),
@@ -10901,6 +10978,39 @@ Examples:
 		message: opts.message,
 		submittedBy: opts.submittedBy
 	})));
+	addGlobalFlags(nodes.command("set-agent-prompts")).description("Set a node's custom scenario prompts, shown in the Agent Prompts dialog instead of the node type's generic ones. Capability prompts (what the node type can actually do) are unaffected.").requiredOption("--node-id <id>", "node id to customize").requiredOption("--file <path>", "JSON file: an array of { key, intent?, label, body } — see the help text below").addHelpText("after", `
+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
+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 —
+a malformed file (duplicate key, an over-limit label/body, an unrecognized
+locale) is reported entry-by-entry and nothing is written. \`--file\`'s
+contents ARE the array to store; this command does not reshape it.
+
+Examples:
+  busabase-cli nodes set-agent-prompts --node-id nod_123 --file prompts.json`).action(runAction(state, (client, opts) => {
+		const filePath = opts.file;
+		let raw;
+		try {
+			raw = JSON.parse(readFileSync(filePath, "utf8"));
+		} catch (error) {
+			throw new CliOutcomeError("VALIDATION", `Could not read/parse ${filePath} as JSON: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const parsed = customAgentPromptsSchema.safeParse(raw);
+		if (!parsed.success) {
+			const detail = formatIssues(parsed.error.issues);
+			throw new CliOutcomeError("VALIDATION", `Invalid agent prompts in ${filePath}${detail ? ` — ${detail}` : ""}`);
+		}
+		return client.nodes.updateMetadata({
+			nodeId: opts.nodeId,
+			metadata: { agentPrompts: parsed.data }
+		});
+	}));
 	const bases = program.command("bases").description("Bases (structured tables)");
 	addGlobalFlags(bases.command("list")).description("List Bases in the active space").addOption(new Option("--status <active|archived>", "live Bases (default) or archived ones").choices(["active", "archived"])).action(runAction(state, (client, opts) => client.bases.list({ status: opts.status ?? "active" })));
 	addGlobalFlags(bases.command("get")).description("Get one Base by slug").requiredOption("--slug <slug>", "Base slug").action(runAction(state, async (client, opts) => {
@@ -11327,4 +11437,90 @@ function explainError(error, config) {
 	return `${body}\n  → Docs: ${DOCS_TROUBLESHOOTING}`;
 }
 //#endregion
-export { runCli as n, render as r, HELP as t };
+//#region src/update-check.ts
+/** 24h — frequent enough to notice a new release, rare enough to never matter for latency. */
+const CHECK_INTERVAL_MS = 864e5;
+/**
+* Only paid on the (at most once per 24h, per package) cache-refresh path, and
+* only for a real network round trip — not on every command. A live check
+* against the real npm registry measured a cold DNS+TLS handshake at ~800ms
+* on its own, so anything near that cuts it too close and turns "occasionally
+* shows the notice a run late" into "usually misses it on the first try
+* after 24h" — 1500ms leaves real headroom while still being far short of
+* anything a human would perceive as the command hanging.
+*/
+const FETCH_TIMEOUT_MS = 1500;
+function cacheDir() {
+	return process.env.BUSABASE_UPDATE_CACHE_DIR || join(homedir(), ".cache", "busabase");
+}
+function cacheFile() {
+	return join(cacheDir(), "update-check.json");
+}
+async function readCache() {
+	try {
+		const raw = await readFile(cacheFile(), "utf8");
+		const parsed = JSON.parse(raw);
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+async function writeCacheEntry(packageName, entry) {
+	try {
+		await mkdir(cacheDir(), { recursive: true });
+		const all = await readCache();
+		all[packageName] = entry;
+		await writeFile(cacheFile(), JSON.stringify(all), "utf8");
+	} catch {}
+}
+async function fetchLatestVersion(packageName) {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`, { signal: controller.signal });
+		if (!res.ok) return null;
+		const data = await res.json();
+		return typeof data.version === "string" ? data.version : null;
+	} catch {
+		return null;
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+/** Opted out via env, CI, or a non-interactive terminal — a notice nobody will read. */
+function checksDisabled() {
+	if (process.env.BUSABASE_NO_UPDATE_CHECK) return true;
+	if (process.env.CI === "true") return true;
+	if (!process.stdout.isTTY) return true;
+	return false;
+}
+function formatNotice(packageName, currentVersion, latestVersion) {
+	return `\nA new version of ${packageName} is available: ${currentVersion} → ${latestVersion}\nRun \`npm i -g ${packageName}@latest\` to update.\n`;
+}
+/**
+* Returns an update notice string if a newer version is known, else `null` —
+* caller decides where that goes (stderr for `busabase-cli`, the server boot
+* banner for `busabase`). Never throws.
+*
+* Cache hit (checked within the last 24h): synchronous-fast, no network call.
+* Cache miss/stale: pays for ONE bounded (`FETCH_TIMEOUT_MS`) registry round
+* trip so this run can already show the notice if a new version just shipped;
+* a genuinely slow/dead network just means this run stays silent and the next
+* stale check tries again — the timeout caps the worst case, it doesn't
+* silently retry in the background past process exit (a short-lived CLI
+* process can't rely on a detached background task actually finishing).
+*/
+async function checkForUpdate(packageName, currentVersion) {
+	if (checksDisabled()) return null;
+	const cached = (await readCache())[packageName];
+	if (!(!cached || Date.now() - cached.lastCheckedAt > CHECK_INTERVAL_MS)) return cached.latestVersion !== currentVersion ? formatNotice(packageName, currentVersion, cached.latestVersion) : null;
+	const latest = await fetchLatestVersion(packageName);
+	if (!latest) return null;
+	await writeCacheEntry(packageName, {
+		lastCheckedAt: Date.now(),
+		latestVersion: latest
+	});
+	return latest !== currentVersion ? formatNotice(packageName, currentVersion, latest) : null;
+}
+//#endregion
+export { render as a, runCli as i, HELP as n, pkgVersion as r, checkForUpdate as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busa-cli",
-  "version": "0.21.0",
+  "version": "0.30.1",
   "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.21.0",
+    "busabase-sdk": "0.30.1",
     "commander": "^14.0.0",
     "tar-stream": "^3.1.7",
     "yaml": "^2.9.0",