@fitlab-ai/agent-infra 0.8.5 → 0.9.0

package/lib/task/resolve-ref.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { execFileSync, spawnSync } from 'node:child_process';
-import { normalizeShortIdInput } from './short-id.ts';
+import { execFileSync } from 'node:child_process';
+import { normalizeShortIdInput, resolveShortIdReadOnly } from './short-id.ts';
+import { parseTaskFrontmatter } from './frontmatter.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 // Flat-structured workspace dirs that hold tasks under `{dir}/{taskId}/task.md`.
@@ -15,8 +16,37 @@ type ResolveRefResult =
       taskId: string;
       taskDir: string;
       taskMdPath: string;
+      state: TaskWorkspaceState;
     }
-  | { ok: false; message: string };
+  | {
+      ok: false;
+      code: ResolveTaskRefErrorCode;
+      message: string;
+      repoRoot: string | null;
+      taskId: string | null;
+    };
+
+type TaskWorkspaceState = 'active' | 'blocked' | 'completed' | 'archive';
+
+type ResolveTaskRefErrorCode =
+  | 'REPO_ROOT_NOT_FOUND'
+  | 'INVALID_TASK_REF'
+  | 'SHORT_ID_RESERVED'
+  | 'SHORT_ID_CAPACITY_EXCEEDED'
+  | 'SHORT_ID_REGISTRY_NOT_FOUND'
+  | 'SHORT_ID_REGISTRY_READ_FAILED'
+  | 'SHORT_ID_REGISTRY_INVALID_JSON'
+  | 'SHORT_ID_REGISTRY_INVALID_SCHEMA'
+  | 'SHORT_ID_REGISTRY_DUPLICATE_TASK'
+  | 'SHORT_ID_NOT_FOUND'
+  | 'SHORT_ID_STALE'
+  | 'TASK_NOT_FOUND'
+  | 'TASK_CONTEXT_DETACHED_HEAD'
+  | 'TASK_CONTEXT_NOT_FOUND'
+  | 'TASK_CONTEXT_AMBIGUOUS'
+  | 'TASK_CONTEXT_UNREADABLE';
+
+type ResolveTaskRefOptions = { repoRoot?: string };
 
 function detectRepoRoot(): string {
   try {
@@ -40,21 +70,6 @@ function readShortIdLength(repoRoot: string): number {
   return 2;
 }
 
-function resolveShortIdToTaskId(arg: string, repoRoot: string): string {
-  const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
-  if (!fs.existsSync(scriptPath)) {
-    throw new Error(`task-short-id.js not found at ${scriptPath}`);
-  }
-  const result = spawnSync('node', [scriptPath, 'resolve', arg], {
-    encoding: 'utf8',
-    cwd: repoRoot
-  });
-  if (result.status !== 0) {
-    throw new Error((result.stderr || '').trim() || `failed to resolve '${arg}'`);
-  }
-  return result.stdout.trim();
-}
-
 function listSortedNumeric(dir: string, width: number): string[] {
   if (!fs.existsSync(dir)) return [];
   const pattern = new RegExp(`^\\d{${width}}$`);
@@ -84,12 +99,16 @@ function findInArchive(repoRoot: string, taskId: string): string | null {
   return null;
 }
 
-function findTaskMd(repoRoot: string, taskId: string): string | null {
+function findTaskMd(
+  repoRoot: string,
+  taskId: string
+): { taskMdPath: string; state: TaskWorkspaceState } | null {
   for (const sub of FLAT_WORKSPACE_DIRS) {
     const candidate = path.join(repoRoot, '.agents', 'workspace', sub, taskId, 'task.md');
-    if (fs.existsSync(candidate)) return candidate;
+    if (fs.existsSync(candidate)) return { taskMdPath: candidate, state: sub };
   }
-  return findInArchive(repoRoot, taskId);
+  const archived = findInArchive(repoRoot, taskId);
+  return archived ? { taskMdPath: archived, state: 'archive' } : null;
 }
 
 /**
@@ -113,16 +132,38 @@ function enumerateTaskDirs(repoRoot: string): { taskId: string; taskDir: string
   return out;
 }
 
+function locateHotTaskDirs(
+  repoRoot: string,
+  taskId: string
+): { taskId: string; taskDir: string; taskMdPath: string; state: Exclude<TaskWorkspaceState, 'archive'> }[] {
+  return FLAT_WORKSPACE_DIRS.flatMap((state) => {
+    const taskDir = path.join(repoRoot, '.agents', 'workspace', state, taskId);
+    const taskMdPath = path.join(taskDir, 'task.md');
+    return fs.existsSync(taskMdPath) ? [{ taskId, taskDir, taskMdPath, state }] : [];
+  });
+}
+
 /**
- * Resolve a task ref (bare short id, `#N`, or `TASK-YYYYMMDD-HHMMSS`) to its
+ * Resolve a task ref (bare short id or `TASK-YYYYMMDD-HHMMSS`) to its
  * task directory across active / blocked / completed / archive.
  *
  * The returned `message` on failure is command-agnostic (no `ai task <cmd>:`
  * prefix); callers prepend their own prefix so each command keeps its existing
  * stderr wording byte-for-byte.
  */
-function resolveTaskRef(arg: string): ResolveRefResult {
-  const repoRoot = detectRepoRoot();
+function resolveTaskRef(arg: string, options: ResolveTaskRefOptions = {}): ResolveRefResult {
+  let repoRoot: string;
+  try {
+    repoRoot = options.repoRoot ? path.resolve(options.repoRoot) : detectRepoRoot();
+  } catch (error) {
+    return {
+      ok: false,
+      code: 'REPO_ROOT_NOT_FOUND',
+      message: error instanceof Error ? error.message : String(error),
+      repoRoot: null,
+      taskId: null
+    };
+  }
   let taskId: string;
   if (TASK_ID_RE.test(arg)) {
     taskId = arg;
@@ -130,31 +171,151 @@ function resolveTaskRef(arg: string): ResolveRefResult {
     const shortIdLength = readShortIdLength(repoRoot);
     const normalized = normalizeShortIdInput(arg, { shortIdLength });
     if (normalized.kind === 'error') {
-      return { ok: false, message: normalized.message };
+      return {
+        ok: false,
+        code: normalized.code,
+        message: normalized.message,
+        repoRoot,
+        taskId: null
+      };
     }
     if (normalized.kind === 'pass') {
       return {
         ok: false,
+        code: 'INVALID_TASK_REF',
         message:
           `'${arg}' is not a valid short id or TASK-id; ` +
-          `expected bare digits, '#N', or 'TASK-YYYYMMDD-HHMMSS'`
+          `expected bare digits or 'TASK-YYYYMMDD-HHMMSS'`,
+        repoRoot,
+        taskId: null
       };
     }
-    try {
-      taskId = resolveShortIdToTaskId(normalized.value, repoRoot);
-    } catch (e) {
-      return { ok: false, message: (e as Error).message };
+    const shortResult = resolveShortIdReadOnly(normalized.value, repoRoot, { shortIdLength });
+    if (!shortResult.ok) {
+      return {
+        ok: false,
+        code: shortResult.code,
+        message: shortResult.message,
+        repoRoot,
+        taskId: shortResult.taskId
+      };
+    }
+    taskId = shortResult.taskId;
+  }
+  const located = findTaskMd(repoRoot, taskId);
+  if (!located) {
+    return {
+      ok: false,
+      code: 'TASK_NOT_FOUND',
+      message: `task ${taskId} not found in active / blocked / completed / archive`,
+      repoRoot,
+      taskId
+    };
+  }
+  return {
+    ok: true,
+    repoRoot,
+    taskId,
+    taskDir: path.dirname(located.taskMdPath),
+    taskMdPath: located.taskMdPath,
+    state: located.state
+  };
+}
+
+function resolveTaskContext(
+  taskRef?: string,
+  options: ResolveTaskRefOptions = {}
+): ResolveRefResult {
+  if (taskRef !== undefined) return resolveTaskRef(taskRef, options);
+
+  let repoRoot: string;
+  try {
+    repoRoot = options.repoRoot ? path.resolve(options.repoRoot) : detectRepoRoot();
+  } catch (error) {
+    return {
+      ok: false,
+      code: 'REPO_ROOT_NOT_FOUND',
+      message: error instanceof Error ? error.message : String(error),
+      repoRoot: null,
+      taskId: null
+    };
+  }
+
+  let branch: string;
+  try {
+    branch = execFileSync('git', ['symbolic-ref', '--quiet', '--short', 'HEAD'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    return {
+      ok: false,
+      code: 'TASK_CONTEXT_DETACHED_HEAD',
+      message: 'cannot infer the current task from detached HEAD',
+      repoRoot,
+      taskId: null
+    };
+  }
+
+  const activeDir = path.join(repoRoot, '.agents', 'workspace', 'active');
+  const matches: { taskId: string; taskDir: string; taskMdPath: string }[] = [];
+  if (fs.existsSync(activeDir)) {
+    for (const entry of fs.readdirSync(activeDir).sort()) {
+      if (!TASK_ID_RE.test(entry)) continue;
+      const taskDir = path.join(activeDir, entry);
+      const taskMdPath = path.join(taskDir, 'task.md');
+      if (!fs.existsSync(taskMdPath)) continue;
+      try {
+        const frontmatter = parseTaskFrontmatter(fs.readFileSync(taskMdPath, 'utf8'));
+        if (!frontmatter.id || !frontmatter.branch) {
+          return {
+            ok: false,
+            code: 'TASK_CONTEXT_UNREADABLE',
+            message: `cannot prove current task context because ${entry}/task.md has invalid frontmatter`,
+            repoRoot,
+            taskId: null
+          };
+        }
+        if (frontmatter.branch === branch) matches.push({ taskId: entry, taskDir, taskMdPath });
+      } catch (error) {
+        return {
+          ok: false,
+          code: 'TASK_CONTEXT_UNREADABLE',
+          message: `cannot read active task candidate ${entry}: ${error instanceof Error ? error.message : String(error)}`,
+          repoRoot,
+          taskId: null
+        };
+      }
     }
   }
-  const taskMdPath = findTaskMd(repoRoot, taskId);
-  if (!taskMdPath) {
+
+  if (matches.length === 0) {
+    return {
+      ok: false,
+      code: 'TASK_CONTEXT_NOT_FOUND',
+      message: `no active task matches current branch '${branch}'; use --task <ref>`,
+      repoRoot,
+      taskId: null
+    };
+  }
+  if (matches.length > 1) {
     return {
       ok: false,
-      message: `task ${taskId} not found in active / blocked / completed / archive`
+      code: 'TASK_CONTEXT_AMBIGUOUS',
+      message: `multiple active tasks match current branch '${branch}'; use --task <ref>`,
+      repoRoot,
+      taskId: null
     };
   }
-  return { ok: true, repoRoot, taskId, taskDir: path.dirname(taskMdPath), taskMdPath };
+  const match = matches[0]!;
+  return { ok: true, repoRoot, ...match, state: 'active' };
 }
 
-export { resolveTaskRef, detectRepoRoot, enumerateTaskDirs, TASK_ID_RE };
-export type { ResolveRefResult };
+export { resolveTaskRef, resolveTaskContext, detectRepoRoot, enumerateTaskDirs, locateHotTaskDirs, TASK_ID_RE };
+export type {
+  ResolveRefResult,
+  ResolveTaskRefErrorCode,
+  ResolveTaskRefOptions,
+  TaskWorkspaceState
+};

package/{templates/.agents/scripts/lib/review-artifacts.js → lib/task/review-artifacts.ts}

@@ -1,16 +1,15 @@
 // Shared helpers for review-artifact parsing.
-// Imported by both .agents/skills/code-task/scripts/detect-mode.js and
-// .agents/scripts/validate-artifact.js so the round/verdict vocabulary stays
+// Imported by typed artifact lifecycle and verification so the round/verdict vocabulary stays
 // in a single source of truth (prevents the cross-file drift this lifecycle
 // is designed to eliminate).
 import fs from "node:fs";
 import path from "node:path";
 
-export function escapeRegExp(value) {
+export function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-export function maxRound(entries, stem) {
+export function maxRound(entries: string[], stem: string): number {
   let max = 0;
   for (const entry of entries) {
     if (entry === `${stem}.md`) {
@@ -26,11 +25,11 @@ export function maxRound(entries, stem) {
   return max;
 }
 
-export function artifactName(stem, round) {
+export function artifactName(stem: string, round: number): string {
   return round === 1 ? `${stem}.md` : `${stem}-r${round}.md`;
 }
 
-export function normalizeVerdict(raw) {
+export function normalizeVerdict(raw: unknown): "Approved" | "Changes Requested" | "Rejected" | "" {
   const value = String(raw).trim().toLowerCase();
   if (value === "通过" || value === "approved") {
     return "Approved";
@@ -44,12 +43,12 @@ export function normalizeVerdict(raw) {
   return "";
 }
 
-export function extractSection(content, names) {
+export function extractSection(content: string, names: string[]): string {
   const lines = content.split(/\r?\n/);
   const nameSet = new Set(names);
   const start = lines.findIndex((line) => {
     const match = line.trim().match(/^##\s+(.+?)\s*$/);
-    return match ? nameSet.has(match[1]) : false;
+    return match ? nameSet.has(match[1]!) : false;
   });
 
   if (start === -1) {
@@ -58,7 +57,7 @@ export function extractSection(content, names) {
 
   const sectionLines = [];
   for (let index = start + 1; index < lines.length; index += 1) {
-    if (/^##\s+/.test(lines[index])) {
+    if (/^##\s+/.test(lines[index]!)) {
       break;
     }
     sectionLines.push(lines[index]);
@@ -69,7 +68,7 @@ export function extractSection(content, names) {
 // Parse the canonical verdict out of a review-* artifact.
 // Returns { ok, verdict, message }. Verdict collapses Approved into
 // "Approved-with-issues" when the findings counts are non-zero.
-export function parseVerdict(reviewPath) {
+export function parseVerdict(reviewPath: string) {
   if (!fs.existsSync(reviewPath)) {
     return { ok: false, verdict: null, message: `Review artifact not found: ${path.basename(reviewPath)}` };
   }
@@ -91,7 +90,7 @@ export function parseVerdict(reviewPath) {
     return {
       ok: false,
       verdict: null,
-      message: `unrecognized verdict '${verdictMatch[1].trim()}' in ${fileName}`
+      message: `unrecognized verdict '${verdictMatch[1]!.trim()}' in ${fileName}`
     };
   }
 
@@ -104,7 +103,7 @@ export function parseVerdict(reviewPath) {
     return { ok: false, verdict, message: `cannot parse findings count in ${fileName}` };
   }
 
-  const counts = findingsMatch[1].match(/(\d+)\s*(?:阻塞项|blockers?).*?(\d+)\s*(?:主要|majors?).*?(\d+)\s*(?:次要|minors?)/i);
+  const counts = findingsMatch[1]!.match(/(\d+)\s*(?:阻塞项|blockers?).*?(\d+)\s*(?:主要|majors?).*?(\d+)\s*(?:次要|minors?)/i);
   if (!counts) {
     return { ok: false, verdict, message: `cannot parse findings count in ${fileName}` };
   }

package/{templates/.agents/scripts/lib/post-review-commit.js → lib/task/review-fingerprint.ts}

@@ -1,18 +1,23 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { artifactName, maxRound } from "./review-artifacts.js";
+import { artifactName, maxRound } from "./review-artifacts.ts";
 
 // Paths excluded from the post-review coverage gate. Fail-closed: the gate
 // covers ALL tracked changes by default. This default denylist is EMPTY —
 // projects opt into exclusions explicitly via review.post_review_exclude_globs.
-export const DEFAULT_POST_REVIEW_EXCLUDES = [];
+export const DEFAULT_POST_REVIEW_EXCLUDES: string[] = [];
 
 // Returns git pathspecs selecting "all tracked changes except project excludes".
 // The leading ":/" makes coverage fail-closed (everything from the repo root);
 // each exclude becomes a top-level negative pathspec. Projects extend the
 // denylist via review.post_review_exclude_globs (union, deduped).
-export function resolvePostReviewGlobs(config = {}, reviewConfig = {}) {
+type ReviewGlobConfig = { post_review_exclude_globs?: unknown };
+
+export function resolvePostReviewGlobs(
+  config: ReviewGlobConfig = {},
+  reviewConfig: ReviewGlobConfig = {}
+): string[] {
   const projectExcludes = [
     ...(Array.isArray(reviewConfig.post_review_exclude_globs) ? reviewConfig.post_review_exclude_globs : []),
     ...(Array.isArray(config.post_review_exclude_globs) ? config.post_review_exclude_globs : [])
@@ -21,7 +26,7 @@ export function resolvePostReviewGlobs(config = {}, reviewConfig = {}) {
   return [":/", ...excludes.map((p) => `:(top,exclude)${p}`)];
 }
 
-export function findAuthoritativeReviewCodeArtifact(taskDir) {
+export function findAuthoritativeReviewCodeArtifact(taskDir: string) {
   const entries = fs.existsSync(taskDir) ? fs.readdirSync(taskDir) : [];
   const round = maxRound(entries, "review-code");
   if (round === 0) {
@@ -37,22 +42,22 @@ export function findAuthoritativeReviewCodeArtifact(taskDir) {
   };
 }
 
-export function extractReviewBaseline(content) {
+export function extractReviewBaseline(content: string): string {
   const match = String(content).match(/^[-*]?\s*\*\*(?:审查基线提交|Review Baseline Commit)\*\*[:：]\s*(.*?)\s*$/m);
-  return match ? match[1].trim().replace(/`/g, "") : "";
+  return match ? match[1]!.trim().replace(/`/g, "") : "";
 }
 
-export function extractReviewDiffFingerprint(content) {
+export function extractReviewDiffFingerprint(content: string): string {
   const match = String(content).match(/^[-*]?\s*\*\*(?:审查差异指纹|Reviewed Diff Fingerprint)\*\*[:：]\s*(.*?)\s*$/m);
-  return match ? match[1].trim().replace(/`/g, "") : "";
+  return match ? match[1]!.trim().replace(/`/g, "") : "";
 }
 
-export function extractReviewedSnapshotTree(content) {
+export function extractReviewedSnapshotTree(content: string): string {
   const match = String(content).match(/^[-*]?\s*\*\*(?:审查快照树|Reviewed Snapshot Tree)\*\*[:：]\s*(.*?)\s*$/m);
-  return match ? match[1].trim().replace(/`/g, "") : "";
+  return match ? match[1]!.trim().replace(/`/g, "") : "";
 }
 
-export function parseReviewVerdict(content) {
+export function parseReviewVerdict(content: string): string {
   const match = String(content).match(/^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.*?)\s*$/m);
-  return match ? match[1].trim() : "";
+  return match ? match[1]!.trim() : "";
 }