@sha3/code 1.0.0

package/lib/profile.mjs

@@ -0,0 +1,108 @@
+import { copyFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { DEFAULT_PROFILE, PROFILE_QUESTIONS } from "./constants.mjs";
+import { getBundledProfilePath } from "./paths.mjs";
+import { getRelativeProfilePath } from "./project/package-metadata.mjs";
+import { normalizeProfile, pathExists, readJsonFile, validateAgainstSchema, writeJsonFile } from "./utils/fs.mjs";
+import { askChoice, promptYesNo, withReadline } from "./utils/prompts.mjs";
+
+export function validateProfile(profile, schema, sourceLabel) {
+  validateAgainstSchema(profile, schema, sourceLabel);
+}
+
+export async function readAndValidateProfile(profilePath, schema) {
+  const profile = await readJsonFile(profilePath);
+  validateProfile(profile, schema, profilePath);
+  return normalizeProfile(profile);
+}
+
+export async function createProfileInteractively(baseProfile) {
+  return withReadline(async (rl) => {
+    const profile = { ...baseProfile };
+
+    for (const question of PROFILE_QUESTIONS) {
+      profile[question.key] = await askChoice(rl, question.prompt, question.options, profile[question.key]);
+    }
+
+    return normalizeProfile(profile);
+  });
+}
+
+export async function maybeInitializeProfileInteractively(packageRoot, profilePath) {
+  const shouldInit = await withReadline((rl) => promptYesNo(rl, `Profile not found at ${profilePath}. Initialize it with package defaults?`, true));
+
+  if (!shouldInit) {
+    throw new Error("Profile initialization declined by user.");
+  }
+
+  await mkdir(path.dirname(profilePath), { recursive: true });
+  await copyFile(getBundledProfilePath(packageRoot), profilePath);
+  console.log(`Profile initialized at ${profilePath}`);
+}
+
+export async function resolveBundledOrDefaultProfile(packageRoot, schema) {
+  const bundledProfilePath = getBundledProfilePath(packageRoot);
+
+  if (await pathExists(bundledProfilePath)) {
+    return { profile: await readAndValidateProfile(bundledProfilePath, schema), profilePathForMetadata: null };
+  }
+
+  validateProfile(DEFAULT_PROFILE, schema, "hardcoded defaults");
+  return { profile: normalizeProfile(DEFAULT_PROFILE), profilePathForMetadata: null };
+}
+
+export async function resolveProfileForInit(packageRoot, targetPath, rawOptions, schema) {
+  const bundledProfilePath = getBundledProfilePath(packageRoot);
+
+  if (!rawOptions.profilePath) {
+    if (!(await pathExists(bundledProfilePath))) {
+      if (rawOptions.yes) {
+        return resolveBundledOrDefaultProfile(packageRoot, schema);
+      }
+
+      await writeJsonFile(bundledProfilePath, normalizeProfile(DEFAULT_PROFILE));
+    }
+
+    return { profile: await readAndValidateProfile(bundledProfilePath, schema), profilePathForMetadata: null };
+  }
+
+  const requestedPath = path.resolve(targetPath, rawOptions.profilePath);
+
+  if (!(await pathExists(requestedPath))) {
+    if (rawOptions.yes) {
+      return resolveBundledOrDefaultProfile(packageRoot, schema);
+    }
+
+    await maybeInitializeProfileInteractively(packageRoot, requestedPath);
+  }
+
+  return { profile: await readAndValidateProfile(requestedPath, schema), profilePathForMetadata: getRelativeProfilePath(requestedPath, targetPath) };
+}
+
+export async function resolveProfileForRefactor(packageRoot, targetPath, rawOptions, schema, projectMetadata) {
+  let selectedProfilePath;
+
+  if (rawOptions.profilePath) {
+    selectedProfilePath = path.resolve(targetPath, rawOptions.profilePath);
+  } else if (typeof projectMetadata.profilePath === "string" && projectMetadata.profilePath.trim().length > 0) {
+    selectedProfilePath = path.resolve(targetPath, projectMetadata.profilePath);
+  }
+
+  if (!selectedProfilePath) {
+    return resolveBundledOrDefaultProfile(packageRoot, schema);
+  }
+
+  if (!(await pathExists(selectedProfilePath))) {
+    if (rawOptions.yes) {
+      return resolveBundledOrDefaultProfile(packageRoot, schema);
+    }
+
+    await maybeInitializeProfileInteractively(packageRoot, selectedProfilePath);
+  }
+
+  return {
+    profile: await readAndValidateProfile(selectedProfilePath, schema),
+    profilePathForMetadata: getRelativeProfilePath(selectedProfilePath, targetPath),
+  };
+}

package/lib/project/ai-instructions.mjs

@@ -0,0 +1,28 @@
+import { loadRuleCatalog } from "../contract/load-rule-catalog.mjs";
+import { renderAdapterFiles, renderExampleFiles, renderProjectAgents, renderProjectRules, renderSkillFiles } from "../contract/render-agents.mjs";
+import { renderContractJson } from "../contract/render-contract-json.mjs";
+import { resolveContract } from "../contract/resolve-contract.mjs";
+import { formatFilesWithBiome } from "../utils/fs.mjs";
+import { collectManagedFiles } from "./managed-files.mjs";
+import { renderPromptFiles } from "./prompt-files.mjs";
+
+export async function generateAiInstructions(options) {
+  const { packageRoot, packageVersion, targetDir, tokens, profile, template, withAiAdapters, workflow = "init" } = options;
+  const ruleCatalog = await loadRuleCatalog(packageRoot);
+  const managedFiles = await collectManagedFiles(packageRoot, withAiAdapters);
+  const contract = resolveContract({ packageVersion, projectName: tokens.projectName, template, profile, withAiAdapters, managedFiles, ruleCatalog });
+
+  await renderContractJson(targetDir, contract);
+  await formatFilesWithBiome(packageRoot, targetDir, ["ai/contract.json"]);
+  await renderProjectAgents(packageRoot, targetDir, contract);
+  await renderSkillFiles(packageRoot, targetDir, tokens);
+  await renderProjectRules(packageRoot, targetDir, contract);
+  await renderPromptFiles(packageRoot, targetDir, tokens, workflow);
+
+  if (withAiAdapters) {
+    await renderAdapterFiles(packageRoot, targetDir, tokens);
+    await renderExampleFiles(packageRoot, targetDir, tokens);
+  }
+
+  return contract;
+}

package/lib/project/biome-ignore.mjs

@@ -0,0 +1,14 @@
+import path from "node:path";
+
+import { writeTextFile } from "../utils/fs.mjs";
+
+const DEFAULT_BIOME_IGNORE_LINES = ["node_modules", "dist", "coverage", ".code-standards"];
+
+function buildBiomeIgnoreLines(managedFiles = []) {
+  return [...new Set([...DEFAULT_BIOME_IGNORE_LINES, ...managedFiles])].sort((left, right) => left.localeCompare(right));
+}
+
+export async function ensureBiomeIgnore(targetDir, managedFiles = []) {
+  const targetPath = path.join(targetDir, ".biomeignore");
+  await writeTextFile(targetPath, `${buildBiomeIgnoreLines(managedFiles).join("\n")}\n`);
+}

package/lib/project/managed-files.mjs

@@ -0,0 +1,105 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { MANAGED_AI_FILES } from "../constants.mjs";
+import { collectTemplateFiles, mirrorFile } from "../utils/fs.mjs";
+import { replaceTokens } from "../utils/text.mjs";
+import { writeProjectPackageJson } from "./package-metadata.mjs";
+import { collectPromptFiles } from "./prompt-files.mjs";
+
+export function mergePackageJsonFromTemplate(projectPackageJson, templatePackageJson) {
+  const mergedPackageJson = { ...projectPackageJson };
+  const mergedDependencies = { ...(projectPackageJson.dependencies ?? {}) };
+  const mergedScripts = { ...(projectPackageJson.scripts ?? {}) };
+  const mergedDevDependencies = { ...(projectPackageJson.devDependencies ?? {}) };
+
+  for (const [dependencyName, dependencyVersion] of Object.entries(templatePackageJson.dependencies ?? {})) {
+    mergedDependencies[dependencyName] = dependencyVersion;
+  }
+
+  for (const [scriptName, scriptValue] of Object.entries(templatePackageJson.scripts ?? {})) {
+    mergedScripts[scriptName] = scriptValue;
+  }
+
+  for (const [dependencyName, dependencyVersion] of Object.entries(templatePackageJson.devDependencies ?? {})) {
+    mergedDevDependencies[dependencyName] = dependencyVersion;
+  }
+
+  mergedPackageJson.scripts = mergedScripts;
+  mergedPackageJson.dependencies = mergedDependencies;
+  mergedPackageJson.devDependencies = mergedDevDependencies;
+
+  for (const key of ["type", "main", "types", "exports", "files"]) {
+    if (templatePackageJson[key] !== undefined) {
+      mergedPackageJson[key] = templatePackageJson[key];
+    }
+  }
+
+  return mergedPackageJson;
+}
+
+export async function applyManagedFiles(options) {
+  const { templateDir, targetDir, tokens, projectPackageJson, dryRun } = options;
+  const templateFiles = await collectTemplateFiles(templateDir);
+  const updatedFiles = [];
+  let mergedPackageJson = { ...projectPackageJson };
+
+  for (const templateFile of templateFiles) {
+    if (templateFile.targetRelativePath === "package.json") {
+      const templatePackageJson = JSON.parse(replaceTokens(await readFile(templateFile.sourcePath, "utf8"), tokens));
+      mergedPackageJson = mergePackageJsonFromTemplate(mergedPackageJson, templatePackageJson);
+      updatedFiles.push("package.json");
+      continue;
+    }
+
+    updatedFiles.push(templateFile.targetRelativePath);
+
+    if (dryRun) {
+      continue;
+    }
+
+    await mirrorFile(templateFile.sourcePath, path.join(targetDir, templateFile.targetRelativePath), tokens);
+  }
+
+  if (!dryRun) {
+    await writeProjectPackageJson(path.join(targetDir, "package.json"), mergedPackageJson);
+  }
+
+  return { updatedFiles, mergedPackageJson };
+}
+
+export async function collectAiFiles(packageRoot, withAiAdapters = true) {
+  const { readdir } = await import("node:fs/promises");
+  const aiFiles = [...MANAGED_AI_FILES];
+  const adaptersTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "adapters");
+  const examplesTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "examples");
+  const skillsTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "skills");
+  const adapterEntries = await readdir(adaptersTemplateDir, { withFileTypes: true });
+  const exampleTemplateFiles = await collectTemplateFiles(examplesTemplateDir);
+  const skillTemplateFiles = await collectTemplateFiles(skillsTemplateDir);
+
+  for (const skillFile of skillTemplateFiles) {
+    aiFiles.push(path.join("skills", skillFile.targetRelativePath));
+  }
+
+  if (!withAiAdapters) {
+    return aiFiles.sort((left, right) => left.localeCompare(right));
+  }
+
+  for (const entry of adapterEntries) {
+    if (entry.isFile() && entry.name.endsWith(".template.md")) {
+      aiFiles.push(path.join("ai", entry.name.replace(/\.template\.md$/, ".md")));
+    }
+  }
+
+  for (const exampleFile of exampleTemplateFiles) {
+    aiFiles.push(path.join("ai", "examples", exampleFile.targetRelativePath));
+  }
+
+  return aiFiles.sort((left, right) => left.localeCompare(right));
+}
+
+export async function collectManagedFiles(packageRoot, withAiAdapters = true) {
+  const [aiFiles, promptFiles] = await Promise.all([collectAiFiles(packageRoot, withAiAdapters), collectPromptFiles(packageRoot)]);
+  return [...new Set([...aiFiles, ...promptFiles])].sort((left, right) => left.localeCompare(right));
+}

