@structor-dev/cli 0.2.1 → 0.2.2

package/README.md

@@ -55,10 +55,11 @@ During local development from a clone of this repo, use
 `node ./structor/bin/structor.mjs init` from the parent workspace instead.
 
 `init` is local-only and deterministic. It detects sibling repos, asks a few
-questions, writes `harness.config.json` only after confirmation, previews every
-generated file with a dry run, and generates nothing until you confirm. No
-network calls, no LLM calls, no telemetry, no package installs, and no remote
-service mutation.
+questions, previews the full setup transaction with a dry run, persists
+`harness.config.json` inside the generated harness only after confirmation, and
+does not report success until consumer entrypoints, workspace entrypoints, and
+completion gates have passed. No network calls, no LLM calls, no telemetry, no
+package installs, and no remote service mutation.
 
 `structor init` remains the normal setup flow for users creating generated
 harnesses for their own target repositories. Contributing to Structor itself is
@@ -222,9 +223,9 @@ These boundaries are intentional in the current template:
 The supported happy path is:
 
 1. Clone this template repo into the same workspace folder as the consumer repos.
-2. Generate the project harness as a sibling of the consumer repos.
-3. Install consumer repo entrypoints during initialization.
-4. Run the generated harness workspace bootstrap script.
+2. Run `structor init` from the workspace folder.
+3. Let Structor generate the project harness as a sibling of the consumer repos.
+4. Let Structor install or verify consumer and workspace entrypoints before success.
 5. Start Codex or Claude Code from the workspace, generated harness, or a
    bootstrapped consumer repo.
 
@@ -241,10 +242,11 @@ workspace/
 
 With that layout, the current flow can bootstrap consumer repos out of the box
 when their agent pointer files are missing. For safety, existing consumer
-`AGENTS.md`, `CLAUDE.md`, and `.claude/CLAUDE.md` files are skipped unless
-`--force` is explicitly passed. If you generate the harness somewhere else,
-move or copy it into the sibling workspace layout before running the generated
-workspace bootstrap scripts.
+`AGENTS.md`, `CLAUDE.md`, and `.claude/CLAUDE.md` files must already match the
+expected Structor-managed pointer surfaces or `init` fails unless `--force` is
+explicitly passed. If you generate the harness somewhere else, move or copy it
+into the sibling workspace layout before running the generated workspace
+bootstrap scripts.
 
 ## Agent-Assisted Manual Setup
 

