@loomhelm/multi-task-flow 0.2.6 → 0.2.8

package/toolkit/skills/spec-sync/scripts/_runtime/compatibility_cli.ts

@@ -0,0 +1,12 @@
+import { basename } from "node:path";
+import { docs } from "./compatibility_docs";
+
+export async function runCompatibilityCli(name: string, argv: string[] = process.argv.slice(2)): Promise<number> {
+  const smoke = argv.includes("--compatibility-smoke");
+  const help = argv.includes("--help") || argv.includes("-h");
+  if (help && !smoke) { console.log(`Usage: bun ${name}.ts [options]`); return 0; }
+  const result = docs(basename(name).replace(/\.ts$/, ""), argv.filter(value => value !== "--compatibility-smoke"));
+  if (smoke && (result === 0 || help)) console.log(`SMOKE dispatched=${basename(name).replace(/\.ts$/, "")}`);
+  if (help) { if (result === 0) return 0; console.log(`Usage: bun ${name}.ts [options]`); return 0; }
+  return result;
+}

package/toolkit/skills/spec-sync/scripts/_runtime/compatibility_docs.ts

@@ -0,0 +1,115 @@
+import { verifyDocLocks } from "./modules/docs/hardware_locks";
+import { ingestExtract } from "./modules/docs/hardware_ingest";
+import { findNextPlan } from "./modules/docs/next_plan";
+import { generateLegacySpecIds } from "./modules/docs/legacy_spec_id";
+import { parseSpecDriftArgs, runSpecDrift } from "./modules/docs/spec_drift";
+import {
+  planSpecsHygiene,
+  planSpecsMigration,
+} from "./modules/docs/spec_migration";
+import { json, option, rootFor } from "./compatibility_shared";
+
+export function docs(name: string, argv: string[]): number {
+  if (name === "verify_doc_locks") {
+    const result = verifyDocLocks(rootFor(argv), {
+      strictPdf: argv.includes("--strict-pdf"),
+      checkPerms: !argv.includes("--no-check-perms"),
+    });
+    result.lines.forEach((line) => console.log(line));
+    return result.exitCode;
+  }
+  if (name === "find_next_plan") {
+    json(findNextPlan(option(argv, "repo", process.cwd())!));
+    return 0;
+  }
+  if (name === "gen_legacy_spec_id") return legacyId(argv);
+  if (name === "specs_migrate_guard") return migrateGuard(argv);
+  if (name === "spec_drift_check") return drift(argv);
+  if (name === "ingest_mineru_extract") return ingest(argv);
+  return 2;
+}
+
+function legacyId(argv: string[]): number {
+  const args: Parameters<typeof generateLegacySpecIds>[0] = {
+    repoRoot: option(argv, "repo", process.cwd())!,
+    legacyCompat: argv.includes("--legacy-compat"),
+    count: Number(option(argv, "count", "1")),
+    length: Number(option(argv, "length", "5")),
+  };
+  const alphabet = option(argv, "alphabet");
+  if (alphabet !== undefined) args.alphabet = alphabet;
+  const result = generateLegacySpecIds(args);
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  return result.exitCode;
+}
+
+function migrateGuard(argv: string[]): number {
+  const repo = option(argv, "repo", process.cwd())!;
+  const source = option(argv, "source")!;
+  const branch = option(argv, "branch");
+  const legacyId = option(argv, "legacy-id");
+  const topic = option(argv, "topic");
+  const options = {
+    ...(branch === undefined ? {} : { branch }),
+    ...(legacyId === undefined ? {} : { legacyId }),
+    ...(topic === undefined ? {} : { topic }),
+  };
+  const result =
+    option(argv, "mode") === "specs-hygiene"
+      ? planSpecsHygiene(repo, source, {
+          ...options,
+          renameConfirmed: argv.includes("--rename-confirmed"),
+        })
+      : planSpecsMigration(repo, source, options);
+  json(result);
+  return result.blocked_reason ? 1 : 0;
+}
+
+function drift(argv: string[]): number {
+  const parsed = parseSpecDriftArgs(argv);
+  if (parsed.error) {
+    console.error(parsed.error);
+    return 2;
+  }
+  if (parsed.help) {
+    console.log(
+      "Usage: spec_drift_check.ts [--base-ref <ref>] [--spec-path <path>]...",
+    );
+    return 0;
+  }
+  const result = runSpecDrift(parsed.options);
+  json(result);
+  return result.exitCode;
+}
+
+function ingest(argv: string[]): number {
+  try {
+    const args: Parameters<typeof ingestExtract>[0] = {
+      extractPath: option(argv, "extract-path")!,
+      destDir: option(argv, "dest-dir")!,
+      slug: option(argv, "slug")!,
+      overwrite: argv.includes("--overwrite"),
+      addHeader: argv.includes("--add-header"),
+      keepMineruJson: argv.includes("--keep-mineru-json"),
+      writeLock: !argv.includes("--no-write-lock"),
+      lockGenerated: !argv.includes("--writable-generated"),
+      createReadme: !argv.includes("--no-readme"),
+    };
+    for (const [key, flag] of [
+      ["docSubdir", "doc-subdir"],
+      ["sourceUrl", "source-url"],
+      ["docType", "doc-type"],
+      ["vendor", "vendor"],
+      ["part", "part"],
+    ] as const) {
+      const value = option(argv, flag);
+      if (value !== undefined) args[key] = value;
+    }
+    ingestExtract(args).lines.forEach((line) => console.log(line));
+    return 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}

package/toolkit/skills/spec-sync/scripts/_runtime/compatibility_shared.ts

@@ -0,0 +1,230 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  parseReplayCases,
+  resolveCasePath,
+  runReplayCases,
+} from "./modules/checks/replay";
+
+export type Analyzer = (path: string) => {
+  findings: Array<{ code: string; line: number; message: string }>;
+};
+
+export function option(
+  argv: string[],
+  name: string,
+  fallback?: string,
+): string | undefined {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === `--${name}`) return argv[index + 1] ?? fallback;
+    if (token?.startsWith(`--${name}=`)) return token.slice(name.length + 3);
+  }
+  return fallback;
+}
+
+export function values(argv: string[], name: string): string[] {
+  const result: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === `--${name}` && argv[index + 1]) result.push(argv[++index]!);
+    else if (token?.startsWith(`--${name}=`))
+      result.push(token.slice(name.length + 3));
+  }
+  return result;
+}
+
+export function groups(argv: string[], name: string, size: number): string[][] {
+  const result: string[][] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] !== `--${name}`) continue;
+    const group = argv.slice(index + 1, index + 1 + size);
+    if (group.length === size) result.push(group);
+    index += size;
+  }
+  return result;
+}
+
+export function positional(argv: string[]): string[] {
+  const skip = new Set([
+    "--repo-root",
+    "--cases",
+    "--path",
+    "--base-sha",
+    "--output-dir",
+    "--repo",
+    "--remote",
+    "--number",
+    "--sha",
+    "--method",
+    "--expected-base",
+    "--expected-head",
+    "--branch",
+    "--title",
+    "--body-file",
+    "--head",
+    "--base",
+    "--run-id",
+    "--expected-sha",
+    "--tag",
+    "--note-file",
+    "--target",
+    "--event",
+    "--text-file",
+    "--context",
+  ]);
+  const result: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index]!;
+    if (skip.has(token)) {
+      index += 1;
+      continue;
+    }
+    if (!token.startsWith("--")) result.push(token);
+  }
+  return result;
+}
+
+export function replay(
+  argv: string[],
+  analyzer: Analyzer,
+  expectation: "required" | "exact" = "required",
+): number {
+  const casePaths = values(argv, "cases");
+  const paths = positional(argv);
+  if (!casePaths.length && !paths.length) {
+    console.error("at least one replay path is required");
+    return 2;
+  }
+  let exitCode = 0;
+  const summary = argv.includes("--summary");
+  for (const casesPath of casePaths) {
+    const failures = replayCases(casesPath, analyzer, expectation, summary);
+    if (failures.length) {
+      exitCode = 1;
+      for (const failure of failures)
+        console.error(formatCaseMismatch(failure, summary));
+    }
+  }
+  for (const path of paths) {
+    try {
+      const caseFailures = path.endsWith(".txt")
+        ? replayCases(path, analyzer, expectation, summary)
+        : undefined;
+      if (caseFailures !== undefined) {
+        if (caseFailures.length) {
+          exitCode = 1;
+          for (const failure of caseFailures)
+            console.error(formatCaseMismatch(failure, summary));
+        }
+        continue;
+      }
+      const findings = analyzer(path).findings;
+      if (findings.length) {
+        exitCode = 1;
+        if (summary)
+          console.log(`SUMMARY file=${path} ${replaySummary(findings)}`);
+        else
+          findings.forEach((finding) =>
+            console.log(
+              `FINDING file=${path} code=${finding.code} line=${finding.line} msg=${finding.message}`,
+            ),
+          );
+      } else {
+        console.log(
+          summary
+            ? `SUMMARY file=${path} status=PASS total=0`
+            : `PASS file=${path}`,
+        );
+      }
+    } catch (error) {
+      exitCode = 1;
+      console.error(
+        `FAIL file=${path} ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  return exitCode;
+}
+
+function formatCaseMismatch(
+  failure: ReturnType<typeof runReplayCases>[number],
+  summary: boolean,
+): string {
+  const actual = failure.actualCodes.join(",") || "PASS";
+  if (summary) {
+    return failure.case.expectFail
+      ? `ERROR file=${failure.path} expected finding ${failure.case.expectedCodes.join(",") || "any"} but saw ${actual}`
+      : `ERROR file=${failure.path} expected PASS but saw findings ${actual}`;
+  }
+  return `CASE_MISMATCH file=${failure.path} line=${failure.case.line} expected=${failure.case.expectedCodes.join(",") || (failure.case.expectFail ? "finding" : "pass")} actual=${failure.actualCodes.join(",") || "pass"}`;
+}
+
+function replayCases(
+  casesPath: string,
+  analyzer: Analyzer,
+  expectation: "required" | "exact",
+  summary: boolean,
+): ReturnType<typeof runReplayCases> {
+  const failures: ReturnType<typeof runReplayCases> = [];
+  for (const item of parseReplayCases(casesPath)) {
+    const localPath = resolveCasePath(dirname(casesPath), item.path);
+    const path = existsSync(localPath)
+      ? localPath
+      : resolveCasePath(process.cwd(), item.path);
+    const actual = analyzer(path).findings;
+    const actualCodes = actual.map((finding) => finding.code).sort();
+    const actualCodeSet = [...new Set(actualCodes)];
+    const expectedCodes = [...new Set(item.expectedCodes)].sort();
+    const matches = item.expectFail
+      ? expectation === "exact"
+        ? actualCodes.length === expectedCodes.length &&
+          actualCodes.every((code, index) => code === expectedCodes[index])
+        : expectedCodes.every((code) => actualCodeSet.includes(code))
+      : actualCodes.length === 0;
+    if (summary) console.log(`SUMMARY file=${path} ${replaySummary(actual)}`);
+    else if (actual.length) {
+      for (const finding of actual)
+        console.log(
+          `FINDING file=${path} code=${finding.code} line=${finding.line} msg=${finding.message}`,
+        );
+    } else console.log(`PASS file=${path}`);
+    if (!matches) failures.push({ case: item, actualCodes, path });
+  }
+  return failures;
+}
+
+function replaySummary(
+  findings: Array<{ code: string; line: number }>,
+): string {
+  if (!findings.length) return "status=PASS total=0";
+  const counts = new Map<string, { count: number; line: number }>();
+  for (const finding of findings) {
+    const previous = counts.get(finding.code);
+    counts.set(finding.code, {
+      count: (previous?.count ?? 0) + 1,
+      line: previous?.line ?? finding.line,
+    });
+  }
+  const details = [...counts.entries()]
+    .sort(
+      (left, right) =>
+        left[1].line - right[1].line || left[0].localeCompare(right[0]),
+    )
+    .map(([code, detail]) => `${code}:${detail.count}@${detail.line}`)
+    .join(",");
+  return `status=FINDINGS total=${findings.length} codes=${details}`;
+}
+
+export function rootFor(argv: string[]): string {
+  return resolve(option(argv, "repo-root", process.cwd())!);
+}
+
+export function printList(valuesToPrint: string[], prefix = "FINDING"): number {
+  valuesToPrint.forEach((value) => console.log(`${prefix} ${value}`));
+  return valuesToPrint.length ? 1 : 0;
+}
+
+export function json(value: unknown): void {
+  console.log(JSON.stringify(value, null, 2));
+}

package/toolkit/skills/spec-sync/scripts/_runtime/modules/checks/replay.ts

@@ -0,0 +1,336 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+
+export type JsonValue =
+  string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+export type JsonRecord = Record<string, unknown>;
+
+export interface Finding {
+  code: string;
+  line: number;
+  message: string;
+}
+
+export interface ReplayResult {
+  findings: Finding[];
+}
+
+export interface ReplayCase {
+  path: string;
+  expectFail: boolean;
+  expectedCodes: string[];
+  line: number;
+}
+
+export function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function collectStrings(value: unknown): string[] {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.flatMap(collectStrings);
+  if (isRecord(value)) return Object.values(value).flatMap(collectStrings);
+  return [];
+}
+
+const trackerCardFields = new Set([
+  "phase",
+  "tracking_phase",
+  "追踪阶段",
+  "tracking_target",
+  "追踪目标",
+  "bound_sha",
+  "checked_sha",
+  "追踪绑定sha",
+  "绑定sha",
+  "terminal_state",
+  "追踪终态",
+  "result",
+  "追踪结果",
+  "external_locator",
+  "外部定位",
+]);
+const routeResolutionFields = new Set([
+  "pre_merge_release_route",
+  "release_disposition",
+  "release_route",
+  "release_route_resolved",
+  "current_repository_facts",
+  "repository_facts",
+  "current_pr_facts",
+  "pr_facts",
+]);
+
+function pythonText(value: unknown): string {
+  if (value === null) return "None";
+  if (typeof value === "boolean") return value ? "True" : "False";
+  return String(value);
+}
+
+export function collectTrackerCardStrings(value: unknown): string[] {
+  if (Array.isArray(value)) return value.flatMap(collectTrackerCardStrings);
+  if (!isRecord(value)) return [];
+  const texts: string[] = [];
+  for (const [key, item] of Object.entries(value)) {
+    if (
+      trackerCardFields.has(key) &&
+      (typeof item === "string" ||
+        typeof item === "number" ||
+        typeof item === "boolean")
+    ) {
+      texts.push(`${key}=${pythonText(item)}`);
+    } else if (routeResolutionFields.has(key)) {
+      if (Array.isArray(item) || isRecord(item)) {
+        texts.push(key);
+        texts.push(...collectTrackerCardStrings(item));
+      } else {
+        texts.push(`${key}=${pythonText(item)}`);
+      }
+    } else if (Array.isArray(item) || isRecord(item)) {
+      texts.push(...collectTrackerCardStrings(item));
+    }
+  }
+  return texts;
+}
+
+type JsonScanResult = number | "duplicate" | undefined;
+
+function skipJsonWhitespace(text: string, index: number): number {
+  while (index < text.length && /\s/.test(text[index]!)) index += 1;
+  return index;
+}
+
+function scanJsonString(
+  text: string,
+  start: number,
+): { end: number; value: string } | undefined {
+  if (text[start] !== '"') return undefined;
+  let index = start + 1;
+  while (index < text.length) {
+    if (text[index] === "\\") {
+      index += 2;
+      continue;
+    }
+    if (text[index] === '"') {
+      const raw = text.slice(start, index + 1);
+      try {
+        const value: unknown = JSON.parse(raw);
+        return typeof value === "string"
+          ? { end: index + 1, value }
+          : undefined;
+      } catch {
+        return undefined;
+      }
+    }
+    index += 1;
+  }
+  return undefined;
+}
+
+function scanJsonValue(text: string, start: number): JsonScanResult {
+  const index = skipJsonWhitespace(text, start);
+  if (text[index] === '"') return scanJsonString(text, index)?.end;
+  if (text[index] === "{") {
+    const keys = new Set<string>();
+    let cursor = skipJsonWhitespace(text, index + 1);
+    if (text[cursor] === "}") return cursor + 1;
+    while (cursor < text.length) {
+      const key = scanJsonString(text, cursor);
+      if (!key) return undefined;
+      if (keys.has(key.value)) return "duplicate";
+      keys.add(key.value);
+      cursor = skipJsonWhitespace(text, key.end);
+      if (text[cursor] !== ":") return undefined;
+      const value = scanJsonValue(text, cursor + 1);
+      if (value === "duplicate" || value === undefined) return value;
+      cursor = skipJsonWhitespace(text, value);
+      if (text[cursor] === "}") return cursor + 1;
+      if (text[cursor] !== ",") return undefined;
+      cursor = skipJsonWhitespace(text, cursor + 1);
+    }
+    return undefined;
+  }
+  if (text[index] === "[") {
+    let cursor = skipJsonWhitespace(text, index + 1);
+    if (text[cursor] === "]") return cursor + 1;
+    while (cursor < text.length) {
+      const value = scanJsonValue(text, cursor);
+      if (value === "duplicate" || value === undefined) return value;
+      cursor = skipJsonWhitespace(text, value);
+      if (text[cursor] === "]") return cursor + 1;
+      if (text[cursor] !== ",") return undefined;
+      cursor = skipJsonWhitespace(text, cursor + 1);
+    }
+    return undefined;
+  }
+  let cursor = index;
+  while (cursor < text.length && !/[\s,\]}]/.test(text[cursor]!)) cursor += 1;
+  return cursor > index ? cursor : undefined;
+}
+
+function hasDuplicateJsonKeys(text: string): boolean {
+  return scanJsonValue(text, 0) === "duplicate";
+}
+
+export function parseJsonArguments(raw: unknown): JsonRecord {
+  if (isRecord(raw)) return raw;
+  if (typeof raw !== "string") return {};
+  const parsed = parseJsonValue(raw);
+  return isRecord(parsed) ? parsed : {};
+}
+
+export function parseJsonValue(raw: string): unknown | undefined {
+  if (hasDuplicateJsonKeys(raw)) return undefined;
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+export function eventTexts(record: JsonRecord): {
+  kind: string | undefined;
+  role: string | undefined;
+  texts: string[];
+} {
+  const recordType = typeof record.type === "string" ? record.type : undefined;
+  const payload = isRecord(record.payload) ? record.payload : {};
+  if (recordType !== "response_item")
+    return {
+      kind: recordType,
+      role: undefined,
+      texts: collectStrings(payload),
+    };
+
+  const payloadType =
+    typeof payload.type === "string" ? payload.type : undefined;
+  if (payloadType === "message") {
+    const content = Array.isArray(payload.content) ? payload.content : [];
+    const texts = content.flatMap((item) => {
+      if (!isRecord(item) || typeof item.text !== "string") return [];
+      return [item.text];
+    });
+    return {
+      kind: "message",
+      role: typeof payload.role === "string" ? payload.role : undefined,
+      texts,
+    };
+  }
+  if (payloadType === "function_call") {
+    const texts = [payload.name, payload.arguments].filter(
+      (item): item is string => typeof item === "string",
+    );
+    return { kind: "function_call", role: undefined, texts };
+  }
+  if (payloadType === "function_call_output")
+    return {
+      kind: "function_call_output",
+      role: undefined,
+      texts: [
+        ...collectStrings(payload.output),
+        ...(typeof payload.output === "object" && payload.output !== null
+          ? [JSON.stringify(payload.output)]
+          : []),
+      ],
+    };
+  return { kind: payloadType, role: undefined, texts: collectStrings(payload) };
+}
+
+export function eventText(record: JsonRecord): string {
+  return eventTexts(record).texts.join("\n");
+}
+
+export function readJsonLines(
+  path: string,
+): Array<{ line: number; value: JsonRecord }> {
+  const records: Array<{ line: number; value: JsonRecord }> = [];
+  for (const [index, raw] of readFileSync(path, "utf8")
+    .split(/\r?\n/)
+    .entries()) {
+    if (!raw.trim()) continue;
+    const parsed: unknown = JSON.parse(raw);
+    if (!isRecord(parsed))
+      throw new Error(`replay record at line ${index + 1} must be an object`);
+    records.push({ line: index + 1, value: parsed });
+  }
+  return records;
+}
+
+export function parseReplayCases(path: string): ReplayCase[] {
+  const cases: ReplayCase[] = [];
+  for (const [index, raw] of readFileSync(path, "utf8")
+    .split(/\r?\n/)
+    .entries()) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const fields = line.split(/\s+/);
+    if (fields.length < 2) throw new Error(`invalid cases line ${index + 1}`);
+    if (fields[0] === "pass" || fields[0] === "fail") {
+      if (fields.length < 3)
+        throw new Error(`missing expectation at line ${index + 1}`);
+      cases.push({
+        path: fields[1]!,
+        expectFail: fields[0] === "fail",
+        expectedCodes: fields[2] === "-" ? [] : fields[2]!.split(","),
+        line: index + 1,
+      });
+      continue;
+    }
+    cases.push({
+      path: fields[0]!,
+      expectFail: fields[1] !== "pass",
+      expectedCodes: fields[1] === "pass" ? [] : fields[1]!.split(","),
+      line: index + 1,
+    });
+  }
+  return cases;
+}
+
+export function resolveCasePath(baseDir: string, rawPath: string): string {
+  return isAbsolute(rawPath) ? rawPath : resolve(baseDir, rawPath);
+}
+
+export type ReplayAnalyzer = (path: string) => ReplayResult;
+
+export interface ReplayCaseFailure {
+  case: ReplayCase;
+  actualCodes: string[];
+  path: string;
+}
+
+export type ReplayExpectation = "required" | "exact";
+
+export function runReplayCases(
+  casesPath: string,
+  analyzer: ReplayAnalyzer,
+  expectation: ReplayExpectation = "required",
+): ReplayCaseFailure[] {
+  const failures: ReplayCaseFailure[] = [];
+  for (const item of parseReplayCases(casesPath)) {
+    const localPath = resolveCasePath(dirname(casesPath), item.path);
+    const path = existsSync(localPath)
+      ? localPath
+      : resolveCasePath(process.cwd(), item.path);
+    const actualCodes = analyzer(path)
+      .findings.map((finding) => finding.code)
+      .sort();
+    const actualCodeSet = [...new Set(actualCodes)];
+    const expectedCodes = [...new Set(item.expectedCodes)].sort();
+    const equal = item.expectFail
+      ? expectation === "exact"
+        ? actualCodes.length === expectedCodes.length &&
+          actualCodes.every((code, index) => code === expectedCodes[index])
+        : expectedCodes.every((code) => actualCodeSet.includes(code))
+      : actualCodes.length === 0;
+    if (!equal) failures.push({ case: item, actualCodes, path });
+  }
+  return failures;
+}
+
+export function result(findings: Finding[]): ReplayResult {
+  return { findings };
+}
+
+export function finding(code: string, line: number, message: string): Finding {
+  return { code, line, message };
+}