@longzai-intelligence-cli/core 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import "./rolldown-runtime-BqT_7tdF.js";
 import { Command } from "commander";
+import * as z from "zod";
 //#region src/contracts.d.ts
 /**
  * 能力契约定义
@@ -464,4 +465,108 @@ declare const log: {
  */
 declare function progressBar(total?: number): ProgressController;
 //#endregion
-export { type ColorProvider, type ConfirmOptions, type CreateCliOptions, type InteractionProvider, type LogToolset, type OutputFormat, OutputFormatter, type ProgressController, type SelectOption, type SpinnerController, type TextInputOptions, confirm, createCli, getCliVersion, getColorProvider, getInteractionProvider, log, note, parseOutputFormat, progressBar, select, setColorProvider, setInteractionProvider, spinner, textInput };
+//#region src/define-command.d.ts
+/**
+ * 选项声明（commander 选项签名 + 是否带默认值）
+ */
+type OptionDecl = {
+  /**
+   * commander 选项签名
+   *
+   * flag 形态：`--json`、`--remote <url>`、`-r, --remote <url>`、`--output <format>`
+   */
+  flags: string;
+  /**
+   * 选项描述
+   */
+  description?: string;
+  /**
+   * 默认值（commander 的第三参数）
+   */
+  defaultValue?: string;
+};
+/**
+ * 命令参数规格
+ *
+ * 统一 commander 选项声明与 zod 校验：消费方提供选项签名（注册 commander）与 zod schema（校验），
+ * core 在 action 内执行 zod 校验，校验失败统一输出错误（集中化规范，消费方无需处理校验失败）。
+ *
+ * @typeParam T - zod schema 类型
+ */
+type CommandSpec<T extends z.ZodType> = {
+  /**
+   * 命令名称
+   */
+  name: string;
+  /**
+   * 命令描述
+   */
+  description?: string;
+  /**
+   * 位置参数声明（commander .argument() 形态）
+   *
+   * 如 `'<executionId>'`（必填）、`'[file]'`（可选）
+   */
+  arguments?: Array<{
+    /**
+     * 参数签名（commander 语法）
+     */
+    signature: string;
+    /**
+     * 位置参数的说明文本（显示在 --help）
+     */
+    description?: string;
+  }>;
+  /**
+   * 选项声明列表（注册到 commander）
+   */
+  options?: OptionDecl[];
+  /**
+   * 选项的 zod schema（校验 action 收到的 options 对象）
+   *
+   * schema 的字段名应与选项声明的长名（去掉 -- 前缀）对应。
+   */
+  schema: T;
+  /**
+   * 命令处理函数（接收已校验的选项与位置参数）
+   *
+   * @param validated - zod 校验后的选项（类型安全）
+   * @param positionals - 位置参数数组
+   */
+  action: (validated: z.infer<T>, positionals: string[]) => Promise<void>;
+};
+/**
+ * 定义并注册命令（commander 选项 + zod 校验统一封装）
+ *
+ * 消费方提供选项签名（OptionDecl）与 zod schema，core 据此注册 commander 选项，
+ * 在 action 执行前用 zod 校验选项，校验失败统一输出错误。
+ *
+ * @example
+ *   ```ts
+ *   defineCommand(program, {
+ *     name: 'cancel',
+ *     description: '取消执行',
+ *     arguments: [{ signature: '<executionId>' }],
+ *     options: [
+ *       { flags: '-r, --remote <url>' },
+ *       { flags: '--token <token>' },
+ *       { flags: '-o, --output <format>', defaultValue: 'text' },
+ *     ],
+ *     schema: z.object({
+ *       remote: z.string().min(1),
+ *       token: z.string().optional(),
+ *       output: z.enum(['text', 'json']).default('text'),
+ *     }),
+ *     action: async (opts, [executionId]) => {
+ *       // opts 已校验，类型安全
+ *     },
+ *   });
+ *   ```;
+ *
+ * @typeParam T - zod schema 类型
+ * @param program - commander Command 实例
+ * @param spec - 命令参数规格
+ */
+declare function defineCommand<T extends z.ZodType>(program: Command, spec: CommandSpec<T>): void;
+//#endregion
+export { type ColorProvider, type CommandSpec, type ConfirmOptions, type CreateCliOptions, type InteractionProvider, type LogToolset, type OptionDecl, type OutputFormat, OutputFormatter, type ProgressController, type SelectOption, type SpinnerController, type TextInputOptions, confirm, createCli, defineCommand, getCliVersion, getColorProvider, getInteractionProvider, log, note, parseOutputFormat, progressBar, select, setColorProvider, setInteractionProvider, spinner, textInput };

package/dist/index.js