package/lib/project/package-metadata.mjs

@@ -0,0 +1,132 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+import { CODE_STANDARDS_METADATA_KEY, CONTRACT_FORMAT_VERSION } from "../constants.mjs";
+import { asPlainObject, pathExists, readJsonFile, writeJsonFile } from "../utils/fs.mjs";
+
+const OBSOLETE_METADATA_KEYS = ["lastRefreshWith"];
+
+export function getRelativeProfilePath(profilePath, targetPath) {
+  if (!profilePath) {
+    return null;
+  }
+
+  const resolvedProfilePath = path.resolve(targetPath, profilePath);
+  const relativePath = path.relative(targetPath, resolvedProfilePath);
+
+  if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    return null;
+  }
+
+  return relativePath;
+}
+
+export async function readProjectPackageJson(targetPath) {
+  const packageJsonPath = path.join(targetPath, "package.json");
+
+  if (!(await pathExists(packageJsonPath))) {
+    throw new Error(`package.json was not found in ${targetPath}. Run refactor from the project root.`);
+  }
+
+  return { packageJsonPath, packageJson: await readJsonFile(packageJsonPath) };
+}
+
+export async function writeProjectPackageJson(packageJsonPath, packageJson) {
+  await writeJsonFile(packageJsonPath, packageJson);
+}
+
+export function extractRepositoryUrl(projectPackageJson) {
+  if (typeof projectPackageJson.repository === "string") {
+    return projectPackageJson.repository;
+  }
+
+  const repository = asPlainObject(projectPackageJson.repository);
+  return typeof repository.url === "string" ? repository.url : "";
+}
+
+export function applyPackageCoordinates(projectPackageJson, packageName, repositoryUrl) {
+  return { ...projectPackageJson, name: packageName, repository: { type: "git", url: repositoryUrl } };
+}
+
+export function updateCodeStandardsMetadata(projectPackageJson, metadataPatch) {
+  const existingMetadata = asPlainObject(projectPackageJson[CODE_STANDARDS_METADATA_KEY]);
+  const nextMetadata = { ...existingMetadata, ...metadataPatch, contractVersion: CONTRACT_FORMAT_VERSION };
+
+  for (const metadataKey of OBSOLETE_METADATA_KEYS) {
+    delete nextMetadata[metadataKey];
+  }
+
+  return { ...projectPackageJson, [CODE_STANDARDS_METADATA_KEY]: nextMetadata };
+}
+
+function isRegistryDependencyRange(versionRange) {
+  return typeof versionRange === "string" && versionRange.length > 0 && !/^(workspace:|file:|link:|git\+|https?:|github:|npm:)/.test(versionRange);
+}
+
+function getVersionPrefix(versionRange) {
+  const match = versionRange.match(/^([\^~])/);
+  return match ? match[1] : "";
+}
+
+async function readLatestPublishedVersion(packageName, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn("npm", ["view", packageName, "version", "--json"], {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+      shell: process.platform === "win32",
+    });
+    let stdout = "";
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+
+    child.on("error", () => resolve(null));
+    child.on("exit", (code) => {
+      if (code !== 0) {
+        resolve(null);
+        return;
+      }
+
+      try {
+        const parsed = JSON.parse(stdout.trim());
+        resolve(typeof parsed === "string" && parsed.length > 0 ? parsed : null);
+      } catch {
+        resolve(null);
+      }
+    });
+  });
+}
+
+async function refreshDependencyBlock(dependencies, options) {
+  const refreshedDependencies = { ...dependencies };
+  const resolveLatestVersion = options.resolveLatestVersion ?? ((dependencyName) => readLatestPublishedVersion(dependencyName, options.cwd));
+
+  for (const [dependencyName, versionRange] of Object.entries(dependencies ?? {})) {
+    if (dependencyName === "@sha3/code") {
+      refreshedDependencies[dependencyName] = `${getVersionPrefix(versionRange)}${options.codeStandardsVersion}`;
+      continue;
+    }
+
+    if (!isRegistryDependencyRange(versionRange)) {
+      continue;
+    }
+
+    const latestPublishedVersion = await resolveLatestVersion(dependencyName);
+    if (!latestPublishedVersion) {
+      continue;
+    }
+
+    refreshedDependencies[dependencyName] = `${getVersionPrefix(versionRange)}${latestPublishedVersion}`;
+  }
+
+  return refreshedDependencies;
+}
+
+export async function refreshPackageDependencyVersions(projectPackageJson, options) {
+  return {
+    ...projectPackageJson,
+    dependencies: await refreshDependencyBlock(projectPackageJson.dependencies, options),
+    devDependencies: await refreshDependencyBlock(projectPackageJson.devDependencies, options),
+  };
+}

