@sha3/code 1.0.0

package/lib/refactor/preservation-questions.mjs

@@ -0,0 +1,33 @@
+import { promptYesNo, withReadline } from "../utils/prompts.mjs";
+
+const DEFAULTS = {
+  publicApi: true,
+  persistence: true,
+  transport: true,
+  configuration: true,
+  runtimeBoundaries: true,
+};
+
+export function getDefaultPreservationDecisions() {
+  return { ...DEFAULTS };
+}
+
+export async function resolvePreservationDecisions(rawOptions) {
+  if (rawOptions.yes || !process.stdin.isTTY) {
+    return getDefaultPreservationDecisions();
+  }
+
+  return withReadline(async (rl) => {
+    const publicApi = await promptYesNo(rl, "Preserve public package contracts (exports, public names, observable types/shapes)?", DEFAULTS.publicApi);
+    const persistence = await promptYesNo(rl, "Preserve persistence contracts (DB schema, migrations, table and column names)?", DEFAULTS.persistence);
+    const transport = await promptYesNo(rl, "Preserve transport contracts (HTTP routes, status codes, message payloads)?", DEFAULTS.transport);
+    const configuration = await promptYesNo(rl, "Preserve configuration contracts (env vars, config keys, config filenames)?", DEFAULTS.configuration);
+    const runtimeBoundaries = await promptYesNo(
+      rl,
+      "Preserve runtime and package boundaries (ESM/CJS mode, bin scripts, exports map, build artifacts)?",
+      DEFAULTS.runtimeBoundaries,
+    );
+
+    return { publicApi, persistence, transport, configuration, runtimeBoundaries };
+  });
+}

package/lib/refactor/public-contract-extractor.mjs

@@ -0,0 +1,22 @@
+export function extractPublicContract(projectPackageJson, template, profilePath, sourceAnalysis) {
+  return {
+    template,
+    profilePath,
+    package: {
+      name: projectPackageJson.name ?? null,
+      version: projectPackageJson.version ?? null,
+      type: projectPackageJson.type ?? null,
+      main: projectPackageJson.main ?? null,
+      types: projectPackageJson.types ?? null,
+      exports: projectPackageJson.exports ?? null,
+      bin: projectPackageJson.bin ?? null,
+    },
+    repository: projectPackageJson.repository ?? null,
+    publicEntrypoints: sourceAnalysis.entrypoints,
+    compatibilitySurface: {
+      hasDatabaseSurface: sourceAnalysis.hasDatabaseSurface,
+      hasTransportSurface: sourceAnalysis.hasTransportSurface,
+      envVars: sourceAnalysis.envVars,
+    },
+  };
+}

package/lib/refactor/render-analysis-summary.mjs

