@loomhelm/multi-task-flow 0.2.6 → 0.2.8

package/toolkit/skills/spec-sync/scripts/_runtime/modules/docs/legacy_spec_id.ts

@@ -0,0 +1,131 @@
+import { randomInt } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const DEFAULT_ALPHABET = "23456789abcdefghjkmnpqrstuvwxyz";
+export const DEFAULT_LENGTH = 5;
+
+export interface LegacyIdOptions {
+  repoRoot?: string;
+  legacyCompat?: boolean;
+  count?: number;
+  length?: number;
+  alphabet?: string;
+  maxAttempts?: number;
+}
+
+export interface LegacyIdResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+function idsInRoot(
+  root: string,
+  alphabet: string,
+  length: number,
+): Set<string> {
+  const ids = new Set<string>();
+  const idPattern = new RegExp(
+    `^(?:\\d{4}|[${escapeRegex(alphabet)}]{${length}})$`,
+  );
+  for (const relativeRoot of ["docs/specs", "docs/plan"]) {
+    const directory = resolve(root, relativeRoot);
+    if (existsSync(directory)) {
+      for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const prefix = entry.name.split(/[-:]/, 1)[0]?.trim() ?? "";
+        if (idPattern.test(prefix)) ids.add(prefix);
+      }
+    }
+    const readme = resolve(directory, "README.md");
+    if (!existsSync(readme)) continue;
+    for (const line of readFileSync(readme, "utf8").split(/\r?\n/)) {
+      if (!line.startsWith("|")) continue;
+      const id =
+        line
+          .replace(/^\||\|$/g, "")
+          .split("|")[0]
+          ?.trim() ?? "";
+      if (idPattern.test(id)) ids.add(id);
+    }
+  }
+  return ids;
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function oneId(alphabet: string, length: number): string {
+  return Array.from(
+    { length },
+    () => alphabet[randomInt(alphabet.length)] ?? alphabet[0],
+  ).join("");
+}
+
+export function generateLegacySpecIds(
+  options: LegacyIdOptions = {},
+): LegacyIdResult {
+  if (!options.legacyCompat)
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr:
+        "[ERROR] legacy ID generation is migration-only; create new specs with docs/specs/<topic>/ instead.\n",
+    };
+  const count = options.count ?? 1;
+  const length = options.length ?? DEFAULT_LENGTH;
+  const alphabet = (options.alphabet ?? DEFAULT_ALPHABET).trim();
+  const maxAttempts = options.maxAttempts ?? 10_000;
+  if (count < 1)
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: "[ERROR] --count must be >= 1\n",
+    };
+  if (length < 1)
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: "[ERROR] --length must be >= 1\n",
+    };
+  if (!alphabet)
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: "[ERROR] --alphabet must be non-empty\n",
+    };
+  if (new Set(alphabet).size !== alphabet.length)
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: "[ERROR] --alphabet must not contain duplicate characters\n",
+    };
+
+  const existing = idsInRoot(
+    resolve(options.repoRoot ?? "."),
+    alphabet,
+    length,
+  );
+  const generated: string[] = [];
+  for (let index = 0; index < count; index += 1) {
+    let candidate: string | undefined;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      const next = oneId(alphabet, length);
+      if (!existing.has(next)) {
+        candidate = next;
+        existing.add(next);
+        break;
+      }
+    }
+    if (!candidate)
+      return {
+        exitCode: 1,
+        stdout: "",
+        stderr: `[ERROR] Failed to generate a unique id after ${maxAttempts} attempts.\n`,
+      };
+    generated.push(candidate);
+  }
+  return { exitCode: 0, stdout: `${generated.join("\n")}\n`, stderr: "" };
+}

package/toolkit/skills/spec-sync/scripts/_runtime/modules/docs/migration_common.ts

