@longzai-intelligence-issues/ledger 0.0.1

package/src/vault/vault.commands.ts

@@ -0,0 +1,434 @@
+/**
+ * 证书库（verify vault）
+ *
+ * 判据指纹 = sha256(git 可见树 + 命令身份)——git 仓取 `git ls-files` 可见面，
+ * 非 git 仓回退目录全树；证书按 <channel>/<指纹>.json 落 .lzi/issues/vault/
+ * certificates/，同指纹复用秒回；run.lock 防并行互踩（D3：FIFO 队列留增强）。
+ */
+
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { walkFilesUnderRoots } from '@/fs/walk-surface.utils';
+
+/**
+ * 判据（verify-close --criterion 四段）
+ */
+export type Criterion = {
+  /**
+   * 判据标签
+   */
+  label: string;
+
+  /**
+   * 判据通道（证书库的通道维度）
+   */
+  channel: string;
+
+  /**
+   * 判据工作目录（相对仓库根）
+   */
+  cwd: string;
+
+  /**
+   * 判据命令（退出码即判据）
+   */
+  command: string;
+};
+
+/**
+ * 判据证书
+ */
+export type CriterionCertificate = {
+  /**
+   * 内容寻址指纹（64 位 hex）
+   */
+  fingerprint: string;
+
+  /**
+   * 通道
+   */
+  channel: string;
+
+  /**
+   * 判据命令
+   */
+  command: string;
+
+  /**
+   * 工作目录
+   */
+  cwd: string;
+
+  /**
+   * 退出码
+   */
+  exitCode: number;
+
+  /**
+   * 输出摘要（首尾各若干行）
+   */
+  outputSummary: string[];
+
+  /**
+   * 执行时刻（ISO）
+   */
+  executedAt: string;
+};
+
+/**
+ * 判据执行入参
+ */
+export type RunCriterionInput = {
+  /**
+   * 仓库根绝对路径
+   */
+  root: string;
+
+  /**
+   * 判据
+   */
+  criterion: Criterion;
+
+  /**
+   * 预计算指纹（缺省现算）
+   */
+  fingerprint?: string;
+};
+
+/**
+ * 判据执行结果
+ */
+export type CriterionRunResult = {
+  /**
+   * 是否全绿（退出码 0）
+   */
+  green: boolean;
+
+  /**
+   * 真实执行 / 复用标记
+   */
+  reused: boolean;
+
+  /**
+   * 证书（执行失败时也落证书）
+   */
+  certificate: CriterionCertificate;
+};
+
+/**
+ * 输出摘要行数上限（首尾各取）
+ */
+const OUTPUT_SUMMARY_LINES = 8;
+
+/**
+ * 计算 git 可见树文本（非 git 仓回退全树）
+ *
+ * @param root - 仓库根绝对路径
+ * @returns 可见面清单文本（排序、换行连接）
+ */
+function readVisibleTree(root: string): string {
+  try {
+    /**
+     * git 可见面（cached + untracked，-z 分隔）
+     */
+    const output = execFileSync(
+      'git',
+      ['ls-files', '--cached', '--others', '--exclude-standard', '-z'],
+      { cwd: root, maxBuffer: 64 * 1024 * 1024 },
+    ).toString('utf8');
+
+    return output
+      .split('\0')
+      .filter((entry) => entry !== '')
+      .sort()
+      .join('\n');
+  } catch {
+    /**
+     * 非 git 仓回退：目录全树（排除 .git）
+     */
+    return walkFilesUnderRoots(root).join('\n');
+  }
+}
+
+/**
+ * 计算判据指纹
+ *
+ * @param root - 仓库根绝对路径
+ * @param criterion - 判据
+ * @returns 64 位 hex 指纹
+ */
+export function computeCriterionFingerprint(root: string, criterion: Criterion): string {
+  /**
+   * 可见树文本
+   */
+  const tree = readVisibleTree(root);
+
+  return createHash('sha256').update(`${tree}\nidentity:${criterion.command}`).digest('hex');
+}
+
+/**
+ * 证书路径
+ *
+ * @param root - 仓库根绝对路径
+ * @param channel - 通道
+ * @param fingerprint - 指纹
+ * @returns 证书文件绝对路径
+ */
+export function certificatePath(root: string, channel: string, fingerprint: string): string {
+  return join(root, '.lzi', 'issues', 'vault', 'certificates', channel, `${fingerprint}.json`);
+}
+
+/**
+ * 查找在册证书（只读）
+ *
+ * @param root - 仓库根绝对路径
+ * @param channel - 通道
+ * @param fingerprint - 指纹
+ * @returns 证书；缺席为 null
+ */
+export function findCertificate(
+  root: string,
+  channel: string,
+  fingerprint: string,
+): CriterionCertificate | null {
+  /**
+   * 证书路径
+   */
+  const path = certificatePath(root, channel, fingerprint);
+
+  if (!existsSync(path)) {
+    return null;
+  }
+
+  try {
+    /**
+     * 解析值
+     */
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+
+    return isCriterionCertificate(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 证书类型守卫（结构性校验：四关键字段形态）
+ *
+ * @param value - 待判定值
+ * @returns 是否证书对象
+ */
+function isCriterionCertificate(value: unknown): value is CriterionCertificate {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  /**
+   * 指纹字段
+   */
+  const fingerprint = Reflect.get(value, 'fingerprint');
+
+  /**
+   * 退出码字段
+   */
+  const exitCode = Reflect.get(value, 'exitCode');
+
+  return typeof fingerprint === 'string' && typeof exitCode === 'number';
+}
+
+/**
+ * 截取输出摘要（首尾各 N 行）
+ *
+ * @param output - 命令完整输出
+ * @returns 摘要行列表
+ */
+function summarizeOutput(output: string): string[] {
+  /**
+   * 输出行列表
+   */
+  const lines = output.split(/\r?\n/).filter((line) => line !== '');
+
+  if (lines.length <= OUTPUT_SUMMARY_LINES * 2) {
+    return lines;
+  }
+
+  return [
+    ...lines.slice(0, OUTPUT_SUMMARY_LINES),
+    `……（共 ${lines.length} 行）`,
+    ...lines.slice(-OUTPUT_SUMMARY_LINES),
+  ];
+}
+
+/**
+ * 执行判据并落证书（同指纹在册直接复用秒回）
+ *
+ * @param input - 执行入参
+ * @param input.root - 仓库根绝对路径
+ * @param input.criterion - 判据
+ * @param input.fingerprint - 预计算指纹（缺省现算）
+ * @returns 执行结果
+ */
+export function runCriterionViaVault(input: RunCriterionInput): CriterionRunResult {
+  /**
+   * 判据指纹
+   */
+  const fingerprint = input.fingerprint ?? computeCriterionFingerprint(input.root, input.criterion);
+
+  /**
+   * 在册证书（复用秒回）
+   */
+  const existing = findCertificate(input.root, input.criterion.channel, fingerprint);
+
+  if (existing !== null && existing.exitCode === 0) {
+    return { green: true, reused: true, certificate: existing };
+  }
+
+  /**
+   * 执行时刻
+   */
+  const executedAt = new Date().toISOString();
+
+  try {
+    /**
+     * 判据执行输出（/bin/sh -c，cwd 锚仓库根；stdio pipe 采集）
+     */
+    const output = execFileSync('/bin/sh', ['-c', input.criterion.command], {
+      cwd: join(input.root, input.criterion.cwd),
+      maxBuffer: 16 * 1024 * 1024,
+    }).toString('utf8');
+
+    /**
+     * 绿证书
+     */
+    const certificate: CriterionCertificate = {
+      fingerprint,
+      channel: input.criterion.channel,
+      command: input.criterion.command,
+      cwd: input.criterion.cwd,
+      exitCode: 0,
+      outputSummary: summarizeOutput(output),
+      executedAt,
+    };
+
+    writeCertificate(input.root, certificate);
+
+    return { green: true, reused: false, certificate };
+  } catch (error) {
+    /**
+     * 非零退出异常对象（Reflect.get 无断言提取）
+     */
+    const runError = typeof error === 'object' && error !== null ? error : {};
+
+    /**
+     * 退出码
+     */
+    const status = Reflect.get(runError, 'status');
+
+    /**
+     * 标准输出
+     */
+    const stdout = Reflect.get(runError, 'stdout');
+
+    /**
+     * 标准错误
+     */
+    const stderr = Reflect.get(runError, 'stderr');
+
+    /**
+     * 红证书（失败也落档）
+     */
+    const certificate: CriterionCertificate = {
+      fingerprint,
+      channel: input.criterion.channel,
+      command: input.criterion.command,
+      cwd: input.criterion.cwd,
+      exitCode: typeof status === 'number' ? status : 127,
+      outputSummary: summarizeOutput(
+        `${typeof stdout === 'string' ? stdout : ''}\n${typeof stderr === 'string' ? stderr : ''}`.trim(),
+      ),
+      executedAt,
+    };
+
+    writeCertificate(input.root, certificate);
+
+    return { green: false, reused: false, certificate };
+  }
+}
+
+/**
+ * 落证书（temp+rename 原子写）
+ *
+ * @param root - 仓库根绝对路径
+ * @param certificate - 证书
+ */
+function writeCertificate(root: string, certificate: CriterionCertificate): void {
+  /**
+   * 证书路径
+   */
+  const path = certificatePath(root, certificate.channel, certificate.fingerprint);
+
+  mkdirSync(dirname(path), { recursive: true });
+
+  /**
+   * 临时路径
+   */
+  const tempPath = `${path}.tmp`;
+
+  writeFileSync(tempPath, `${JSON.stringify(certificate, null, 2)}\n`);
+
+  renameSync(tempPath, path);
+}
+
+/**
+ * 运行锁句柄
+ */
+export type RunLockHandle = {
+  /**
+   * 释放锁（仅释放本进程写入的锁）
+   */
+  unlock: () => void;
+};
+
+/**
+ * 运行锁（防并行真跑互踩；进程退出自动释放）
+ *
+ * @param root - 仓库根绝对路径
+ * @returns 锁句柄（unlock 释放；持锁失败抛错）
+ * @throws {@link Error} 已有并行真跑持锁
+ */
+export function acquireRunLock(root: string): RunLockHandle {
+  /**
+   * 锁文件路径
+   */
+  const lockPath = join(root, '.lzi', 'issues', 'vault', 'run.lock');
+
+  mkdirSync(dirname(lockPath), { recursive: true });
+
+  if (existsSync(lockPath)) {
+    throw new Error(
+      `已有并行真跑持锁（${lockPath}）——完成后自动释放；如为残留死锁请人工确认后删除`,
+    );
+  }
+
+  writeFileSync(lockPath, `${process.pid}\n`);
+
+  return {
+    unlock: () => {
+      try {
+        /**
+         * 锁内 PID（仅释放本进程写入的锁）
+         */
+        const holder = readFileSync(lockPath, 'utf8').trim();
+
+        if (holder === String(process.pid)) {
+          rmSync(lockPath, { force: true });
+        }
+      } catch {
+        return;
+      }
+    },
+  };
+}