package/bin/structor.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { access, mkdir, readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { access, mkdir, readdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import path from "node:path";
 import process from "node:process";
@@ -13,6 +13,15 @@ import {
   resolveHarnessConfig,
   validateConfigShape,
 } from "../scripts/lib.mjs";
+import {
+  generateHarness,
+  installConsumerEntrypoints,
+  render,
+} from "../scripts/init-harness.mjs";
+import {
+  consumerEntrypointValues,
+  harnessTemplateValues,
+} from "../scripts/rendered-config.mjs";
 import {
   consumerEntrypointsForSettings,
   requiredHarnessRepoFilesForWorkspaceCheck,
@@ -453,11 +462,67 @@ async function loadExistingConfig(configPath) {
   }
 }
 
+async function discoverWorkspaceConfigPath(workspaceRoot, explicitConfigPath = null) {
+  if (explicitConfigPath) return path.resolve(workspaceRoot, explicitConfigPath);
+
+  const workspaceConfigPath = path.join(workspaceRoot, configFileName);
+  const matches = [];
+  const skipDirectoryNames = new Set([".git", "node_modules"]);
+
+  async function visitDirectory(directoryPath, depth = 0) {
+    if (depth > 4) return;
+
+    const candidatePath = path.join(directoryPath, configFileName);
+    const candidate = await maybeReadJson(candidatePath);
+    const resolvedWorkspaceRoot = candidate?.workspace?.root
+      ? path.resolve(path.dirname(candidatePath), candidate.workspace.root)
+      : null;
+    if (resolvedWorkspaceRoot === workspaceRoot) {
+      matches.push(candidatePath);
+    }
+
+    const entries = await readdir(directoryPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || skipDirectoryNames.has(entry.name)) continue;
+      await visitDirectory(path.join(directoryPath, entry.name), depth + 1);
+    }
+  }
+
+  await visitDirectory(workspaceRoot);
+  return matches.length === 1 ? matches[0] : workspaceConfigPath;
+}
+
 async function writeConfig(configPath, config) {
   await mkdir(path.dirname(configPath), { recursive: true });
   await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
 }
 
+function configContent(config) {
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+function durableConfigPathFor(workspaceRoot, outputPath) {
+  return path.join(path.resolve(workspaceRoot, outputPath), configFileName);
+}
+
+function initConfigWithWorkspaceRoot(config, workspaceRoot) {
+  const configPath = durableConfigPathFor(workspaceRoot, config.output.path);
+  return {
+    workspace: {
+      root: relativeFrom(path.dirname(configPath), workspaceRoot),
+    },
+    ...config,
+  };
+}
+
+function initCompletionCommands(harnessRoot) {
+  return [
+    commandText(process.execPath, ["scripts/validate-governance.mjs"]),
+    commandText(process.execPath, ["scripts/check-workspace.mjs"]),
+    `Config: ${path.join(harnessRoot, configFileName)}`,
+  ];
+}
+
 export function nextValidationCommands(config) {
   const commands = [
     `cd ${config.output.path}`,
@@ -629,7 +694,7 @@ function printDoctorCheck(results, status, label, detail = "") {
 async function doctor(options) {
   const results = [];
   const workspaceRoot = path.resolve(options.workspace ?? process.cwd());
-  const configPath = path.resolve(workspaceRoot, options.config ?? configFileName);
+  const configPath = await discoverWorkspaceConfigPath(workspaceRoot, options.config);
   section("Structor doctor");
   note("Diagnosis only. No files will be repaired or written.");
 
@@ -796,6 +861,162 @@ function printNextSteps(config) {
   }
 }
 
+function printSetupTransactionPreview(config, configPath) {
+  const settings = {
+    models: config.models,
+    clientSupport: {
+      codexHooks: config.clientSupport?.codex?.hooks ?? config.models.openai,
+      claudeRules: config.clientSupport?.claude?.rules ?? config.models.anthropic,
+      claudeHooks: false,
+      claudeSkills: false,
+    },
+  };
+
+  section("Setup transaction preview");
+  console.log(`Durable config: ${configPath}`);
+  console.log(`Generated harness: ${config.output.path}`);
+  console.log("Consumer entrypoints:");
+  for (const consumer of config.consumers) {
+    for (const entrypoint of consumerEntrypointsForSettings(settings)) {
+      console.log(`  - ${consumer.path}/${entrypoint.path}`);
+    }
+  }
+  console.log("Workspace entrypoints:");
+  for (const entrypoint of workspaceEntrypointsForSettings(settings)) {
+    console.log(`  - ${entrypoint.path}`);
+  }
+  console.log("Completion gates:");
+  console.log("  - node scripts/validate-governance.mjs");
+  console.log("  - node scripts/check-workspace.mjs");
+}
+
+async function runGeneratedNodeScript({ harnessRoot, relativeScriptPath, args = [], failureLabel }) {
+  const result = spawnSync(process.execPath, [relativeScriptPath, ...args], {
+    cwd: harnessRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  printCommandOutput(result);
+  if (result.status !== 0) {
+    throw new Error(failureLabel);
+  }
+}
+
+function assertGeneratedScriptsReady(generatedFiles, scriptPaths) {
+  const filesByPath = new Map(generatedFiles.map((file) => [file.targetRelative, file]));
+  const notReady = [];
+  for (const scriptPath of scriptPaths) {
+    const file = filesByPath.get(scriptPath);
+    if (!file || file.action === "skipped" || !file.rendered) {
+      notReady.push(scriptPath);
+    }
+  }
+
+  if (notReady.length > 0) {
+    throw new Error(
+      `Generated setup scripts were not refreshed or verified:\n${notReady.map((item) => `- ${item}`).join("\n")}\nInspect the existing files and re-run with --force if they should be replaced.`,
+    );
+  }
+}
+
+async function assertNoEntrypointConflicts({ config, resolvedConfig, harnessRoot, force }) {
+  if (force) return;
+
+  const settings = { models: config.models, clientSupport: resolvedConfig.support };
+  const conflicts = [];
+  const templateWorkspaceRoot = config.workspace?.root
+    ? path.resolve(harnessRoot, config.workspace.root)
+    : path.dirname(harnessRoot);
+  const harnessValues = harnessTemplateValues(
+    config,
+    resolvedConfig.support,
+    resolvedConfig.consumers,
+    harnessRoot,
+    templateWorkspaceRoot,
+  );
+
+  for (const entrypoint of workspaceEntrypointsForSettings(settings)) {
+    const targetPath = path.join(resolvedConfig.workspaceRoot, entrypoint.path);
+    if (!(await exists(targetPath))) continue;
+
+    const templatePath = path.join(packageRoot, "template", entrypoint.template);
+    const [actual, template] = await Promise.all([
+      readFile(targetPath, "utf8"),
+      readFile(templatePath, "utf8"),
+    ]);
+    const expected = render(template, harnessValues);
+    if (actual !== expected) {
+      conflicts.push(`workspace:${entrypoint.path}`);
+    }
+  }
+
+  for (const resolvedConsumer of resolvedConfig.consumers) {
+    const consumer = resolvedConsumer.config;
+    const consumerRoot = resolvedConsumer.confirmedRoot ?? resolvedConsumer.root;
+    const harnessRelativePath = path.relative(consumerRoot, harnessRoot).replaceAll(path.sep, "/") || ".";
+    const values = consumerEntrypointValues(config, consumer, harnessRelativePath);
+
+    for (const entrypoint of consumerEntrypointsForSettings(settings)) {
+      const targetPath = path.join(consumerRoot, entrypoint.path);
+      if (!(await exists(targetPath))) continue;
+
+      const templatePath = path.join(packageRoot, "template", entrypoint.template);
+      const [actual, template] = await Promise.all([
+        readFile(targetPath, "utf8"),
+        readFile(templatePath, "utf8"),
+      ]);
+      const expected = render(template, values);
+      if (actual !== expected) {
+        conflicts.push(`consumer:${consumer.name}:${entrypoint.path}`);
+      }
+    }
+  }
+
+  if (conflicts.length > 0) {
+    throw new Error(
+      `Entrypoint conflicts detected before bootstrap:\n${conflicts.map((item) => `- ${item}`).join("\n")}\nRe-run with --force to overwrite known Structor pointer surfaces.`,
+    );
+  }
+}
+
+async function removeEmptyParents(startPath, stopPath) {
+  let current = path.dirname(startPath);
+  const resolvedStop = path.resolve(stopPath);
+  while (current.startsWith(resolvedStop) && current !== resolvedStop) {
+    try {
+      await rm(current);
+    } catch (error) {
+      if (error?.code === "ENOTEMPTY" || error?.code === "ENOENT") return;
+      throw error;
+    }
+    current = path.dirname(current);
+  }
+}
+
+async function cleanupFailedInit({
+  harnessRoot,
+  harnessRootExisted,
+  workspaceRoot,
+  workspaceCreatedPaths,
+  consumerCreatedPaths,
+  harnessCreatedPaths,
+}) {
+  for (const targetPath of [...workspaceCreatedPaths, ...consumerCreatedPaths]) {
+    await rm(targetPath, { force: true });
+    await removeEmptyParents(targetPath, workspaceRoot);
+  }
+
+  if (!harnessRootExisted) {
+    await rm(harnessRoot, { recursive: true, force: true });
+    return;
+  }
+
+  for (const targetPath of harnessCreatedPaths) {
+    await rm(targetPath, { force: true });
+    await removeEmptyParents(targetPath, harnessRoot);
+  }
+}
+
 async function printContributorPlan(plan, options, sourceReady) {
   section(options.dryRun ? "Contributor workspace preview" : "Contributor workspace");
   console.log(`Workspace: ${plan.workspaceRoot}`);
@@ -926,11 +1147,11 @@ async function init(options) {
 
     const workspaceDefault = options.workspace ? path.resolve(options.workspace) : process.cwd();
     const workspaceRoot = path.resolve(await askLine(rl, "Workspace folder", workspaceDefault));
-    const configPath = path.resolve(workspaceRoot, options.config ?? configFileName);
-    const existingConfig = await loadExistingConfig(configPath);
+    const legacyConfigPath = await discoverWorkspaceConfigPath(workspaceRoot, options.config);
+    const existingConfig = await loadExistingConfig(legacyConfigPath);
     let startingConfig = null;
     if (existingConfig) {
-      printConfigSummary(existingConfig, configPath);
+      printConfigSummary(existingConfig, legacyConfigPath);
       if (await askYesNo(rl, "Use this existing config as the starting point?", true)) {
         startingConfig = existingConfig;
       } else {
@@ -1010,47 +1231,130 @@ async function init(options) {
       consumers,
     };
 
-    printConfigSummary(config, configPath);
+    const initConfig = initConfigWithWorkspaceRoot(config, workspaceRoot);
+    const configPath = durableConfigPathFor(workspaceRoot, initConfig.output.path);
+    printConfigSummary(initConfig, configPath);
     warnIfOutputIsNotWorkspaceChild(workspaceRoot, config.output.path);
-    note("harness.config.json is Structor's project-specific input: project facts, output path, agent clients, consumer repos, and validation commands.");
-    const canWriteConfig = existingConfig
-      ? await askYesNo(rl, "Replace existing harness.config.json with this config?", false)
-      : await askYesNo(rl, "Write harness.config.json?", true);
-    if (!canWriteConfig) {
-      warn("Stopped before writing config.");
+    note("harness.config.json will be persisted inside the generated harness so init can finish with a fully bootstrapped workspace.");
+    printSetupTransactionPreview(initConfig, configPath);
+    const canContinue = existingConfig
+      ? await askYesNo(rl, "Replace the generated harness config with this setup?", false)
+      : await askYesNo(rl, "Continue with this setup?", true);
+    if (!canContinue) {
+      warn("Stopped before generation.");
       return;
     }
-    await writeConfig(configPath, config);
-    success(`Wrote ${configPath}`);
 
     section("Dry-run preview");
-    note("The initializer dry-run renders the plan without writing harness or consumer files.");
-    const dryRun = runGenerator(["--config", configPath, "--dry-run"], workspaceRoot);
-    printCommandOutput(dryRun);
-    if (dryRun.status !== 0) throw new Error("Generator dry-run failed.");
+    note("The initializer dry-run renders the generated harness plan before any files are written.");
+    const renderedConfig = configContent(initConfig);
+    const dryRunGenerated = await generateHarness(initConfig, {
+      configPath,
+      configContent: renderedConfig,
+      requireExistingConsumers: true,
+      dryRun: true,
+    });
 
     const apply = options.yes || await askYesNo(rl, "Generate harness now?", true);
     if (!apply) {
       warn("Stopped after dry-run preview.");
-      printNextSteps(config);
       return;
     }
 
-    const generateArgs = ["--config", configPath];
-    if (options.force) generateArgs.push("--force");
-    const installEntrypoints = options.installConsumerEntrypoints || await askYesNo(
-      rl,
-      "Install consumer entrypoint pointer files? These are thin AGENTS.md/CLAUDE.md files that route agents to the generated Structor repo.",
-      true,
-    );
-    if (installEntrypoints) generateArgs.push("--install-consumer-entrypoints");
-
     section("Generate");
-    const result = runGenerator(generateArgs, workspaceRoot);
-    printCommandOutput(result);
-    if (result.status !== 0) throw new Error("Generation failed.");
+    const harnessRoot = path.dirname(configPath);
+    const harnessRootExisted = await exists(harnessRoot);
+    const workspaceCreatedPaths = [];
+    const consumerCreatedPaths = [];
+    const harnessCreatedPaths = [];
+
+    try {
+      await assertNoEntrypointConflicts({
+        config: initConfig,
+        resolvedConfig: dryRunGenerated.resolvedConfig,
+        harnessRoot,
+        force: options.force,
+      });
+
+      const generated = await generateHarness(initConfig, {
+        configPath,
+        configContent: renderedConfig,
+        requireExistingConsumers: true,
+        force: options.force,
+        dryRun: false,
+      });
+      harnessCreatedPaths.push(
+        ...generated.generatedFiles
+          .filter((file) => file.action === "created")
+          .map((file) => file.targetPath),
+      );
+      if (generated.manifestFile?.action === "created") {
+        harnessCreatedPaths.push(generated.manifestFile.targetPath);
+      }
+      assertGeneratedScriptsReady(generated.generatedFiles, [
+        "scripts/bootstrap-workspace.mjs",
+        "scripts/validate-governance.mjs",
+        "scripts/check-workspace.mjs",
+      ]);
+
+      const durableConfigExisted = await exists(configPath);
+      await writeConfig(configPath, initConfig);
+      success(`${durableConfigExisted ? "Updated" : "Wrote"} ${configPath}`);
+      if (!durableConfigExisted) harnessCreatedPaths.push(configPath);
+
+      const consumerEntrypoints = await installConsumerEntrypoints(generated.resolvedConfig, {
+        dryRun: false,
+        force: options.force,
+      });
+      consumerCreatedPaths.push(
+        ...consumerEntrypoints
+          .filter((entrypoint) => entrypoint.action === "created")
+          .map((entrypoint) => path.join(generated.resolvedConfig.workspaceRoot, entrypoint.consumerPath, entrypoint.path)),
+      );
+
+      const settings = { models: initConfig.models, clientSupport: generated.resolvedConfig.support };
+      for (const entrypoint of workspaceEntrypointsForSettings(settings)) {
+        const targetPath = path.join(generated.resolvedConfig.workspaceRoot, entrypoint.path);
+        if (!(await exists(targetPath))) workspaceCreatedPaths.push(targetPath);
+      }
+
+      section("Workspace bootstrap");
+      await runGeneratedNodeScript({
+        harnessRoot,
+        relativeScriptPath: "scripts/bootstrap-workspace.mjs",
+        args: options.force ? ["--force"] : [],
+        failureLabel: "Workspace bootstrap failed.",
+      });
+
+      section("Completion gates");
+      await runGeneratedNodeScript({
+        harnessRoot,
+        relativeScriptPath: "scripts/validate-governance.mjs",
+        failureLabel: "Generated governance validation failed.",
+      });
+      await runGeneratedNodeScript({
+        harnessRoot,
+        relativeScriptPath: "scripts/check-workspace.mjs",
+        failureLabel: "Workspace completion check failed.",
+      });
+    } catch (error) {
+      await cleanupFailedInit({
+        harnessRoot,
+        harnessRootExisted,
+        workspaceRoot,
+        workspaceCreatedPaths,
+        consumerCreatedPaths,
+        harnessCreatedPaths,
+      });
+      throw error;
+    }
+
     success("Structor setup complete.");
-    printNextSteps(config);
+    section("Setup ready");
+    note("No post-success bootstrap steps are required.");
+    for (const command of initCompletionCommands(harnessRoot)) {
+      console.log(`  ${command}`);
+    }
   } finally {
     rl.close();
   }

package/docs/INIT.md

@@ -33,10 +33,12 @@ The default first-run path is:
 1. Run `npx @structor-dev/cli init` from the parent workspace folder.
 2. Confirm the workspace, project name, generated harness path, agent clients,
    and consumer repos.
-3. Let Structor write `harness.config.json` only after reviewing the summary.
-4. Review the dry-run preview of generated harness and consumer pointer files.
+3. Review the setup summary, including the durable harness-local
+   `harness.config.json` path, entrypoint writes, and completion gates.
+4. Review the dry-run preview of the generated harness plan.
 5. Confirm generation only if the preview is correct.
-6. Run the next validation commands printed by the CLI.
+6. Let Structor install or verify consumer and workspace entrypoints, then run
+   generated governance and workspace completion gates before success.
 
 During development from this repository, the equivalent local command is
 `npm run init -- --workspace ..`.
@@ -59,13 +61,16 @@ service; generated files remain local until you review and commit them.
 
 Only after confirmation, it can write:
 
-- `harness.config.json` in the selected workspace.
+- `harness.config.json` inside the generated harness.
 - A generated Structor repo at the configured `output.path`.
-- Optional consumer entrypoint pointer files: `AGENTS.md`, `CLAUDE.md`, and
-  `.claude/CLAUDE.md`.
+- Required consumer entrypoint pointer files: `AGENTS.md`, `CLAUDE.md`, and
+  `.claude/CLAUDE.md` when the selected model support enables them.
+- Required workspace entrypoint pointer files owned by the generated harness
+  bootstrap contract.
 
-Existing generated harness files and consumer entrypoints are skipped by the
-underlying generator unless the user passes `--force`.
+Existing generated harness files and known Structor-managed pointer surfaces are
+updated only when they already match the expected content or the user passes
+`--force`. Conflicting user-owned or stale pointer files block setup.
 
 Consumer entrypoints are thin pointer files. They route Codex and Claude Code
 back to the generated harness; they are not copies of the canonical harness
@@ -118,14 +123,17 @@ implementation.
 
 `harness.config.json` is Structor's project-specific input file. It records:
 
+- workspace root semantics for workspace-relative topology paths when the
+  config lives inside the generated harness
 - project name, slug, and generated repo name
 - output path
 - Codex and Claude support flags
 - consumer repo paths, purposes, and validation commands
 
-Consumer repo paths are workspace-relative. The generator rejects absolute
-consumer paths, `..` traversal, symlinked consumer paths, and entrypoint writes
-to directories that do not look like repositories.
+Consumer repo paths and the durable init `output.path` remain workspace-relative
+even when the config is stored inside the generated harness. The generator
+rejects absolute consumer paths, `..` traversal, symlinked consumer paths, and
+entrypoint writes to directories that do not look like repositories.
 
 `structor generate --config harness.config.json` uses this file to render the
 generated harness deterministically.

package/docs/adr/0002-store-harness-configuration-in-generated-harness.md

@@ -0,0 +1,42 @@
+# ADR 0002: Store Harness Configuration In Generated Harness
+
+## Status
+
+Accepted
+
+## Context
+
+`structor init` used to persist `harness.config.json` at the workspace root,
+generate the harness, and then print manual bootstrap commands. That left two
+problems:
+
+- setup could report success before workspace entrypoints were actually
+  installed and verified
+- a loose workspace-root config was fragile when the parent workspace was not a
+  repository and the generated harness was the durable artifact users kept
+
+We also needed a way for paths such as `output.path` and consumer repo paths to
+stay workspace-relative after moving the durable config into the generated
+harness.
+
+## Decision
+
+- New `structor init` runs persist `harness.config.json` inside the generated
+  harness repo.
+- Init-authored configs include explicit `workspace.root` semantics so
+  workspace-relative topology paths keep resolving correctly even though the
+  config file now lives inside the harness repo.
+- `structor init` does not print `Structor setup complete.` until consumer
+  entrypoints, workspace entrypoints, `node scripts/validate-governance.mjs`,
+  and `node scripts/check-workspace.mjs` have completed successfully.
+- Existing manual `structor generate --config <path>` flows remain supported for
+  workspace-root configs that do not declare `workspace.root`.
+
+## Consequences
+
+- The generated harness becomes the durable home for both policy and the init
+  recipe that produced it.
+- Failed init attempts can clean up files created during that same setup
+  transaction without depending on a loose workspace-root config.
+- Tooling that looks for a config from the workspace should prefer the explicit
+  harness-local config when it is the only unambiguous match.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structor-dev/cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Harness-engineering toolkit that generates repository-local AI engineering harnesses for consumer repos.",
   "license": "MIT",
   "author": "Nicolay Camacho",

package/schemas/harness-config.schema.json

@@ -6,6 +6,14 @@
   "required": ["project", "output", "models", "consumers"],
   "properties": {
     "$schema": { "type": "string" },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["root"],
+      "properties": {
+        "root": { "type": "string", "minLength": 1 }
+      }
+    },
     "project": {
       "type": "object",
       "additionalProperties": false,

package/scripts/init-harness.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import path from "node:path";
@@ -109,6 +109,26 @@ async function collectTemplateFiles() {
   return files.sort();
 }
 
+async function collectExistingFiles(basePath) {
+  const files = new Set();
+  if (!(await exists(basePath))) return files;
+
+  async function walk(currentPath) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolute = path.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        await walk(absolute);
+      } else if (entry.isFile()) {
+        files.add(absolute);
+      }
+    }
+  }
+
+  await walk(basePath);
+  return files;
+}
+
 async function generatedScriptHashes(templateFiles, config, values) {
   const hashes = {};
   const trustedScriptTemplates = new Set(trustedGeneratedScriptTemplatesForSettings(config));
@@ -137,6 +157,11 @@ export async function writeRenderedFile(sourceRelative, targetRoot, values, opti
   }
 
   if ((await exists(targetPath)) && !options.force) {
+    const actual = await readFile(targetPath, "utf8");
+    if (actual === content) {
+      console.log(`verified existing ${targetPath}`);
+      return { action: "verified", rendered: true, targetPath, targetRelative };
+    }
     console.log(`skipped existing ${targetPath}`);
     return { action: "skipped", rendered: false, targetPath, targetRelative };
   }
@@ -198,9 +223,10 @@ export async function installConsumerEntrypoints(resolvedConfig, options) {
         label: `Consumer entrypoint ${targetRelative}`,
       });
       await mkdir(path.dirname(targetPath), { recursive: true });
+      const existed = await exists(targetPath);
       await writeFile(targetPath, content);
       console.log(`wrote consumer entrypoint ${targetPath}`);
-      records.push({ ...record, action: "wrote", rendered: true });
+      records.push({ ...record, action: existed ? "wrote" : "created", rendered: true });
     }
   }
 
@@ -255,9 +281,16 @@ async function writeGenerationManifest({
     rootPath: outputRoot,
     label: "Generation manifest .structor/manifest.json",
   });
+  const existed = await exists(manifestPath);
   await mkdir(path.dirname(manifestPath), { recursive: true });
   await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
   console.log(`wrote ${manifestPath}`);
+  return {
+    action: existed ? "wrote" : "created",
+    rendered: true,
+    targetPath: manifestPath,
+    targetRelative: path.relative(outputRoot, manifestPath).replaceAll(path.sep, "/"),
+  };
 }
 
 export async function generateHarness(config, {
@@ -268,6 +301,7 @@ export async function generateHarness(config, {
   dryRun = false,
   force = false,
   installConsumerEntrypoints: shouldInstallConsumerEntrypoints = false,
+  requireExistingConsumers = false,
   allowAbsoluteOutput = false,
   allowTemplateRepoConsumer = false,
 } = {}) {
@@ -279,11 +313,15 @@ export async function generateHarness(config, {
     configDir,
     outputPath,
     allowAbsoluteOutput,
-    requireExistingConsumers: shouldInstallConsumerEntrypoints,
+    requireExistingConsumers: requireExistingConsumers || shouldInstallConsumerEntrypoints,
     allowTemplateRepoConsumer,
   });
   const { outputRoot, support } = resolvedConfig;
-  const values = harnessTemplateValues(config, support, resolvedConfig.consumers, outputRoot);
+  const templateWorkspaceRoot = config.workspace?.root
+    ? path.resolve(configDir, config.workspace.root)
+    : path.resolve(configDir);
+  const templateOutputRoot = path.resolve(templateWorkspaceRoot, outputPath);
+  const values = harnessTemplateValues(config, support, resolvedConfig.consumers, templateOutputRoot, templateWorkspaceRoot);
   values.GENERATED_HARNESS_CONTRACT_MODULE = await readFile(
     path.join(repoRoot, "scripts/generated-harness-contract.mjs"),
     "utf8",
@@ -304,11 +342,36 @@ export async function generateHarness(config, {
     }
   }
 
+  const htmlViewsRoot = path.join(outputRoot, "ai", "views");
+  const htmlViewFilesBefore = renderedHtmlViewsScript
+    ? await collectExistingFiles(htmlViewsRoot)
+    : new Set();
   if (!dryRun && renderedHtmlViewsScript) {
-    execFileSync(process.execPath, [path.join(outputRoot, "scripts/generate-html-views.mjs")], {
-      cwd: outputRoot,
-      stdio: "inherit",
-    });
+    let htmlViewFilesAfter;
+    try {
+      execFileSync(process.execPath, [path.join(outputRoot, "scripts/generate-html-views.mjs")], {
+        cwd: outputRoot,
+        stdio: "inherit",
+      });
+      htmlViewFilesAfter = await collectExistingFiles(htmlViewsRoot);
+    } catch (error) {
+      htmlViewFilesAfter = await collectExistingFiles(htmlViewsRoot);
+      for (const targetPath of htmlViewFilesAfter) {
+        if (!htmlViewFilesBefore.has(targetPath)) {
+          await rm(targetPath, { force: true });
+        }
+      }
+      throw error;
+    }
+    for (const targetPath of htmlViewFilesAfter) {
+      if (htmlViewFilesBefore.has(targetPath)) continue;
+      generatedFiles.push({
+        action: "created",
+        rendered: true,
+        targetPath,
+        targetRelative: path.relative(outputRoot, targetPath).replaceAll(path.sep, "/"),
+      });
+    }
   } else if (!dryRun) {
     console.log("skipped HTML view generation because scripts/generate-html-views.mjs was not freshly rendered");
   }
@@ -317,8 +380,8 @@ export async function generateHarness(config, {
     ? await installConsumerEntrypoints(resolvedConfig, { dryRun, force, config: configPath })
     : [];
 
-  if (!dryRun) {
-    await writeGenerationManifest({
+  const manifestFile = !dryRun
+    ? await writeGenerationManifest({
       config,
       configContent: manifestConfigContent,
       configPath,
@@ -327,10 +390,15 @@ export async function generateHarness(config, {
       outputRoot,
       resolvedConfig,
       support,
-    });
-  }
+    })
+    : null;
 
-  return resolvedConfig;
+  return {
+    resolvedConfig,
+    generatedFiles,
+    consumerEntrypoints,
+    manifestFile,
+  };
 }
 
 async function main() {

package/scripts/lib.mjs

@@ -102,6 +102,15 @@ export function workspaceRootForConfig(configDir, templateRepoRoot = repoRoot) {
     : resolvedConfigDir;
 }
 
+function resolveWorkspaceRoot(config, configDir, templateRepoRoot = repoRoot) {
+  const configuredRoot = config.workspace?.root;
+  if (typeof configuredRoot !== "string" || configuredRoot.trim() === "") {
+    return workspaceRootForConfig(configDir, templateRepoRoot);
+  }
+
+  return path.resolve(configDir, configuredRoot);
+}
+
 export async function canonicalPathForWrite(targetPath) {
   let currentPath = path.resolve(targetPath);
   const missingSegments = [];
@@ -355,10 +364,15 @@ export async function resolveHarnessConfig(config, {
   }
 
   const resolvedConfigDir = path.resolve(configDir);
-  const workspaceRoot = workspaceRootForConfig(resolvedConfigDir, templateRepoRoot);
-  const requestedOutputRoot = path.resolve(resolvedConfigDir, outputPath);
+  const workspaceRoot = resolveWorkspaceRoot(config, resolvedConfigDir, templateRepoRoot);
+  const topologyRoot = config.workspace?.root ? workspaceRoot : resolvedConfigDir;
+  const requestedOutputRoot = path.resolve(topologyRoot, outputPath);
   const consumerRoots = [];
 
+  if (!isSameOrInsidePath(resolvedConfigDir, workspaceRoot)) {
+    errors.push(`${label}: config path ${resolvedConfigDir} must stay inside the workspace root ${workspaceRoot}.`);
+  }
+
   for (const consumer of config.consumers) {
     try {
       consumerRoots.push(assertSafeConsumerPath({

package/scripts/rendered-config.mjs

@@ -57,13 +57,12 @@ function consumerNames(consumers) {
   return consumers.map((consumer) => rawSlug(consumer.name, "consumer.name"));
 }
 
-function consumerConfig(resolvedConsumers, outputRoot) {
-  const generatedWorkspaceRoot = path.dirname(outputRoot);
-  return resolvedConsumers.map(({ config: consumer, root: consumerRoot }) => {
+function consumerConfig(resolvedConsumers, workspaceRoot) {
+  return resolvedConsumers.map(({ config: consumer, requestedRoot, root: consumerRoot }) => {
     return {
       ...consumer,
       name: rawSlug(consumer.name, "consumer.name"),
-      workspacePath: path.relative(generatedWorkspaceRoot, consumerRoot).replaceAll(path.sep, "/") || ".",
+      workspacePath: path.relative(workspaceRoot, requestedRoot ?? consumerRoot).replaceAll(path.sep, "/") || ".",
     };
   });
 }
@@ -72,16 +71,20 @@ export function renderedGeneratedScriptHashes(hashes) {
   return jsonLiteral(hashes);
 }
 
-export function harnessTemplateValues(config, support, resolvedConsumers, outputRoot) {
+export function harnessTemplateValues(config, support, resolvedConsumers, outputRoot, workspaceRoot = path.dirname(outputRoot)) {
+  const workspaceHarnessPath = path.relative(workspaceRoot, outputRoot).replaceAll(path.sep, "/") || ".";
+
   return {
     PROJECT_NAME: markdownText(config.project.name),
     PROJECT_NAME_CODE: markdownCodeSpan(config.project.name),
     PROJECT_NAME_JSON: javascriptLiteral(config.project.name),
     PROJECT_SLUG: rawSlug(config.project.slug, "project.slug"),
     HARNESS_REPO_NAME: rawSlug(config.project.harnessRepoName, "project.harnessRepoName"),
+    WORKSPACE_HARNESS_PATH: workspaceHarnessPath.startsWith(".") ? workspaceHarnessPath : `./${workspaceHarnessPath}`,
+    WORKSPACE_ROOT_FROM_HARNESS_JSON: javascriptLiteral(path.relative(outputRoot, workspaceRoot).replaceAll(path.sep, "/") || "."),
     CONSUMER_REPOS_LIST: consumerList(config.consumers),
     CONSUMER_REPO_NAMES_JSON: javascriptLiteral(consumerNames(config.consumers)),
-    CONSUMER_CONFIG_JSON: jsonLiteral(consumerConfig(resolvedConsumers, outputRoot)),
+    CONSUMER_CONFIG_JSON: jsonLiteral(consumerConfig(resolvedConsumers, workspaceRoot)),
     PRIMARY_CONSUMER_NAME: rawSlug(config.consumers[0].name, "consumer.name"),
     MODEL_OPENAI_ENABLED: javascriptBoolean(config.models.openai),
     MODEL_ANTHROPIC_ENABLED: javascriptBoolean(config.models.anthropic),

package/scripts/setup-contributor.mjs

@@ -75,7 +75,7 @@ async function main() {
   console.log(`Workspace: ${workspaceRoot}`);
   console.log(`Preset: ${presetConfigPath}`);
 
-  const resolvedConfig = await generateHarness(config, {
+  const { resolvedConfig } = await generateHarness(config, {
     configPath: presetConfigPath,
     configDir: workspaceRoot,
     dryRun: options.dryRun,

package/template/scripts/bootstrap-workspace.mjs.tpl

@@ -8,7 +8,7 @@ import { workspaceEntrypointsForSettings } from "./generated-harness-contract.mj
 import { assertSafeWriteTarget, exists } from "./lib/path-safety.mjs";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const workspaceRoot = path.resolve(repoRoot, "..");
+const workspaceRoot = path.resolve(repoRoot, {{WORKSPACE_ROOT_FROM_HARNESS_JSON}});
 const consumers = {{CONSUMER_CONFIG_JSON}};
 const models = {
   openai: {{MODEL_OPENAI_ENABLED}},

package/template/scripts/check-workspace.mjs.tpl

@@ -13,7 +13,7 @@ import {
 } from "./generated-harness-contract.mjs";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const workspaceRoot = path.resolve(repoRoot, "..");
+const workspaceRoot = path.resolve(repoRoot, {{WORKSPACE_ROOT_FROM_HARNESS_JSON}});
 const harnessRepoName = "{{HARNESS_REPO_NAME}}";
 const consumers = {{CONSUMER_CONFIG_JSON}};
 const models = {

package/template/workspace/AGENTS.md.tpl

@@ -4,14 +4,13 @@ This workspace is governed by the {{PROJECT_NAME}} engineering harness.
 
 Read the harness first:
 
-1. `./{{HARNESS_REPO_NAME}}/AGENTS.md`
-2. `./{{HARNESS_REPO_NAME}}/ai/AGENTS.md`
-3. `./{{HARNESS_REPO_NAME}}/ai/HUB.md`
-4. `./{{HARNESS_REPO_NAME}}/ai/context.md`
+1. `{{WORKSPACE_HARNESS_PATH}}/AGENTS.md`
+2. `{{WORKSPACE_HARNESS_PATH}}/ai/AGENTS.md`
+3. `{{WORKSPACE_HARNESS_PATH}}/ai/HUB.md`
+4. `{{WORKSPACE_HARNESS_PATH}}/ai/context.md`
 
 Consumer repositories:
 
 {{CONSUMER_REPOS_LIST}}
 
 Keep this file short. Canonical policy belongs in the harness repo.
-

package/template/workspace/CLAUDE.md.tpl

@@ -2,14 +2,14 @@
 
 This workspace is governed by the {{PROJECT_NAME}} engineering harness.
 
-@./{{HARNESS_REPO_NAME}}/ai/context.md
+@{{WORKSPACE_HARNESS_PATH}}/ai/context.md
 
 Read the harness first:
 
-1. `./{{HARNESS_REPO_NAME}}/CLAUDE.md`
-2. `./{{HARNESS_REPO_NAME}}/ai/AGENTS.md`
-3. `./{{HARNESS_REPO_NAME}}/ai/HUB.md`
-4. `./{{HARNESS_REPO_NAME}}/ai/context.md`
+1. `{{WORKSPACE_HARNESS_PATH}}/CLAUDE.md`
+2. `{{WORKSPACE_HARNESS_PATH}}/ai/AGENTS.md`
+3. `{{WORKSPACE_HARNESS_PATH}}/ai/HUB.md`
+4. `{{WORKSPACE_HARNESS_PATH}}/ai/context.md`
 
 Consumer repositories: