@longzai-intelligence-issues/cli 0.0.1 → 0.0.3

package/src/commands/issue.commands.ts

@@ -7,10 +7,19 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import * as z from 'zod';
 
-import { fail, info, loadConfigOrExit, ok, repoRoot, resolveScopeFromCwd } from './context.utils.js';
+import {
+  fail,
+  info,
+  loadConfigOrExit,
+  ok,
+  repoRoot,
+  resolveScopeFromCwd,
+} from './context.utils.js';
 
 /**
  * create / list / show 命令组：建档与查询
+ *
+ * @param program - CLI 程序实例
  */
 export function registerIssueCommands(program: Command): void {
   defineCommand(program, {
@@ -26,38 +35,47 @@ export function registerIssueCommands(program: Command): void {
       { flags: '--dry-run', description: '只呈现不落盘' },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
-    schema: z
-      .object({
-        title: z.string(),
-        slug: z.string().optional(),
-        priority: z.string().optional(),
-        type: z.string().optional(),
-        scope: z.string().optional(),
-        source: z.string().optional(),
-        dryRun: z.boolean().optional(),
-        config: z.string().optional(),
-      })
-      .passthrough(),
+    schema: z.looseObject({
+      title: z.string(),
+      slug: z.string().optional(),
+      priority: z.enum(['P1', 'P2', 'P3']).optional(),
+      type: z.string().optional(),
+      scope: z.string().optional(),
+      source: z.string().optional(),
+      dryRun: z.boolean().optional(),
+      config: z.string().optional(),
+    }),
     action: async (opts) => {
       /**
        * 仓库根与配置
        */
       const root = repoRoot();
+
+      /**
+       * 解析后配置
+       */
       const { config } = await loadConfigOrExit(opts.config);
 
       /**
        * scope key（显式 > cwd 最长前缀 > 全部列出退出）
        */
       const cwdRel = relative(root, process.cwd());
+
+      /**
+       * 生效 scope key（显式 --scope 优先，缺省按 cwd 解析）
+       */
       const scopeKey =
         opts.scope ??
         resolveScopeFromCwd(config, cwdRel) ??
-        fail(`cwd「${cwdRel}」未命中任何 scope 覆盖面——候选：${config.scopes.map((s) => s.key).join('、')}（或显式 --scope）`);
+        fail(
+          `cwd「${cwdRel}」未命中任何 scope 覆盖面——候选：${config.scopes.map((s) => s.key).join('、')}（或显式 --scope）`,
+        );
 
       /**
        * 目标 scope
        */
-      const scope = config.scopes.find((s) => s.key === scopeKey) ?? fail(`scope「${scopeKey}」未登记`);
+      const scope =
+        config.scopes.find((s) => s.key === scopeKey) ?? fail(`scope「${scopeKey}」未登记`);
 
       /**
        * 写入时刻取号（落盘前现算最新值）
@@ -83,9 +101,14 @@ export function registerIssueCommands(program: Command): void {
           .replace(/-+/g, '-')
           .replace(/^-|-$/g, '');
 
+      /**
+       * slug 合法性门禁（纯 ASCII kebab；中文标题派生为空即拒绝并要求显式 --slug）
+       */
       const slug = /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(derivedSlug)
         ? derivedSlug
-        : fail('slug 须为纯 ASCII kebab（小写字母/数字/连字符，禁中文）——中文标题请显式提供 --slug <slug>');
+        : fail(
+            'slug 须为纯 ASCII kebab（小写字母/数字/连字符，禁中文）——中文标题请显式提供 --slug <slug>',
+          );
 
       /**
        * 标准模板落盘（instance 渲染）
@@ -94,7 +117,7 @@ export function registerIssueCommands(program: Command): void {
         number: next.ok ? next.number : '0001',
         slug,
         title: opts.title,
-        priority: (opts.priority === 'P1' || opts.priority === 'P3' ? opts.priority : 'P2') as 'P1' | 'P2' | 'P3',
+        priority: opts.priority ?? 'P2',
         scopeTitle: scope.title,
         date: new Date().toISOString().slice(0, 10),
         source: opts.source ?? 'CLI 建档',
@@ -104,6 +127,10 @@ export function registerIssueCommands(program: Command): void {
        * 文件路径（注册表目录缺席自创建——init 的轻量等价）
        */
       const registryAbs = join(root, scope.registryDir);
+
+      /**
+       * 建档目标文件路径（编号门禁取号 + slug）
+       */
       const filePath = join(registryAbs, `${next.ok ? next.number : '0001'}-${slug}.md`);
 
       if (opts.dryRun === true) {
@@ -126,7 +153,9 @@ export function registerIssueCommands(program: Command): void {
        */
       const check = runNumberingNext({ root, config, scopeKey });
 
-      info(`编号自检：下一可用编号 ${check.ok ? check.number : '—'}（${scope.registryDir} 目录口径）`);
+      info(
+        `编号自检：下一可用编号 ${check.ok ? check.number : '—'}（${scope.registryDir} 目录口径）`,
+      );
 
       /**
        * 编号撞号即让号提示
@@ -141,12 +170,26 @@ export function registerIssueCommands(program: Command): void {
     description: '列出注册表 issue（按 scope 分组）',
     options: [
       { flags: '--scope <scope>', description: '限定 scope' },
-      { flags: '--status <status>', description: '限定状态灯位（red/yellow/green/frozen/canceled）' },
+      {
+        flags: '--status <status>',
+        description: '限定状态灯位（red/yellow/green/frozen/canceled）',
+      },
       { flags: '--config <path>', description: '显式配置路径' },
     ],
-    schema: z.object({ scope: z.string().optional(), status: z.string().optional(), config: z.string().optional() }).passthrough(),
+    schema: z.looseObject({
+      scope: z.string().optional(),
+      status: z.string().optional(),
+      config: z.string().optional(),
+    }),
     action: async (opts) => {
+      /**
+       * 仓库根
+       */
       const root = repoRoot();
+
+      /**
+       * 解析后配置
+       */
       const { config } = await loadConfigOrExit(opts.config);
 
       for (const scope of config.scopes) {
@@ -162,7 +205,8 @@ export function registerIssueCommands(program: Command): void {
         /**
          * 状态过滤
          */
-        const filtered = opts.status === undefined ? records : records.filter((r) => r.status === opts.status);
+        const filtered =
+          opts.status === undefined ? records : records.filter((r) => r.status === opts.status);
 
         process.stdout.write(`# ${scope.key}（${scope.title}）— ${filtered.length} 项\n`);
 
@@ -178,19 +222,21 @@ export function registerIssueCommands(program: Command): void {
     description: '展示单份 issue（ref 支持 编号 / 编号-slug / 不完整前缀；多义列候选）',
     arguments: [{ signature: '<ref>', description: 'issue 引用' }],
     options: [{ flags: '--config <path>', description: '显式配置路径' }],
-    schema: z.object({ ref: z.string() }).passthrough(),
-    action: async (rawOpts) => {
+    schema: z.looseObject({ config: z.string().optional() }),
+    action: async (opts, positionals) => {
       /**
-       * 位置参数（defineCommand 位置参数注入 opts）
+       * ref 取值（defineCommand 位置参数第二通道；<ref> 必填由 commander 拦截，此处窄化兜底）
        */
-      const opts = rawOpts as unknown as { ref?: string; config?: string; _: string[] };
+      const ref = positionals[0] ?? fail('缺少 issue 引用（show <ref>）');
 
       /**
-       * ref 取值（位置参数或 ref 字段）
+       * 仓库根
        */
-      const ref = opts.ref ?? opts._?.[0] ?? fail('缺少 issue 引用（show <ref>）');
-
       const root = repoRoot();
+
+      /**
+       * 解析后配置
+       */
       const { config } = await loadConfigOrExit(opts.config);
 
       /**
@@ -205,12 +251,24 @@ export function registerIssueCommands(program: Command): void {
       /**
        * 全 scope 候选收集
        */
-      const candidates: Array<{ scopeKey: string; file: string; slug: string; title: string; record: ReturnType<typeof scanRegistryDir>[number] }> = [];
+      const candidates: Array<{
+        scopeKey: string;
+        file: string;
+        slug: string;
+        title: string;
+        record: ReturnType<typeof scanRegistryDir>[number];
+      }> = [];
 
       for (const scope of config.scopes) {
         for (const record of scanRegistryDir(join(root, scope.registryDir))) {
           if (record.id === match[1] && (match[2] === undefined || record.slug === match[2])) {
-            candidates.push({ scopeKey: scope.key, file: `${scope.registryDir}/${record.file}`, slug: record.slug, title: record.title, record });
+            candidates.push({
+              scopeKey: scope.key,
+              file: `${scope.registryDir}/${record.file}`,
+              slug: record.slug,
+              title: record.title,
+              record,
+            });
           }
         }
       }
@@ -221,17 +279,23 @@ export function registerIssueCommands(program: Command): void {
          */
         for (const scope of config.scopes) {
           for (const record of scanRegistryDir(join(root, scope.registryDir))) {
-            if (record.id === match[1] && match[2] !== undefined && record.slug.startsWith(match[2])) {
-              candidates.push({ scopeKey: scope.key, file: `${scope.registryDir}/${record.file}`, slug: record.slug, title: record.title, record });
+            if (
+              record.id === match[1] &&
+              match[2] !== undefined &&
+              record.slug.startsWith(match[2])
+            ) {
+              candidates.push({
+                scopeKey: scope.key,
+                file: `${scope.registryDir}/${record.file}`,
+                slug: record.slug,
+                title: record.title,
+                record,
+              });
             }
           }
         }
       }
 
-      if (candidates.length === 0) {
-        fail(`引用「${ref}」无命中`);
-      }
-
       if (candidates.length > 1) {
         process.stderr.write(`错误: 引用「${ref}」命中不唯一——候选：\n`);
         for (const c of candidates) {
@@ -241,9 +305,9 @@ export function registerIssueCommands(program: Command): void {
       }
 
       /**
-       * 唯一命中输出全文
+       * 唯一命中输出全文（多义已列候选退出；零命在此窄化拦截）
        */
-      const hit = candidates[0]!;
+      const hit = candidates[0] ?? fail(`引用「${ref}」无命中`);
 
       info(`命中：${hit.scopeKey} ${hit.file}`);
       process.stdout.write(hit.record.rawContent);

package/src/commands/migrate.commands.ts

@@ -0,0 +1,113 @@
+import type { Command } from '@longzai-intelligence-cli/core';
+
+import { defineCommand } from '@longzai-intelligence-cli/core';
+import { migrateLegacyFile, scanRegistryDir } 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';
+
+/**
+ * 存量清偿命令组：migrate-legacy
+ *
+ * 判据口径：exit 0 过（含 skipped 交人工案，逐条列出）/ exit 1 守卫失败。
+ *
+ * @param program - CLI 程序实例
+ */
+export function registerMigrateCommands(program: Command): void {
+  defineCommand(program, {
+    name: 'migrate-legacy',
+    description: '存量注册表清偿（五方言解析→状态词规范化→处置段对齐→必填回填；零丢失守卫；幂等）',
+    options: [
+      { flags: '--issue <issue>', description: 'issue 文件路径（可重复，与 --dir 互斥）' },
+      { flags: '--dir <dir>', description: '注册表目录批量（与 --issue 互斥）' },
+      { flags: '--default-priority <priority>', description: '优先级缺省回填 P1|P2|P3' },
+      { flags: '--default-source <source>', description: '来源缺省回填文案' },
+      { flags: '--default-filing-date <date>', description: '立案日期缺省回填（YYYY-MM-DD）' },
+      {
+        flags: '--status <status>',
+        description: '无状态行历史文档的显式灯位 red|green（人工定档，引擎承接机械迁移）',
+      },
+      { flags: '--dry-run', description: '只呈现不落盘' },
+      { flags: '--config <path>', description: '显式配置路径' },
+    ],
+    schema: z.looseObject({
+      issue: z.union([z.string(), z.array(z.string())]).optional(),
+      dir: z.string().optional(),
+      defaultPriority: z.enum(['P1', 'P2', 'P3']).optional(),
+      defaultSource: z.string().optional(),
+      defaultFilingDate: z.string().optional(),
+      status: z.enum(['red', 'green']).optional(),
+      dryRun: z.boolean().optional(),
+      config: z.string().optional(),
+    }),
+    action: async (opts) => {
+      /**
+       * 仓库根
+       */
+      const root = repoRoot();
+
+      /**
+       * 解析后配置
+       */
+      const { config } = await loadConfigOrExit(opts.config);
+
+      if (opts.issue !== undefined && opts.dir !== undefined) {
+        fail('--issue 与 --dir 互斥（单文件指定或目录批量二选一）');
+      }
+
+      /**
+       * 目标文件清单（--dir 展开为注册表编号文件）
+       */
+      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 <路径>（可重复）或 --dir <注册表目录>');
+      }
+
+      /**
+       * 形态计数器
+       */
+      const counts = { rewritten: 0, unchanged: 0, skipped: 0, failed: 0 };
+
+      for (const file of files) {
+        /**
+         * 单文件迁移结果
+         */
+        const result = migrateLegacyFile({
+          root,
+          file,
+          config,
+          defaultPriority: opts.defaultPriority,
+          defaultSource: opts.defaultSource,
+          defaultFilingDate: opts.defaultFilingDate,
+          status: opts.status,
+          dryRun: opts.dryRun === true,
+        });
+
+        counts[result.outcome] += 1;
+
+        violation(
+          `${file}: ${result.outcome}（${result.message}；变换 ${result.transformations.length} 项${opts.dryRun === true && result.outcome === 'rewritten' ? '，dry-run 未落盘' : ''}）`,
+        );
+      }
+
+      info(
+        `migrate-legacy 汇总：rewritten ${counts.rewritten}｜unchanged ${counts.unchanged}｜skipped（交人工）${counts.skipped}｜failed ${counts.failed}`,
+      );
+
+      if (counts.failed > 0) {
+        process.exit(1);
+      }
+
+      ok('清偿批次完成（failed=0；skipped 案逐条列出待人工处置）');
+    },
+  });
+}

package/src/commands/scaffold.commands.ts

@@ -1,16 +1,31 @@
 import type { Command } from '@longzai-intelligence-cli/core';
 
 import { defineCommand } from '@longzai-intelligence-cli/core';
-import { appendScopeToConfigText, renderConfigScaffoldFile } from '@longzai-intelligence-issues/config';
-import { TEMPLATE_FIELDS, renderCriteriaBlockExample, renderIssueTemplateSkeleton, renderRegistryReadmeStub } from '@longzai-intelligence-issues/ledger';
+import {
+  appendScopeToConfigText,
+  renderConfigScaffoldFile,
+} from '@longzai-intelligence-issues/config';
+import {
+  renderCriteriaBlockExample,
+  renderIssueTemplateSkeleton,
+  renderRegistryReadmeStub,
+  TEMPLATE_FIELDS,
+} from '@longzai-intelligence-issues/ledger';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import * as z from 'zod';
 
 import { fail, info, loadConfigOrExit, ok, repoRoot } from './context.utils.js';
 
+/**
+ * package.json 最小内省 schema（init 推导 scope key 用——仅认 name 字段）
+ */
+const packageJsonSchema = z.looseObject({ name: z.string().optional() });
+
 /**
  * init / template 命令组：标准格式的「提供 + 初始化」入口
+ *
+ * @param program - CLI 程序实例
  */
 export function registerScaffoldCommands(program: Command): void {
   defineCommand(program, {
@@ -22,14 +37,12 @@ export function registerScaffoldCommands(program: Command): void {
       { flags: '--registry-dir <dir>', description: '注册表目录（缺省 docs/issues）' },
       { flags: '--paths <paths...>', description: '覆盖路径 glob（缺省 .）' },
     ],
-    schema: z
-      .object({
-        key: z.string().optional(),
-        title: z.string().optional(),
-        registryDir: z.string().optional(),
-        paths: z.array(z.string()).optional(),
-      })
-      .passthrough(),
+    schema: z.looseObject({
+      key: z.string().optional(),
+      title: z.string().optional(),
+      registryDir: z.string().optional(),
+      paths: z.array(z.string()).optional(),
+    }),
     action: async (opts) => {
       /**
        * 仓库根
@@ -50,11 +63,15 @@ export function registerScaffoldCommands(program: Command): void {
           ? (() => {
               try {
                 /**
-                 * package.json 名
+                 * package.json 名（zod safeParse 守卫——形态异常兜底 root）
                  */
-                const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { name?: string };
+                const pkg = packageJsonSchema.safeParse(
+                  JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')),
+                );
 
-                return (pkg.name ?? 'root').replace(/^@[^/]+\//, '').replace(/[^a-z0-9-]/g, '-');
+                return ((pkg.success ? pkg.data.name : undefined) ?? 'root')
+                  .replace(/^@[^/]+\//, '')
+                  .replace(/[^a-z0-9-]/g, '-');
               } catch {
                 return 'root';
               }
@@ -76,6 +93,9 @@ export function registerScaffoldCommands(program: Command): void {
          * 追加模式（不动其他节）
          */
         try {
+          /**
+           * 追加 scope 后的配置全文
+           */
           const appended = appendScopeToConfigText(readFileSync(configPath, 'utf8'), scope);
           writeFileSync(configPath, appended);
           info(`已追加 scope「${key}」到 ${configPath}`);
@@ -91,13 +111,31 @@ export function registerScaffoldCommands(program: Command): void {
        * 注册表目录 + README 存根
        */
       const registryAbs = join(root, scope.registryDir);
+
+      /**
+       * README 存根路径（幂等不覆盖）
+       */
       const readmePath = join(registryAbs, 'README.md');
 
+      /**
+       * 指南候选相对路径（按注册表目录深度回溯到仓库根；采用仓不携带指南文件时回退 null）
+       */
+      const guideRepoRel = `${'../'.repeat(scope.registryDir.split('/').length)}docs/guides/issue-file-format.md`;
+
+      /**
+       * 存根指南链接（本仓指南在场才落链接，否则 null 触发机器真源回退）
+       */
+      const guideRelPath = existsSync(join(root, 'docs', 'guides', 'issue-file-format.md'))
+        ? guideRepoRel
+        : null;
+
       mkdirSync(registryAbs, { recursive: true });
 
       if (!existsSync(readmePath)) {
-        writeFileSync(readmePath, renderRegistryReadmeStub(scope.title, '../../docs/guides/issue-file-format.md'));
-        ok(`已创建注册表目录 ${scope.registryDir} 并落格式存根 README.md`);
+        writeFileSync(readmePath, renderRegistryReadmeStub(scope.title, guideRelPath));
+        ok(
+          `已创建注册表目录 ${scope.registryDir} 并落格式存根 README.md${guideRelPath === null ? '（本仓无指南文件，存根指向 lzi-issues template 机器真源）' : ''}`,
+        );
       } else {
         info(`注册表 README 已存在，跳过（幂等不覆盖）`);
       }
@@ -113,7 +151,7 @@ export function registerScaffoldCommands(program: Command): void {
       { flags: '--with-criteria', description: '附 criteria 判据块示例' },
       { flags: '--format <format>', description: 'text | json（json 返回字段契约）' },
     ],
-    schema: z.object({ withCriteria: z.boolean().optional(), format: z.string().optional() }).passthrough(),
+    schema: z.looseObject({ withCriteria: z.boolean().optional(), format: z.string().optional() }),
     action: async (opts) => {
       /**
        * 骨架全文（渲染真源产物）
@@ -121,7 +159,9 @@ export function registerScaffoldCommands(program: Command): void {
       const skeleton = renderIssueTemplateSkeleton();
 
       if (opts.format === 'json') {
-        process.stdout.write(`${JSON.stringify({ template: skeleton, fields: TEMPLATE_FIELDS }, null, 2)}\n`);
+        process.stdout.write(
+          `${JSON.stringify({ template: skeleton, fields: TEMPLATE_FIELDS }, null, 2)}\n`,
+        );
         return;
       }
 

package/src/main.ts

@@ -0,0 +1,19 @@
+/**
+ * 库入口（采用仓单依赖接入面；package.json main / exports "."）
+ *
+ * `lzi-issues init` 生成的 `lzi-issues.config.ts` 从本包导入 defineConfig——
+ * 采用仓只安装 `@longzai-intelligence-issues/cli` 即可加载配置，无需显式安装
+ * config 包（其为本包运行时依赖，由包管理器解析）。bin 入口（dist/index.js，
+ * package.json bin / exports "./bin"）与本入口分路径构建发布，import 本模块
+ * 不会触发 CLI 命令面。
+ */
+
+export {
+  parseLziIssuesConfig,
+  type LintBaselineEntry,
+  type LziIssuesConfig,
+  type LziIssuesConfigInput,
+  type ScopeEntry,
+  type ScopeEntryInput,
+  defineConfig,
+} from '@longzai-intelligence-issues/config';