package/lib/project/prompt-files.mjs

@@ -0,0 +1,111 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { collectTemplateFiles, mirrorFile } from "../utils/fs.mjs";
+
+async function readPromptTemplateFiles(packageRoot) {
+  return collectTemplateFiles(path.join(packageRoot, "prompts"));
+}
+
+async function buildRootPrompt(packageRoot, targetDir, tokens, workflow) {
+  const promptPath = path.join(packageRoot, "prompts", `${workflow}.prompt.md`);
+  const promptRaw = await readFile(promptPath, "utf8");
+  const renderedPrompt = promptRaw.replaceAll("{{projectName}}", tokens.projectName ?? "");
+  const rootPromptPath = path.join(targetDir, "PROMPT.md");
+  const phasePaths =
+    workflow === "init"
+      ? ["prompts/init.prompt.md", "prompts/init-phase-2-implement.md", "prompts/init-phase-3-verify.md"]
+      : ["prompts/refactor.prompt.md", "prompts/refactor-phase-2-rebuild.md", "prompts/refactor-phase-3-verify.md"];
+  const implementationLines =
+    workflow === "init"
+      ? [
+          "Complete this section before starting phase 1.",
+          "Describe the behavior you want to implement, the expected public API, runtime constraints, and any explicit non-goals.",
+          "",
+          "Task:",
+          "- ",
+          "",
+          "Public API:",
+          "- ",
+          "",
+          "Runtime constraints:",
+          "- ",
+          "",
+          "Non-goals:",
+          "- ",
+          "",
+        ]
+      : [
+          "Complete this section before starting phase 1.",
+          "Describe the contracts that must survive the refactor, the intended target behavior, runtime constraints, and anything that should intentionally not be preserved.",
+          "",
+          "Task:",
+          "- ",
+          "",
+          "Must preserve:",
+          "- ",
+          "",
+          "Can simplify or drop:",
+          "- ",
+          "",
+          "Runtime constraints:",
+          "- ",
+          "",
+        ];
+  const promptBody = [
+    "# Single LLM Entry Point",
+    "",
+    `This repository is prepared for the \`${workflow}\` workflow.`,
+    "The user should only complete the request section below and then paste this `PROMPT.md` file into the LLM.",
+    "The LLM must read the referenced phase files itself, follow them internally, and complete the workflow end to end without asking the user to orchestrate phase handoffs.",
+    "",
+    "## LLM Execution Contract",
+    "",
+    "1. Read `PROMPT.md` first.",
+    `2. Open \`${phasePaths[0]}\`, then continue through \`${phasePaths[1]}\` and \`${phasePaths[2]}\` yourself.`,
+    "3. Treat the phase files as internal workflow instructions, not as separate user prompts.",
+    "4. Load optional skills only when their trigger condition actually applies.",
+    "5. Do not stop between phases unless you are blocked by a real ambiguity or missing information that cannot be resolved from repository context.",
+    "",
+    "## Always True",
+    "",
+    "- You MUST implement the task without editing managed files unless this is a standards update.",
+    "- Managed files are ignored by Biome by default; do not remove those ignores during normal feature work.",
+    "- `single-return` stays strict outside `src/http/**`; in HTTP transport files, early returns are allowed when they keep validation and response flow clearer.",
+    "- You MUST execute `npm run check` yourself before finishing.",
+    "- If `npm run check` fails, you MUST fix the issues and rerun it until it passes.",
+    "- As the final step, you MUST create or update `SCAFFOLD-FEEDBACK.md` in the project root with concrete feedback on scaffold issues, ambiguities, friction, and improvements.",
+    "",
+    "## Phase Files",
+    "",
+    ...phasePaths.map((phasePath) => `- \`${phasePath}\``),
+    "",
+    "## Phase 1 Entry Prompt",
+    "",
+    renderedPrompt.trimEnd(),
+    "",
+    "## User Request",
+    "",
+    ...implementationLines,
+  ].join("\n");
+
+  return { promptBody, rootPromptPath };
+}
+
+export async function renderPromptFiles(packageRoot, targetDir, tokens, workflow = "init") {
+  const promptFiles = await readPromptTemplateFiles(packageRoot);
+
+  for (const promptFile of promptFiles) {
+    await mirrorFile(promptFile.sourcePath, path.join(targetDir, "prompts", promptFile.targetRelativePath), tokens);
+  }
+
+  const { promptBody, rootPromptPath } = await buildRootPrompt(packageRoot, targetDir, tokens, workflow);
+  await writeFile(rootPromptPath, promptBody, "utf8");
+}
+
+export async function collectPromptFiles(packageRoot) {
+  const promptFiles = await readPromptTemplateFiles(packageRoot);
+  return ["PROMPT.md", ...promptFiles.map((promptFile) => path.join("prompts", promptFile.targetRelativePath))].sort((left, right) =>
+    left.localeCompare(right),
+  );
+}

