@structor-dev/cli 0.1.0 → 0.2.1

package/scripts/init-harness.mjs

@@ -2,9 +2,25 @@
 
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { assertSafeOutputRoot, exists, validateConfigShape } from "./lib.mjs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  assertSafeWriteTarget,
+  exists,
+  resolveHarnessConfig,
+} from "./lib.mjs";
+import {
+  consumerEntrypointsForSettings,
+  freshRenderScriptTemplatesForSettings,
+  shouldRenderTemplate as shouldRenderContractTemplate,
+  trustedGeneratedScriptTemplatesForSettings,
+} from "./generated-harness-contract.mjs";
+import {
+  consumerEntrypointValues,
+  harnessTemplateValues,
+  renderedGeneratedScriptHashes,
+} from "./rendered-config.mjs";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -15,15 +31,9 @@ const dryRunArg = "--dry-run";
 const forceArg = "--force";
 const installConsumerEntrypointsArg = "--install-consumer-entrypoints";
 const allowAbsoluteOutputArg = "--allow-absolute-output";
+const allowTemplateRepoConsumerArg = "--allow-template-repo-consumer";
 
-const consumerPathPrefix = "consumer/";
-const anthropicPathPrefix = ".claude/";
-const codexHookPathPrefix = ".codex/";
-const scriptRulesPath = "scripts/check-claude-compatibility.mjs.tpl";
-const scriptCodexPath = "scripts/check-codex-hooks.mjs.tpl";
-const scriptHooksPath = "scripts/hooks/";
-
-function parseArgs(argv) {
+export function parseArgs(argv) {
   const options = {
     config: configFileDefault,
     output: null,
@@ -31,6 +41,7 @@ function parseArgs(argv) {
     force: false,
     installConsumerEntrypoints: false,
     allowAbsoluteOutput: false,
+    allowTemplateRepoConsumer: false,
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -41,13 +52,14 @@ function parseArgs(argv) {
     else if (arg === forceArg) options.force = true;
     else if (arg === installConsumerEntrypointsArg) options.installConsumerEntrypoints = true;
     else if (arg === allowAbsoluteOutputArg) options.allowAbsoluteOutput = true;
+    else if (arg === allowTemplateRepoConsumerArg) options.allowTemplateRepoConsumer = true;
     else throw new Error(`Unknown argument: ${arg}`);
   }
 
   return options;
 }
 
-function render(content, values) {
+export function render(content, values) {
   return content.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => {
     if (!(key in values)) {
       throw new Error(`No value provided for template placeholder {{${key}}}`);
@@ -56,70 +68,24 @@ function render(content, values) {
   });
 }
 
-function consumerList(consumers) {
-  return consumers.map((consumer) => `- ${consumer.name}: ${consumer.purpose}`).join("\n");
-}
-
-function validationList(validation) {
-  const entries = Object.entries(validation ?? {});
-  if (entries.length === 0) return "- No local validation commands documented yet.";
-  return entries.map(([name, command]) => `- ${name}: \`${command}\``).join("\n");
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
 }
 
-function consumerNames(consumers) {
-  return JSON.stringify(consumers.map((consumer) => consumer.name));
-}
-
-function consumerConfig(consumers, configDir, outputRoot) {
-  const workspaceRoot = path.dirname(outputRoot);
-  const normalizedConsumers = consumers.map((consumer) => {
-    const consumerRoot = path.resolve(configDir, consumer.path);
-    return {
-      ...consumer,
-      workspacePath: path.relative(workspaceRoot, consumerRoot).replaceAll(path.sep, "/") || ".",
-    };
-  });
-  return JSON.stringify(normalizedConsumers, null, 2);
+function relativePath(from, to) {
+  return path.relative(from, to).replaceAll(path.sep, "/") || ".";
 }
 
-function booleanLiteral(value) {
-  return value ? "true" : "false";
-}
-
-function clientSupport(config) {
+async function packageMetadata() {
+  const packageJson = JSON.parse(await readFile(path.join(repoRoot, "package.json"), "utf8"));
   return {
-    codexHooks: config.models.openai && (config.clientSupport?.codex?.hooks ?? true),
-    claudeRules: config.models.anthropic && (config.clientSupport?.claude?.rules ?? true),
-    claudeHooks: config.models.anthropic && (config.clientSupport?.claude?.hooks ?? false),
-    claudeSkills: config.models.anthropic && (config.clientSupport?.claude?.skills ?? false),
+    name: packageJson.name,
+    version: packageJson.version,
   };
 }
 
-function shouldRenderTemplate(sourceRelative, config) {
-  const support = clientSupport(config);
-  const claudePath = "workspace/.claude/";
-  const openaiWorkspacePath = "workspace/AGENTS.md.tpl";
-  const claudeWorkspacePath = "workspace/CLAUDE.md.tpl";
-
-  if (sourceRelative.startsWith(consumerPathPrefix)) return false;
-  if (!config.models.anthropic && sourceRelative.startsWith(anthropicPathPrefix)) return false;
-  if (!support.claudeRules && sourceRelative.startsWith(`${anthropicPathPrefix}rules/`)) return false;
-  if (!support.claudeHooks && sourceRelative.startsWith(`${anthropicPathPrefix}hooks/`)) return false;
-  if (!support.claudeSkills && sourceRelative.startsWith(`${anthropicPathPrefix}skills/`)) return false;
-  if (!support.codexHooks && sourceRelative.startsWith(codexHookPathPrefix)) return false;
-  if (!support.codexHooks && sourceRelative.startsWith(scriptHooksPath)) return false;
-  if (!support.codexHooks && sourceRelative === scriptCodexPath) return false;
-  if (!support.codexHooks && sourceRelative === "ai/contracts/codex-hooks.contract.json.tpl") return false;
-  if (!config.models.anthropic && sourceRelative === scriptRulesPath) return false;
-  if (!config.models.openai && sourceRelative === openaiWorkspacePath) return false;
-  if (!config.models.anthropic && sourceRelative === claudeWorkspacePath) return false;
-  if (!config.models.anthropic && sourceRelative.startsWith(claudePath)) return false;
-  if (!support.claudeRules && sourceRelative.startsWith(`${claudePath}rules/`)) return false;
-  if (!config.models.openai && sourceRelative === "AGENTS.md.tpl") return false;
-  if (!config.models.anthropic && sourceRelative === "CLAUDE.md.tpl") return false;
-  if (!config.models.openai && sourceRelative.startsWith("ai/model-overlays/openai/")) return false;
-  if (!config.models.anthropic && sourceRelative.startsWith("ai/model-overlays/anthropic/")) return false;
-  return true;
+export function shouldRenderTemplate(sourceRelative, config) {
+  return shouldRenderContractTemplate(sourceRelative, config);
 }
 
 async function collectTemplateFiles() {
@@ -143,128 +109,250 @@ async function collectTemplateFiles() {
   return files.sort();
 }
 
-async function writeRenderedFile(sourceRelative, targetRoot, values, options) {
-  const sourcePath = path.join(repoRoot, "template", sourceRelative);
+async function generatedScriptHashes(templateFiles, config, values) {
+  const hashes = {};
+  const trustedScriptTemplates = new Set(trustedGeneratedScriptTemplatesForSettings(config));
+
+  for (const sourceRelative of templateFiles) {
+    if (!trustedScriptTemplates.has(sourceRelative)) continue;
+
+    const sourcePath = path.join(repoRoot, "template", sourceRelative);
+    const targetRelative = sourceRelative.replace(/\.tpl$/, "");
+    hashes[targetRelative] = sha256(render(await readFile(sourcePath, "utf8"), values));
+  }
+
+  return renderedGeneratedScriptHashes(hashes);
+}
+
+export async function writeRenderedFile(sourceRelative, targetRoot, values, options, templateRoot = path.join(repoRoot, "template")) {
+  const sourcePath = path.join(templateRoot, sourceRelative);
   const targetRelative = sourceRelative.replace(/\.tpl$/, "");
   const targetPath = path.join(targetRoot, targetRelative);
   const content = render(await readFile(sourcePath, "utf8"), values);
 
   if (options.dryRun) {
-    console.log(`would create ${targetPath}`);
-    return;
+    const action = (await exists(targetPath)) ? (options.force ? "overwrite" : "skip existing") : "create";
+    console.log(`would ${action} ${targetPath}`);
+    return { action: "dry-run", rendered: false, targetPath, targetRelative };
   }
 
   if ((await exists(targetPath)) && !options.force) {
     console.log(`skipped existing ${targetPath}`);
-    return;
+    return { action: "skipped", rendered: false, targetPath, targetRelative };
   }
 
   const existed = await exists(targetPath);
+  await assertSafeWriteTarget({
+    targetPath,
+    rootPath: targetRoot,
+    label: `Generated harness file ${targetRelative}`,
+  });
   await mkdir(path.dirname(targetPath), { recursive: true });
   await writeFile(targetPath, content);
   console.log(`${existed ? "wrote" : "created"} ${targetPath}`);
+  return { action: existed ? "wrote" : "created", rendered: true, targetPath, targetRelative };
 }
 
-async function installConsumerEntrypoints(config, harnessRoot, options) {
-  for (const consumer of config.consumers) {
-    const consumerRoot = path.resolve(path.dirname(path.resolve(options.config)), consumer.path);
-    if (!(await exists(consumerRoot))) {
-      throw new Error(`Consumer repo path does not exist: ${consumerRoot}`);
-    }
+export async function installConsumerEntrypoints(resolvedConfig, options) {
+  const { config, outputRoot: harnessRoot, support, consumers } = resolvedConfig;
+  const entrypoints = consumerEntrypointsForSettings({
+    models: config.models,
+    clientSupport: support,
+  });
+  const records = [];
+
+  for (const resolvedConsumer of consumers) {
+    const consumer = resolvedConsumer.config;
+    const consumerRoot = resolvedConsumer.confirmedRoot ?? resolvedConsumer.root;
 
     const harnessRelativePath = path.relative(consumerRoot, harnessRoot).replaceAll(path.sep, "/") || ".";
-    const values = {
-      PROJECT_NAME: config.project.name,
-      CONSUMER_NAME: consumer.name,
-      CONSUMER_PURPOSE: consumer.purpose,
-      CONSUMER_VALIDATION_LIST: validationList(consumer.validation),
-      HARNESS_RELATIVE_PATH: harnessRelativePath,
-    };
-
-    const entrypoints = [];
-    if (config.models.openai) entrypoints.push(["AGENTS.md", "AGENTS.md.tpl"]);
-    if (config.models.anthropic) {
-      entrypoints.push(["CLAUDE.md", "CLAUDE.md.tpl"]);
-      entrypoints.push([path.join(".claude", "CLAUDE.md"), path.join(".claude", "CLAUDE.md.tpl")]);
-    }
+    const values = consumerEntrypointValues(config, consumer, harnessRelativePath);
 
-    for (const [targetRelative, sourceRelative] of entrypoints) {
-      const sourcePath = path.join(repoRoot, "template", "consumer", sourceRelative);
+    for (const entrypoint of entrypoints) {
+      const targetRelative = entrypoint.path;
+      const sourcePath = path.join(repoRoot, "template", entrypoint.template);
       const targetPath = path.join(consumerRoot, targetRelative);
       const content = render(await readFile(sourcePath, "utf8"), values);
+      const record = {
+        consumer: consumer.name,
+        consumerPath: consumer.path,
+        path: targetRelative,
+        rendered: false,
+      };
 
       if (options.dryRun) {
-        console.log(`would create consumer entrypoint ${targetPath}`);
+        const action = (await exists(targetPath)) ? (options.force ? "overwrite" : "skip existing") : "create";
+        console.log(`would ${action} consumer entrypoint ${targetPath}`);
+        records.push({ ...record, action: "dry-run" });
         continue;
       }
       if ((await exists(targetPath)) && !options.force) {
         console.log(`skipped existing consumer entrypoint ${targetPath}`);
+        records.push({ ...record, action: "skipped" });
         continue;
       }
 
+      await assertSafeWriteTarget({
+        targetPath,
+        rootPath: consumerRoot,
+        label: `Consumer entrypoint ${targetRelative}`,
+      });
       await mkdir(path.dirname(targetPath), { recursive: true });
       await writeFile(targetPath, content);
       console.log(`wrote consumer entrypoint ${targetPath}`);
+      records.push({ ...record, action: "wrote", rendered: true });
     }
   }
+
+  return records;
 }
 
-async function main() {
-  const options = parseArgs(process.argv.slice(2));
-  const configPath = path.resolve(options.config);
-  const config = JSON.parse(await readFile(configPath, "utf8"));
-  const errors = await validateConfigShape(config, options.config);
-  if (errors.length > 0) {
-    throw new Error(errors.join("\n"));
-  }
+async function writeGenerationManifest({
+  config,
+  configContent,
+  configPath,
+  consumerEntrypoints,
+  generatedFiles,
+  outputRoot,
+  resolvedConfig,
+  support,
+}) {
+  const manifestPath = path.join(outputRoot, ".structor", "manifest.json");
+  const metadata = await packageMetadata();
+  const manifest = {
+    generatorName: metadata.name,
+    generatorVersion: metadata.version,
+    generatedAt: new Date().toISOString(),
+    config: {
+      path: relativePath(resolvedConfig.workspaceRoot, configPath),
+      sha256: sha256(configContent),
+      project: {
+        name: config.project.name,
+        slug: config.project.slug,
+        harnessRepoName: config.project.harnessRepoName,
+      },
+      models: {
+        openai: Boolean(config.models.openai),
+        anthropic: Boolean(config.models.anthropic),
+      },
+      clientSupport: support,
+      consumers: config.consumers.map((consumer) => ({
+        name: consumer.name,
+        path: consumer.path,
+        purpose: consumer.purpose,
+      })),
+    },
+    files: generatedFiles.map((file) => ({
+      path: file.targetRelative,
+      action: file.action,
+      rendered: file.rendered,
+    })),
+    consumerEntrypoints,
+  };
 
-  const configDir = path.dirname(configPath);
-  const outputPath = options.output ?? config.output.path;
-  const outputRoot = path.resolve(configDir, outputPath);
-  const consumerRepos = config.consumers.map((consumer) => path.resolve(configDir, consumer.path));
-  assertSafeOutputRoot({
-    outputPath,
-    outputRoot,
-    repoRoot,
-    workspaceRoot: configDir,
-    consumerRepos,
-    allowAbsoluteOutput: options.allowAbsoluteOutput,
+  await assertSafeWriteTarget({
+    targetPath: manifestPath,
+    rootPath: outputRoot,
+    label: "Generation manifest .structor/manifest.json",
   });
-  const support = clientSupport(config);
-  const values = {
-    PROJECT_NAME: config.project.name,
-    PROJECT_SLUG: config.project.slug,
-    HARNESS_REPO_NAME: config.project.harnessRepoName,
-    CONSUMER_REPOS_LIST: consumerList(config.consumers),
-    CONSUMER_REPO_NAMES_JSON: consumerNames(config.consumers),
-    CONSUMER_CONFIG_JSON: consumerConfig(config.consumers, configDir, outputRoot),
-    PRIMARY_CONSUMER_NAME: config.consumers[0].name,
-    MODEL_OPENAI_ENABLED: booleanLiteral(config.models.openai),
-    MODEL_ANTHROPIC_ENABLED: booleanLiteral(config.models.anthropic),
-    CLIENT_CODEX_HOOKS_ENABLED: booleanLiteral(support.codexHooks),
-    CLIENT_CLAUDE_RULES_ENABLED: booleanLiteral(support.claudeRules),
-    CLIENT_CLAUDE_HOOKS_ENABLED: booleanLiteral(support.claudeHooks),
-    CLIENT_CLAUDE_SKILLS_ENABLED: booleanLiteral(support.claudeSkills),
-  };
+  await mkdir(path.dirname(manifestPath), { recursive: true });
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  console.log(`wrote ${manifestPath}`);
+}
 
-  for (const sourceRelative of await collectTemplateFiles()) {
+export async function generateHarness(config, {
+  configPath = null,
+  configContent = null,
+  configDir = configPath ? path.dirname(path.resolve(configPath)) : process.cwd(),
+  outputPath = config.output.path,
+  dryRun = false,
+  force = false,
+  installConsumerEntrypoints: shouldInstallConsumerEntrypoints = false,
+  allowAbsoluteOutput = false,
+  allowTemplateRepoConsumer = false,
+} = {}) {
+  const manifestConfigContent = configContent
+    ?? (configPath ? await readFile(path.resolve(configPath), "utf8") : `${JSON.stringify(config, null, 2)}\n`);
+  const resolvedConfig = await resolveHarnessConfig(config, {
+    label: configPath ?? "harness config",
+    configPath,
+    configDir,
+    outputPath,
+    allowAbsoluteOutput,
+    requireExistingConsumers: shouldInstallConsumerEntrypoints,
+    allowTemplateRepoConsumer,
+  });
+  const { outputRoot, support } = resolvedConfig;
+  const values = harnessTemplateValues(config, support, resolvedConfig.consumers, outputRoot);
+  values.GENERATED_HARNESS_CONTRACT_MODULE = await readFile(
+    path.join(repoRoot, "scripts/generated-harness-contract.mjs"),
+    "utf8",
+  );
+
+  const templateFiles = await collectTemplateFiles();
+  values.GENERATED_SCRIPT_HASHES_JSON = await generatedScriptHashes(templateFiles, config, values);
+  const freshRenderScriptTemplates = new Set(freshRenderScriptTemplatesForSettings(config));
+
+  let renderedHtmlViewsScript = false;
+  const generatedFiles = [];
+  for (const sourceRelative of templateFiles) {
     if (!shouldRenderTemplate(sourceRelative, config)) continue;
-    await writeRenderedFile(sourceRelative, outputRoot, values, options);
+    const result = await writeRenderedFile(sourceRelative, outputRoot, values, { dryRun, force });
+    generatedFiles.push(result);
+    if (freshRenderScriptTemplates.has(sourceRelative) && result.rendered) {
+      renderedHtmlViewsScript = true;
+    }
   }
 
-  if (!options.dryRun) {
+  if (!dryRun && renderedHtmlViewsScript) {
     execFileSync(process.execPath, [path.join(outputRoot, "scripts/generate-html-views.mjs")], {
       cwd: outputRoot,
       stdio: "inherit",
     });
+  } else if (!dryRun) {
+    console.log("skipped HTML view generation because scripts/generate-html-views.mjs was not freshly rendered");
   }
 
-  if (options.installConsumerEntrypoints) {
-    await installConsumerEntrypoints(config, outputRoot, { ...options, config: configPath });
+  const consumerEntrypoints = shouldInstallConsumerEntrypoints
+    ? await installConsumerEntrypoints(resolvedConfig, { dryRun, force, config: configPath })
+    : [];
+
+  if (!dryRun) {
+    await writeGenerationManifest({
+      config,
+      configContent: manifestConfigContent,
+      configPath,
+      consumerEntrypoints,
+      generatedFiles,
+      outputRoot,
+      resolvedConfig,
+      support,
+    });
   }
+
+  return resolvedConfig;
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const configPath = path.resolve(options.config);
+  const configContent = await readFile(configPath, "utf8");
+  const config = JSON.parse(configContent);
+  await generateHarness(config, {
+    configPath,
+    configContent,
+    outputPath: options.output ?? config.output.path,
+    dryRun: options.dryRun,
+    force: options.force,
+    installConsumerEntrypoints: options.installConsumerEntrypoints,
+    allowAbsoluteOutput: options.allowAbsoluteOutput,
+    allowTemplateRepoConsumer: options.allowTemplateRepoConsumer,
+  });
 }
 
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}