@lark-apaas/miaoda-cli 0.1.1 → 0.1.2

package/dist/cli/handlers/file/cp.js

@@ -45,15 +45,23 @@ const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 const error_1 = require("../../../utils/error");
 const shared_1 = require("../../../cli/commands/shared");
+const colors_1 = require("../../../utils/colors");
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
 /**
- * 判断 src 是本地文件还是远程引用：
- * - src 本地 fs 可访问 → upload（dst 当 remote）
- * - 其他 → download（src 是 /path 或 file_name，由 resolveRemotePath 解析）
- *
- * `cp` 语义要求 src 必须存在；本地不存在就认为用户指向远程。不需要给 dst 猜方向。
+ * 判断 src 是本地路径还是远程引用——按 PRD `miaoda file cp` 规则的优先级：
+ *   1. `./` / `../` / `~/` 开头 + 裸文件名（不含 `/`）→ 本地路径（即使不存在）
+ *      给 handleUpload 把"不存在"准确抛成 FILE_SRC_NOT_FOUND，
+ *      避免回退到远程 download 输出 `FILE_NOT_FOUND` + "Run miaoda file ls"
+ *      这种与用户意图（上传）背离的引导。
+ *   2. `/` 开头：fs.existsSync 兜底——存在即本地（绝对路径上传），
+ *      不存在即远程 path（download，由 resolveRemotePath 处理）。
  */
 function isLocalSrc(src) {
+    if (src.startsWith("./") || src.startsWith("../") || src.startsWith("~/"))
+        return true;
+    if (!src.includes("/"))
+        return true;
+    // `/` 开头：可能是本地绝对路径，也可能是远程 path；交给 fs 探测。
     const expanded = expandHome(src);
     try {
         return node_fs_1.default.existsSync(expanded);
@@ -104,23 +112,37 @@ async function resolveRemotePath(appId, input) {
 async function handleUpload(appId, localRaw, remoteRaw, rename) {
     const localPath = expandHome(localRaw);
     if (!node_fs_1.default.existsSync(localPath) || !node_fs_1.default.statSync(localPath).isFile()) {
-        throw new error_1.AppError("FILE_SRC_NOT_FOUND", `Local file '${localRaw}' does not exist`);
+        throw new error_1.AppError("FILE_SRC_NOT_FOUND", `Local file '${localRaw}' does not exist`, {
+            // 引导本地路径自检；远程下载请用 `/path` 形态，避免裸名/相对路径误入上传分支
+            next_actions: ["Check the local file path; use `/path` prefix for remote download."],
+        });
     }
     const stat = node_fs_1.default.statSync(localPath);
     if (stat.size > MAX_UPLOAD_BYTES) {
         throw new error_1.AppError("FILE_SIZE_EXCEEDED", `File size ${(0, render_1.formatSize)(stat.size)} exceeds the 100 MB upload limit`, {
-            next_actions: [
-                "Split the file, or use the web console for large uploads.",
-            ],
+            next_actions: ["Split the file, or use the web console for large uploads."],
         });
     }
-    const fileName = rename ?? node_path_1.default.basename(localPath);
-    let remotePath = remoteRaw;
-    if (remoteRaw.endsWith("/")) {
-        remotePath = remoteRaw + fileName;
+    // PRD：path 末段**始终**由平台生成 16 位 ID 确保唯一，不受 dst 形态或
+    // --rename 影响；用户指定的 file_name 仅作为显示名（同目录下允许重名）。
+    // 因此 CLI 端把 dst 拆成"目录前缀 + file_name"两段：
+    //   - dst 以 / 结尾或为空  → 整段当目录前缀，file_name 用 --rename 或本地 basename
+    //                          例：cp ./logo.png /imgs/        → path=/imgs/<GID>.png, file_name=logo.png
+    //   - dst 不以 / 结尾      → 末段当 file_name，前段（含尾 /）当目录前缀
+    //                          例：cp ./1.jpg /post-covers/cover.jpg → path=/post-covers/<GID>.jpg, file_name=cover.jpg
+    // 这样无论用户怎么写 dst，都走服务端目录前缀模式（PreUpload `filePath`
+    // 末尾带 /），保证 path 全局唯一性，不会因用户指定了完整路径而退化成
+    // 完整对象 key 模式。--rename 始终覆盖 file_name 推断结果（PRD 优先级）。
+    let fileName;
+    let remotePath;
+    if (remoteRaw === "" || remoteRaw.endsWith("/")) {
+        fileName = rename ?? node_path_1.default.basename(localPath);
+        remotePath = remoteRaw;
     }
-    else if (remoteRaw === "/") {
-        remotePath = "/" + fileName;
+    else {
+        const lastSlash = remoteRaw.lastIndexOf("/");
+        fileName = rename ?? remoteRaw.slice(lastSlash + 1);
+        remotePath = remoteRaw.slice(0, lastSlash + 1);
     }
     const contentType = detectMime(localPath);
     const result = await api.file.uploadFile({
@@ -147,7 +169,7 @@ async function handleUpload(appId, localRaw, remoteRaw, rename) {
     const tty = (0, render_1.isStdoutTty)();
     const lines = [];
     if (tty) {
-        lines.push(`✓ Uploaded ${node_path_1.default.basename(localPath)} → ${result.path}`);
+        lines.push(colors_1.c.success(`✓ Uploaded ${node_path_1.default.basename(localPath)} → ${result.path}`));
         lines.push(`   file_name:     ${result.file_name}`);
         lines.push(`   path:          ${result.path}`);
         lines.push(`   size:          ${(0, render_1.formatSize)(result.size)} (${String(result.size)} bytes)`);
@@ -204,7 +226,7 @@ async function handleDownload(appId, remoteRaw, localRaw) {
     }
     const tty = (0, render_1.isStdoutTty)();
     if (tty) {
-        (0, output_1.emit)(`✓ Downloaded ${baseName} → ${localTarget} (${(0, render_1.formatSize)(writtenBytes)})`);
+        (0, output_1.emit)(colors_1.c.success(`✓ Downloaded ${baseName} → ${localTarget} (${(0, render_1.formatSize)(writtenBytes)})`));
     }
     else {
         (0, output_1.emit)(`OK Downloaded ${baseName} -> ${localTarget} (${String(writtenBytes)} bytes)`);

package/dist/cli/handlers/file/ls.js

@@ -101,9 +101,7 @@ async function handleFileLs(opts) {
         info.type,
         (0, render_1.formatTime)(info.uploaded_at, tty),
     ]);
-    const table = tty
-        ? (0, render_1.renderAlignedTable)(headers, rows)
-        : (0, render_1.renderTsv)(headers, rows);
+    const table = tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows);
     const hint = result.has_more && result.next_cursor
         ? `\n— ${String(result.items.length)} results. Next: --cursor ${result.next_cursor}`
         : "";

package/dist/cli/handlers/file/rm.js

@@ -43,6 +43,7 @@ const error_1 = require("../../../utils/error");
 const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../api/file/index");
 const render_1 = require("../../../utils/render");
+const colors_1 = require("../../../utils/colors");
 const node_readline_1 = __importDefault(require("node:readline"));
 const MAX_BATCH = 100;
 /**
@@ -169,7 +170,7 @@ async function handleFileRm(paths, opts) {
             results.push({
                 status: "ok",
                 input: entry?.input ?? p,
-                file_name: entry?.file_name ?? (p.split("/").pop() ?? p),
+                file_name: entry?.file_name ?? p.split("/").pop() ?? p,
                 path: p,
             });
         }
@@ -228,9 +229,9 @@ async function handleFileRm(paths, opts) {
         const lines = [];
         for (const r of results) {
             if (r.status === "ok")
-                lines.push(`✓ Deleted ${r.input}`);
+                lines.push(colors_1.c.success(`✓ Deleted ${r.input}`));
             else
-                lines.push(`✗ ${r.input}: ${r.error.message}`);
+                lines.push(colors_1.c.fail(`✗ ${r.input}: ${r.error.message}`));
         }
         if (failCount === 0) {
             lines.push(`Deleted ${String(okCount)} of ${String(totalCount)} files`);

package/dist/cli/handlers/plugin/plugin-local.js

@@ -82,7 +82,9 @@ function parsePluginName(input) {
 function readPackageJson() {
     const pkgPath = getPackageJsonPath();
     if (!node_fs_1.default.existsSync(pkgPath)) {
-        throw new error_1.AppError("PKG_JSON_NOT_FOUND", "package.json not found in current directory", { next_actions: ["在应用项目根目录运行"] });
+        throw new error_1.AppError("PKG_JSON_NOT_FOUND", "package.json not found in current directory", {
+            next_actions: ["在应用项目根目录运行"],
+        });
     }
     const content = node_fs_1.default.readFileSync(pkgPath, "utf-8");
     return JSON.parse(content);
@@ -189,9 +191,14 @@ function installMissingDeps(deps) {
     if (deps.length === 0)
         return;
     (0, logger_1.log)("plugin", `Installing missing dependencies: ${deps.join(", ")}`);
-    const result = (0, node_child_process_1.spawnSync)("npm", ["install", ...deps, "--no-save", "--no-package-lock"], { cwd: getProjectRoot(), stdio: "inherit" });
+    const result = (0, node_child_process_1.spawnSync)("npm", ["install", ...deps, "--no-save", "--no-package-lock"], {
+        cwd: getProjectRoot(),
+        stdio: "inherit",
+    });
     if (result.error) {
-        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, { next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"] });
+        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, {
+            next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"],
+        });
     }
     if (result.status !== 0) {
         throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed with exit code ${String(result.status)}`, { next_actions: ["检查上方 npm 输出日志定位具体错误"] });
@@ -200,7 +207,9 @@ function installMissingDeps(deps) {
 function npmInstall(tgzPath) {
     const result = (0, node_child_process_1.spawnSync)("npm", ["install", tgzPath, "--no-save", "--no-package-lock", "--ignore-scripts"], { cwd: getProjectRoot(), stdio: "inherit" });
     if (result.error) {
-        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, { next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"] });
+        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, {
+            next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"],
+        });
     }
     if (result.status !== 0) {
         throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed with exit code ${String(result.status)}`, { next_actions: ["检查上方 npm 输出日志定位具体错误"] });
@@ -232,7 +241,9 @@ function listCapabilityIds() {
 function readCapability(id) {
     const filePath = node_path_1.default.join(getCapabilitiesDir(), `${id}.json`);
     if (!node_fs_1.default.existsSync(filePath)) {
-        throw new error_1.AppError("CAPABILITY_NOT_FOUND", `Capability not found: ${id}`, { next_actions: ["运行 miaoda plugin list 查看所有可用 capability id"] });
+        throw new error_1.AppError("CAPABILITY_NOT_FOUND", `Capability not found: ${id}`, {
+            next_actions: ["运行 miaoda plugin list 查看所有可用 capability id"],
+        });
     }
     try {
         const content = node_fs_1.default.readFileSync(filePath, "utf-8");
@@ -240,7 +251,9 @@ function readCapability(id) {
     }
     catch (error) {
         if (error instanceof SyntaxError) {
-            throw new error_1.AppError("INVALID_JSON", `Invalid JSON in capability file: ${id}.json`, { next_actions: [`检查 server/capabilities/${id}.json 的 JSON 语法`] });
+            throw new error_1.AppError("INVALID_JSON", `Invalid JSON in capability file: ${id}.json`, {
+                next_actions: [`检查 server/capabilities/${id}.json 的 JSON 语法`],
+            });
         }
         throw error;
     }
@@ -303,7 +316,9 @@ async function loadPlugin(pluginKey) {
     }
     catch (error) {
         if (error.code === "MODULE_NOT_FOUND") {
-            throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin not installed: ${pluginKey}`, { next_actions: [`运行 miaoda plugin install ${pluginKey}`] });
+            throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin not installed: ${pluginKey}`, {
+                next_actions: [`运行 miaoda plugin install ${pluginKey}`],
+            });
         }
         throw new error_1.AppError("INTERNAL_PLUGIN_LOAD_FAILED", `Failed to load plugin ${pluginKey}: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -314,8 +329,7 @@ async function hydrateCapability(capability) {
         if (manifest.actions.length === 0) {
             throw new error_1.AppError("INTERNAL_PLUGIN_LOAD_FAILED", `Plugin ${capability.pluginKey} has no actions defined`);
         }
-        const hasDynamic = manifest.actions.some((action) => isDynamicSchema(action.inputSchema) ||
-            isDynamicSchema(action.outputSchema));
+        const hasDynamic = manifest.actions.some((action) => isDynamicSchema(action.inputSchema) || isDynamicSchema(action.outputSchema));
         let pluginInstance = null;
         if (hasDynamic) {
             const plugin = await loadPlugin(capability.pluginKey);

package/dist/cli/handlers/plugin/plugin.js

@@ -44,7 +44,9 @@ const output_1 = require("../../../utils/output");
 const error_1 = require("../../../utils/error");
 const logger_1 = require("../../../utils/logger");
 const plugin_local_1 = require("./plugin-local");
-const log = (msg) => { (0, logger_1.log)("plugin", msg); };
+const log = (msg) => {
+    (0, logger_1.log)("plugin", msg);
+};
 // ── Install ──
 function syncActionPluginsRecord(name, version) {
     const plugins = (0, plugin_local_1.readActionPlugins)();
@@ -63,7 +65,9 @@ async function installOne(nameWithVersion) {
             if (actualVersion === requestedVersion) {
                 log(`${name}@${requestedVersion} already installed`);
                 syncActionPluginsRecord(name, actualVersion);
-                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => { });
+                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => {
+                    /* fire-and-forget */
+                });
                 return { name, version: actualVersion, success: true, skipped: true };
             }
         }
@@ -74,7 +78,9 @@ async function installOne(nameWithVersion) {
             if (actualVersion === targetVersion) {
                 log(`${name} already up to date (${actualVersion})`);
                 syncActionPluginsRecord(name, actualVersion);
-                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => { });
+                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => {
+                    /* fire-and-forget */
+                });
                 return { name, version: actualVersion, success: true, skipped: true };
             }
             log(`Found newer version: ${targetVersion} (installed: ${actualVersion ?? "none"})`);
@@ -106,8 +112,12 @@ async function installOne(nameWithVersion) {
         (0, plugin_local_1.writeActionPlugins)(plugins);
         const source = fromCache ? "from cache" : "downloaded";
         log(`Installed ${name}@${installedVersion} (${source})`);
-        api.plugin.reportInstallEvent(name, installedVersion).catch(() => { });
-        api.plugin.reportCreateInstanceEvent(name, installedVersion).catch(() => { });
+        api.plugin.reportInstallEvent(name, installedVersion).catch(() => {
+            /* fire-and-forget */
+        });
+        api.plugin.reportCreateInstanceEvent(name, installedVersion).catch(() => {
+            /* fire-and-forget */
+        });
         return { name, version: installedVersion, success: true };
     }
     catch (error) {
@@ -193,7 +203,9 @@ async function handlePluginUpdate(opts) {
 function handlePluginRemove(opts) {
     const { name } = (0, plugin_local_1.parsePluginName)(opts.name);
     if (!(0, plugin_local_1.isPluginInstalled)(name)) {
-        throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin ${name} is not installed`, { next_actions: ["运行 miaoda plugin list-packages 查看已安装插件"] });
+        throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin ${name} is not installed`, {
+            next_actions: ["运行 miaoda plugin list-packages 查看已安装插件"],
+        });
     }
     (0, plugin_local_1.removePluginDirectory)(name);
     const plugins = (0, plugin_local_1.readActionPlugins)();
@@ -263,7 +275,9 @@ async function handlePluginInit() {
 // ── List (capability configs) ──
 async function handlePluginList(opts) {
     if (!(0, plugin_local_1.capabilitiesDirExists)()) {
-        throw new error_1.AppError("CAPABILITIES_DIR_NOT_FOUND", "server/capabilities directory not found", { next_actions: ["当前目录必须是含 server/capabilities/ 的应用项目"] });
+        throw new error_1.AppError("CAPABILITIES_DIR_NOT_FOUND", "server/capabilities directory not found", {
+            next_actions: ["当前目录必须是含 server/capabilities/ 的应用项目"],
+        });
     }
     if (opts.id) {
         const capability = (0, plugin_local_1.readCapability)(opts.id);

package/dist/cli/help.js

@@ -115,7 +115,9 @@ class MiaodaHelp extends commander_1.Help {
         out.push("Usage:", `  ${helper.commandUsage(cmd)}`, "");
         // 3. Commands（仅父级命令组有，spec 要求 Commands 在 Flags 前）
         //    spec 不展示 Arguments 段，参数说明放在 description 文本里
-        const subs = helper.visibleCommands(cmd).map((c) => formatItem(helper.subcommandTerm(c), helper.subcommandDescription(c)));
+        const subs = helper
+            .visibleCommands(cmd)
+            .map((c) => formatItem(helper.subcommandTerm(c), helper.subcommandDescription(c)));
         if (subs.length) {
             out.push("Commands:", formatList(subs), "");
         }
@@ -125,7 +127,8 @@ class MiaodaHelp extends commander_1.Help {
         //    - `-h, --help` 永远不放 Flags 段，统一放 Global Flags（spec 约定）
         const isParent = subs.length > 0;
         if (!isRoot && !isParent) {
-            const opts = helper.visibleOptions(cmd)
+            const opts = helper
+                .visibleOptions(cmd)
                 .filter((o) => !isHelpOption(o))
                 .map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
             if (opts.length) {

package/dist/utils/colors.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * 终端彩色高亮的语义层封装。
+ *
+ * 三层结构（自上而下：稳定→灵活）：
+ *
+ *   1. **ColorAdapter**（公共契约）：6 个语义方法 string → string，业务代码
+ *      只接触这层，对底层库 0 感知。
+ *   2. **ColorFactory**（适配器签名）：`(useColor: boolean) => ColorAdapter`，
+ *      把"是否染色"参数化，便于按需构造。一个三方库对应一个 factory 实现。
+ *   3. **当前底层库实现**：picocolors（[picocolors npm](https://www.npmjs.com/package/picocolors)，~3KB）。
+ *      切换到 chalk / kleur 等只需新增一个 ColorFactory 实现，并改最下方的
+ *      `factory =` 一行赋值，业务代码与 ColorAdapter contract 0 改动。
+ *
+ * # 色谱（对齐 spec）
+ *
+ *   - header     表头 / 命令名 / key 标签：bold + cyan
+ *   - highlight  强调值（表名等）：cyan
+ *   - success    ✓ Uploaded / ✓ Deleted：green
+ *   - fail       ✗ / Error:：red
+ *   - warn       ⚠ Approaching quota：yellow
+ *   - muted      NULL / 辅助 hint / 次要信息：dim + gray
+ *
+ * # 染色判定（NO_COLOR / FORCE_COLOR / TTY，[no-color.org](https://no-color.org/) 业界标准）
+ *
+ *   - `NO_COLOR=1`            强制关颜色（任何非空值生效）
+ *   - `FORCE_COLOR=1`         强制开颜色（管道 / CI 场景）
+ *   - 否则按 `process.stdout.isTTY` 判定
+ *
+ * 每次调用 `c.xxx(s)` 时按当前状态实时构造 adapter——避免模块加载时缓存的
+ * `process.stdout.isTTY` 与测试 / pipe 切换脱节。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.c = void 0;
+exports.shouldColorize = shouldColorize;
+const picocolors_1 = require("picocolors");
+// ──────────────────────────────────────────────────────────────────────
+// 2. 库无关的染色判定：哪个 factory 都能复用
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * 当前是否应当染色。读取的是**调用时**的状态，而非模块加载时缓存——
+ * 测试经常 `Object.defineProperty(process.stdout, "isTTY", ...)` 实时切换，
+ * 这里直接每次问 process。
+ *
+ * 优先级：FORCE_COLOR > NO_COLOR > TTY。
+ */
+function shouldColorize() {
+    const env = process.env;
+    const noColor = env.NO_COLOR != null && env.NO_COLOR !== "";
+    const forceColor = env.FORCE_COLOR != null && env.FORCE_COLOR !== "";
+    const isTTY = process.stdout.isTTY === true;
+    return forceColor || (!noColor && isTTY);
+}
+/** picocolors 实现：当前生产用 factory。~3KB，业界 CLI 标准之一。 */
+const picocolorsFactory = (useColor) => {
+    const x = (0, picocolors_1.createColors)(useColor);
+    return {
+        header: (s) => x.bold(x.cyan(s)),
+        highlight: (s) => x.cyan(s),
+        success: (s) => x.green(s),
+        fail: (s) => x.red(s),
+        warn: (s) => x.yellow(s),
+        muted: (s) => x.dim(x.gray(s)),
+    };
+};
+// ──────────────────────────────────────────────────────────────────────
+// 4. 唯一切换点：换库改这一行（其它都不用动）
+// ──────────────────────────────────────────────────────────────────────
+//
+// 切换示例：
+//
+//   import chalk, { Chalk } from "chalk";
+//   const chalkFactory: ColorFactory = (useColor) => {
+//     const k = new Chalk({ level: useColor ? 1 : 0 });
+//     return {
+//       header:    (s) => k.bold.cyan(s),
+//       highlight: (s) => k.cyan(s),
+//       success:   (s) => k.green(s),
+//       fail:      (s) => k.red(s),
+//       warn:      (s) => k.yellow(s),
+//       muted:     (s) => k.dim.gray(s),
+//     };
+//   };
+//   const factory: ColorFactory = chalkFactory;   // ← 改这里
+//
+const factory = picocolorsFactory;
+// ──────────────────────────────────────────────────────────────────────
+// 5. 公共出口：业务代码 import { c } from "../utils/colors"
+// ──────────────────────────────────────────────────────────────────────
+/** 语义染色器：业务代码唯一接触的对象。底层库切换 0 感知。 */
+exports.c = {
+    header: (s) => factory(shouldColorize()).header(s),
+    highlight: (s) => factory(shouldColorize()).highlight(s),
+    success: (s) => factory(shouldColorize()).success(s),
+    fail: (s) => factory(shouldColorize()).fail(s),
+    warn: (s) => factory(shouldColorize()).warn(s),
+    muted: (s) => factory(shouldColorize()).muted(s),
+};

package/dist/utils/error.js

@@ -6,6 +6,14 @@ class AppError extends Error {
     retryable;
     next_actions;
     statement_index;
+    total_statements;
+    /**
+     * 多语句失败时由 api.db.execSql 透传服务端 results（已成功的 statement 原始结构）。
+     * 由 db sql handler 转成 PRD 友好的 `completed` 数组 + 推断 `rolled_back` 后挂回到本对象。
+     */
+    partial_results;
+    completed;
+    rolled_back;
     constructor(code, message, opts) {
         super(message);
         this.name = "AppError";
@@ -21,6 +29,9 @@ class AppError extends Error {
             retryable: this.retryable,
             next_actions: this.next_actions,
             statement_index: this.statement_index,
+            total_statements: this.total_statements,
+            completed: this.completed,
+            rolled_back: this.rolled_back,
         };
     }
 }

package/dist/utils/fuzzy-match.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * 模糊匹配：基于 Levenshtein 编辑距离的"did-you-mean"建议器。
+ *
+ * 用于 CLI 错误路径的拼写纠错提示——当用户输入的 token（关键字 / 表名 / 列名）
+ * 与某个有效候选词"接近"时，给出 "Did you mean X?" 类的 hint。
+ *
+ * # 设计取舍
+ *
+ *   - **算法**：Damerau-Levenshtein DP（在标准 Levenshtein 基础上把"相邻字符
+ *     交换"算 1 步编辑——SQL 用户最常见的拼写错误就是 FORM/FROM、SELCT/SELECT
+ *     这类 transposition；纯 Levenshtein 把它们算 2 步会过严，触发不到 hint）。
+ *     约 30 行二维 DP 实现，不引第三方库；业界 CLI 拼写纠错事实标准。
+ *   - **大小写不敏感**：CLI 用户混用 SELECT / select 是常态，统一 lowercase 比较
+ *   - **阈值按候选词长度自适应**：避免短词过度匹配（"id" 不应该建议成 "in"）
+ *       len ≤ 4：max 1 编辑（短词严）
+ *       len 5-8：max 2 编辑
+ *       len ≥ 9：max 3 编辑（长词宽）
+ *   - **同分多候选**：返第一个；调用方负责候选词列表的稳定排序
+ *   - **找不到不强凑**：阈值外返 null，不"硬贴"无关建议
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshtein = levenshtein;
+exports.suggest = suggest;
+/**
+ * 计算两个字符串的 Damerau-Levenshtein 编辑距离（不区分大小写）。
+ *
+ * 在标准 Levenshtein（增 / 删 / 替换）基础上加"相邻字符交换"作为单步编辑。
+ * 二维 DP 实现（transposition 需要回看 dp[i-2][j-2]，所以不再用单行优化）。
+ * 候选词通常 < 30 字符，二维 DP 的常数空间开销可忽略。
+ */
+function levenshtein(a, b) {
+    const aa = a.toLowerCase();
+    const bb = b.toLowerCase();
+    const m = aa.length;
+    const n = bb.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = aa[i - 1] === bb[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, // 删除
+            dp[i][j - 1] + 1, // 插入
+            dp[i - 1][j - 1] + cost);
+            // transposition: 当前字符 = 对方前一字符 && 我方前一字符 = 对方当前字符
+            // 例：aa="form", bb="from"，i=2,j=2 时 aa[1]=o=bb[0]=f? 不命中；i=3,j=3
+            // 时 aa[2]=r=bb[1]=r? bb[2]=o, aa[1]=o → 命中 → dp[3][3] = dp[1][1] + 1 = 1
+            if (i > 1 && j > 1 && aa[i - 1] === bb[j - 2] && aa[i - 2] === bb[j - 1]) {
+                dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return dp[m][n];
+}
+/** 默认阈值：候选词越短匹配越严，越长越宽。避免 "id" 错配 "in" 这种 false positive。 */
+function defaultThreshold(len) {
+    if (len <= 4)
+        return 1;
+    if (len <= 8)
+        return 2;
+    return 3;
+}
+/**
+ * 在候选词列表里找与 input 最相近的一个。
+ *
+ * 距离 ≤ 阈值时按"距离最小"返回；多个候选词相同距离时返"列表中最先出现"的；
+ * 阈值外没有命中返 null（调用方按 null 静默不加 hint，不要强凑）。
+ */
+function suggest(input, candidates, opts) {
+    if (!input || candidates.length === 0)
+        return null;
+    const threshold = opts?.maxDistance ?? defaultThreshold;
+    let best = null;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const cand of candidates) {
+        const d = levenshtein(input, cand);
+        const limit = threshold(cand.length);
+        if (d <= limit && d < bestDist) {
+            best = cand;
+            bestDist = d;
+        }
+    }
+    return best;
+}

package/dist/utils/output.js

@@ -7,6 +7,27 @@ exports.emitOk = emitOk;
 exports.emitPaged = emitPaged;
 const config_1 = require("./config");
 const error_1 = require("./error");
+const colors_1 = require("./colors");
+/**
+ * 服务端错误码 → CLI 兜底 hint 文案。
+ *
+ * 服务端错误协议只有 `{code, msg}` 两个字段（dataloom InnerExecuteSQL 等 IDL
+ * 没有 hint / next_actions 通道），所以服务端给的错误本身永远没有 hint。
+ * 这里是 CLI 展示层为常见错误码补一份 spec 一致的 actionable 引导，按错误码
+ * 落到 next_actions。
+ *
+ * 仅在 next_actions 已经为空时介入——保留 handler / enrichSqlError 自己塞过的
+ * 具体 hint（如 did-you-mean、shared.resolveAppId 等），它们优先级更高。
+ */
+const SERVER_ERROR_HINTS = {
+    // SELECT 结果集超过 1000 行硬拦：spec 多行引导。
+    // key 用 BIZ_ERR_MAP 映射后的语义 code（不是原始服务端 k_dl_xxx），保持
+    // 与 help / 文档里宣传的 RESULT_SET_TOO_LARGE 一致。
+    RESULT_SET_TOO_LARGE: [
+        "Add `LIMIT <n>` to your SQL to narrow the result.",
+        "For counts, use `SELECT count(*) FROM ...`; for aggregation, use GROUP BY with filters.",
+    ],
+};
 function isJsonMode() {
     const cfg = (0, config_1.getConfig)();
     return cfg.output === "json" || Boolean(cfg.json);
@@ -36,23 +57,56 @@ function emit(data) {
  */
 function emitError(err) {
     const info = toErrorInfo(err);
+    // 没人给过 next_actions 才走错误码兜底；handler 已经塞过具体 hint 时不覆盖
+    const hints = info.next_actions && info.next_actions.length > 0
+        ? info.next_actions
+        : (SERVER_ERROR_HINTS[info.code] ?? []);
     if (isJsonMode()) {
         const errObj = {
             code: info.code,
             message: info.message,
         };
-        if (info.next_actions && info.next_actions.length > 0) {
-            errObj.hint = info.next_actions.join(" ");
+        if (hints.length > 0) {
+            // JSON 输出压平成单行，更便于机器消费（脚本 / agent 拼字符串）
+            errObj.hint = hints.join(" ");
         }
         if (typeof info.statement_index === "number") {
             errObj.statement_index = info.statement_index;
         }
+        // PRD 多语句失败 envelope 额外字段：completed / rolled_back
+        if (Array.isArray(info.completed)) {
+            errObj.completed = info.completed;
+        }
+        if (typeof info.rolled_back === "boolean") {
+            errObj.rolled_back = info.rolled_back;
+        }
         process.stderr.write(JSON.stringify({ error: errObj }) + "\n");
     }
     else {
-        process.stderr.write(`Error: ${info.message}\n`);
-        if (info.next_actions && info.next_actions.length > 0) {
-            process.stderr.write(`  hint: ${info.next_actions.join(" ")}\n`);
+        // stderr 染色：picocolors 默认按 stdout.isTTY 判断；stderr 通常也是 tty，
+        // 这里复用 stdout 探测保持简单（stderr only-pipe 的极端场景留作后续优化）
+        // 多语句失败时 Error 行末尾追加 "(at statement K of N)"，与 PRD spec 对齐
+        let errorLine = `${colors_1.c.fail("Error:")} ${info.message}`;
+        if (typeof info.statement_index === "number") {
+            const k = info.statement_index + 1;
+            const n = info.total_statements;
+            errorLine +=
+                typeof n === "number" && n > 0
+                    ? ` (at statement ${String(k)} of ${String(n)})`
+                    : ` (at statement ${String(k)})`;
+        }
+        process.stderr.write(errorLine + "\n");
+        // 多行 hint：第一行带 "hint:" 标签，后续行用 8 空格缩进对齐 "  hint: " 之后的列。
+        // 对应 spec 期望的格式：
+        //   Error: ...
+        //     hint: 第一条建议
+        //           第二条建议
+        if (hints.length > 0) {
+            const [first, ...rest] = hints;
+            process.stderr.write(`  ${colors_1.c.muted("hint:")} ${first}\n`);
+            for (const line of rest) {
+                process.stderr.write(`        ${line}\n`);
+            }
         }
     }
 }