package/lib/project/template-resolution.mjs

@@ -0,0 +1,70 @@
+import { constants } from "node:fs";
+import { access, readdir } from "node:fs/promises";
+import path from "node:path";
+
+import { NODE_LIB_TEMPLATE_SIGNATURE, NODE_SERVICE_START_SIGNATURE, TEMPLATE_NAMES } from "../constants.mjs";
+import { pathExists } from "../utils/fs.mjs";
+
+export async function validateInitResources(packageRoot, templateName) {
+  const templateDir = path.join(packageRoot, "templates", templateName);
+  const agentsTemplatePath = path.join(packageRoot, "resources", "ai", "templates", "agents.project.template.md");
+  const adaptersTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "adapters");
+  const examplesTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "examples");
+
+  await access(templateDir, constants.R_OK);
+  await access(agentsTemplatePath, constants.R_OK);
+  await access(adaptersTemplateDir, constants.R_OK);
+  await access(examplesTemplateDir, constants.R_OK);
+
+  return { templateDir };
+}
+
+export async function resolveTemplateForRefactor(rawOptions, projectPackageJson, targetPath) {
+  if (rawOptions.template) {
+    return rawOptions.template;
+  }
+
+  const metadata = typeof projectPackageJson.codeStandards === "object" && projectPackageJson.codeStandards ? projectPackageJson.codeStandards : {};
+
+  if (typeof metadata.template === "string" && TEMPLATE_NAMES.includes(metadata.template)) {
+    return metadata.template;
+  }
+
+  const projectScripts = typeof projectPackageJson.scripts === "object" && projectPackageJson.scripts ? projectPackageJson.scripts : {};
+  const startScript = typeof projectScripts.start === "string" ? projectScripts.start : "";
+
+  if (startScript.includes(NODE_SERVICE_START_SIGNATURE)) {
+    return "node-service";
+  }
+
+  const hasNodeLibSignature =
+    (await pathExists(path.join(targetPath, "tsconfig.build.json"))) &&
+    projectPackageJson.main === NODE_LIB_TEMPLATE_SIGNATURE.main &&
+    projectPackageJson.types === NODE_LIB_TEMPLATE_SIGNATURE.types;
+
+  if (hasNodeLibSignature) {
+    return "node-lib";
+  }
+
+  throw new Error("Unable to infer template for refactor. Use --template <node-lib|node-service>.");
+}
+
+export async function listRelativeFiles(baseDir, currentDir = baseDir) {
+  const entries = await readdir(currentDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(currentDir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await listRelativeFiles(baseDir, fullPath)));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(path.relative(baseDir, fullPath));
+    }
+  }
+
+  return files;
+}

