@loomhelm/multi-task-flow 0.2.6 → 0.2.7

package/toolkit/skills/spec-sync/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/spec-sync/scripts/spec_drift_check.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("spec_drift_check");

package/toolkit/skills/support-manifest.json

@@ -57,5 +57,81 @@
   "skills/multi-task-flow/web/task-context-menu.ts",
   "skills/multi-task-flow/tests/ui/task-context-menu.test.ts",
   "skills/multi-task-flow/tests/viewer-runtime.test.ts",
-  "skills/multi-task-flow/tests/viewer-socket.test.ts"
+  "skills/multi-task-flow/tests/viewer-socket.test.ts",
+  "skills/docs-migrate/scripts/_runtime/compatibility_cli.ts",
+  "skills/docs-migrate/scripts/_runtime/compatibility_docs.ts",
+  "skills/docs-migrate/scripts/_runtime/compatibility_shared.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/checks/replay.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/git.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/hardware_ingest.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/hardware_locks.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/legacy_spec_id.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/migration_common.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/next_plan.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/next_plan_support.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/spec_contract.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/spec_drift.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/spec_drift_helpers.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/spec_drift_legacy.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/spec_drift_paths.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/spec_drift_types.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/spec_drift_validation.ts",
+  "skills/docs-migrate/scripts/_runtime/modules/docs/spec_migration.ts",
+  "skills/find-next-plan/scripts/_runtime/compatibility_cli.ts",
+  "skills/find-next-plan/scripts/_runtime/compatibility_docs.ts",
+  "skills/find-next-plan/scripts/_runtime/compatibility_shared.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/checks/replay.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/git.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/hardware_ingest.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/hardware_locks.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/legacy_spec_id.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/migration_common.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/next_plan.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/next_plan_support.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/spec_contract.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/spec_drift.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/spec_drift_helpers.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/spec_drift_legacy.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/spec_drift_paths.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/spec_drift_types.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/spec_drift_validation.ts",
+  "skills/find-next-plan/scripts/_runtime/modules/docs/spec_migration.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/compatibility_cli.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/compatibility_docs.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/compatibility_shared.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/checks/replay.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/git.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/hardware_ingest.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/hardware_locks.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/legacy_spec_id.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/migration_common.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/next_plan.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/next_plan_support.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/spec_contract.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/spec_drift.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/spec_drift_helpers.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/spec_drift_legacy.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/spec_drift_paths.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/spec_drift_types.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/spec_drift_validation.ts",
+  "skills/hardware-doc-ingest/scripts/_runtime/modules/docs/spec_migration.ts",
+  "skills/spec-sync/scripts/_runtime/compatibility_cli.ts",
+  "skills/spec-sync/scripts/_runtime/compatibility_docs.ts",
+  "skills/spec-sync/scripts/_runtime/compatibility_shared.ts",
+  "skills/spec-sync/scripts/_runtime/modules/checks/replay.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/git.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/hardware_ingest.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/hardware_locks.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/legacy_spec_id.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/migration_common.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/next_plan.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/next_plan_support.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/spec_contract.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/spec_drift.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/spec_drift_helpers.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/spec_drift_legacy.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/spec_drift_paths.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/spec_drift_types.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/spec_drift_validation.ts",
+  "skills/spec-sync/scripts/_runtime/modules/docs/spec_migration.ts"
 ]