@@ -0,0 +1,50 @@
+function renderList(items, fallback = "- none detected") {
+  if (!items || items.length === 0) {
+    return fallback;
+  }
+
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+export function renderAnalysisSummary(projectPackageJson, sourceAnalysis, preservation) {
+  const publicEntrypoints = sourceAnalysis.entrypoints.map((entrypoint) => `\`${entrypoint.kind}\`: \`${JSON.stringify(entrypoint.value)}\``);
+  const compatibilityNotes = [
+    `- preserve public API: ${preservation.publicApi ? "yes" : "no"}`,
+    `- preserve persistence contracts: ${preservation.persistence ? "yes" : "no"}`,
+    `- preserve transport contracts: ${preservation.transport ? "yes" : "no"}`,
+    `- preserve configuration surface: ${preservation.configuration ? "yes" : "no"}`,
+    `- preserve runtime/package boundaries: ${preservation.runtimeBoundaries ? "yes" : "no"}`,
+  ].join("\n");
+
+  return `# Refactor Analysis Summary
+
+## Package
+
+- name: \`${projectPackageJson.name ?? "unknown"}\`
+- version: \`${projectPackageJson.version ?? "unknown"}\`
+- module type: \`${projectPackageJson.type ?? "unknown"}\`
+- inferred architecture: ${sourceAnalysis.architecture}
+
+## Public Entrypoints
+
+${renderList(publicEntrypoints)}
+
+## Surfaces
+
+- database-related files detected: ${sourceAnalysis.hasDatabaseSurface ? "yes" : "no"}
+- transport-related files detected: ${sourceAnalysis.hasTransportSurface ? "yes" : "no"}
+
+## Environment Variables
+
+${renderList(sourceAnalysis.envVars.map((envVar) => `\`${envVar}\``))}
+
+## Source Layout
+
+- source files: ${sourceAnalysis.sourceFiles.length}
+- test files: ${sourceAnalysis.testFiles.length}
+
+## Preservation Decisions
+
+${compatibilityNotes}
+`;
+}

package/lib/refactor/source-analysis.mjs

@@ -0,0 +1,74 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { listRelativeFiles } from "../project/template-resolution.mjs";
+
+const DATABASE_PATH_PATTERN = /(^|\/)(db|database|prisma|drizzle|sequelize|typeorm|migrations?)(\/|$)/i;
+const TRANSPORT_PATH_PATTERN = /(^|\/)(http|server|routes?|controllers?|handlers?|events?|messages?)(\/|$)/i;
+const ENV_VAR_PATTERN = /\bprocess\.env\.([A-Z0-9_]+)/g;
+
+function summarizeArchitecture(files) {
+  if (files.some((filePath) => filePath.startsWith("src/app/")) || files.some((filePath) => filePath.startsWith("src/http/"))) {
+    return "service-oriented feature folders";
+  }
+
+  if (files.some((filePath) => filePath.startsWith("src/") && filePath.split("/").length >= 3)) {
+    return "feature folders";
+  }
+
+  return "flat module layout";
+}
+
+function collectPublicEntrypoints(projectPackageJson) {
+  const entrypoints = [];
+
+  if (projectPackageJson.main) {
+    entrypoints.push({ kind: "main", value: projectPackageJson.main });
+  }
+
+  if (projectPackageJson.types) {
+    entrypoints.push({ kind: "types", value: projectPackageJson.types });
+  }
+
+  if (projectPackageJson.bin) {
+    entrypoints.push({ kind: "bin", value: projectPackageJson.bin });
+  }
+
+  if (projectPackageJson.exports) {
+    entrypoints.push({ kind: "exports", value: projectPackageJson.exports });
+  }
+
+  return entrypoints;
+}
+
+async function collectEnvVars(targetPath, files) {
+  const envVars = new Set();
+
+  for (const filePath of files.filter((candidate) => candidate.endsWith(".ts") || candidate === ".env.example")) {
+    const raw = await readFile(path.join(targetPath, filePath), "utf8").catch(() => "");
+    const matches = raw.matchAll(ENV_VAR_PATTERN);
+
+    for (const match of matches) {
+      envVars.add(match[1]);
+    }
+  }
+
+  return [...envVars].sort((left, right) => left.localeCompare(right));
+}
+
+export async function analyzeProjectSource(targetPath, projectPackageJson) {
+  const files = await listRelativeFiles(targetPath);
+  const envVars = await collectEnvVars(targetPath, files);
+
+  return {
+    files,
+    packageType: typeof projectPackageJson.type === "string" ? projectPackageJson.type : null,
+    entrypoints: collectPublicEntrypoints(projectPackageJson),
+    architecture: summarizeArchitecture(files),
+    hasDatabaseSurface: files.some((filePath) => DATABASE_PATH_PATTERN.test(filePath)),
+    hasTransportSurface: files.some((filePath) => TRANSPORT_PATH_PATTERN.test(filePath)),
+    envVars,
+    testFiles: files.filter((filePath) => filePath.startsWith("test/")),
+    sourceFiles: files.filter((filePath) => filePath.startsWith("src/")),
+  };
+}

package/lib/utils/fs.mjs

@@ -0,0 +1,220 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access, copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import Ajv2020 from "ajv/dist/2020.js";
+
+import { PROFILE_KEY_ORDER } from "../constants.mjs";
+import { mapTemplateFileName, replaceTokens } from "./text.mjs";
+
+export async function readJsonFile(filePath) {
+  const raw = await readFile(filePath, "utf8");
+  return JSON.parse(raw);
+}
+
+export async function writeJsonFile(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export async function writeTextFile(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, value, "utf8");
+}
+
+export async function pathExists(targetPath) {
+  try {
+    await access(targetPath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureTargetReady(targetPath, force) {
+  const exists = await pathExists(targetPath);
+
+  if (!exists) {
+    await mkdir(targetPath, { recursive: true });
+    return;
+  }
+
+  const fileStat = await stat(targetPath);
+
+  if (!fileStat.isDirectory()) {
+    throw new Error(`Target exists and is not a directory: ${targetPath}`);
+  }
+
+  const entries = await readdir(targetPath);
+  const nonGitEntries = entries.filter((entry) => entry !== ".git");
+
+  if (nonGitEntries.length > 0 && !force) {
+    throw new Error(`Target directory is not empty: ${targetPath}. Use --force to continue and overwrite files.`);
+  }
+}
+
+export async function collectTemplateFiles(templateDir, baseDir = templateDir) {
+  const entries = await readdir(templateDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const sourcePath = path.join(templateDir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await collectTemplateFiles(sourcePath, baseDir)));
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const sourceRelativePath = path.relative(baseDir, sourcePath);
+    const sourceDirectory = path.dirname(sourceRelativePath);
+    const sourceFileName = path.basename(sourceRelativePath);
+    const mappedFileName = mapTemplateFileName(sourceFileName);
+    const targetRelativePath = sourceDirectory === "." ? mappedFileName : path.join(sourceDirectory, mappedFileName);
+
+    files.push({ sourcePath, sourceRelativePath, targetRelativePath });
+  }
+
+  return files.sort((left, right) => left.targetRelativePath.localeCompare(right.targetRelativePath));
+}
+
+export async function copyTemplateDirectory(sourceDir, targetDir, tokens) {
+  await mkdir(targetDir, { recursive: true });
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyTemplateDirectory(sourcePath, path.join(targetDir, entry.name), tokens);
+      continue;
+    }
+
+    if (entry.isSymbolicLink()) {
+      continue;
+    }
+
+    const raw = await readFile(sourcePath, "utf8");
+    const targetName = mapTemplateFileName(entry.name);
+    const targetPath = path.join(targetDir, targetName);
+    await writeFile(targetPath, replaceTokens(raw, tokens), "utf8");
+  }
+}
+
+export async function mirrorFile(sourcePath, targetPath, tokens) {
+  const raw = await readFile(sourcePath, "utf8");
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, replaceTokens(raw, tokens), "utf8");
+}
+
+export function asPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return value;
+}
+
+export function normalizeProfile(rawProfile) {
+  const normalized = {};
+
+  for (const key of PROFILE_KEY_ORDER) {
+    normalized[key] = rawProfile[key];
+  }
+
+  return normalized;
+}
+
+export function validateAgainstSchema(value, schema, sourceLabel) {
+  const ajv = new Ajv2020({ allErrors: true, strict: true });
+  const validate = ajv.compile(schema);
+  const valid = validate(value);
+
+  if (valid) {
+    return;
+  }
+
+  const details = (validate.errors ?? []).map((issue) => `${issue.instancePath || "/"}: ${issue.message ?? "invalid"}`).join("; ");
+  throw new Error(`Invalid data at ${sourceLabel}: ${details}`);
+}
+
+export async function runCommand(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: "inherit", shell: process.platform === "win32" });
+
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(new Error(`${command} ${args.join(" ")} exited with code ${code ?? "unknown"}`));
+    });
+  });
+}
+
+export async function formatFilesWithBiome(packageRoot, targetDir, relativePaths) {
+  const filesToFormat = [...new Set(relativePaths)].filter((relativePath) => typeof relativePath === "string" && relativePath.length > 0);
+
+  if (filesToFormat.length === 0) {
+    return;
+  }
+
+  const biomeBinPath = path.join(packageRoot, "node_modules", "@biomejs", "biome", "bin", "biome");
+
+  if (!(await pathExists(biomeBinPath))) {
+    throw new Error(`Biome binary was not found at ${biomeBinPath}. Install @biomejs/biome before running init or refactor.`);
+  }
+
+  await runCommand(process.execPath, [biomeBinPath, "format", "--write", ...filesToFormat], targetDir);
+}
+
+export async function copyFileIfExists(sourcePath, targetPath) {
+  if (!(await pathExists(sourcePath))) {
+    return;
+  }
+
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  await copyFile(sourcePath, targetPath);
+}
+
+export async function removePathIfExists(targetPath) {
+  if (!(await pathExists(targetPath))) {
+    return;
+  }
+
+  await rm(targetPath, { force: true, recursive: true });
+}
+
+export async function copyDirectoryWithFilter(sourceDir, targetDir, shouldSkipRelativePath, baseDir = sourceDir) {
+  await mkdir(targetDir, { recursive: true });
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const relativePath = path.relative(baseDir, sourcePath);
+
+    if (shouldSkipRelativePath(relativePath)) {
+      continue;
+    }
+
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirectoryWithFilter(sourcePath, targetPath, shouldSkipRelativePath, baseDir);
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await copyFile(sourcePath, targetPath);
+  }
+}

package/lib/utils/prompts.mjs

@@ -0,0 +1,63 @@
+import readline from "node:readline/promises";
+
+export async function askChoice(rl, prompt, options, defaultValue) {
+  const defaultIndex = options.indexOf(defaultValue);
+
+  if (defaultIndex < 0) {
+    throw new Error(`Invalid default value for question ${prompt}`);
+  }
+
+  console.log(`\n${prompt}`);
+
+  for (let index = 0; index < options.length; index += 1) {
+    console.log(`  ${index + 1}) ${options[index]}`);
+  }
+
+  const answer = await rl.question(`Select option [${defaultIndex + 1}]: `);
+  const normalized = answer.trim();
+
+  if (normalized.length === 0) {
+    return defaultValue;
+  }
+
+  const numeric = Number.parseInt(normalized, 10);
+
+  if (!Number.isNaN(numeric) && numeric >= 1 && numeric <= options.length) {
+    return options[numeric - 1];
+  }
+
+  if (options.includes(normalized)) {
+    return normalized;
+  }
+
+  throw new Error(`Invalid option for ${prompt}: ${answer}`);
+}
+
+export async function promptYesNo(rl, prompt, defaultYes = true) {
+  const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+  const answer = (await rl.question(`${prompt} ${suffix}: `)).trim().toLowerCase();
+
+  if (answer.length === 0) {
+    return defaultYes;
+  }
+
+  if (answer === "y" || answer === "yes") {
+    return true;
+  }
+
+  if (answer === "n" || answer === "no") {
+    return false;
+  }
+
+  throw new Error(`Invalid yes/no answer: ${answer}`);
+}
+
+export async function withReadline(action) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    return await action(rl);
+  } finally {
+    rl.close();
+  }
+}

package/lib/utils/text.mjs

@@ -0,0 +1,43 @@
+export function replaceTokens(template, tokens) {
+  let rendered = template;
+
+  for (const [key, value] of Object.entries(tokens)) {
+    rendered = rendered.replaceAll(`{{${key}}}`, value);
+  }
+
+  return rendered;
+}
+
+export function normalizePackageName(rawPackageName, projectName) {
+  if (!rawPackageName || rawPackageName.trim().length === 0) {
+    return `@sha3/${projectName}`;
+  }
+
+  return rawPackageName.trim();
+}
+
+export function defaultPackageNameForProject(projectName) {
+  return `@sha3/${projectName}`;
+}
+
+export function defaultRepositoryUrlForPackage(packageName) {
+  const repositoryName = packageName.replace(/^@/, "").replace("/", "/");
+  const normalizedRepositoryName = repositoryName.includes("/") ? repositoryName.split("/")[1] : repositoryName;
+  return `https://github.com/sha3dev/${normalizedRepositoryName}`;
+}
+
+export function normalizeRepositoryUrl(rawRepositoryUrl, packageName) {
+  if (!rawRepositoryUrl || rawRepositoryUrl.trim().length === 0) {
+    return defaultRepositoryUrlForPackage(packageName);
+  }
+
+  return rawRepositoryUrl.trim();
+}
+
+export function mapTemplateFileName(fileName) {
+  if (fileName === "gitignore") {
+    return ".gitignore";
+  }
+
+  return fileName;
+}

