@longzai-intelligence-issues/cli 0.0.1 → 0.0.2

package/src/commands/close.commands.ts

@@ -7,9 +7,11 @@ import {
   listPrompts,
   normalizeHeaderFile,
   rerunCloseFlow,
+  scanRegistryDir,
   showPrompt,
   unfreezeIssue,
 } from '@longzai-intelligence-issues/ledger';
+import { join } from 'node:path';
 import * as z from 'zod';
 
 import { fail, info, loadConfigOrExit, ok, repoRoot, violation } from './context.utils.js';
@@ -18,8 +20,15 @@ import { fail, info, loadConfigOrExit, ok, repoRoot, violation } from './context
  * 收口与冻结命令组：verify-close / freeze / unfreeze / normalize-header / prompts
  *
  * 判据口径：exit 0 过 / 1 违规 / 2 门禁拦截零执行。
+ *
+ * @param program - CLI 程序实例
  */
-export function registerCloseCommands(program: Command): void {
+/**
+ * issue 收口命令（缺省零执行证据收口；--rerun 证书化真跑）
+ *
+ * @param program - CLI 程序实例
+ */
+function registerVerifyCloseCommand(program: Command): void {
   defineCommand(program, {
     name: 'verify-close',
     description: 'issue 收口（缺省零执行证据收口；--rerun 证书化真跑）',
@@ -28,33 +37,42 @@ export function registerCloseCommands(program: Command): void {
       { flags: '--summary <summary>', description: '收口概要（批量禁用）' },
       { flags: '--dry-run', description: '只呈现不落盘/不执行' },
       { flags: '--rerun', description: '证书化真跑（重度命令，仅人类明令）' },
-      { flags: '--criterion <criterion>', description: '显式判据 label|channel|cwd|command（可重复）' },
+      {
+        flags: '--criterion <criterion>',
+        description: '显式判据 label|channel|cwd|command（可重复）',
+      },
       { flags: '--criteria-from-issue', description: '从各案 criteria 块取判据' },
       { flags: '--confirm-heavy', description: '重度命令确认' },
       { flags: '--allow-full-criterion', description: '全量判据豁免（须留痕）' },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
-    schema: z
-      .object({
-        issue: z.union([z.string(), z.array(z.string())]).optional(),
-        summary: z.string().optional(),
-        dryRun: z.boolean().optional(),
-        rerun: z.boolean().optional(),
-        criterion: z.union([z.string(), z.array(z.string())]).optional(),
-        criteriaFromIssue: z.boolean().optional(),
-        confirmHeavy: z.boolean().optional(),
-        allowFullCriterion: z.boolean().optional(),
-        config: z.string().optional(),
-      })
-      .passthrough(),
+    schema: z.looseObject({
+      issue: z.union([z.string(), z.array(z.string())]).optional(),
+      summary: z.string().optional(),
+      dryRun: z.boolean().optional(),
+      rerun: z.boolean().optional(),
+      criterion: z.union([z.string(), z.array(z.string())]).optional(),
+      criteriaFromIssue: z.boolean().optional(),
+      confirmHeavy: z.boolean().optional(),
+      allowFullCriterion: z.boolean().optional(),
+      config: z.string().optional(),
+    }),
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
+
+      /**
+       * 解析后配置
+       */
       const { config } = await loadConfigOrExit(opts.config);
 
       /**
        * 目标文件归一
        */
-      const files = opts.issue === undefined ? [] : Array.isArray(opts.issue) ? opts.issue : [opts.issue];
+      const files =
+        opts.issue === undefined ? [] : Array.isArray(opts.issue) ? opts.issue : [opts.issue];
 
       if (files.length === 0) {
         fail('缺少 --issue <路径>（可重复指定批量）');
@@ -63,7 +81,12 @@ export function registerCloseCommands(program: Command): void {
       /**
        * 显式判据归一
        */
-      const criteria = opts.criterion === undefined ? [] : Array.isArray(opts.criterion) ? opts.criterion : [opts.criterion];
+      const criteria =
+        opts.criterion === undefined
+          ? []
+          : Array.isArray(opts.criterion)
+            ? opts.criterion
+            : [opts.criterion];
 
       if (opts.rerun === true) {
         /**
@@ -102,10 +125,20 @@ export function registerCloseCommands(program: Command): void {
       /**
        * 缺省证据收口（零执行）
        */
-      if (criteria.length > 0 || opts.criteriaFromIssue === true || opts.confirmHeavy === true || opts.allowFullCriterion === true) {
-        fail('证据收口（缺省模式）不接受 --criterion/--criteria-from-issue/--confirm-heavy/--allow-full-criterion（属 --rerun 真跑旗标）');
+      if (
+        criteria.length > 0 ||
+        opts.criteriaFromIssue === true ||
+        opts.confirmHeavy === true ||
+        opts.allowFullCriterion === true
+      ) {
+        fail(
+          '证据收口（缺省模式）不接受 --criterion/--criteria-from-issue/--confirm-heavy/--allow-full-criterion（属 --rerun 真跑旗标）',
+        );
       }
 
+      /**
+       * 零执行证据收口批次结果
+       */
       const result = evidenceCloseFlow({
         root,
         config,
@@ -125,7 +158,14 @@ export function registerCloseCommands(program: Command): void {
       }
     },
   });
+}
 
+/**
+ * 冻结命令（freeze：--reason 须含「用户裁定」）
+ *
+ * @param program - CLI 程序实例
+ */
+function registerFreezeCommand(program: Command): void {
   defineCommand(program, {
     name: 'freeze',
     description: '冻结 issue（--reason 须含「用户裁定」）',
@@ -134,8 +174,15 @@ export function registerCloseCommands(program: Command): void {
       { flags: '--reason <reason>', description: '裁定理由（须含「用户裁定」）' },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
-    schema: z.object({ issue: z.string().optional(), reason: z.string().optional(), config: z.string().optional() }).passthrough(),
+    schema: z.looseObject({
+      issue: z.string().optional(),
+      reason: z.string().optional(),
+      config: z.string().optional(),
+    }),
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
       await loadConfigOrExit(opts.config);
 
@@ -143,6 +190,9 @@ export function registerCloseCommands(program: Command): void {
         fail('freeze 须 --issue <路径> 与 --reason <裁定理由>');
       }
 
+      /**
+       * 冻结写入结果
+       */
       const result = freezeIssue({ root, file: opts.issue, reason: opts.reason });
 
       if (!result.ok) {
@@ -152,7 +202,14 @@ export function registerCloseCommands(program: Command): void {
       ok(`${opts.issue}: ${result.message}`);
     },
   });
+}
 
+/**
+ * 解冻命令（unfreeze：--note 须含「用户裁定」；恢复 🔴）
+ *
+ * @param program - CLI 程序实例
+ */
+function registerUnfreezeCommand(program: Command): void {
   defineCommand(program, {
     name: 'unfreeze',
     description: '解冻 issue（--note 须含「用户裁定」；恢复 🔴）',
@@ -161,8 +218,15 @@ export function registerCloseCommands(program: Command): void {
       { flags: '--note <note>', description: '解冻注记（须含「用户裁定」）' },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
-    schema: z.object({ issue: z.string().optional(), note: z.string().optional(), config: z.string().optional() }).passthrough(),
+    schema: z.looseObject({
+      issue: z.string().optional(),
+      note: z.string().optional(),
+      config: z.string().optional(),
+    }),
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
       await loadConfigOrExit(opts.config);
 
@@ -170,6 +234,9 @@ export function registerCloseCommands(program: Command): void {
         fail('unfreeze 须 --issue <路径> 与 --note <解冻注记>');
       }
 
+      /**
+       * 解冻写入结果
+       */
       const result = unfreezeIssue({ root, file: opts.issue, note: opts.note });
 
       if (!result.ok) {
@@ -179,26 +246,60 @@ export function registerCloseCommands(program: Command): void {
       ok(`${opts.issue}: ${result.message}`);
     },
   });
+}
 
+/**
+ * 方言头部迁移命令（normalize-header：字段规范序 / 零丢失守卫 / 幂等）
+ *
+ * @param program - CLI 程序实例
+ */
+function registerNormalizeHeaderCommand(program: Command): void {
   defineCommand(program, {
     name: 'normalize-header',
     description: '方言头部迁移（字段规范序 / 零丢失守卫 / 幂等）',
     options: [
-      { flags: '--issue <issue>', description: 'issue 文件路径（可重复）' },
+      { flags: '--issue <issue>', description: 'issue 文件路径（可重复，与 --dir 互斥）' },
+      {
+        flags: '--dir <dir>',
+        description: '注册表目录批量（目录内全部编号文件，与 --issue 互斥）',
+      },
+      {
+        flags: '--status <status>',
+        description: '无可识别状态行时的显式灯位 red|yellow|green|canceled（frozen 须经 freeze）',
+      },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
-    schema: z.object({ issue: z.union([z.string(), z.array(z.string())]).optional(), config: z.string().optional() }).passthrough(),
+    schema: z.looseObject({
+      issue: z.union([z.string(), z.array(z.string())]).optional(),
+      dir: z.string().optional(),
+      status: z.enum(['red', 'yellow', 'green', 'canceled']).optional(),
+      config: z.string().optional(),
+    }),
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
       await loadConfigOrExit(opts.config);
 
+      if (opts.issue !== undefined && opts.dir !== undefined) {
+        fail('--issue 与 --dir 互斥（单文件指定或目录批量二选一）');
+      }
+
       /**
-       * 目标文件归一
+       * 目标文件清单（--dir 展开为注册表编号文件）
        */
-      const files = opts.issue === undefined ? [] : Array.isArray(opts.issue) ? opts.issue : [opts.issue];
+      const files =
+        opts.dir !== undefined
+          ? scanRegistryDir(join(root, opts.dir)).map((record) => `${opts.dir}/${record.file}`)
+          : opts.issue === undefined
+            ? []
+            : Array.isArray(opts.issue)
+              ? opts.issue
+              : [opts.issue];
 
       if (files.length === 0) {
-        fail('缺少 --issue <路径>（可重复）');
+        fail('缺少 --issue <路径>（可重复）或 --dir <注册表目录>');
       }
 
       /**
@@ -207,7 +308,10 @@ export function registerCloseCommands(program: Command): void {
       let failed = 0;
 
       for (const file of files) {
-        const result = normalizeHeaderFile({ root, file });
+        /**
+         * 单文件头部迁移结果
+         */
+        const result = normalizeHeaderFile({ root, file, status: opts.status });
         violation(`${file}: ${result.outcome}（${result.message}）`);
         failed += result.outcome === 'failed' ? 1 : 0;
       }
@@ -217,7 +321,14 @@ export function registerCloseCommands(program: Command): void {
       }
     },
   });
+}
 
+/**
+ * 推荐提示词命令（prompts：list / show <id>）
+ *
+ * @param program - CLI 程序实例
+ */
+function registerPromptsCommand(program: Command): void {
   defineCommand(program, {
     name: 'prompts',
     description: '推荐提示词（list / show <id>）',
@@ -226,8 +337,11 @@ export function registerCloseCommands(program: Command): void {
       { flags: '--id <id>', description: '提示词 id（show 用）' },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
-    schema: z.object({ action: z.string().optional(), id: z.string().optional(), config: z.string().optional() }).passthrough(),
-    action: async (opts) => {
+    schema: z.looseObject({ id: z.string().optional(), config: z.string().optional() }),
+    action: async (opts, positionals) => {
+      /**
+       * 解析后配置
+       */
       const { config } = await loadConfigOrExit(opts.config);
 
       /**
@@ -235,15 +349,29 @@ export function registerCloseCommands(program: Command): void {
        */
       const options = {
         builtin: config.prompts.builtin,
-        extraDir: config.prompts.extraDir === undefined ? undefined : `${repoRoot()}/${config.prompts.extraDir}`,
+        extraDir:
+          config.prompts.extraDir === undefined
+            ? undefined
+            : `${repoRoot()}/${config.prompts.extraDir}`,
       };
 
-      const action = opts.action ?? 'list';
+      /**
+       * 子动作（defineCommand 位置参数第二通道；缺省 list）
+       */
+      const action = positionals[0] ?? 'list';
 
       if (action === 'show') {
+        /**
+         * 目标提示词 id
+         */
         const id = opts.id ?? fail('show 须 --id <提示词 id>');
 
-        const entry = showPrompt(id, options) ?? fail(`提示词「${id}」未命中（lzi-issues prompts list 查看全部）`);
+        /**
+         * 命中的提示词条目
+         */
+        const entry =
+          showPrompt(id, options) ??
+          fail(`提示词「${id}」未命中（lzi-issues prompts list 查看全部）`);
 
         process.stdout.write(`${entry.content}\n`);
         return;
@@ -255,3 +383,18 @@ export function registerCloseCommands(program: Command): void {
     },
   });
 }
+
+/**
+ * 收口与冻结命令组：verify-close / freeze / unfreeze / normalize-header / prompts
+ *
+ * 判据口径：exit 0 过 / 1 违规 / 2 门禁拦截零执行。
+ *
+ * @param program - CLI 程序实例
+ */
+export function registerCloseCommands(program: Command): void {
+  registerVerifyCloseCommand(program);
+  registerFreezeCommand(program);
+  registerUnfreezeCommand(program);
+  registerNormalizeHeaderCommand(program);
+  registerPromptsCommand(program);
+}

package/src/commands/context.utils.ts

@@ -5,12 +5,17 @@
  * 信息走 stdout（[INFO]/[SUCCESS] 前缀）；exit 2 = 门禁拦截零执行。
  */
 
-import { loadLziIssuesConfig, type LoadLziIssuesConfigResult, type LziIssuesConfig } from '@longzai-intelligence-issues/config';
-
+import {
+  loadLziIssuesConfig,
+  type LoadLziIssuesConfigResult,
+  type LziIssuesConfig,
+} from '@longzai-intelligence-issues/config';
 import { resolve } from 'node:path';
 
 /**
  * 仓库根绝对路径（cwd 锚定；配置查找亦自 cwd 向上）
+ *
+ * @returns 仓库根绝对路径
  */
 export function repoRoot(): string {
   return resolve(process.cwd());
@@ -22,7 +27,9 @@ export function repoRoot(): string {
  * @param configPath - 显式配置路径（--config）
  * @returns 解析后配置与命中路径
  */
-export async function loadConfigOrExit(configPath?: string): Promise<{ config: LziIssuesConfig; configFilePath: string }> {
+export async function loadConfigOrExit(
+  configPath?: string,
+): Promise<{ config: LziIssuesConfig; configFilePath: string }> {
   /**
    * 加载结果
    */
@@ -88,6 +95,9 @@ export function resolveScopeFromCwd(config: LziIssuesConfig, cwdRel: string): st
    */
   let bestKey: string | null = null;
 
+  /**
+   * 当前最长命中 path 的长度（'.' 全仓命中按 -1 起步，任意具体 path 更长）
+   */
   let bestLen = -1;
 
   for (const scope of config.scopes) {