@@ -0,0 +1,291 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { gitText } from "./git";
+
+export const PREFIXED_NAME = /^(?<legacyId>[a-z0-9]{4,5})[-:](?<topic>.+)$/i;
+const TOPIC_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const INLINE_LINK = /\]\(\s*(?:<(?<angle>[^>]+)>|(?<bare>[^\s)]+))/gm;
+const REFERENCE_LINK =
+  /^\s*\[[^\]]+\]:\s*(?:<(?<angle>[^>]+)>|(?<bare>[^\s]+))/gm;
+const CATALOG_LINK =
+  /^\s*\[[^\]]*\]\(\s*(?:<(?<angle>[^>]+)>|(?<bare>[^\s)]+))(?:\s+["'][^"']*["'])?\s*\)\s*$/;
+
+export type Json = Record<string, unknown>;
+
+export function relativePath(root: string, path: string): string {
+  const value = relative(resolve(root), resolve(path)).replaceAll("\\", "/");
+  if (value === "" || value === ".") return ".";
+  return value;
+}
+
+export function parsePrefixedName(name: string): [string, string] | null {
+  const match = PREFIXED_NAME.exec(name);
+  return match?.groups?.legacyId && match.groups.topic
+    ? [match.groups.legacyId, match.groups.topic]
+    : null;
+}
+
+export function isTopicSlug(value: string): boolean {
+  return TOPIC_SLUG.test(value);
+}
+
+export function tableRows(text: string): Json[] {
+  const rows: Json[] = [];
+  const lines = text.split(/\r?\n/);
+  for (let index = 0; index + 1 < lines.length;) {
+    const header = lines[index] as string;
+    const separator = lines[index + 1] as string;
+    if (
+      !header.trimStart().startsWith("|") ||
+      !separator.trimStart().startsWith("|")
+    ) {
+      index += 1;
+      continue;
+    }
+    const headers = header
+      .trim()
+      .replace(/^\||\|$/g, "")
+      .split("|")
+      .map((cell) => cell.trim().toLowerCase());
+    const separators = separator
+      .trim()
+      .replace(/^\||\|$/g, "")
+      .split("|")
+      .map((cell) => cell.trim());
+    if (
+      !headers.length ||
+      headers.length !== separators.length ||
+      separators.some((cell) => !/^:?-{3,}:?$/.test(cell))
+    ) {
+      index += 1;
+      continue;
+    }
+    index += 2;
+    while (
+      index < lines.length &&
+      (lines[index] as string).trimStart().startsWith("|")
+    ) {
+      const values = (lines[index] as string)
+        .trim()
+        .replace(/^\||\|$/g, "")
+        .split("|")
+        .map((cell) => cell.trim());
+      if (values.length === headers.length) {
+        const row: Json = {};
+        headers.forEach((key, position) => {
+          row[key] = values[position] ?? "";
+        });
+        rows.push(row);
+      }
+      index += 1;
+    }
+  }
+  return rows;
+}
+
+function unwrapCatalogPath(value: string): string {
+  let candidate = value.trim();
+  if (candidate.startsWith("`") && candidate.endsWith("`"))
+    candidate = candidate.slice(1, -1).trim();
+  const match = CATALOG_LINK.exec(candidate);
+  return match?.groups?.angle ?? match?.groups?.bare ?? candidate;
+}
+
+export function normalizeRepoRelativePath(value: string): string | null {
+  const withoutFragment = decodeURIComponent(
+    value.split("#", 1)[0]?.split("?", 1)[0] ?? "",
+  ).trim();
+  if (
+    !withoutFragment ||
+    withoutFragment.startsWith("/") ||
+    withoutFragment.startsWith("#") ||
+    withoutFragment.includes("://")
+  )
+    return null;
+  const parts: string[] = [];
+  for (const part of withoutFragment.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      if (!parts.length) return null;
+      parts.pop();
+    } else parts.push(part);
+  }
+  return parts.join("/") || null;
+}
+
+function catalogPathCandidates(
+  value: string,
+  catalogRelative: string,
+): Set<string> {
+  const path = unwrapCatalogPath(value);
+  const direct = normalizeRepoRelativePath(path);
+  const catalogRoot = normalizeRepoRelativePath(
+    dirname(catalogRelative).replaceAll("\\", "/"),
+  );
+  const relativePathValue = catalogRoot
+    ? normalizeRepoRelativePath(`${catalogRoot}/${path}`)
+    : null;
+  return new Set(
+    [direct, relativePathValue].filter(
+      (candidate): candidate is string => candidate !== null,
+    ),
+  );
+}
+
+function catalogTexts(repoRoot: string, catalogRelative: string): string[] {
+  const texts: string[] = [];
+  const path = resolve(repoRoot, catalogRelative);
+  if (existsSync(path)) texts.push(readFileSync(path, "utf8"));
+  const history = gitText(repoRoot, [
+    "log",
+    "--format=%H",
+    "HEAD",
+    "--",
+    catalogRelative,
+  ]);
+  for (const revision of history?.split(/\r?\n/).filter(Boolean) ?? []) {
+    const text = gitText(repoRoot, ["show", `${revision}:${catalogRelative}`]);
+    if (text !== null && !texts.includes(text)) texts.push(text);
+  }
+  return texts;
+}
+
+export function catalogConfirmsLegacyId(
+  repoRoot: string,
+  catalogRelative: string,
+  sourceRelative: string,
+  legacyId: string,
+): boolean {
+  const expected = normalizeRepoRelativePath(sourceRelative);
+  if (!expected) return false;
+  return catalogTexts(repoRoot, catalogRelative).some((text) =>
+    tableRows(text).some((row) => {
+      if (
+        String(row.id ?? "")
+          .replaceAll("`", "")
+          .toLowerCase() !== legacyId.toLowerCase()
+      )
+        return false;
+      return ["spec", "plan", "path"].some((column) =>
+        catalogPathCandidates(String(row[column] ?? ""), catalogRelative).has(
+          expected,
+        ),
+      );
+    }),
+  );
+}
+
+export function legacyIdentity(
+  repoRoot: string,
+  name: string,
+  catalogRelative: string,
+  sourceRelative: string,
+  explicit?: string,
+): [string, string, string] | null {
+  const parsed = parsePrefixedName(name);
+  if (!parsed) return null;
+  const [legacyId, topic] = parsed;
+  if (explicit !== undefined) {
+    if (explicit.toLowerCase() !== legacyId.toLowerCase())
+      throw new Error(
+        `--legacy-id '${explicit}' does not match source prefix '${legacyId}'`,
+      );
+    return [legacyId, topic, "explicit"];
+  }
+  return catalogConfirmsLegacyId(
+    repoRoot,
+    catalogRelative,
+    sourceRelative,
+    legacyId,
+  )
+    ? [legacyId, topic, "catalog"]
+    : null;
+}
+
+function targetIsSource(
+  target: string,
+  markdownPath: string,
+  source: string,
+): boolean {
+  const cleaned = decodeURIComponent(
+    target.split("#", 1)[0]?.split("?", 1)[0] ?? "",
+  ).trim();
+  if (!cleaned || cleaned.includes("://") || cleaned.startsWith("#"))
+    return false;
+  const resolvedTarget = resolve(dirname(markdownPath), cleaned);
+  const sourcePath = resolve(source);
+  if (existsSync(sourcePath) && statSafe(sourcePath)?.isFile())
+    return resolvedTarget === sourcePath;
+  return (
+    resolvedTarget === sourcePath || resolvedTarget.startsWith(`${sourcePath}/`)
+  );
+}
+
+function links(text: string): string[] {
+  const result: string[] = [];
+  for (const pattern of [INLINE_LINK, REFERENCE_LINK]) {
+    pattern.lastIndex = 0;
+    for (const match of text.matchAll(pattern))
+      result.push(match.groups?.angle ?? match.groups?.bare ?? "");
+  }
+  return result;
+}
+
+function statSafe(path: string): ReturnType<typeof statSync> | null {
+  try {
+    return statSync(path);
+  } catch {
+    return null;
+  }
+}
+
+export function inboundLinks(
+  repoRoot: string,
+  source: string,
+  sourceRelative: string,
+): string[] {
+  const matches: string[] = [];
+  function visit(directory: string): void {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (!entry.isSymbolicLink()) visit(path);
+        continue;
+      }
+      if (
+        !entry.isFile() ||
+        !entry.name.endsWith(".md") ||
+        resolve(path) === resolve(source)
+      )
+        continue;
+      const sourceStat = statSafe(source);
+      if (
+        sourceStat?.isDirectory() &&
+        resolve(path).startsWith(`${resolve(source)}/`)
+      )
+        continue;
+      const text = readFileSync(path, "utf8");
+      if (
+        text.includes(sourceRelative) ||
+        links(text).some((target) => targetIsSource(target, path, source))
+      )
+        matches.push(relativePath(repoRoot, path));
+    }
+  }
+  visit(resolve(repoRoot));
+  return matches.sort();
+}
+
+export function isProtectedBranch(branch: string): boolean {
+  return (
+    new Set(["main", "master", "trunk"]).has(branch) ||
+    /^(release|hotfix|support)\//.test(branch)
+  );
+}
+
+export function currentBranch(repoRoot: string): string {
+  return (
+    gitText(repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"])?.trim() ||
+    "unknown"
+  );
+}

package/toolkit/skills/spec-sync/scripts/_runtime/modules/docs/next_plan.ts

@@ -0,0 +1,199 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  STATUS_DONE,
+  STATUS_PARTIAL_PREFIX,
+  STATUS_PENDING_DESIGN,
+  STATUS_READY,
+  STATUS_REDESIGN_PREFIX,
+  STATUS_SKIPPED,
+  STATUS_VOID,
+  createdAt,
+  detectRoot,
+  noPick,
+  relOrAbs,
+  resolveCandidate,
+  row,
+  separator,
+  statusRank,
+  table,
+  type Candidate,
+  type Json,
+} from "./next_plan_support";
+export {
+  STATUS_DONE,
+  STATUS_PARTIAL_PREFIX,
+  STATUS_PENDING_DESIGN,
+  STATUS_READY,
+  STATUS_REDESIGN_PREFIX,
+  STATUS_SKIPPED,
+  STATUS_VOID,
+} from "./next_plan_support";
+
+export function findNextPlan(repoRootInput = "."): Json {
+  const root = resolve(repoRootInput);
+  const detected = detectRoot(root);
+  if (!detected)
+    return {
+      ok: false,
+      reason: "missing_docs_specs_and_plan",
+      expected_paths: [
+        join(root, "docs/specs/README.md"),
+        join(root, "docs/plan/README.md"),
+      ],
+    };
+  const primaryReadme = join(detected.primary, "README.md");
+  if (!existsSync(primaryReadme))
+    return {
+      ok: false,
+      reason: "missing_specs_index_readme",
+      path: primaryReadme,
+      spec_root_mode: detected.mode,
+    };
+  let lines = readFileSync(primaryReadme, "utf8").split(/\r?\n/);
+  let found = table(lines);
+  if (!found)
+    return {
+      ok: false,
+      reason: "index_table_not_found",
+      path: primaryReadme,
+      spec_root_mode: detected.mode,
+    };
+  let indexRoot = detected.primary;
+  let indexSource = "primary";
+  if (found.mode === "lifecycle" && detected.fallback) {
+    const fallbackReadme = join(detected.fallback, "README.md");
+    if (existsSync(fallbackReadme)) {
+      const fallbackLines = readFileSync(fallbackReadme, "utf8").split(/\r?\n/);
+      const fallbackTable = table(fallbackLines);
+      if (fallbackTable?.mode === "status") {
+        lines = fallbackLines;
+        found = fallbackTable;
+        indexRoot = detected.fallback;
+        indexSource = "fallback_legacy_plan_queue";
+      }
+    }
+  }
+  if (found.mode === "lifecycle") {
+    const lifecycles = lines
+      .slice(found.start)
+      .filter((line) => line.trimStart().startsWith("|"))
+      .map((line) => row(line)[found.columns.lifecycle ?? -1])
+      .filter((value): value is string => Boolean(value));
+    return {
+      ok: false,
+      reason: "topic_spec_repo_has_no_task_queue",
+      index_mode: "lifecycle",
+      index_source: indexSource,
+      lifecycles,
+      spec_root: relOrAbs(root, indexRoot),
+      spec_root_mode: detected.mode,
+      index_path_column: found.pathLabel,
+      next_action: "use_other_task_source",
+    };
+  }
+  const idColumn = found.columns.id;
+  const titleColumn = found.columns.title;
+  const statusColumn = found.columns.status;
+  const pathColumn = found.columns.path;
+  if (
+    idColumn === undefined ||
+    titleColumn === undefined ||
+    statusColumn === undefined ||
+    pathColumn === undefined
+  ) {
+    return {
+      ok: false,
+      reason: "index_table_not_found",
+      path: primaryReadme,
+      spec_root_mode: detected.mode,
+    };
+  }
+  const statuses: string[] = [];
+  const candidates: Candidate[] = [];
+  const unresolved: Json[] = [];
+  for (const line of lines.slice(found.start)) {
+    if (!line.trimStart().startsWith("|")) break;
+    const cells = row(line);
+    if (!cells.length || separator(cells)) continue;
+    const max = Math.max(...Object.values(found.columns));
+    if (cells.length <= max) continue;
+    const id = cells[idColumn] ?? "";
+    const title = cells[titleColumn] ?? "";
+    const status = cells[statusColumn] ?? "";
+    if (status) statuses.push(status);
+    if (status !== STATUS_READY && !status.startsWith(STATUS_PARTIAL_PREFIX))
+      continue;
+    const resolved = resolveCandidate(
+      root,
+      id,
+      cells[pathColumn] ?? "",
+      detected.primary,
+      detected.fallback,
+    );
+    if (!resolved.path) {
+      unresolved.push({
+        spec_id: id,
+        plan_id: id,
+        title,
+        status,
+        candidates: resolved.candidates,
+      });
+      continue;
+    }
+    candidates.push({
+      id,
+      title,
+      status,
+      path: resolved.path,
+      createdAt: createdAt(root, resolved.path),
+      rank: statusRank(status),
+    });
+  }
+  if (unresolved.length)
+    return {
+      ok: false,
+      reason: "spec_path_not_unique_or_missing",
+      implementable_candidates: unresolved,
+      spec_root: relOrAbs(root, detected.primary),
+      spec_root_mode: detected.mode,
+      index_path_column: found.pathLabel,
+      index_mode: found.mode,
+    };
+  if (!candidates.length)
+    return {
+      ok: false,
+      reason: noPick(statuses),
+      statuses,
+      spec_root: relOrAbs(root, indexRoot),
+      spec_root_mode: detected.mode,
+      index_mode: found.mode,
+      index_source: indexSource,
+    };
+  candidates.sort(
+    (left, right) =>
+      left.rank - right.rank ||
+      (left.createdAt === null ? 1 : 0) - (right.createdAt === null ? 1 : 0) ||
+      (left.createdAt ?? "").localeCompare(right.createdAt ?? "") ||
+      left.id.localeCompare(right.id),
+  );
+  const pick = candidates[0] as Candidate;
+  return {
+    ok: true,
+    spec_id: pick.id,
+    plan_id: pick.id,
+    title: pick.title,
+    status: pick.status,
+    spec_path: pick.path,
+    plan_path: pick.path,
+    created_at: pick.createdAt,
+    selection_mode: "status_then_git_created_at",
+    spec_root: relOrAbs(root, indexRoot),
+    spec_root_mode: detected.mode,
+    index_path_column: found.pathLabel,
+    index_mode: found.mode,
+    index_source: indexSource,
+    next_action: "implement",
+    next: `implement ${pick.path}`,
+  };
+}