package/lib/refactor/materialize-refactor-context.mjs

@@ -0,0 +1,106 @@
+import { copyFile, mkdir, readdir, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  MANAGED_PROJECT_SURFACE_ROOTS,
+  REFACTOR_ANALYSIS_SUMMARY_PATH,
+  REFACTOR_LATEST_DIR,
+  REFACTOR_PRESERVATION_PATH,
+  REFACTOR_PUBLIC_CONTRACT_PATH,
+  isRefactorArtifactPath,
+} from "../constants.mjs";
+import { copyDirectoryWithFilter, pathExists, removePathIfExists, writeJsonFile } from "../utils/fs.mjs";
+
+const SNAPSHOT_IGNORED_TOP_LEVEL_NAMES = new Set(["node_modules", "dist", "coverage", ".git", ".code-standards"]);
+
+function shouldSkipSnapshotRelativePath(relativePath) {
+  const normalizedPath = relativePath.split(path.sep).join("/");
+  const topLevelName = normalizedPath.split("/")[0];
+
+  return isRefactorArtifactPath(normalizedPath) || SNAPSHOT_IGNORED_TOP_LEVEL_NAMES.has(topLevelName);
+}
+
+async function movePath(sourcePath, targetPath) {
+  await mkdir(path.dirname(targetPath), { recursive: true });
+
+  try {
+    await rename(sourcePath, targetPath);
+  } catch (error) {
+    if (!(error instanceof Error) || !("code" in error) || error.code !== "EXDEV") {
+      throw error;
+    }
+
+    const sourceExists = await pathExists(sourcePath);
+
+    if (!sourceExists) {
+      return;
+    }
+
+    const sourceStat = await stat(sourcePath);
+
+    if (sourceStat.isDirectory()) {
+      await copyDirectoryWithFilter(sourcePath, targetPath, () => false);
+      await removePathIfExists(sourcePath);
+      return;
+    }
+
+    await copyFile(sourcePath, targetPath);
+    await removePathIfExists(sourcePath);
+  }
+}
+
+async function moveProjectContentsToSnapshot(targetPath, latestReferenceDir) {
+  await mkdir(latestReferenceDir, { recursive: true });
+  const entries = await readdir(targetPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const relativePath = entry.name;
+
+    if (shouldSkipSnapshotRelativePath(relativePath)) {
+      continue;
+    }
+
+    await movePath(path.join(targetPath, entry.name), path.join(latestReferenceDir, entry.name));
+  }
+}
+
+export async function materializeRefactorContext(targetPath, publicContract, preservation, analysisSummary) {
+  const latestReferenceDir = path.join(targetPath, REFACTOR_LATEST_DIR);
+
+  await removePathIfExists(latestReferenceDir);
+  await moveProjectContentsToSnapshot(targetPath, latestReferenceDir);
+  await writeJsonFile(path.join(targetPath, REFACTOR_PUBLIC_CONTRACT_PATH), publicContract);
+  await writeJsonFile(path.join(targetPath, REFACTOR_PRESERVATION_PATH), preservation);
+  await writeFile(path.join(targetPath, REFACTOR_ANALYSIS_SUMMARY_PATH), `${analysisSummary}\n`, "utf8");
+
+  return {
+    latestReferenceDir,
+    publicContractPath: path.join(targetPath, REFACTOR_PUBLIC_CONTRACT_PATH),
+    preservationPath: path.join(targetPath, REFACTOR_PRESERVATION_PATH),
+    analysisSummaryPath: path.join(targetPath, REFACTOR_ANALYSIS_SUMMARY_PATH),
+  };
+}
+
+export async function removeManagedProjectSurface(templateDir, targetDir) {
+  const { collectTemplateFiles } = await import("../utils/fs.mjs");
+
+  const templateFiles = await collectTemplateFiles(templateDir);
+  const removableRoots = new Set(MANAGED_PROJECT_SURFACE_ROOTS);
+
+  for (const templateFile of templateFiles) {
+    if (templateFile.targetRelativePath === "package.json") {
+      continue;
+    }
+
+    const normalizedPath = templateFile.targetRelativePath.split(path.sep).join("/");
+    const [topLevelName] = normalizedPath.split("/");
+
+    if (topLevelName.length > 0) {
+      removableRoots.add(topLevelName);
+    }
+  }
+
+  for (const rootName of removableRoots) {
+    await removePathIfExists(path.join(targetDir, rootName));
+  }
+}