@structor-dev/cli 0.1.0 → 0.2.1

package/bin/structor.mjs

@@ -1,16 +1,29 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { access, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { access, mkdir, readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import readline from "node:readline/promises";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  assertSafeConsumerPath,
+  hasConsumerRepositorySignal,
+  resolveHarnessConfig,
+  validateConfigShape,
+} from "../scripts/lib.mjs";
+import {
+  consumerEntrypointsForSettings,
+  requiredHarnessRepoFilesForWorkspaceCheck,
+  requiredWorkspaceFilesForWorkspaceCheck,
+  workspaceEntrypointsForSettings,
+} from "../scripts/generated-harness-contract.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const generatorPath = path.join(packageRoot, "scripts/init-harness.mjs");
 const configFileName = "harness.config.json";
+const structorRepoUrlDefault = "https://github.com/nicolaycamacho/structor.git";
 const reset = "\x1b[0m";
 const styles = {
   bold: "\x1b[1m",
@@ -83,7 +96,7 @@ async function maybeReadJson(filePath) {
   }
 }
 
-function slugify(value) {
+export function slugify(value) {
   return value
     .trim()
     .toLowerCase()
@@ -92,12 +105,12 @@ function slugify(value) {
     || "project";
 }
 
-function relativeFrom(basePath, targetPath) {
+export function relativeFrom(basePath, targetPath) {
   const relative = path.relative(basePath, targetPath).replaceAll(path.sep, "/");
   return relative === "" ? "." : relative.startsWith(".") ? relative : `./${relative}`;
 }
 
-function parseArgs(argv) {
+export function parseArgs(argv) {
   const [command = "help", ...rest] = argv;
   const options = { _: [] };
   for (let index = 0; index < rest.length; index += 1) {
@@ -110,15 +123,25 @@ function parseArgs(argv) {
     else if (arg === "--help" || arg === "-h") options.help = true;
     else if (arg === "--install-consumer-entrypoints") options.installConsumerEntrypoints = true;
     else if (arg === "--force") options.force = true;
+    else if (arg === "--dry-run") options.dryRun = true;
     else if (arg === "--workspace") options.workspace = rest[++index];
+    else if (arg === "--repo-url") options.repoUrl = rest[++index];
     else if (arg === "--config") options.config = rest[++index];
     else options._.push(arg);
   }
   return { command, options, rawArgs: rest };
 }
 
+function assertNoUnknownCommandFlags(command, options) {
+  const unknownFlags = options._.filter((arg) => arg.startsWith("--"));
+  if (unknownFlags.length === 0) return;
+
+  const noun = unknownFlags.length === 1 ? "argument" : "arguments";
+  throw new Error(`Unknown ${noun} for structor ${command}: ${unknownFlags.join(", ")}`);
+}
+
 function printHelp() {
-  console.log(`Structor\n\nUsage:\n  structor init [--workspace <path>] [--config <path>] [--yes]\n  structor generate --config <path> [generator options]\n  structor doctor\n\nCommands:\n  init      Guided local setup for a Structor workspace.\n  generate  Render a generated harness from an existing config.\n  doctor    Planned diagnostic and repair command.\n`);
+  console.log(`Structor\n\nUsage:\n  structor init [--workspace <path>] [--config <path>] [--yes]\n  structor generate --config <path> [generator options]\n  structor contribute structor [--workspace <path>] [--repo-url <url-or-path>] [--yes] [--dry-run] [--force]\n  structor doctor [--workspace <path>] [--config <path>]\n\nCommands:\n  init                 Guided local setup for a Structor workspace.\n  generate             Render a generated harness from an existing config.\n  contribute structor  Create or refresh a local Structor contributor workspace.\n  doctor               Diagnose local Structor workspace drift without repairing files.\n`);
 }
 
 function runGenerator(args, cwd = process.cwd()) {
@@ -216,7 +239,52 @@ async function isDirectory(filePath) {
   }
 }
 
-function shouldExcludeCandidate(name) {
+async function isEmptyDirectory(filePath) {
+  try {
+    return (await readdir(filePath)).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function isUsableStructorCheckout(repoRoot) {
+  if (!(await isDirectory(repoRoot))) return false;
+  const packageJson = await maybeReadJson(path.join(repoRoot, "package.json"));
+  return (
+    packageJson?.name === "@structor-dev/cli" &&
+    await exists(path.join(repoRoot, "bin/structor.mjs")) &&
+    await exists(path.join(repoRoot, "scripts/setup-contributor.mjs")) &&
+    await exists(path.join(repoRoot, "contrib/self-harness/harness.config.json"))
+  );
+}
+
+export function contributorWorkspacePlan(options = {}, cwd = process.cwd()) {
+  const workspaceRoot = path.resolve(cwd, options.workspace ?? ".");
+  const sourceRoot = path.join(workspaceRoot, "structor");
+  const selfHarnessRoot = path.join(workspaceRoot, "structor-self");
+  return {
+    workspaceRoot,
+    sourceRoot,
+    selfHarnessRoot,
+    repoUrl: options.repoUrl ?? structorRepoUrlDefault,
+  };
+}
+
+function runCommand(command, args, cwd, stdio = "inherit") {
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio,
+    encoding: stdio === "pipe" ? "utf8" : undefined,
+  });
+  if (result.error) throw result.error;
+  return result;
+}
+
+function commandText(command, args) {
+  return [command, ...args].join(" ");
+}
+
+export function shouldExcludeCandidate(name) {
   return (
     name.startsWith(".") ||
     name === "node_modules" ||
@@ -261,7 +329,7 @@ async function detectPackageManager(repoRoot) {
   return null;
 }
 
-function packageCommand(packageManager, scriptName) {
+export function packageCommand(packageManager, scriptName) {
   if (packageManager === "yarn") return `yarn ${scriptName}`;
   if (scriptName === "test") return `${packageManager} test`;
   return `${packageManager} run ${scriptName}`;
@@ -297,7 +365,7 @@ async function inferValidation(repoRoot) {
   return validation;
 }
 
-function compactValidation(validation) {
+export function compactValidation(validation) {
   return Object.fromEntries(Object.entries(validation).filter(([, value]) => value.trim() !== ""));
 }
 
@@ -323,12 +391,24 @@ async function collectConsumerDetails(rl, workspaceRoot, selectedCandidates) {
   return consumers;
 }
 
-async function promptManualConsumers(rl, workspaceRoot) {
+async function promptManualConsumers(rl, workspaceRoot, outputPath) {
   const consumers = [];
   while (consumers.length === 0 || await askYesNo(rl, "Add another consumer repo?", false)) {
     section(`Consumer ${consumers.length + 1}`);
     const repoPath = await askLine(rl, "Path to consumer repo, relative to workspace", "./app");
     const absolutePath = path.resolve(workspaceRoot, repoPath);
+    try {
+      assertSafeConsumerPath({
+        consumerName: slugify(path.basename(absolutePath)),
+        consumerPath: repoPath,
+        workspaceRoot,
+        outputRoot: path.resolve(workspaceRoot, outputPath),
+        repoRoot: packageRoot,
+      });
+    } catch (error) {
+      warn(error instanceof Error ? error.message : String(error));
+      continue;
+    }
     if (!(await isDirectory(absolutePath))) {
       warn(`Path does not exist yet: ${absolutePath}`);
       if (!(await askYesNo(rl, "Use this path anyway?", false))) continue;
@@ -378,7 +458,7 @@ async function writeConfig(configPath, config) {
   await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
 }
 
-function nextValidationCommands(config) {
+export function nextValidationCommands(config) {
   const commands = [
     `cd ${config.output.path}`,
     "node scripts/validate-governance.mjs",
@@ -389,6 +469,325 @@ function nextValidationCommands(config) {
   return commands;
 }
 
+function cleanHarnessReference(rawReference) {
+  return rawReference.trim().replace(/^[`'"]+/, "").replace(/[`'",;:.)\]}]+$/, "");
+}
+
+function extractHarnessReferences(content, harnessRepoName) {
+  const escapedName = harnessRepoName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp("(?:\\.\\.?/|/)[^`'\"\\s)<\\]}]*(?:" + escapedName + ")[^`'\"\\s)<\\]}]*", "g");
+  return [...new Set((content.match(pattern) ?? []).map(cleanHarnessReference).filter(Boolean))];
+}
+
+function resolveHarnessReferenceTarget({ reference: rawReference, basePath, harnessRepoName }) {
+  const reference = cleanHarnessReference(rawReference);
+  const absoluteReference = path.isAbsolute(reference) ? path.resolve(reference) : path.resolve(basePath, reference);
+  const parts = absoluteReference.split(path.sep);
+  if (parts.lastIndexOf(harnessRepoName) === -1) return null;
+  return absoluteReference;
+}
+
+function resolveHarnessReferenceRoot({ reference: rawReference, basePath, harnessRepoName }) {
+  const target = resolveHarnessReferenceTarget({ reference: rawReference, basePath, harnessRepoName });
+  if (!target) return null;
+  const parts = target.split(path.sep);
+  const index = parts.lastIndexOf(harnessRepoName);
+  return parts.slice(0, index + 1).join(path.sep) || path.sep;
+}
+
+async function isFileTarget(targetPath) {
+  try {
+    return (await stat(targetPath)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function canonicalExistingPath(targetPath) {
+  try {
+    return await realpath(targetPath);
+  } catch {
+    return path.resolve(targetPath);
+  }
+}
+
+function isWithinRoot(root, candidate) {
+  if (candidate === root) return true;
+  return candidate.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+}
+
+async function validateHarnessReferences({
+  pointerPath,
+  pointerContent,
+  basePath,
+  expectedHarnessRoot,
+  harnessRepoName,
+  models,
+  requireHarnessReference = true,
+}) {
+  const references = extractHarnessReferences(pointerContent, harnessRepoName);
+  if (references.length === 0) {
+    return requireHarnessReference
+      ? [`${pointerPath} does not contain a resolvable ${harnessRepoName} path.`]
+      : [];
+  }
+
+  const issues = [];
+  for (const reference of references) {
+    const target = resolveHarnessReferenceTarget({ reference, basePath, harnessRepoName });
+    const referenceRoot = resolveHarnessReferenceRoot({ reference, basePath, harnessRepoName });
+    if (!target || !referenceRoot) {
+      issues.push(`${pointerPath} does not contain a resolvable ${harnessRepoName} path.`);
+      continue;
+    }
+    const canonicalReferenceRoot = await canonicalExistingPath(referenceRoot);
+    const canonicalExpectedHarnessRoot = await canonicalExistingPath(expectedHarnessRoot);
+    if (canonicalReferenceRoot !== canonicalExpectedHarnessRoot) {
+      issues.push(`${pointerPath} points at ${referenceRoot} instead of ${expectedHarnessRoot}.`);
+      continue;
+    }
+
+    const relativeTarget = path.relative(referenceRoot, target).replaceAll(path.sep, "/");
+    if (!models.openai && relativeTarget === "AGENTS.md") {
+      issues.push(`${pointerPath} must not reference ${relativeTarget} when OpenAI support is disabled.`);
+    } else if (!models.anthropic && relativeTarget === "CLAUDE.md") {
+      issues.push(`${pointerPath} must not reference ${relativeTarget} when Anthropic support is disabled.`);
+    } else if (relativeTarget === "" || !(await isFileTarget(target))) {
+      issues.push(`${pointerPath} references missing generated-harness file ${relativeTarget || "."}.`);
+    } else {
+      // The lexical reference root can match while the target file resolves,
+      // via a symlink, to policy outside the harness. Require the canonical
+      // (realpath-resolved) target to stay under the canonical harness root.
+      const canonicalTarget = await canonicalExistingPath(target);
+      if (!isWithinRoot(canonicalExpectedHarnessRoot, canonicalTarget)) {
+        issues.push(`${pointerPath} resolves to ${canonicalTarget} outside the generated harness ${canonicalExpectedHarnessRoot}.`);
+      }
+    }
+  }
+  return issues;
+}
+
+async function readIfExists(filePath) {
+  if (!(await exists(filePath))) return null;
+  return readFile(filePath, "utf8");
+}
+
+async function collectEntrypointRoutingIssues({
+  label,
+  basePath,
+  entrypoints,
+  expectedHarnessRoot,
+  harnessRepoName,
+  models,
+}) {
+  const issues = [];
+  for (const entrypoint of entrypoints) {
+    const pointerPath = path.join(basePath, entrypoint.path);
+    const pointerContent = await readIfExists(pointerPath);
+    if (pointerContent === null) {
+      issues.push(`${label}:${entrypoint.path} missing.`);
+      continue;
+    }
+    if (entrypoint.routing === "claude-memory") {
+      if (!pointerContent.includes("../CLAUDE.md")) {
+        issues.push(`${label}:${entrypoint.path} must route through ../CLAUDE.md.`);
+      }
+      const referenceIssues = await validateHarnessReferences({
+        pointerPath: `${label}:${entrypoint.path}`,
+        pointerContent,
+        basePath,
+        expectedHarnessRoot,
+        harnessRepoName,
+        models,
+        requireHarnessReference: false,
+      });
+      issues.push(...referenceIssues);
+      continue;
+    }
+    const referenceIssues = await validateHarnessReferences({
+      pointerPath: `${label}:${entrypoint.path}`,
+      pointerContent,
+      basePath,
+      expectedHarnessRoot,
+      harnessRepoName,
+      models,
+    });
+    issues.push(...referenceIssues);
+  }
+  return issues;
+}
+
+function printDoctorCheck(results, status, label, detail = "") {
+  results.push({ status, label, detail });
+  const renderedStatus =
+    status === "OK" ? color("green", "OK") :
+    status === "WARN" ? color("yellow", "WARN") :
+    color("red", "FAIL");
+  console.log(`${renderedStatus} ${label}${detail ? ` - ${detail}` : ""}`);
+}
+
+async function doctor(options) {
+  const results = [];
+  const workspaceRoot = path.resolve(options.workspace ?? process.cwd());
+  const configPath = path.resolve(workspaceRoot, options.config ?? configFileName);
+  section("Structor doctor");
+  note("Diagnosis only. No files will be repaired or written.");
+
+  let config = null;
+  if (await exists(configPath)) {
+    printDoctorCheck(results, "OK", "config file exists", configPath);
+    try {
+      config = await readJson(configPath);
+      printDoctorCheck(results, "OK", "config file parses");
+    } catch (error) {
+      printDoctorCheck(results, "FAIL", "config file parses", error instanceof Error ? error.message : String(error));
+    }
+  } else {
+    printDoctorCheck(results, "FAIL", "config file exists", configPath);
+  }
+
+  let resolvedConfig = null;
+  if (config) {
+    const shapeErrors = await validateConfigShape(config, configPath);
+    if (shapeErrors.length === 0) {
+      printDoctorCheck(results, "OK", "config shape is valid");
+    } else {
+      for (const error of shapeErrors) printDoctorCheck(results, "FAIL", "config shape is valid", error);
+    }
+
+    if (shapeErrors.length === 0) {
+      try {
+        resolvedConfig = await resolveHarnessConfig(config, {
+          label: configPath,
+          configPath,
+          outputPath: config.output.path,
+        });
+        printDoctorCheck(results, "OK", "output root is safe", resolvedConfig.outputRoot);
+      } catch (error) {
+        printDoctorCheck(results, "FAIL", "output root is safe", error instanceof Error ? error.message : String(error));
+      }
+    }
+  }
+
+  if (resolvedConfig) {
+    const { outputRoot, workspaceRoot: resolvedWorkspaceRoot, consumers, support } = resolvedConfig;
+    const settings = { models: config.models, clientSupport: support };
+    const harnessRepoName = config.project.harnessRepoName;
+    const repoRequiredFiles = requiredHarnessRepoFilesForWorkspaceCheck(settings);
+    const workspaceRequiredFiles = requiredWorkspaceFilesForWorkspaceCheck(settings);
+    const workspaceRoutingEntrypoints = workspaceEntrypointsForSettings(settings).filter(
+      (entrypoint) => entrypoint.routing !== "presence",
+    );
+    const consumerRoutingEntrypoints = consumerEntrypointsForSettings(settings);
+
+    if (path.basename(outputRoot) === harnessRepoName) {
+      printDoctorCheck(results, "OK", "generated harness folder name matches config", harnessRepoName);
+    } else {
+      printDoctorCheck(results, "FAIL", "generated harness folder name matches config", `expected ${harnessRepoName}, found ${path.basename(outputRoot)}`);
+    }
+
+    if (await isDirectory(outputRoot)) {
+      printDoctorCheck(results, "OK", "generated harness output directory exists", outputRoot);
+    } else {
+      printDoctorCheck(results, "FAIL", "generated harness output directory exists", outputRoot);
+    }
+
+    const missingRepoFiles = [];
+    for (const relativePath of repoRequiredFiles) {
+      if (!(await exists(path.join(outputRoot, relativePath)))) missingRepoFiles.push(relativePath);
+    }
+    if (missingRepoFiles.length === 0) {
+      printDoctorCheck(results, "OK", "generated harness required files exist");
+    } else {
+      for (const relativePath of missingRepoFiles) {
+        printDoctorCheck(results, "FAIL", "generated harness required file exists", relativePath);
+      }
+    }
+
+    const missingWorkspaceFiles = [];
+    for (const relativePath of workspaceRequiredFiles) {
+      if (!(await exists(path.join(resolvedWorkspaceRoot, relativePath)))) missingWorkspaceFiles.push(relativePath);
+    }
+    if (missingWorkspaceFiles.length === 0) {
+      printDoctorCheck(results, "OK", "workspace entrypoint files exist");
+    } else {
+      for (const relativePath of missingWorkspaceFiles) {
+        printDoctorCheck(results, "FAIL", "workspace entrypoint file exists", relativePath);
+      }
+    }
+
+    const workspaceRoutingIssues = await collectEntrypointRoutingIssues({
+      label: "workspace",
+      basePath: resolvedWorkspaceRoot,
+      entrypoints: workspaceRoutingEntrypoints,
+      expectedHarnessRoot: outputRoot,
+      harnessRepoName,
+      models: config.models,
+    });
+    if (workspaceRoutingIssues.length === 0) {
+      printDoctorCheck(results, "OK", "workspace pointer files route to generated harness");
+    } else {
+      for (const issue of workspaceRoutingIssues) printDoctorCheck(results, "FAIL", "workspace pointer file routes to generated harness", issue);
+    }
+
+    for (const consumer of consumers) {
+      const consumerRoot = consumer.root;
+      if (await isDirectory(consumerRoot)) {
+        if (await hasConsumerRepositorySignal(consumerRoot)) {
+          printDoctorCheck(results, "OK", `consumer repo exists: ${consumer.config.name}`, consumerRoot);
+        } else {
+          printDoctorCheck(results, "FAIL", `consumer repo exists: ${consumer.config.name}`, `missing repository signal at ${consumerRoot}`);
+        }
+      } else {
+        printDoctorCheck(results, "FAIL", `consumer repo exists: ${consumer.config.name}`, consumerRoot);
+        continue;
+      }
+
+      if (Object.values(consumer.config.validation ?? {}).some((value) => typeof value === "string" && value.trim() !== "")) {
+        printDoctorCheck(results, "OK", `consumer validation command documented: ${consumer.config.name}`);
+      } else {
+        printDoctorCheck(results, "WARN", `consumer validation command documented: ${consumer.config.name}`, "no validation commands configured");
+      }
+
+      const consumerRoutingIssues = await collectEntrypointRoutingIssues({
+        label: `consumer:${consumer.config.name}`,
+        basePath: consumerRoot,
+        entrypoints: consumerRoutingEntrypoints,
+        expectedHarnessRoot: outputRoot,
+        harnessRepoName,
+        models: config.models,
+      });
+      if (consumerRoutingIssues.length === 0) {
+        printDoctorCheck(results, "OK", `consumer pointer files route to generated harness: ${consumer.config.name}`);
+      } else {
+        for (const issue of consumerRoutingIssues) {
+          printDoctorCheck(results, "FAIL", `consumer pointer file routes to generated harness: ${consumer.config.name}`, issue);
+        }
+      }
+    }
+
+    const manifestPath = path.join(outputRoot, ".structor/manifest.json");
+    if (await exists(manifestPath)) {
+      try {
+        await readJson(manifestPath);
+        printDoctorCheck(results, "OK", "manifest is present and parses", manifestPath);
+      } catch (error) {
+        printDoctorCheck(results, "WARN", "manifest is present but does not parse", error instanceof Error ? error.message : String(error));
+      }
+    } else {
+      printDoctorCheck(results, "WARN", "manifest is present", "optional in doctor v1");
+    }
+  }
+
+  const failures = results.filter((result) => result.status === "FAIL").length;
+  const warnings = results.filter((result) => result.status === "WARN").length;
+  if (failures > 0) {
+    fail(`Structor doctor found ${failures} failure(s) and ${warnings} warning(s).`);
+    process.exit(1);
+  }
+  success(`Structor doctor passed with ${warnings} warning(s).`);
+}
+
 function printNextSteps(config) {
   section("Next validation commands");
   note("Run these from the workspace after generation to prove harness policy and workspace routing are healthy.");
@@ -397,6 +796,128 @@ function printNextSteps(config) {
   }
 }
 
+async function printContributorPlan(plan, options, sourceReady) {
+  section(options.dryRun ? "Contributor workspace preview" : "Contributor workspace");
+  console.log(`Workspace: ${plan.workspaceRoot}`);
+  console.log(`Structor source: ${plan.sourceRoot}`);
+  console.log(`Structor self-harness: ${plan.selfHarnessRoot}`);
+  console.log(`Repo URL: ${plan.repoUrl}`);
+  console.log(`Source checkout: ${sourceReady ? "reuse existing local checkout" : "clone required"}`);
+
+  section("Network reads");
+  if (sourceReady) {
+    console.log("  - none; existing local Structor checkout will be reused");
+  } else {
+    console.log(`  - ${commandText("git", ["clone", plan.repoUrl, plan.sourceRoot])}`);
+  }
+
+  section("Local filesystem writes");
+  if (!sourceReady) console.log(`  - create or use workspace folder ${plan.workspaceRoot}`);
+  if (!sourceReady) console.log(`  - create Structor checkout ${plan.sourceRoot}`);
+  console.log(`  - generate or refresh self-harness ${plan.selfHarnessRoot}`);
+  console.log("  - install missing source repo agent entrypoint pointers");
+  if (options.force) {
+    console.log("  - overwrite existing source repo agent entrypoint pointers because --force was provided");
+  } else {
+    console.log("  - skip existing source repo agent entrypoint pointers unless --force is provided");
+  }
+
+  section("Validation");
+  console.log(`  - ${commandText(process.execPath, ["scripts/setup-contributor.mjs", ...(options.dryRun ? ["--dry-run"] : []), ...(options.force ? ["--force"] : [])])}`);
+  console.log(`  - ${commandText(process.execPath, ["scripts/validate-governance.mjs"])} in ${plan.selfHarnessRoot}`);
+  console.log(`  - ${commandText(process.execPath, ["scripts/check-workspace.mjs"])} in ${plan.selfHarnessRoot}`);
+  console.log(`  - deferred source validation: cd ${plan.sourceRoot} && npm run validate`);
+}
+
+async function confirmContributorRun(options, plan, sourceReady) {
+  if (options.yes || options.dryRun) return true;
+  const rl = await createPrompt();
+  try {
+    await printContributorPlan(plan, options, sourceReady);
+    return await askYesNo(rl, "Continue with local writes and any required clone read?", false);
+  } finally {
+    rl.close();
+  }
+}
+
+async function ensureStructorCheckout(plan, options) {
+  const sourceReady = await isUsableStructorCheckout(plan.sourceRoot);
+  if (sourceReady) return { sourceReady: true, cloned: false };
+
+  if (await exists(plan.sourceRoot) && !(await isEmptyDirectory(plan.sourceRoot))) {
+    throw new Error(
+      `Existing ${plan.sourceRoot} is not a usable Structor checkout. Move it, choose a different --workspace, or provide a workspace with a valid structor checkout.`,
+    );
+  }
+
+  if (options.dryRun) return { sourceReady: false, cloned: false };
+
+  await mkdir(plan.workspaceRoot, { recursive: true });
+  section("Clone Structor source");
+  note("Network read only: this clones source code and does not authenticate, fork, push, open PRs, or mutate remotes.");
+  const clone = runCommand("git", ["clone", plan.repoUrl, plan.sourceRoot], process.cwd());
+  if (clone.status !== 0) throw new Error(`Clone failed: ${commandText("git", ["clone", plan.repoUrl, plan.sourceRoot])}`);
+  if (!(await isUsableStructorCheckout(plan.sourceRoot))) {
+    throw new Error(`Clone completed but ${plan.sourceRoot} is not a usable Structor checkout.`);
+  }
+  return { sourceReady: false, cloned: true };
+}
+
+function runContributorValidation(plan) {
+  section("Validate self-harness");
+  const validationCommands = [
+    [process.execPath, ["scripts/validate-governance.mjs"]],
+    [process.execPath, ["scripts/check-workspace.mjs"]],
+  ];
+  for (const [command, args] of validationCommands) {
+    console.log(`$ ${commandText(command, args)}`);
+    const result = runCommand(command, args, plan.selfHarnessRoot);
+    if (result.status !== 0) {
+      throw new Error(`Validation failed in ${plan.selfHarnessRoot}: ${commandText(command, args)}`);
+    }
+  }
+}
+
+function printContributorSummary(plan, setupArgs, validationRan) {
+  section("Structor contributor workspace ready");
+  console.log(`Workspace: ${plan.workspaceRoot}`);
+  console.log(`Structor source: ${plan.sourceRoot}`);
+  console.log(`Structor self-harness: ${plan.selfHarnessRoot}`);
+  console.log(`Contributor setup: ${commandText(process.execPath, setupArgs)}`);
+  console.log(`Validation: ${validationRan ? "passed" : "preview only; no validation commands were run"}`);
+
+  section("Next agent prompt");
+  console.log(`Work in ${plan.sourceRoot} using the sibling self-harness at ${plan.selfHarnessRoot}. Read AGENTS.md, ai/HUB.md, and the relevant issue, then make the smallest Structor change with validation evidence.`);
+}
+
+async function contributeStructor(options) {
+  if (options._.length !== 1) {
+    throw new Error("Usage: structor contribute structor [--workspace <path>] [--repo-url <url-or-path>] [--yes] [--dry-run] [--force]");
+  }
+  const plan = contributorWorkspacePlan(options);
+  const sourceReady = await isUsableStructorCheckout(plan.sourceRoot);
+  if (!(await confirmContributorRun(options, plan, sourceReady))) {
+    warn("Stopped before cloning, generating, or writing local files.");
+    return;
+  }
+
+  if (options.dryRun) {
+    await printContributorPlan(plan, options, sourceReady);
+    return;
+  }
+
+  await ensureStructorCheckout(plan, options);
+
+  section("Generate Structor self-harness");
+  const setupArgs = ["scripts/setup-contributor.mjs"];
+  if (options.force) setupArgs.push("--force");
+  const setup = runCommand(process.execPath, setupArgs, plan.sourceRoot);
+  if (setup.status !== 0) throw new Error(`Contributor setup failed: ${commandText(process.execPath, setupArgs)}`);
+
+  runContributorValidation(plan);
+  printContributorSummary(plan, setupArgs, true);
+}
+
 async function init(options) {
   const rl = await createPrompt();
   try {
@@ -435,12 +956,8 @@ async function init(options) {
     ], defaultModelIndex);
 
     section("Customization");
-    await askChoice(rl, "How much should Structor customize from consumer repos?", [
-      { label: "Starter only", value: "starter", note: "available now" },
-      { label: "Light scan", value: "starter", note: "coming soon" },
-      { label: "Deep scan", value: "starter", note: "coming soon" },
-    ]);
     note("Starter only creates generic harness content. It does not infer real contracts or coding conventions.");
+    note("Light Scan and Deep Scan are planned future opt-in Consumer Repo Scan modes.");
 
     section("Consumer repos");
     note("For best results, run Structor from the workspace folder that contains your consumer repos as siblings.");
@@ -463,7 +980,7 @@ async function init(options) {
       consumers = await collectConsumerDetails(rl, workspaceRoot, selected);
       } else {
       warn("No obvious sibling consumer repos found.");
-      consumers = await promptManualConsumers(rl, workspaceRoot);
+      consumers = await promptManualConsumers(rl, workspaceRoot, outputPath);
       }
     }
 
@@ -512,7 +1029,7 @@ async function init(options) {
     printCommandOutput(dryRun);
     if (dryRun.status !== 0) throw new Error("Generator dry-run failed.");
 
-    const apply = options.yes || await askYesNo(rl, "Generate harness now?", false);
+    const apply = options.yes || await askYesNo(rl, "Generate harness now?", true);
     if (!apply) {
       warn("Stopped after dry-run preview.");
       printNextSteps(config);
@@ -551,6 +1068,7 @@ async function main() {
     return;
   }
   if (command === "init") {
+    assertNoUnknownCommandFlags(command, options);
     await init(options);
     return;
   }
@@ -558,19 +1076,33 @@ async function main() {
     passthroughGenerate(rawArgs);
     return;
   }
+  if (command === "contribute") {
+    const [target] = options._;
+    if (target !== "structor") {
+      throw new Error("Unknown contribute target. Supported target: structor");
+    }
+    await contributeStructor(options);
+    return;
+  }
   if (command === "doctor") {
-    note("structor doctor is planned but not implemented yet.");
-    note("It will diagnose and repair drift in an existing Structor workspace:");
-    note("  - stale or missing consumer entrypoints");
-    note("  - moved harness or consumer folders");
-    note("  - unsafe output paths");
-    note("Track progress: docs/issues/0001-structor-doctor.md");
-    process.exit(1);
+    assertNoUnknownCommandFlags(command, options);
+    await doctor(options);
+    return;
   }
   throw new Error(`Unknown command: ${command}`);
 }
 
-main().catch((error) => {
-  fail(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});
+async function isDirectCliInvocation() {
+  if (!process.argv[1]) return false;
+
+  const invokedPath = await realpath(process.argv[1]).catch(() => path.resolve(process.argv[1]));
+  const modulePath = await realpath(fileURLToPath(import.meta.url)).catch(() => fileURLToPath(import.meta.url));
+  return pathToFileURL(invokedPath).href === pathToFileURL(modulePath).href;
+}
+
+if (await isDirectCliInvocation()) {
+  main().catch((error) => {
+    fail(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}