package/lib/verify/change-audit-verifier.mjs

@@ -0,0 +1,140 @@
+import ts from "typescript";
+
+import { pathExists } from "../utils/fs.mjs";
+import { createContractIssue, getActiveVerifyRuleIds, shouldRunRule } from "./issue-helpers.mjs";
+
+const MANAGED_FILE_PREFIXES = ["AGENTS.md", "SKILLS.md", "ai/", "prompts/", "skills/", "biome.json", "tsconfig.json", "tsconfig.build.json", ".vscode/"];
+
+function createIssue(contract, ruleId, relativePath, message, options = {}) {
+  return createContractIssue(contract, {
+    ruleId,
+    category: "change-audit",
+    relativePath,
+    message,
+    verificationMode: options.verificationMode,
+    confidence: options.confidence,
+    evidence: options.evidence,
+  });
+}
+
+export async function verifyChangeAudits(targetPath, contract, analysisContext, changedFilesContext, options = {}) {
+  const activeRuleIds = getActiveVerifyRuleIds(contract);
+  const issues = [];
+  const isRefactorSession = await pathExists(`${targetPath}/.code-standards/refactor-source/latest`);
+
+  if (activeRuleIds.has("managed-files-read-only") && shouldRunRule(options.onlyRuleIds, "managed-files-read-only")) {
+    issues.push(...verifyManagedFilesReadOnly(contract, changedFilesContext, isRefactorSession));
+  }
+
+  if (activeRuleIds.has("simplicity-audit") && shouldRunRule(options.onlyRuleIds, "simplicity-audit")) {
+    issues.push(...verifySimplicityAudit(contract, analysisContext));
+  }
+
+  if (activeRuleIds.has("no-speculative-abstractions") && shouldRunRule(options.onlyRuleIds, "no-speculative-abstractions")) {
+    issues.push(...verifyNoSpeculativeAbstractions(contract, analysisContext));
+  }
+
+  return issues;
+}
+
+function verifyManagedFilesReadOnly(contract, changedFilesContext, isRefactorSession) {
+  if (isRefactorSession) {
+    return [];
+  }
+
+  if (!changedFilesContext.available) {
+    return [];
+  }
+
+  const changedManagedFiles = changedFilesContext.files.filter((file) => MANAGED_FILE_PREFIXES.some((prefix) => file === prefix || file.startsWith(prefix)));
+  return changedManagedFiles.map((relativePath) =>
+    createIssue(contract, "managed-files-read-only", relativePath, "managed files are read-only during normal feature work", {
+      verificationMode: "audit",
+      confidence: "medium",
+    }),
+  );
+}
+
+function verifySimplicityAudit(contract, analysisContext) {
+  const issues = [];
+  const featureLayerCounts = new Map();
+
+  for (const file of analysisContext.sourceFiles) {
+    if (!file.featureName || file.relativePath.endsWith(".types.ts")) {
+      continue;
+    }
+
+    const role = file.relativePath.split("/").at(-1)?.split(".").slice(-2, -1)[0] ?? "unknown";
+    const roles = featureLayerCounts.get(file.featureName) ?? new Set();
+    roles.add(role);
+    featureLayerCounts.set(file.featureName, roles);
+  }
+
+  for (const [featureName, roles] of featureLayerCounts) {
+    if (roles.size >= 4) {
+      issues.push(
+        createIssue(
+          contract,
+          "simplicity-audit",
+          `src/${featureName}`,
+          "feature appears to have accumulated many role layers; review whether the design can be simplified",
+          {
+            verificationMode: "audit",
+            confidence: "medium",
+            evidence: [...roles].sort((left, right) => left.localeCompare(right)).join(", "),
+          },
+        ),
+      );
+    }
+  }
+
+  return issues;
+}
+
+function verifyNoSpeculativeAbstractions(contract, analysisContext) {
+  const issues = [];
+
+  for (const file of analysisContext.sourceFiles.filter((candidate) => candidate.relativePath.startsWith("src/"))) {
+    const wrapperSignals = countWrapperSignals(file.ast);
+    if (wrapperSignals >= 6) {
+      issues.push(
+        createIssue(
+          contract,
+          "no-speculative-abstractions",
+          file.relativePath,
+          "file appears to contain multiple abstraction signals without proof of current need",
+          {
+            verificationMode: "heuristic",
+            confidence: "medium",
+            evidence: `${wrapperSignals} wrapper signal(s)`,
+          },
+        ),
+      );
+    }
+  }
+
+  return issues;
+}
+
+function countWrapperSignals(ast) {
+  let count = 0;
+
+  function visit(node) {
+    if (ts.isTypeAliasDeclaration(node) && /Options$/.test(node.name.text)) {
+      count += 1;
+    }
+
+    if (ts.isMethodDeclaration(node) && ts.isIdentifier(node.name) && /^(create|build|make)/.test(node.name.text)) {
+      count += 1;
+    }
+
+    if (ts.isClassDeclaration(node) && node.name && /Factory|Builder|Wrapper/.test(node.name.text)) {
+      count += 2;
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(ast);
+  return count;
+}

package/lib/verify/change-context.mjs

@@ -0,0 +1,36 @@
+import { spawnSync } from "node:child_process";
+
+function runGit(args, cwd) {
+  return spawnSync("git", args, { cwd, encoding: "utf8" });
+}
+
+function parseChangedFiles(raw) {
+  return raw
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+}
+
+export function readChangedFiles(targetPath, options = {}) {
+  const hasGit = runGit(["rev-parse", "--is-inside-work-tree"], targetPath);
+  if (hasGit.status !== 0) {
+    return { available: false, files: [], reason: "git repository not available" };
+  }
+
+  if (options.allFiles) {
+    return { available: true, files: [], reason: "all-files" };
+  }
+
+  const args = options.staged
+    ? ["diff", "--name-only", "--cached", options.changedAgainst ?? "HEAD"]
+    : options.changedAgainst
+      ? ["diff", "--name-only", options.changedAgainst]
+      : ["diff", "--name-only", "HEAD"];
+  const result = runGit(args, targetPath);
+
+  if (result.status !== 0) {
+    return { available: false, files: [], reason: result.stderr.trim() || "unable to compute git diff" };
+  }
+
+  return { available: true, files: parseChangedFiles(result.stdout), reason: options.staged ? "staged" : (options.changedAgainst ?? "HEAD") };
+}