@@ -1,3 +1,3 @@
-import"./rolldown-runtime-BqT_7tdF.js";import{createNodeLogger as e}from"@longzai-intelligence-logger/node";import{Command as t}from"commander";import"node:fs";import"node:path";import"node:url";const n=e(`@longzai-intelligence-cli/core/provider`),r={red:e=>e,green:e=>e,yellow:e=>e,blue:e=>e,bold:e=>e,gray:e=>e};let i={select:async(e,t)=>t[0]?.value??``,textInput:async(e,t)=>t?.defaultValue??``,confirm:async(e,t)=>t?.defaultValue??!1,spinner:()=>({start:e=>n.info(e),stop:e=>n.info(e)}),note:(e,t)=>{t?n.info(`${t}: ${e}`):n.info(e)},log:{info:e=>n.info(e),success:e=>n.info(e),warn:e=>n.warn(e),error:e=>n.error(e),step:e=>n.info(e)}},a=r;function o(e){i=e}function s(e){a=e}function c(){return i}function l(){return a}const u=()=>`0.0.2`;function d(e){let n=e.version??u();e.interaction&&o(e.interaction),e.color&&s(e.color);let r=new t;return r.name(e.name).version(n,`-v, --version`,`输出 ${e.name} 的版本号`),e.description&&r.description(e.description),r}const f=e(`@longzai-intelligence-cli/core/output`);var p=class{format;constructor(e=`text`){this.format=e}get colors(){return l()}success(e,t){this.format===`json`?f.info(JSON.stringify({success:!0,data:e},null,2)):f.info(t?this.colors.green(t):this.colors.green(this.formatData(e)))}error(e){if(this.format===`json`){let t=e instanceof Error?{message:e.message,name:e.name}:{message:String(e)};f.info(JSON.stringify({success:!1,error:t},null,2))}else{let t=e instanceof Error?e.message:String(e);f.error(this.colors.red(`错误: ${t}`))}}info(e){this.format===`json`?f.info(JSON.stringify({success:!0,message:e},null,2)):f.info(this.colors.blue(e))}warn(e){this.format===`json`?f.info(JSON.stringify({success:!0,warning:e},null,2)):f.info(this.colors.yellow(e))}table(e,t){if(this.format===`json`){let n=t.map(t=>{let n={};return e.forEach((e,r)=>{n[e]=t[r]??``}),n});f.info(JSON.stringify({success:!0,data:n},null,2))}else{let n=e.map((e,n)=>Math.max(e.length,...t.map(e=>(e[n]??``).length)));f.info(e.map((e,t)=>this.colors.bold(e.padEnd(n[t]??0))).join(`  `)),f.info(n.map(e=>`-`.repeat(e??0)).join(`  `));for(let e of t)f.info(e.map((e,t)=>(e??``).padEnd(n[t]??0)).join(`  `))}}formatData(e){return typeof e==`string`?e:typeof e==`number`||typeof e==`boolean`?String(e):JSON.stringify(e,null,2)}};function m(e){return e===`json`?`json`:`text`}async function h(e,t){return c().select(e,t)}async function g(e,t){return c().textInput(e,t)}async function _(e,t){return c().confirm(e,t)}function v(){return c().spinner()}function y(e,t){c().note(e,t)}const b={info(e){c().log.info(e)},success(e){c().log.success(e)},warn(e){c().log.warn(e)},error(e){c().log.error(e)},step(e){c().log.step(e)}},x=e(`@longzai-intelligence-cli/core/progress`);function S(e=100){let t=-1;return{update(e,n){let r=Math.max(0,Math.min(100,e)),i=Math.round(r/100*30),a=`█`.repeat(i)+`░`.repeat(30-i);if(e!==t){t=e;let i=n?` ${n}`:``;process.stdout.write(`\r${l().blue(a)} ${r.toFixed(0)}%${i}`),r>=100&&process.stdout.write(`
+import"./rolldown-runtime-BqT_7tdF.js";import{createNodeLogger as e}from"@longzai-intelligence-logger/node";import{Command as t}from"commander";import"node:fs";import"node:path";import"node:url";const n=e(`@longzai-intelligence-cli/core/provider`),r={red:e=>e,green:e=>e,yellow:e=>e,blue:e=>e,bold:e=>e,gray:e=>e};let i={select:async(e,t)=>t[0]?.value??``,textInput:async(e,t)=>t?.defaultValue??``,confirm:async(e,t)=>t?.defaultValue??!1,spinner:()=>({start:e=>n.info(e),stop:e=>n.info(e)}),note:(e,t)=>{t?n.info(`${t}: ${e}`):n.info(e)},log:{info:e=>n.info(e),success:e=>n.info(e),warn:e=>n.warn(e),error:e=>n.error(e),step:e=>n.info(e)}},a=r;function o(e){i=e}function s(e){a=e}function c(){return i}function l(){return a}const u=()=>`0.0.3`;function d(e){let n=e.version??u();e.interaction&&o(e.interaction),e.color&&s(e.color);let r=new t;return r.name(e.name).version(n,`-v, --version`,`输出 ${e.name} 的版本号`),e.description&&r.description(e.description),r}const f=e(`@longzai-intelligence-cli/core/output`);var p=class{format;constructor(e=`text`){this.format=e}get colors(){return l()}success(e,t){this.format===`json`?f.info(JSON.stringify({success:!0,data:e},null,2)):f.info(t?this.colors.green(t):this.colors.green(this.formatData(e)))}error(e){if(this.format===`json`){let t=e instanceof Error?{message:e.message,name:e.name}:{message:String(e)};f.info(JSON.stringify({success:!1,error:t},null,2))}else{let t=e instanceof Error?e.message:String(e);f.error(this.colors.red(`错误: ${t}`))}}info(e){this.format===`json`?f.info(JSON.stringify({success:!0,message:e},null,2)):f.info(this.colors.blue(e))}warn(e){this.format===`json`?f.info(JSON.stringify({success:!0,warning:e},null,2)):f.info(this.colors.yellow(e))}table(e,t){if(this.format===`json`){let n=t.map(t=>{let n={};return e.forEach((e,r)=>{n[e]=t[r]??``}),n});f.info(JSON.stringify({success:!0,data:n},null,2))}else{let n=e.map((e,n)=>Math.max(e.length,...t.map(e=>(e[n]??``).length)));f.info(e.map((e,t)=>this.colors.bold(e.padEnd(n[t]??0))).join(`  `)),f.info(n.map(e=>`-`.repeat(e??0)).join(`  `));for(let e of t)f.info(e.map((e,t)=>(e??``).padEnd(n[t]??0)).join(`  `))}}formatData(e){return typeof e==`string`?e:typeof e==`number`||typeof e==`boolean`?String(e):JSON.stringify(e,null,2)}};function m(e){return e===`json`?`json`:`text`}async function h(e,t){return c().select(e,t)}async function g(e,t){return c().textInput(e,t)}async function _(e,t){return c().confirm(e,t)}function v(){return c().spinner()}function y(e,t){c().note(e,t)}const b={info(e){c().log.info(e)},success(e){c().log.success(e)},warn(e){c().log.warn(e)},error(e){c().log.error(e)},step(e){c().log.step(e)}},x=e(`@longzai-intelligence-cli/core/progress`);function S(e=100){let t=-1;return{update(e,n){let r=Math.max(0,Math.min(100,e)),i=Math.round(r/100*30),a=`█`.repeat(i)+`░`.repeat(30-i);if(e!==t){t=e;let i=n?` ${n}`:``;process.stdout.write(`\r${l().blue(a)} ${r.toFixed(0)}%${i}`),r>=100&&process.stdout.write(`
 `)}},done(e){process.stdout.write(`
-`),e&&x.info(l().green(`✓ ${e}`))}}}export{p as OutputFormatter,_ as confirm,d as createCli,u as getCliVersion,l as getColorProvider,c as getInteractionProvider,b as log,y as note,m as parseOutputFormat,S as progressBar,h as select,s as setColorProvider,o as setInteractionProvider,v as spinner,g as textInput};
+`),e&&x.info(l().green(`✓ ${e}`))}}}const C=e(`@longzai-intelligence-cli/core/define-command`);function w(e,n){let r=e.command(n.name);n.description&&r.description(n.description);for(let e of n.arguments??[])e.description?r.argument(e.signature,e.description):r.argument(e.signature);for(let e of n.options??[])e.defaultValue===void 0?r.option(e.flags,e.description??``):r.option(e.flags,e.description??``,e.defaultValue);r.action(async(...e)=>{let r=e[e.length-1];if(!(r instanceof t))return;let i=r.opts(),a=r.args,o=n.schema.safeParse(i);if(!o.success){let e=o.error.issues.map(e=>e.message).join(`, `);C.error(l().red(`参数校验失败: ${e}`)),c().log.error(`参数校验失败: ${e}`),process.exit(1)}await n.action(o.data,a)})}export{p as OutputFormatter,_ as confirm,d as createCli,w as defineCommand,u as getCliVersion,l as getColorProvider,c as getInteractionProvider,b as log,y as note,m as parseOutputFormat,S as progressBar,h as select,s as setColorProvider,o as setInteractionProvider,v as spinner,g as textInput};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longzai-intelligence-cli/core",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "private": false,
   "keywords": [
     "cli",
@@ -38,7 +38,8 @@
   "dependencies": {
     "@longzai-intelligence-builder/utils": "^0.2.13",
     "@longzai-intelligence-logger/node": "^0.1.0",
-    "commander": "^14.0.0"
+    "commander": "^14.0.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {}
 }