@longzai-intelligence-plugin/kit 0.0.1

package/README.md

@@ -0,0 +1,15 @@
+# @longzai-intelligence-plugin/kit
+
+Longzai Intelligence Plugin 的零框架工具包，为宿主载体件与插件命令提供子进程执行、脚本探测与结果呈现的通用工具，不含业务知识。
+
+## 简介
+
+治理插件命令执行链的通用工具面：在目标仓根执行子进程命令的统一服务、root 脚本形态的探测与改道决策、检查报告的终端与 JSON 双模式呈现、用户自定义命令的文件契约。全部工具零框架依赖，宿主自持装配时按需取用。
+
+## 能力
+
+- 子进程执行服务，含目标仓根注入、超时控制、退出码透传、输出尾部摘录与可选流式转发
+- root 脚本形态探测，识别缺失、守卫哨兵、禁令守卫与直跑四形态并做改道决策
+- 检查报告终端渲染，含四态状态行、失败输出面板与汇总行
+- 命令结果 JSON 双模式输出，供机读透出
+- 用户自定义命令文件契约，含读取、校验与重名拒绝

package/dist/index.d.ts

@@ -0,0 +1,277 @@
+import * as z from "zod";
+import { CheckReport, PluginCommandResult } from "@longzai-intelligence-plugin/core";
+//#region src/exec.service.d.ts
+/**
+ * 子进程执行服务，机制七的执行面
+ *
+ * 统一 cwd 注入、超时、退出码、输出尾部摘录与可选流式转发。宿主无关，
+ * 使用 node 标准 child_process，bun 与 node 宿主均可运行
+ */
+/**
+ * 执行入参
+ */
+type ExecSpec = {
+  /**
+   * 命令名（如 `bun`）
+   */
+  command: string;
+  /**
+   * 参数数组
+   */
+  args: readonly string[];
+  /**
+   * 工作目录，通常为目标仓根
+   */
+  cwd: string;
+  /**
+   * 超时毫秒数，缺省取服务缺省
+   */
+  timeoutMs?: number;
+  /**
+   * 附加环境变量，与 process.env 合并
+   */
+  env?: Record<string, string>;
+  /**
+   * 是否流式转发，实时透传 stdio，此时摘录为空
+   */
+  stream?: boolean;
+};
+/**
+ * 执行产物
+ */
+type ExecOutcome = {
+  /**
+   * 退出码，超时被杀为非零
+   */
+  code: number;
+  /**
+   * 耗时毫秒数
+   */
+  durationMs: number;
+  /**
+   * 标准输出尾部摘录
+   */
+  stdoutExcerpt: string;
+  /**
+   * 标准错误尾部摘录
+   */
+  stderrExcerpt: string;
+  /**
+   * 是否因超时被终止
+   */
+  timedOut: boolean;
+};
+/**
+ * 执行服务缺省项
+ */
+type ExecServiceOptions = {
+  /**
+   * 缺省超时毫秒数
+   *
+   * @default 300000
+   */
+  defaultTimeoutMs?: number;
+  /**
+   * 摘录保留尾部行数
+   *
+   * @default 40
+   */
+  excerptLines?: number;
+};
+/**
+ * 执行服务
+ */
+type ExecService = {
+  /**
+   * 同步执行一条命令
+   *
+   * @param spec - 执行入参
+   * @returns 执行产物
+   */
+  run(spec: ExecSpec): ExecOutcome;
+};
+/**
+ * 创建子进程执行服务
+ *
+ * @param options - 缺省项
+ * @returns 执行服务实例
+ */
+declare function createExecService(options?: ExecServiceOptions): ExecService;
+//#endregion
+//#region src/script-probe.utils.d.ts
+/**
+ * 目标仓 root 脚本形态探测
+ *
+ * 普查事实见架构报告 records/002 质量守卫族，产品仓 root 的 lint 与 typecheck
+ * 与 test 等质量脚本多为 `lzi-dev-cli forbid` 哨兵或 echo 禁令，库仓 root 为真实
+ * turbo 任务，执行前必须识别形态并决定直跑还是改道 `bun turbo run`
+ */
+/**
+ * root 脚本四形态
+ */
+type RootScriptForm = 'missing' | 'forbid-sentinel' | 'echo-guard' | 'direct';
+/**
+ * 探测结果
+ */
+type RootScriptProbe = {
+  /**
+   * 脚本形态
+   */
+  form: RootScriptForm;
+  /**
+   * 脚本原文，missing 时缺省
+   */
+  command?: string;
+};
+/**
+ * 探测目标仓 root 脚本形态
+ *
+ * @param repoRoot - 目标仓根绝对路径
+ * @param scriptName - scripts 键名（如 `lint`、`test`）
+ * @returns 形态与原文
+ */
+declare function probeRootScript(repoRoot: string, scriptName: string): RootScriptProbe;
+/**
+ * 质量任务的执行改道决策产物，含命令与参数，脚本缺失时为 null
+ */
+type QualityTaskInvocation = {
+  command: string;
+  args: readonly string[];
+} | null;
+/**
+ * 质量任务的执行改道决策
+ *
+ * 直跑形态执行 `bun run <scriptName>`；forbid 哨兵与 echo 禁令形态改道
+ * `bun turbo run <scriptName>`；脚本缺失返回 null 由调用方记 skip。
+ *
+ * @param probe - 探测结果
+ * @param scriptName - scripts 键名
+ * @returns 执行命令与参数，缺失时为 null
+ */
+declare function resolveQualityTaskInvocation(probe: RootScriptProbe, scriptName: string): QualityTaskInvocation;
+//#endregion
+//#region src/render.service.d.ts
+/**
+ * 输出格式，text 人读或 json 机读，结构化类型与宿主 CLI 框架的格式枚举同构
+ */
+type OutputFormat = 'text' | 'json';
+/**
+ * 渲染着色器，结构化类型与宿主 CLI 框架的颜色 Provider 结构同构
+ */
+type RenderColor = {
+  /**
+   * 绿色（通过态）
+   */
+  green: (text: string) => string;
+  /**
+   * 红色（失败态）
+   */
+  red: (text: string) => string;
+  /**
+   * 黄色（警告态）
+   */
+  yellow: (text: string) => string;
+  /**
+   * 灰色（次要信息）
+   */
+  gray: (text: string) => string;
+  /**
+   * 加粗（汇总标题）
+   */
+  bold: (text: string) => string;
+};
+/**
+ * 渲染检查报告为多行文本
+ *
+ * @param report - 检查报告
+ * @param color - 着色器
+ * @returns 行数组（逐项行 + 失败摘录面板 + 汇总行）
+ */
+declare function renderCheckReportLines(report: CheckReport, color: RenderColor): string[];
+/**
+ * 结果输出选项
+ */
+type PrintPluginCommandResultOptions = {
+  /**
+   * 输出格式（text 人读或 json 机读）
+   */
+  format: OutputFormat;
+  /**
+   * 着色器
+   */
+  color: RenderColor;
+  /**
+   * 输出行回调
+   */
+  write: (line: string) => void;
+};
+/**
+ * 输出命令结果（text 或 json 双模式）
+ *
+ * @param result - 命令结果
+ * @param options - 输出选项
+ */
+declare function printPluginCommandResult(result: PluginCommandResult, options: PrintPluginCommandResultOptions): void;
+//#endregion
+//#region src/user-commands.schema.d.ts
+/**
+ * 用户命令定义文件路径段，相对仓根
+ */
+declare const USER_COMMANDS_PATH: string;
+/**
+ * 单条用户命令定义
+ */
+declare const UserCommandSpecSchema: z.ZodObject<{
+  name: z.ZodString;
+  description: z.ZodString;
+  command: z.ZodString;
+  args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  timeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * 单条用户命令定义类型
+ */
+type UserCommandSpec = z.infer<typeof UserCommandSpecSchema>;
+/**
+ * 用户命令文件整体 schema
+ */
+declare const UserCommandsFileSchema: z.ZodObject<{
+  commands: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    command: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * 用户命令文件解析结果
+ */
+type UserCommandsParseResult = {
+  /**
+   * 解析成功标记
+   */
+  ok: true;
+  /**
+   * 命令清单
+   */
+  commands: readonly UserCommandSpec[];
+} | {
+  /**
+   * 解析失败标记
+   */
+  ok: false;
+  /**
+   * 全部问题，逐条人类可读
+   */
+  issues: string[];
+};
+/**
+ * 读目标仓的用户命令文件，缺失视为空清单成功，未配置属常态
+ *
+ * @param repoRoot - 目标仓根绝对路径
+ * @returns 解析结果
+ */
+declare function readUserCommands(repoRoot: string): UserCommandsParseResult;
+//#endregion
+export { type ExecOutcome, type ExecService, type ExecServiceOptions, type ExecSpec, type PrintPluginCommandResultOptions, type QualityTaskInvocation, type RenderColor, type RootScriptForm, type RootScriptProbe, USER_COMMANDS_PATH, type UserCommandSpec, UserCommandSpecSchema, UserCommandsFileSchema, type UserCommandsParseResult, createExecService, printPluginCommandResult, probeRootScript, readUserCommands, renderCheckReportLines, resolveQualityTaskInvocation };

package/dist/index.js

@@ -0,0 +1,4 @@
+import{spawnSync as e}from"node:child_process";import{existsSync as t,readFileSync as n}from"node:fs";import{join as r}from"node:path";import*as i from"zod";function a(e,t){let n=e.length===0?[]:e.split(`
+`);return n.length<=t?e:n.slice(n.length-t).join(`
+`)}function o(t={}){let n=t.defaultTimeoutMs??3e5,r=t.excerptLines??40;return{run(t){let i=Date.now(),o=e(t.command,[...t.args],{cwd:t.cwd,timeout:t.timeoutMs??n,encoding:`utf-8`,env:{...process.env,...t.env},stdio:t.stream===!0?`inherit`:`pipe`}),s=Date.now()-i,c=o.signal===`SIGTERM`,l=typeof o.stdout==`string`?o.stdout:``,u=typeof o.stderr==`string`?o.stderr:``,d=typeof o.status==`number`?o.status:1;return o.error!==void 0&&d===1&&l.length===0&&u.length===0?{code:d,durationMs:s,stdoutExcerpt:``,stderrExcerpt:o.error.message,timedOut:c}:{code:d,durationMs:s,stdoutExcerpt:a(l,r),stderrExcerpt:a(u,r),timedOut:c}}}}function s(e){return typeof e==`object`&&!!e}function c(e,i){let a=r(e,`package.json`);if(!t(a))return{form:`missing`};try{let e=JSON.parse(n(a,`utf-8`));if(!s(e)||!s(e.scripts))return{form:`missing`};let t=e.scripts;if(!(i in t))return{form:`missing`};let r=t[i];return typeof r==`string`?r.includes(`lzi-dev-cli forbid`)?{form:`forbid-sentinel`,command:r}:r.trimStart().startsWith(`echo`)?{form:`echo-guard`,command:r}:{form:`direct`,command:r}:{form:`missing`}}catch{return{form:`missing`}}}function l(e,t){return e.form===`missing`?null:e.form===`direct`?{command:`bun`,args:[`run`,t]}:{command:`bun`,args:[`turbo`,`run`,t]}}function u(e){switch(e){case`pass`:return`✓`;case`fail`:return`✗`;case`warn`:return`⚠`;default:return`–`}}function d(e,t){let n=(e.status===`pass`?t.green:e.status===`fail`?t.red:e.status===`warn`?t.yellow:t.gray)(u(e.status)),r=e.durationMs===void 0?``:` ${t.gray(`${e.durationMs}ms`)}`,i=e.detail===void 0?``:` — ${e.detail}`;return`${n} ${e.label}${r}${i}`}function f(e,t){let n=[];for(let r of e.items)if(n.push(d(r,t)),r.status===`fail`&&r.outputExcerpt!==void 0&&r.outputExcerpt!==``)for(let e of r.outputExcerpt.split(`
+`))n.push(t.gray(`  ${e}`));let{pass:r,fail:i,warn:a,skip:o}=e.totals;return n.push(`${t.bold(`汇总`)} ${t.green(`通过 ${r}`)} ${t.red(`失败 ${i}`)} ${t.yellow(`警告 ${a}`)} ${t.gray(`跳过 ${o}`)}`),n}function p(e,t){if(t.format===`json`){t.write(JSON.stringify(e,null,2));return}let n=e.status===`ok`?t.color.green(e.status):e.status===`warn`?t.color.yellow(e.status):t.color.red(e.status);if(t.write(`${n} ${e.summary}`),e.report!==void 0)for(let n of f(e.report,t.color))t.write(n)}const m=r(`.lzi`,`plugin`,`user-commands.json`),h=i.object({name:i.string().regex(/^[a-z][a-z0-9-]*$/,`命令名必须 kebab-case`),description:i.string().min(1),command:i.string().min(1),args:i.array(i.string()).default([]),timeoutMs:i.number().int().positive().default(3e5)}),g=i.object({commands:i.array(h).min(1,`命令清单至少一条`)});function _(e){let i=r(e,m);if(!t(i))return{ok:!0,commands:[]};let a;try{a=n(i,`utf-8`)}catch(e){return{ok:!1,issues:[`文件不可读：${e instanceof Error?e.message:String(e)}`]}}let o;try{o=JSON.parse(a)}catch(e){return{ok:!1,issues:[`不是合法 JSON：${e instanceof Error?e.message:String(e)}`]}}let s=g.safeParse(o);if(!s.success)return{ok:!1,issues:s.error.issues.map(e=>`${e.path.map(String).join(`.`)||`<root>`}: ${e.message}`)};let c=/* @__PURE__ */ new Set;for(let e of s.data.commands){if(c.has(e.name))return{ok:!1,issues:[`commands.name 重复：${e.name}`]};c.add(e.name)}return{ok:!0,commands:s.data.commands}}export{m as USER_COMMANDS_PATH,h as UserCommandSpecSchema,g as UserCommandsFileSchema,o as createExecService,p as printPluginCommandResult,c as probeRootScript,_ as readUserCommands,f as renderCheckReportLines,l as resolveQualityTaskInvocation};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@longzai-intelligence-plugin/kit",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Longzai Intelligence Plugin 零框架工具包",
+  "keywords": [
+    "kit",
+    "longzai-intelligence",
+    "plugin"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "bun test",
+    "clean": "lzi-dev-cli clean"
+  },
+  "dependencies": {
+    "@longzai-intelligence-plugin/core": "0.0.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {}
+}