@loomhelm/multi-task-flow 0.2.1 → 0.2.7

package/toolkit/skills/docs-migrate/scripts/_runtime/modules/docs/spec_migration.ts

@@ -0,0 +1,191 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  currentBranch,
+  inboundLinks,
+  isProtectedBranch,
+  isTopicSlug,
+  legacyIdentity,
+  parsePrefixedName,
+  relativePath,
+  type Json,
+} from "./migration_common";
+
+function regularFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function baseResult(
+  repoRoot: string,
+  source: string,
+  sourceRelative: string,
+  topic: string,
+  branch: string,
+): Json {
+  const targetRoot = `docs/specs/${topic}`;
+  return {
+    source: sourceRelative,
+    topic,
+    target_root: targetRoot,
+    target_spec: `${targetRoot}/SPEC.md`,
+    branch,
+    write_allowed: !isProtectedBranch(branch),
+    blocked_reason: null,
+    inbound_links: inboundLinks(repoRoot, source, sourceRelative),
+    pending_delete_approval: [],
+  };
+}
+
+function withTopic(result: Json, topic: string): Json {
+  if (isTopicSlug(topic)) return result;
+  result.candidate_topic = topic;
+  result.target_root = null;
+  result.target_spec = null;
+  result.required_topic_slug = "lowercase-kebab-case";
+  result.blocked_reason = "topic_slug_required";
+  return result;
+}
+
+export function planSpecsMigration(
+  repoRootInput: string,
+  sourceInput: string,
+  options: { branch?: string; legacyId?: string; topic?: string } = {},
+): Json {
+  const repoRoot = resolve(repoRootInput);
+  const source = resolve(sourceInput);
+  const sourceRelative = relativePath(repoRoot, source);
+  if (
+    !regularFile(source) ||
+    !sourceRelative.startsWith("docs/plan/") ||
+    !source.endsWith("/PLAN.md")
+  )
+    throw new Error("source must be an existing docs/plan/**/PLAN.md file");
+  const branch = options.branch ?? currentBranch(repoRoot);
+  const identity = legacyIdentity(
+    repoRoot,
+    source.split("/").at(-2) ?? "",
+    "docs/plan/README.md",
+    sourceRelative,
+    options.legacyId,
+  );
+  const topic =
+    options.topic ?? identity?.[1] ?? source.split("/").at(-2) ?? "";
+  const result = baseResult(repoRoot, source, sourceRelative, topic, branch);
+  result.legacy_id = identity?.[0] ?? null;
+  result.legacy_id_provenance = identity?.[2] ?? "none";
+  withTopic(result, topic);
+  if (result.blocked_reason) return result;
+  if (isProtectedBranch(branch)) {
+    result.blocked_reason = "protected_branch_read_only";
+    return result;
+  }
+  if (existsSync(resolve(repoRoot, String(result.target_root)))) {
+    result.blocked_reason = "slug_conflict";
+    return result;
+  }
+  result.action = "create_slug_spec";
+  result.pending_delete_approval = [sourceRelative];
+  return result;
+}
+
+export function planSpecsHygiene(
+  repoRootInput: string,
+  legacyRootInput: string,
+  options: {
+    branch?: string;
+    renameConfirmed?: boolean;
+    legacyId?: string;
+    topic?: string;
+  } = {},
+): Json {
+  const repoRoot = resolve(repoRootInput);
+  const legacyRoot = resolve(legacyRootInput);
+  const sourceRelative = relativePath(repoRoot, legacyRoot);
+  if (!directoryExists(legacyRoot) || !sourceRelative.startsWith("docs/specs/"))
+    throw new Error(
+      "source must be an existing docs/specs/<legacy-id>-<topic> directory",
+    );
+  const sourceSpecRelative = `${sourceRelative}/SPEC.md`;
+  const identity = legacyIdentity(
+    repoRoot,
+    legacyRoot.split("/").at(-1) ?? "",
+    "docs/specs/README.md",
+    sourceSpecRelative,
+    options.legacyId,
+  );
+  const topic =
+    options.topic ?? identity?.[1] ?? legacyRoot.split("/").at(-1) ?? "";
+  const branch = options.branch ?? currentBranch(repoRoot);
+  const result = baseResult(
+    repoRoot,
+    legacyRoot,
+    sourceRelative,
+    topic,
+    branch,
+  );
+  result.target_spec = `docs/specs/${topic}/SPEC.md`;
+  result.legacy_root = sourceRelative;
+  result.legacy_id = identity?.[0] ?? null;
+  result.legacy_id_provenance = identity?.[2] ?? "none";
+  if (!identity) {
+    result.blocked_reason = parsePrefixedName(
+      legacyRoot.split("/").at(-1) ?? "",
+    )
+      ? "legacy_id_proof_required"
+      : "not_legacy_id_directory";
+    return result;
+  }
+  withTopic(result, topic);
+  if (result.blocked_reason) return result;
+  if (isProtectedBranch(branch)) {
+    result.blocked_reason = "protected_branch_read_only";
+    return result;
+  }
+  if (existsSync(resolve(repoRoot, String(result.target_root)))) {
+    result.blocked_reason = "slug_conflict";
+    return result;
+  }
+  const conflicting: string[] = [];
+  const specsRoot = resolve(repoRoot, "docs/specs");
+  if (directoryExists(specsRoot)) {
+    for (const entry of readdirSync(specsRoot, { withFileTypes: true })) {
+      if (
+        !entry.isDirectory() ||
+        entry.name === (legacyRoot.split("/").at(-1) ?? "")
+      )
+        continue;
+      const sibling = resolve(specsRoot, entry.name);
+      const siblingRelative = relativePath(repoRoot, sibling);
+      const siblingIdentity = legacyIdentity(
+        repoRoot,
+        entry.name,
+        "docs/specs/README.md",
+        `${siblingRelative}/SPEC.md`,
+      );
+      if (siblingIdentity?.[1] === topic) conflicting.push(siblingRelative);
+    }
+  }
+  if (conflicting.length) {
+    result.blocked_reason = "duplicate_slug_mapping";
+    result.conflicting_legacy_roots = conflicting.sort();
+    return result;
+  }
+  if (!options.renameConfirmed) {
+    result.blocked_reason = "rename_confirmation_required";
+    return result;
+  }
+  result.action = "git_mv";
+  return result;
+}
+
+function directoryExists(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/toolkit/skills/docs-migrate/scripts/gen_legacy_spec_id.ts

@@ -1,4 +1,4 @@
-import { runCompatibilityCli } from "../../bin/compatibility_cli";
+import { runCompatibilityCli } from "./_runtime/compatibility_cli";
 
 if (import.meta.main)
   process.exitCode = await runCompatibilityCli("gen_legacy_spec_id");

package/toolkit/skills/docs-migrate/scripts/specs_migrate_guard.ts

@@ -1,4 +1,4 @@
-import { runCompatibilityCli } from "../../bin/compatibility_cli";
+import { runCompatibilityCli } from "./_runtime/compatibility_cli";
 
 if (import.meta.main)
   process.exitCode = await runCompatibilityCli("specs_migrate_guard");

package/toolkit/skills/find-next-plan/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/find-next-plan/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/find-next-plan/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));
+}