ai-check-template 0.2.0-alpha.0

package/src/cli/init.mjs

@@ -0,0 +1,433 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ciWorkflowFiles, ciWorkflowRelativePath, renderedCiWorkflow } from "./ci-workflows.mjs";
+import {
+  dependencyInstallOperation,
+  planDependencyInstall,
+  preflightDependencyInstaller,
+  runDependencyInstall,
+} from "./dependency-installer.mjs";
+import { renderClaudeHookSettings } from "./claude-hooks.mjs";
+import { installStatePath, writeInstallState } from "./install-state.mjs";
+import { DEFAULT_PACKAGE_MANAGER, detectPackageManager, validatePackageManager } from "./package-manager.mjs";
+import { getProfileDocFiles } from "./profile-docs.mjs";
+import { parseProfiles } from "./profile.mjs";
+import { getProfileScripts, getProfileSupportScripts } from "./profile-scripts.mjs";
+import {
+  CliError,
+  copyFileSafe,
+  fromTemplates,
+  pathExists,
+  readJson,
+  resolveTarget,
+  writeJson,
+  writeLine,
+} from "./utils.mjs";
+
+const INIT_USAGE = `ai-check-template init
+
+Usage:
+  ai-check-template init --target <dir> --profile <name> --yes [options]
+
+Options:
+  --target <dir>       Target project directory. Defaults to the current directory.
+  --profile <name>     Base profile, optionally with +supabase-rls. Defaults to react-nextjs.
+  --package-manager <name> Package manager: pnpm, npm, yarn, or bun. Defaults to target detection.
+  --ci <mode>          CI mode: direct, reusable, or none. Defaults to direct.
+  --claude-hooks       Copy Claude hook rule and merge hook settings.
+  --install-deps       Install missing dev dependencies for generated package scripts.
+  --dry-run            Print planned operations without writing files.
+  --yes                Confirm non-interactive writes.
+  --overwrite          Replace conflicting files/scripts.`;
+
+export async function runInit(argv, io = {}) {
+  const options = parseInitArgs(argv, io.cwd ?? process.cwd());
+
+  if (options.help) {
+    writeLine(io.stdout, INIT_USAGE);
+    return;
+  }
+
+  if (!options.yes && !options.dryRun) {
+    throw new CliError("Refusing to write without --yes. Use --dry-run to preview.");
+  }
+
+  const profile = parseProfiles(options.profile);
+  const targetDir = await normalizeTargetDir(options.target);
+  const packageJsonPath = path.join(targetDir, "package.json");
+  const packageManager = options.explicit.packageManager
+    ? options.packageManager
+    : await detectPackageManager(targetDir);
+  const writeOptions = { ...options, packageManager };
+
+  if (!(await pathExists(packageJsonPath))) {
+    throw new CliError(`Target project must contain package.json: ${packageJsonPath}`);
+  }
+
+  const dependencyInstallPlan = writeOptions.installDeps
+    ? await planDependencyInstall(packageJsonPath, profile, writeOptions.packageManager)
+    : null;
+
+  if (dependencyInstallPlan && !writeOptions.dryRun) {
+    preflightDependencyInstaller(dependencyInstallPlan, targetDir);
+  }
+
+  const operations = [];
+
+  await mergePackageScripts(packageJsonPath, profile, writeOptions, operations);
+  await copyScripts(targetDir, writeOptions, operations);
+  await copyProfileDocs(targetDir, profile, writeOptions, operations);
+  await copyCiFiles(targetDir, writeOptions, operations);
+
+  if (writeOptions.claudeHooks) {
+    await copyClaudeHooks(targetDir, writeOptions, operations);
+  }
+
+  await writeInitInstallState(targetDir, profile, writeOptions, operations);
+  await maybeInstallDependencies(targetDir, dependencyInstallPlan, writeOptions, operations);
+
+  writeLine(io.stdout, `ai-check-template init ${writeOptions.dryRun ? "dry-run" : "completed"}`);
+  writeLine(io.stdout, `target: ${targetDir}`);
+  writeLine(io.stdout, `profile: ${profile.all.join("+")}`);
+  writeLine(io.stdout, `package-manager: ${writeOptions.packageManager}`);
+  for (const operation of operations) {
+    writeLine(
+      io.stdout,
+      `${operation.action}: ${relativeTarget(targetDir, operation.targetPath)}${operation.reason ? ` (${operation.reason})` : ""}${operation.command ? ` [${operation.command}]` : ""}`,
+    );
+  }
+}
+
+function parseInitArgs(argv, cwd) {
+  const options = {
+    target: cwd,
+    profile: "react-nextjs",
+    packageManager: DEFAULT_PACKAGE_MANAGER,
+    ci: "direct",
+    claudeHooks: false,
+    installDeps: false,
+    dryRun: false,
+    yes: false,
+    overwrite: false,
+    help: false,
+    explicit: {
+      packageManager: false,
+    },
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === "--claude-hooks") {
+      options.claudeHooks = true;
+      continue;
+    }
+
+    if (arg === "--install-deps") {
+      options.installDeps = true;
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg === "--yes") {
+      options.yes = true;
+      continue;
+    }
+
+    if (arg === "--overwrite") {
+      options.overwrite = true;
+      continue;
+    }
+
+    if (arg.startsWith("--target=")) {
+      options.target = resolveTarget(arg.slice("--target=".length), cwd);
+      continue;
+    }
+
+    if (arg === "--target") {
+      options.target = resolveTarget(readFlagValue(argv, (index += 1), arg), cwd);
+      continue;
+    }
+
+    if (arg.startsWith("--profile=")) {
+      options.profile = arg.slice("--profile=".length);
+      continue;
+    }
+
+    if (arg === "--profile") {
+      options.profile = readFlagValue(argv, (index += 1), arg);
+      continue;
+    }
+
+    if (arg.startsWith("--package-manager=")) {
+      options.packageManager = validatePackageManager(arg.slice("--package-manager=".length));
+      options.explicit.packageManager = true;
+      continue;
+    }
+
+    if (arg === "--package-manager") {
+      options.packageManager = validatePackageManager(readFlagValue(argv, (index += 1), arg));
+      options.explicit.packageManager = true;
+      continue;
+    }
+
+    if (arg.startsWith("--ci=")) {
+      options.ci = arg.slice("--ci=".length);
+      continue;
+    }
+
+    if (arg === "--ci") {
+      options.ci = readFlagValue(argv, (index += 1), arg);
+      continue;
+    }
+
+    throw new CliError(`Unknown init option: ${arg}\n\n${INIT_USAGE}`);
+  }
+
+  if (!["direct", "reusable", "none"].includes(options.ci)) {
+    throw new CliError("--ci must be one of: direct, reusable, none");
+  }
+
+  return options;
+}
+
+function readFlagValue(argv, index, flagName) {
+  const value = argv[index];
+
+  if (!value || value.startsWith("--")) {
+    throw new CliError(`Missing value for ${flagName}`);
+  }
+
+  return value;
+}
+
+async function normalizeTargetDir(target) {
+  const resolved = path.resolve(target);
+
+  try {
+    return await fs.realpath(resolved);
+  } catch (error) {
+    throw new CliError(`Target directory does not exist: ${resolved}\n${error.message}`);
+  }
+}
+
+async function mergePackageScripts(packageJsonPath, profile, options, operations) {
+  const packageJson = await readJson(packageJsonPath);
+  const existingScripts = packageJson.scripts ?? {};
+  const expectedScripts = getProfileScripts(profile, { packageManager: options.packageManager });
+  const supportScripts = getProfileSupportScripts(profile);
+  const nextScripts = { ...existingScripts };
+  let changed = false;
+
+  for (const [name, command] of Object.entries(expectedScripts)) {
+    if (existingScripts[name] === command) {
+      operations.push({ action: "keep", reason: "same script", targetPath: packageJsonPath });
+      continue;
+    }
+
+    if (existingScripts[name] && !options.overwrite) {
+      operations.push({ action: "skip", reason: `script ${name} exists`, targetPath: packageJsonPath });
+      continue;
+    }
+
+    nextScripts[name] = command;
+    changed = true;
+    operations.push({
+      action: existingScripts[name]
+        ? options.dryRun
+          ? "would-overwrite"
+          : "overwrite"
+        : options.dryRun
+          ? "would-merge"
+          : "merge",
+      reason: `script ${name}`,
+      targetPath: packageJsonPath,
+    });
+  }
+
+  for (const [name, command] of Object.entries(supportScripts)) {
+    if (nextScripts[name]) {
+      operations.push({ action: "keep", reason: `support script ${name}`, targetPath: packageJsonPath });
+      continue;
+    }
+
+    nextScripts[name] = command;
+    changed = true;
+    operations.push({
+      action: options.dryRun ? "would-merge" : "merge",
+      reason: `support script ${name}`,
+      targetPath: packageJsonPath,
+    });
+  }
+
+  if (changed) {
+    packageJson.scripts = nextScripts;
+    await writeJson(packageJsonPath, packageJson, { dryRun: options.dryRun });
+  }
+}
+
+async function copyScripts(targetDir, options, operations) {
+  for (const fileName of ["ai-check.sh", "ai-check-fast.sh"]) {
+    operations.push(
+      await copyFileSafe(
+        fromTemplates("scripts", fileName),
+        path.join(targetDir, "scripts", fileName),
+        options,
+      ),
+    );
+  }
+}
+
+async function copyCiFiles(targetDir, options, operations) {
+  for (const fileName of ciWorkflowFiles(options.ci)) {
+    const relativePath = ciWorkflowRelativePath(fileName);
+    operations.push(await copyTextFileSafe(
+      await renderedCiWorkflow(fileName, options.packageManager),
+      path.join(targetDir, relativePath),
+      options,
+    ));
+  }
+}
+
+async function copyTextFileSafe(content, targetPath, options = {}) {
+  const { dryRun = false, overwrite = false } = options;
+  const exists = await pathExists(targetPath);
+
+  if (exists && !overwrite) {
+    return { action: "skip", reason: "exists", targetPath };
+  }
+
+  if (!dryRun) {
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, content);
+  }
+
+  if (exists && overwrite) {
+    return { action: dryRun ? "would-overwrite" : "overwrite", targetPath };
+  }
+
+  return { action: dryRun ? "would-copy" : "copy", targetPath };
+}
+
+async function copyProfileDocs(targetDir, profile, options, operations) {
+  for (const file of getProfileDocFiles(profile)) {
+    const operation = await copyFileSafe(
+      file.sourcePath,
+      path.join(targetDir, file.relativePath),
+      options,
+    );
+    operations.push({
+      ...operation,
+      reason: operation.reason === "exists" ? "profile doc exists" : "profile doc",
+    });
+  }
+}
+
+async function copyClaudeHooks(targetDir, options, operations) {
+  operations.push(
+    await copyFileSafe(
+      fromTemplates(".claude", "rules", "test-rules.md"),
+      path.join(targetDir, ".claude", "rules", "test-rules.md"),
+      options,
+    ),
+  );
+
+  await mergeClaudeSettings(targetDir, options, operations);
+}
+
+async function mergeClaudeSettings(targetDir, options, operations) {
+  const targetPath = path.join(targetDir, ".claude", "settings.json");
+  const fragment = renderClaudeHookSettings(
+    await readJson(fromTemplates(".claude", "settings.hook-fragment.json")),
+    options.packageManager,
+  );
+  const settings = (await pathExists(targetPath)) ? await readJson(targetPath) : {};
+  const nextSettings = { ...settings, hooks: { ...(settings.hooks ?? {}) } };
+  let changed = false;
+
+  for (const [name, hooks] of Object.entries(fragment.hooks ?? {})) {
+    if (nextSettings.hooks[name] && !options.overwrite) {
+      operations.push({ action: "skip", reason: `Claude hook ${name} exists`, targetPath });
+      continue;
+    }
+
+    nextSettings.hooks[name] = hooks;
+    changed = true;
+    operations.push({
+      action: nextSettings.hooks[name] && settings.hooks?.[name]
+        ? options.dryRun
+          ? "would-overwrite"
+          : "overwrite"
+        : options.dryRun
+          ? "would-merge"
+          : "merge",
+      reason: `Claude hook ${name}`,
+      targetPath,
+    });
+  }
+
+  if (changed) {
+    await writeJson(targetPath, nextSettings, { dryRun: options.dryRun });
+  }
+}
+
+async function writeInitInstallState(targetDir, profile, options, operations) {
+  const targetPath = installStatePath(targetDir);
+  const exists = await pathExists(targetPath);
+  operations.push({
+    action: exists
+      ? options.dryRun
+        ? "would-update"
+        : "update"
+      : options.dryRun
+        ? "would-create"
+        : "create",
+    reason: "install state",
+    targetPath,
+  });
+
+  await writeInstallState(
+    targetDir,
+    {
+      profile,
+      packageManager: options.packageManager,
+      ci: options.ci,
+      claudeHooks: options.claudeHooks,
+    },
+    { dryRun: options.dryRun },
+  );
+}
+
+async function maybeInstallDependencies(targetDir, dependencyInstallPlan, options, operations) {
+  if (!dependencyInstallPlan) {
+    return;
+  }
+
+  const dependencyOperation = dependencyInstallOperation(dependencyInstallPlan, {
+    dryRun: options.dryRun,
+    path: "package.json",
+  });
+  operations.push({
+    action: dependencyOperation.action,
+    reason: dependencyOperation.detail,
+    targetPath: path.join(targetDir, dependencyOperation.path),
+    ...(dependencyOperation.command ? { command: dependencyOperation.command } : {}),
+  });
+
+  if (!options.dryRun) {
+    runDependencyInstall(dependencyInstallPlan, targetDir);
+  }
+}
+
+function relativeTarget(targetDir, targetPath) {
+  return path.relative(targetDir, targetPath) || ".";
+}

package/src/cli/install-state.mjs

@@ -0,0 +1,242 @@
+import path from "node:path";
+import { DEFAULT_PACKAGE_MANAGER, validatePackageManager } from "./package-manager.mjs";
+import { parseProfiles } from "./profile.mjs";
+import {
+  CliError,
+  pathExists,
+  readJson,
+  repoRoot,
+  writeJson,
+} from "./utils.mjs";
+
+export const INSTALL_STATE_FILE = ".ai-check-template.json";
+export const INSTALL_STATE_SCHEMA_VERSION = 1;
+
+const PACKAGE_NAME = "ai-check-template";
+const VALID_CI_MODES = new Set(["direct", "reusable", "none"]);
+
+export function installStatePath(targetDir) {
+  return path.join(targetDir, INSTALL_STATE_FILE);
+}
+
+export async function buildInstallState({ profile, ci, claudeHooks, packageManager = DEFAULT_PACKAGE_MANAGER }) {
+  const packageJson = await readJson(path.join(repoRoot, "package.json"));
+  const parsedProfile = normalizeProfile(profile);
+  const normalizedPackageManager = validatePackageManager(packageManager);
+
+  return {
+    schemaVersion: INSTALL_STATE_SCHEMA_VERSION,
+    packageName: packageJson.name ?? PACKAGE_NAME,
+    packageVersion: packageJson.version ?? "0.0.0",
+    profile: serializeProfile(parsedProfile),
+    packageManager: normalizedPackageManager,
+    ci,
+    claudeHooks: Boolean(claudeHooks),
+    managedBy: PACKAGE_NAME,
+  };
+}
+
+export async function writeInstallState(targetDir, input, { dryRun = false } = {}) {
+  const state = await buildInstallState(input);
+  await writeJson(installStatePath(targetDir), state, { dryRun });
+  return state;
+}
+
+export async function loadInstallState(targetDir) {
+  const targetPath = installStatePath(targetDir);
+
+  if (!(await pathExists(targetPath))) {
+    return { source: "defaults", state: null, error: null };
+  }
+
+  let state;
+  try {
+    state = await readJson(targetPath);
+  } catch (error) {
+    return invalidState("invalid-install-state", error.message);
+  }
+
+  return validateInstallState(state);
+}
+
+export function resolveEffectiveOptions(options, installState) {
+  const state = installState?.source === "state" ? installState.state : null;
+  const stateProfile = state ? serializeProfile(state.profile) : null;
+  const profileInput = options.explicit.profile
+    ? options.profile
+    : stateProfile ?? parseProfiles(options.profile);
+  const profile = normalizeProfile(profileInput);
+
+  return {
+    profile,
+    packageManager: options.explicit.packageManager
+      ? options.packageManager
+      : state?.packageManager ?? options.packageManager ?? DEFAULT_PACKAGE_MANAGER,
+    ci: options.explicit.ci ? options.ci : state?.ci ?? options.ci,
+    claudeHooks: options.explicit.claudeHooks
+      ? options.claudeHooks
+      : state?.claudeHooks ?? options.claudeHooks,
+  };
+}
+
+export function installStateIssue(installState) {
+  if (!installState?.error) {
+    return null;
+  }
+
+  return {
+    code: installState.error.code,
+    path: INSTALL_STATE_FILE,
+    message: installState.error.message,
+  };
+}
+
+export function installationSummary(installState) {
+  const summary = {
+    source: installState?.source ?? "defaults",
+    path: INSTALL_STATE_FILE,
+  };
+
+  if (installState?.state) {
+    return {
+      ...summary,
+      schemaVersion: installState.state.schemaVersion,
+      packageVersion: installState.state.packageVersion,
+      profile: installState.state.profile,
+      packageManager: installState.state.packageManager,
+      ci: installState.state.ci,
+      claudeHooks: installState.state.claudeHooks,
+    };
+  }
+
+  if (installState?.error) {
+    return {
+      ...summary,
+      error: installState.error,
+    };
+  }
+
+  return summary;
+}
+
+export function effectiveOptionsSummary(effectiveOptions) {
+  return {
+    profile: effectiveOptions.profile.all.join("+"),
+    profiles: serializeProfile(effectiveOptions.profile),
+    packageManager: effectiveOptions.packageManager,
+    ci: effectiveOptions.ci,
+    claudeHooks: effectiveOptions.claudeHooks,
+  };
+}
+
+export function assertWritableInstallState(installState) {
+  if (installState?.error) {
+    throw new CliError(`Invalid install state: ${installState.error.message}`);
+  }
+}
+
+export function validateCiMode(ci) {
+  if (!VALID_CI_MODES.has(ci)) {
+    throw new CliError("--ci must be one of: direct, reusable, none");
+  }
+}
+
+function validateInstallState(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state)) {
+    return invalidState("invalid-install-state", "Install state must be a JSON object");
+  }
+
+  if (state.schemaVersion !== INSTALL_STATE_SCHEMA_VERSION) {
+    return invalidState(
+      "unsupported-install-state",
+      `Unsupported install state schemaVersion: ${String(state.schemaVersion)}`,
+    );
+  }
+
+  if (state.packageName !== PACKAGE_NAME || state.managedBy !== PACKAGE_NAME) {
+    return invalidState("invalid-install-state", "Install state is not managed by ai-check-template");
+  }
+
+  if (typeof state.packageVersion !== "string" || state.packageVersion.length === 0) {
+    return invalidState("invalid-install-state", "Install state packageVersion must be a string");
+  }
+
+  let packageManager;
+  try {
+    packageManager = state.packageManager === undefined
+      ? DEFAULT_PACKAGE_MANAGER
+      : validatePackageManager(state.packageManager);
+  } catch (error) {
+    return invalidState("invalid-install-state", error.message);
+  }
+
+  let profile;
+  try {
+    profile = normalizeProfile(state.profile);
+  } catch (error) {
+    return invalidState("invalid-install-state", error.message);
+  }
+
+  if (!VALID_CI_MODES.has(state.ci)) {
+    return invalidState("invalid-install-state", "Install state ci must be direct, reusable, or none");
+  }
+
+  if (typeof state.claudeHooks !== "boolean") {
+    return invalidState("invalid-install-state", "Install state claudeHooks must be a boolean");
+  }
+
+  return {
+    source: "state",
+    state: {
+      schemaVersion: state.schemaVersion,
+      packageName: state.packageName,
+      packageVersion: state.packageVersion,
+      profile: serializeProfile(profile),
+      packageManager,
+      ci: state.ci,
+      claudeHooks: state.claudeHooks,
+      managedBy: state.managedBy,
+    },
+    error: null,
+  };
+}
+
+function normalizeProfile(profile) {
+  if (typeof profile === "string") {
+    return parseProfiles(profile);
+  }
+
+  if (profile?.base && Array.isArray(profile.addons) && Array.isArray(profile.all)) {
+    const parsed = parseProfiles(profile.all.join("+"));
+    if (parsed.base !== profile.base || parsed.addons.join("+") !== profile.addons.join("+")) {
+      throw new CliError("Install state profile fields are inconsistent");
+    }
+    return parsed;
+  }
+
+  if (profile?.base && Array.isArray(profile.addons)) {
+    return parseProfiles([profile.base, ...profile.addons].join("+"));
+  }
+
+  if (profile?.all && Array.isArray(profile.all)) {
+    return parseProfiles(profile.all.join("+"));
+  }
+
+  throw new CliError("Install state profile is invalid");
+}
+
+function serializeProfile(profile) {
+  return {
+    base: profile.base,
+    addons: [...profile.addons],
+    all: [...profile.all],
+  };
+}
+
+function invalidState(code, message) {
+  return {
+    source: code === "unsupported-install-state" ? "unsupported" : "invalid",
+    state: null,
+    error: { code, message },
+  };
+}