@documentation-robotics/cli 0.1.13 → 0.3.0

package/dist/commands/farm.js

@@ -0,0 +1,773 @@
+import ansis from "ansis";
+import path from "path";
+import { rm } from "fs/promises";
+import { FarmManifest } from "../core/farm-manifest.js";
+import { findFarmRoot, resolveModelDirectory } from "../utils/project-paths.js";
+import { fileExists } from "../utils/file-io.js";
+import { execSync, execFileSync } from "child_process";
+import * as prompts from "@clack/prompts";
+import { getErrorMessage, handleSuccess, handleInfo, handleWarning } from "../utils/errors.js";
+import { isJson } from "../utils/globals.js";
+import { isTelemetryEnabled, startSpan, endSpan } from "../telemetry/index.js";
+import { Model } from "../core/model.js";
+import { ComposedReferenceValidator } from "../validators/composed-reference-validator.js";
+import { ValidationFormatter } from "../validators/validation-formatter.js";
+import { FarmSyncEngine } from "../core/farm-sync-engine.js";
+import { FarmSyncState, FarmSyncStateNotFoundError } from "../core/farm-sync-state.js";
+function checkGitRepository(cwd) {
+  try {
+    return execSync("git rev-parse --git-dir", { cwd, stdio: "pipe" }), { isRepo: !0 };
+  } catch (error) {
+    const errorMsg = getErrorMessage(error);
+    return errorMsg.toLowerCase().includes("not a git repository") ? { isRepo: !1 } : { isRepo: !1, error: errorMsg.trim() };
+  }
+}
+function uncommittedChangeWarning(what, farmRoot, gitError) {
+  return `${what} was saved but not committed: could not check git repository at ${farmRoot}: ${gitError}`;
+}
+function gitTopLevel(cwd) {
+  try {
+    return execSync("git rev-parse --show-toplevel", { cwd, stdio: "pipe", encoding: "utf-8" }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+function isInSameGitRepository(farmRoot, target) {
+  const farmTop = gitTopLevel(farmRoot);
+  return farmTop !== null && farmTop === gitTopLevel(target);
+}
+function farmRelativePath(farmRoot, target) {
+  const rel = path.relative(farmRoot, target);
+  return rel === "" ? "." : rel.split(path.sep).join("/");
+}
+function isWithinPath(target, parent) {
+  return target === parent || target.startsWith(parent + path.sep);
+}
+async function resolveProjectModel(name, input) {
+  const { farmRoot, codebaseFullPath, explicitModel, forceNewModel } = input;
+  if (explicitModel) {
+    const explicitFullPath = path.resolve(farmRoot, explicitModel), resolved = await resolveModelDirectory(explicitFullPath, { requireManifest: !0 });
+    if (!resolved)
+      throw new Error(`No model found at '${explicitModel}': expected manifest.yaml in ${explicitFullPath}, ${path.join(explicitFullPath, "model")} or ${path.join(explicitFullPath, "documentation-robotics", "model")}. Omit --model to scaffold a new model at ${name}-model.`);
+    return {
+      modelFolder: farmRelativePath(farmRoot, resolved.modelDir),
+      modelFullPath: resolved.modelDir,
+      adopted: !0
+    };
+  }
+  const detected = codebaseFullPath === farmRoot ? null : await resolveModelDirectory(codebaseFullPath, { requireManifest: !0 });
+  if (detected && !forceNewModel)
+    return {
+      modelFolder: farmRelativePath(farmRoot, detected.modelDir),
+      modelFullPath: detected.modelDir,
+      adopted: !0
+    };
+  const modelFolder = `${name}-model`, modelFullPath = path.resolve(path.join(farmRoot, modelFolder));
+  if (!modelFullPath.startsWith(farmRoot + path.sep))
+    throw new Error(`Invalid model path: would escape farm root. Path: ${modelFolder}`);
+  return {
+    modelFolder,
+    modelFullPath,
+    adopted: !1,
+    ...detected ? { ignoredModelPath: farmRelativePath(farmRoot, detected.modelDir) } : {}
+  };
+}
+async function farmInitCommand(options) {
+  const span = isTelemetryEnabled ? startSpan("farm.init") : null;
+  try {
+    const farmPath = process.cwd(), farmYamlPath = path.join(farmPath, "farm.yaml"), useJson = options.format === "json" || isJson();
+    if (await fileExists(farmYamlPath)) {
+      const message = "Farm already initialized in this directory";
+      useJson ? console.log(JSON.stringify({ status: "error", code: 1, message })) : console.error(ansis.red(`Error: ${message}`)), span && endSpan(span), process.exit(1);
+    }
+    let farmName = options.name;
+    if (!farmName && process.stdin.isTTY) {
+      const result = await prompts.text({
+        message: "Farm name",
+        placeholder: "My Architecture Farm"
+      });
+      typeof result == "string" && (farmName = result);
+    }
+    farmName || (farmName = "Architecture Farm"), await FarmManifest.create(farmName, {
+      platform_view: options.platformView || !1
+    }).save(farmYamlPath);
+    try {
+      execSync("git init", { cwd: farmPath, stdio: useJson ? "pipe" : "inherit" }), execSync("git config user.email 'dr-farm@localhost'", {
+        cwd: farmPath,
+        stdio: "pipe"
+      }), execSync("git config user.name 'DR Farm'", {
+        cwd: farmPath,
+        stdio: "pipe"
+      }), execSync("git add farm.yaml", { cwd: farmPath, stdio: "pipe" }), execSync("git commit -m 'Initialize farm manifest'", {
+        cwd: farmPath,
+        stdio: useJson ? "pipe" : "inherit"
+      });
+    } catch (gitError) {
+      throw new Error(`Failed to initialize farm git repository: ${getErrorMessage(gitError)}`);
+    }
+    if (useJson)
+      console.log(JSON.stringify({ status: "ok", farmPath, farmName, platform_view: options.platformView || !1 }));
+    else {
+      const platformViewNote = options.platformView ? " (platform-view enabled)" : "";
+      handleSuccess(`Farm initialized: ${ansis.bold(farmName)}${platformViewNote}
+  Location: ${farmPath}`);
+    }
+    span && endSpan(span);
+  } catch (error) {
+    options.format === "json" || isJson() ? console.log(JSON.stringify({
+      status: "error",
+      code: 1,
+      message: getErrorMessage(error)
+    })) : console.error(ansis.red(`Error: ${getErrorMessage(error)}`)), span && endSpan(span), process.exit(1);
+  }
+}
+async function farmAddCommand(name, options) {
+  const span = isTelemetryEnabled ? startSpan("farm.add", { "project.name": name }) : null, useJson = options.format === "json" || isJson();
+  try {
+    if (options.model && options.newModel)
+      throw new Error("--model and --new-model cannot be combined: --model registers an existing model, --new-model scaffolds a fresh one");
+    const farmRoot = await findFarmRoot();
+    if (!farmRoot)
+      throw new Error("Not in a farm directory. Run 'dr farm init' first.");
+    const farmYamlPath = path.join(farmRoot, "farm.yaml"), manifest = await FarmManifest.load(farmYamlPath);
+    if (manifest.getProject(name))
+      throw new Error(`Project '${name}' already exists in this farm`);
+    let codebasePath = options.codebase || name;
+    const codebaseFullPath = path.resolve(path.join(farmRoot, codebasePath)), farmRootResolved = path.resolve(farmRoot);
+    if (options.remote) {
+      if (!codebaseFullPath.startsWith(farmRootResolved + path.sep))
+        throw new Error(`Invalid codebase path: would escape farm root. Path: ${codebasePath}`);
+      if (await fileExists(codebaseFullPath))
+        throw new Error(`Codebase directory '${codebasePath}' already exists`);
+      useJson || handleInfo(`Cloning ${options.remote} to ${codebasePath}...`);
+      try {
+        execFileSync("git", ["clone", options.remote, codebaseFullPath], {
+          stdio: useJson ? "pipe" : "inherit"
+        });
+      } catch (error) {
+        throw new Error(`Failed to clone repository: ${getErrorMessage(error)}`);
+      }
+    }
+    const registration = await resolveProjectModel(name, {
+      farmRoot: farmRootResolved,
+      codebaseFullPath,
+      explicitModel: options.model,
+      forceNewModel: options.newModel ?? !1
+    }), modelFolder = registration.modelFolder;
+    if (registration.ignoredModelPath) {
+      const ignoredWarning = `Codebase '${codebasePath}' already has a model at ${registration.ignoredModelPath}; ignoring it and scaffolding a new model at ${modelFolder} (--new-model)`;
+      registration.warning = ignoredWarning, useJson || handleWarning(ignoredWarning);
+    }
+    registration.adopted ? useJson || handleInfo(`Using existing model at ${registration.modelFullPath}; nothing was created`) : await fileExists(registration.modelFullPath) || (await Model.init(registration.modelFullPath, {
+      name,
+      version: "0.1.0",
+      description: void 0,
+      author: void 0,
+      specVersion: (await import("../utils/spec-version.js")).getCliBundledSpecVersion(),
+      created: (/* @__PURE__ */ new Date()).toISOString()
+    }, { lazyLoad: !1 }), useJson || handleInfo(`Created and initialized model folder: ${modelFolder}`)), manifest.addProject(name, {
+      name,
+      source: codebasePath,
+      model: modelFolder,
+      remote: options.remote
+    }), await manifest.save(farmYamlPath);
+    const gitCheck = checkGitRepository(farmRoot);
+    let gitCommitted = !1, gitWarning;
+    if (gitCheck.error)
+      gitWarning = uncommittedChangeWarning("farm.yaml", farmRoot, gitCheck.error), useJson || handleWarning(gitWarning);
+    else if (gitCheck.isRepo)
+      try {
+        execSync("git add farm.yaml", { cwd: farmRoot, stdio: "pipe" }), execFileSync("git", ["commit", "-m", `Add project: ${name}`], {
+          cwd: farmRoot,
+          stdio: useJson ? "pipe" : "inherit"
+        }), gitCommitted = !0;
+      } catch (commitError) {
+        const errorMsg = getErrorMessage(commitError);
+        if (!errorMsg.includes("nothing to commit"))
+          throw new Error(`Failed to commit farm changes: ${errorMsg}`);
+      }
+    if (useJson)
+      console.log(JSON.stringify({
+        status: "ok",
+        project: name,
+        source: codebasePath,
+        model: modelFolder,
+        model_path: registration.modelFullPath,
+        model_adopted: registration.adopted,
+        ...registration.ignoredModelPath ? { ignored_model: registration.ignoredModelPath } : {},
+        ...registration.warning ? { warning: registration.warning } : {},
+        git_committed: gitCommitted,
+        ...gitWarning ? { git_warning: gitWarning } : {}
+      }));
+    else {
+      const modelNote = registration.adopted ? " (existing model, adopted in place)" : "";
+      handleSuccess(`Project added to farm: ${ansis.bold(name)}
+  Codebase: ${codebasePath}
+  Model: ${modelFolder}${modelNote}`);
+    }
+    span && endSpan(span);
+  } catch (error) {
+    useJson ? console.log(JSON.stringify({
+      status: "error",
+      code: 1,
+      message: getErrorMessage(error)
+    })) : console.error(ansis.red(`Error: ${getErrorMessage(error)}`)), span && endSpan(span), process.exit(1);
+  }
+}
+async function farmRemoveCommand(name, options) {
+  const span = isTelemetryEnabled ? startSpan("farm.remove", { "project.name": name }) : null, useJson = options.format === "json" || isJson();
+  try {
+    const farmRoot = await findFarmRoot();
+    if (!farmRoot)
+      throw new Error("Not in a farm directory.");
+    const farmYamlPath = path.join(farmRoot, "farm.yaml"), manifest = await FarmManifest.load(farmYamlPath), project = manifest.getProject(name);
+    if (!project)
+      throw new Error(`Project '${name}' not found in farm`);
+    let modelDeleted = !1, modelKeptReason;
+    if (options.deleteModel) {
+      const modelFullPath = path.resolve(path.join(farmRoot, project.model)), farmRootResolved = path.resolve(farmRoot), codebaseFullPath = path.resolve(path.join(farmRoot, project.source));
+      if (modelFullPath.startsWith(farmRootResolved + path.sep) ? isWithinPath(modelFullPath, codebaseFullPath) && (modelKeptReason = `model '${project.model}' is the codebase's own model (inside '${project.source}')`) : modelKeptReason = `model '${project.model}' lies outside the farm root and is not managed by the farm`, modelKeptReason)
+        useJson || handleWarning(`Model folder not deleted: ${modelKeptReason}. Remove it by hand if that is what you want.`);
+      else if (await fileExists(modelFullPath))
+        try {
+          await rm(modelFullPath, { recursive: !0, force: !1 }), modelDeleted = !0, useJson || handleInfo(`Deleted model folder: ${project.model}`);
+        } catch (error) {
+          throw new Error(`Failed to delete model folder: ${getErrorMessage(error)}`);
+        }
+    }
+    manifest.removeProject(name), await manifest.save(farmYamlPath);
+    const gitCheck = checkGitRepository(farmRoot);
+    let gitCommitted = !1, gitWarning;
+    if (gitCheck.error)
+      gitWarning = uncommittedChangeWarning("farm.yaml", farmRoot, gitCheck.error), useJson || handleWarning(gitWarning);
+    else if (gitCheck.isRepo)
+      try {
+        execSync("git add farm.yaml", { cwd: farmRoot, stdio: "pipe" }), execFileSync("git", ["commit", "-m", `Remove project: ${name}`], {
+          cwd: farmRoot,
+          stdio: useJson ? "pipe" : "inherit"
+        }), gitCommitted = !0;
+      } catch (commitError) {
+        const errorMsg = getErrorMessage(commitError);
+        if (!errorMsg.includes("nothing to commit"))
+          throw new Error(`Failed to commit farm changes: ${errorMsg}`);
+      }
+    useJson ? console.log(JSON.stringify({
+      status: "ok",
+      project: name,
+      model: project.model,
+      modelDeleted,
+      ...modelKeptReason ? { model_kept_reason: modelKeptReason } : {},
+      git_committed: gitCommitted,
+      ...gitWarning ? { git_warning: gitWarning } : {}
+    })) : handleSuccess(`Project removed from farm: ${ansis.bold(name)}`), span && endSpan(span);
+  } catch (error) {
+    useJson ? console.log(JSON.stringify({
+      status: "error",
+      code: 1,
+      message: getErrorMessage(error)
+    })) : console.error(ansis.red(`Error: ${getErrorMessage(error)}`)), span && endSpan(span), process.exit(1);
+  }
+}
+async function farmStatusCommand(options) {
+  const span = isTelemetryEnabled ? startSpan("farm.status") : null;
+  try {
+    const farmRoot = await findFarmRoot();
+    if (!farmRoot)
+      throw new Error("Not in a farm directory.");
+    const farmYamlPath = path.join(farmRoot, "farm.yaml"), manifest = await FarmManifest.load(farmYamlPath), projects = manifest.getAllProjects(), engine = new FarmSyncEngine(farmRoot), useJson = options.format === "json" || isJson(), projectsWithStatus = await Promise.all(projects.map(async (p) => {
+      const result = {
+        name: p.name,
+        source: p.source,
+        model: p.model,
+        remote: p.remote,
+        last_sync_commit: void 0,
+        current_commit: void 0,
+        has_pending_changes: void 0
+      };
+      let lastSyncCommit;
+      try {
+        const syncStatePath = path.join(farmRoot, p.model, ".farm-sync.yaml");
+        lastSyncCommit = (await FarmSyncState.loadOrCreate(syncStatePath, p.name)).lastSyncCommit, result.last_sync_commit = lastSyncCommit;
+      } catch (error) {
+        return error instanceof FarmSyncStateNotFoundError ? (result.has_pending_changes = !1, result) : (result.sync_state_error = getErrorMessage(error), useJson || handleWarning(`${p.name}: could not read sync state: ${result.sync_state_error}`), result);
+      }
+      try {
+        const currentCommit = await engine.getCurrentCommit(p.source);
+        result.current_commit = currentCommit, result.has_pending_changes = !!(lastSyncCommit && lastSyncCommit !== currentCommit);
+      } catch (error) {
+        result.codebase_error = getErrorMessage(error), useJson || handleWarning(`${p.name}: ${result.codebase_error}`);
+      }
+      return result;
+    })), projectsWithErrors = projectsWithStatus.filter((p) => p.sync_state_error !== void 0 || p.codebase_error !== void 0), allHealthy = projectsWithErrors.length === 0;
+    useJson ? console.log(JSON.stringify({
+      status: allHealthy ? "ok" : "error",
+      code: allHealthy ? 0 : 1,
+      farm: {
+        name: manifest.name,
+        path: farmRoot,
+        created: manifest.created,
+        modified: manifest.modified,
+        platform_view: manifest.platform_view
+      },
+      projects: projectsWithStatus,
+      project_count: projects.length
+    })) : (console.log(ansis.bold(`Farm: ${manifest.name}`)), console.log(`Location: ${farmRoot}`), manifest.platform_view && console.log(`Platform-View: ${ansis.green("enabled")}`), console.log(`Projects: ${projects.length}
+`), projects.length === 0 ? console.log(ansis.dim("No projects registered yet.")) : projectsWithStatus.forEach((project) => {
+      console.log(`  ${ansis.cyan(project.name)}`), console.log(`    Codebase: ${project.source}`), console.log(`    Model:    ${project.model}`), project.remote && console.log(`    Remote:   ${project.remote}`), project.sync_state_error ? (console.log(`    Status:   ${ansis.red("\u2717 Sync state corrupted")}`), console.log(`    Error:    ${project.sync_state_error}`)) : project.codebase_error ? (console.log(`    Status:   ${ansis.red("\u2717 Codebase unavailable")}`), console.log(`    Error:    ${project.codebase_error}`)) : project.has_pending_changes ? console.log(`    Status:   ${ansis.yellow("\u26A0 Pending changes")}`) : project.last_sync_commit ? console.log(`    Status:   ${ansis.green("\u2713 Up to date")}`) : console.log(`    Status:   ${ansis.dim("Not synced yet")}`);
+    }), allHealthy || console.error(ansis.red(`
+${projectsWithErrors.length} project(s) could not be checked (see errors above)`))), span && endSpan(span), allHealthy || process.exit(1);
+  } catch (error) {
+    options.format === "json" || isJson() ? console.log(JSON.stringify({
+      status: "error",
+      code: 2,
+      message: getErrorMessage(error)
+    })) : console.error(ansis.red(`Error: ${getErrorMessage(error)}`)), span && endSpan(span), process.exit(2);
+  }
+}
+async function farmValidateCommand(options) {
+  const span = isTelemetryEnabled ? startSpan("farm.validate") : null;
+  try {
+    const farmRoot = await findFarmRoot();
+    if (!farmRoot)
+      throw new Error("Not in a farm directory. Run 'dr farm init' first.");
+    const farmYamlPath = path.join(farmRoot, "farm.yaml"), farmManifest = await FarmManifest.load(farmYamlPath), useJson = options.format === "json" || isJson();
+    let projectsToValidate = farmManifest.getAllProjects(), isPlatformViewValidation = !1;
+    if (options.project) {
+      const project = farmManifest.getProject(options.project);
+      if (!project)
+        throw new Error(`Project '${options.project}' not found in farm`);
+      projectsToValidate = [project], farmManifest.isPlatformViewEnabled() && options.project === "platform-view" ? isPlatformViewValidation = !0 : options.project === "platform-view" && !farmManifest.isPlatformViewEnabled() && !useJson && !options.quiet && handleInfo("Note: Validating platform-view project, but platform-view is not enabled on this farm");
+    }
+    if (projectsToValidate.length === 0)
+      throw new Error("No projects found in farm");
+    const composedValidator = await ComposedReferenceValidator.fromFarm(farmRoot);
+    if (useJson)
+      console.log(JSON.stringify({ status: "validating", projects: projectsToValidate.length, platform_view: isPlatformViewValidation }));
+    else if (!options.quiet)
+      if (options.project) {
+        const platformViewNote = isPlatformViewValidation ? " (platform-view aggregation)" : "";
+        handleInfo(`Validating project '${options.project}'${platformViewNote} with farm-aware references...`);
+      } else
+        handleInfo(`Validating ${projectsToValidate.length} farm project(s) with farm-aware references...`);
+    const allResults = [], reportData = [];
+    for (const project of projectsToValidate) {
+      const modelPath = path.join(farmRoot, project.model);
+      if (!await fileExists(modelPath)) {
+        const error = `Model folder not found for project '${project.name}' at ${modelPath}`;
+        useJson ? console.log(JSON.stringify({
+          status: "error",
+          code: 2,
+          project: project.name,
+          message: error
+        })) : console.error(ansis.red(`Error: ${error}`)), span && endSpan(span), process.exit(2);
+      }
+      let drModelPath = modelPath;
+      const manifestPath = path.join(modelPath, "manifest.yaml");
+      await fileExists(manifestPath) && (drModelPath = manifestPath);
+      const model = await Model.load(drModelPath);
+      let platformViewInfo;
+      if (isPlatformViewValidation) {
+        const declaredModels = model.manifest.models || {}, declaredModelNames = Object.keys(declaredModels);
+        if (platformViewInfo = {
+          declared_models: declaredModelNames,
+          missing_models: []
+        }, declaredModelNames.length === 0)
+          !useJson && !options.quiet && handleInfo("  Platform-view project has no declared external models");
+        else {
+          !useJson && !options.quiet && handleInfo(`  Platform-view is declaring external models: ${declaredModelNames.join(", ")}`);
+          const missingModels = [];
+          for (const declaredModelName of declaredModelNames)
+            farmManifest.getProject(declaredModelName) || missingModels.push(declaredModelName);
+          platformViewInfo.missing_models = missingModels, missingModels.length > 0 && (useJson || console.error(ansis.yellow(`  \u26A0 Warning: The following declared external models are not registered in the farm: ${missingModels.join(", ")}`)));
+        }
+      }
+      const result = await composedValidator.validateModel(model);
+      allResults.push({ project: project.name, result });
+      const formatted = ValidationFormatter.format(result, model, {
+        verbose: options.verbose,
+        quiet: options.quiet
+      }), reportItem = {
+        project: project.name,
+        valid: result.isValid(),
+        errors: result.errors.map((e) => ({
+          message: e.message,
+          layer: e.layer,
+          elementId: e.elementId,
+          location: e.location
+        })),
+        warnings: result.warnings.map((w) => ({
+          message: w.message,
+          layer: w.layer,
+          elementId: w.elementId,
+          location: w.location
+        })),
+        formatted
+      };
+      if (platformViewInfo && (reportItem.platform_view_info = platformViewInfo), reportData.push(reportItem), options.quiet || (console.log(ansis.bold(`
+Project: ${project.name}`)), console.log(formatted)), !result.isValid() && options.project)
+        throw new Error(`Validation failed for project '${project.name}'`);
+    }
+    const allValid = allResults.every((r) => r.result.isValid());
+    if (options.output) {
+      const outputExt = path.extname(options.output).toLowerCase();
+      if (outputExt === ".json") {
+        const jsonReport = {
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          farm_root: farmRoot,
+          all_valid: allValid,
+          projects: reportData.map((r) => {
+            const projectData = {
+              project: r.project,
+              valid: r.valid,
+              errors: r.errors,
+              warnings: r.warnings
+            };
+            return r.platform_view_info && (projectData.platform_view_info = r.platform_view_info), projectData;
+          })
+        };
+        await (await import("fs/promises")).writeFile(options.output, JSON.stringify(jsonReport, null, 2), "utf-8");
+      } else if (outputExt === ".md") {
+        let mdContent = `# Farm Validation Report
+
+`;
+        mdContent += `**Date**: ${(/* @__PURE__ */ new Date()).toISOString()}
+`, mdContent += `**Farm Root**: ${farmRoot}
+`, mdContent += `**Overall Status**: ${allValid ? "\u2705 Valid" : "\u274C Invalid"}
+
+`, mdContent += `## Projects
+
+`;
+        for (const r of reportData) {
+          if (mdContent += `### ${r.project}
+
+`, mdContent += `**Status**: ${r.valid ? "\u2705 Valid" : "\u274C Invalid"}
+
+`, r.errors.length > 0) {
+            mdContent += `#### Errors (${r.errors.length})
+
+`;
+            for (const err of r.errors)
+              mdContent += `- ${err.message}
+`;
+            mdContent += `
+`;
+          }
+          if (r.warnings.length > 0) {
+            mdContent += `#### Warnings (${r.warnings.length})
+
+`;
+            for (const warn of r.warnings)
+              mdContent += `- ${warn.message}
+`;
+            mdContent += `
+`;
+          }
+        }
+        await (await import("fs/promises")).writeFile(options.output, mdContent, "utf-8");
+      } else
+        throw new Error(`Unsupported output format: ${outputExt}. Use .json or .md`);
+      options.quiet || handleInfo(`Report written to ${options.output}`);
+    }
+    useJson && console.log(JSON.stringify({
+      status: "ok",
+      projects: allResults.map((r) => ({
+        name: r.project,
+        valid: r.result.isValid(),
+        errors: r.result.errors.length,
+        warnings: r.result.warnings.length
+      })),
+      all_valid: allValid,
+      output: options.output ? path.resolve(options.output) : void 0
+    })), allValid || (span && endSpan(span), process.exit(1)), options.quiet || handleSuccess(options.project ? `Project '${options.project}' validated successfully` : "All farm projects validated successfully"), span && endSpan(span);
+  } catch (error) {
+    options.format === "json" || isJson() ? console.log(JSON.stringify({
+      status: "error",
+      code: 2,
+      message: getErrorMessage(error)
+    })) : console.error(ansis.red(`Error: ${getErrorMessage(error)}`)), span && endSpan(span), process.exit(2);
+  }
+}
+async function farmPullCommand(options) {
+  const span = isTelemetryEnabled ? startSpan("farm.pull") : null;
+  try {
+    const farmRoot = await findFarmRoot();
+    if (!farmRoot)
+      throw new Error("Not in a farm directory. Run 'dr farm init' first.");
+    const farmYamlPath = path.join(farmRoot, "farm.yaml"), manifest = await FarmManifest.load(farmYamlPath);
+    let projectsToPull = manifest.getAllProjects();
+    if (options.project) {
+      const project = manifest.getProject(options.project);
+      if (!project)
+        throw new Error(`Project '${options.project}' not found in farm`);
+      projectsToPull = [project];
+    }
+    if (projectsToPull.length === 0)
+      throw new Error("No projects found in farm");
+    const useJson = options.format === "json" || isJson();
+    !useJson && !options.verbose && handleInfo(`Pulling ${projectsToPull.length} project(s)...`);
+    const engine = new FarmSyncEngine(farmRoot), results = [];
+    for (const project of projectsToPull)
+      try {
+        const commit = await engine.pullCodebase(project.source);
+        results.push({
+          project: project.name,
+          status: "success",
+          commit
+        }), options.verbose && !useJson && handleInfo(`  \u2713 ${project.name}: ${commit.substring(0, 8)}`);
+      } catch (error) {
+        results.push({
+          project: project.name,
+          status: "error",
+          message: getErrorMessage(error)
+        }), useJson || console.error(ansis.red(`  \u2717 ${project.name}: ${getErrorMessage(error)}`));
+      }
+    const allSucceeded = results.every((r) => r.status === "success");
+    useJson ? console.log(JSON.stringify({
+      status: allSucceeded ? "ok" : "partial",
+      code: allSucceeded ? 0 : 1,
+      projects: results,
+      pulled: results.filter((r) => r.status === "success").length,
+      failed: results.filter((r) => r.status === "error").length
+    })) : allSucceeded ? handleSuccess(`Pulled ${projectsToPull.length} project(s) successfully`) : console.error(ansis.red("Pull failed for some projects")), span && endSpan(span), allSucceeded || process.exit(1);
+  } catch (error) {
+    options.format === "json" || isJson() ? console.log(JSON.stringify({
+      status: "error",
+      code: 2,
+      message: getErrorMessage(error)
+    })) : console.error(ansis.red(`Error: ${getErrorMessage(error)}`)), span && endSpan(span), process.exit(2);
+  }
+}
+async function farmSyncCommand(options) {
+  const span = isTelemetryEnabled ? startSpan("farm.sync") : null;
+  try {
+    const farmRoot = await findFarmRoot();
+    if (!farmRoot)
+      throw new Error("Not in a farm directory. Run 'dr farm init' first.");
+    const farmYamlPath = path.join(farmRoot, "farm.yaml"), manifest = await FarmManifest.load(farmYamlPath);
+    let projectsToSync = manifest.getAllProjects();
+    if (options.project) {
+      const project = manifest.getProject(options.project);
+      if (!project)
+        throw new Error(`Project '${options.project}' not found in farm`);
+      projectsToSync = [project];
+    }
+    if (projectsToSync.length === 0)
+      throw new Error("No projects found in farm");
+    const concurrency = options.concurrency ? Math.max(1, parseInt(options.concurrency, 10)) : 1;
+    if (isNaN(concurrency))
+      throw new Error("Concurrency must be a positive number");
+    if (options.autoCommit && concurrency > 1)
+      throw new Error("Cannot use --auto-commit with --concurrency > 1: concurrent git operations would cause race conditions. Use --concurrency 1 for auto-commit, or remove --auto-commit for parallel processing.");
+    if (options.output) {
+      const outputExt = path.extname(options.output).toLowerCase();
+      if (outputExt !== ".json")
+        throw new Error(`Unsupported output format: ${outputExt || "(no extension)"}. Use .json`);
+    }
+    const useJson = options.format === "json" || isJson();
+    !useJson && !options.verbose && handleInfo(`Syncing ${projectsToSync.length} project(s) (concurrency: ${concurrency})...`);
+    const allResults = [], processSyncProject = async (project) => {
+      try {
+        const modelPath = path.join(farmRoot, project.model);
+        if (!await fileExists(modelPath))
+          throw new Error(`Model folder not found for project '${project.name}' at ${modelPath}`);
+        let drModelPath = modelPath;
+        const manifestPath = path.join(modelPath, "manifest.yaml");
+        await fileExists(manifestPath) && (drModelPath = manifestPath);
+        try {
+          const model = await Model.load(drModelPath), result = await new FarmSyncEngine(farmRoot, model).syncProject(project, {
+            verbose: options.verbose,
+            dryRun: options.dryRun,
+            force: options.force
+          }), resultEntry = {
+            project: project.name,
+            status: result.status === "failed" ? "error" : result.status,
+            change_count: result.changeCount,
+            changeset_id: result.changesetId,
+            files_changed: result.filesChanged,
+            ambiguities: result.ambiguities.length,
+            commits_before: result.commitsBefore,
+            commits_after: result.commitsAfter
+          };
+          if (options.autoCommit && result.changesetId && result.changeCount > 0 && !options.dryRun)
+            try {
+              const commitResult = await new (await import("../core/staging-area.js")).StagingAreaManager(model.rootPath, model).commit(model, result.changesetId);
+              resultEntry.auto_committed = !0, resultEntry.committed_changes = commitResult.committed;
+              const gitCheck = checkGitRepository(farmRoot);
+              if (gitCheck.error)
+                resultEntry.git_committed = !1, resultEntry.git_warning = uncommittedChangeWarning(`Model '${project.model}'`, farmRoot, gitCheck.error), useJson || handleWarning(`${project.name}: ${resultEntry.git_warning}`);
+              else if (gitCheck.isRepo && !isInSameGitRepository(farmRoot, modelPath))
+                resultEntry.git_committed = !1, resultEntry.git_warning = `Model '${project.model}' is outside the farm git repository at ${farmRoot}: the synced changes were saved but not committed. Commit them in the model's own repository.`, useJson || handleWarning(`${project.name}: ${resultEntry.git_warning}`);
+              else if (gitCheck.isRepo)
+                try {
+                  execFileSync("git", ["add", project.model], { cwd: farmRoot, stdio: "pipe" }), execFileSync("git", ["commit", "-m", `Sync: ${result.changesetId} - ${commitResult.committed} change(s)`], { cwd: farmRoot, stdio: "pipe" }), resultEntry.git_committed = !0;
+                } catch (gitCommitError) {
+                  if (!getErrorMessage(gitCommitError).includes("nothing to commit"))
+                    throw gitCommitError;
+                  resultEntry.git_committed = !0;
+                }
+              else
+                resultEntry.git_committed = !1;
+              options.verbose && !useJson && handleInfo(`  Auto-committed: ${commitResult.committed} change(s)`);
+            } catch (commitError) {
+              resultEntry.auto_committed = !1, resultEntry.commit_error = getErrorMessage(commitError), resultEntry.status = "error", useJson || handleWarning(`${project.name}: auto-commit failed: ${getErrorMessage(commitError)}`);
+            }
+          if (allResults.push(resultEntry), options.verbose && !useJson) {
+            handleInfo(`
+Project: ${project.name}`);
+            const statusEmoji = result.status === "success" ? "\u2713" : result.status === "partial" ? "\u26A0" : "\u2717", statusText = result.status === "success" ? "Success" : result.status === "partial" ? "Partial" : "Failed";
+            handleInfo(`  Status: ${statusEmoji} ${statusText}`), handleInfo(`  Commits: ${result.commitsBefore}...${result.commitsAfter}`), handleInfo(`  Files changed: +${result.filesChanged.added.length} ~${result.filesChanged.modified.length} -${result.filesChanged.deleted.length}`), handleInfo(`  Staged changes: ${result.changeCount}`), result.changesetId && handleInfo(`  Changeset: ${result.changesetId}`), result.ambiguities.length > 0 && handleInfo(`  Ambiguities: ${result.ambiguities.length} (flagged for review)`);
+            for (const note of result.notes)
+              console.log(`    ${note}`);
+          }
+        } catch (error) {
+          allResults.push({
+            project: project.name,
+            status: "error",
+            message: getErrorMessage(error)
+          }), useJson || console.error(ansis.red(`\u2717 ${project.name}: ${getErrorMessage(error)}`));
+        }
+      } catch (error) {
+        allResults.push({
+          project: project.name,
+          status: "error",
+          message: getErrorMessage(error)
+        }), useJson || console.error(ansis.red(`\u2717 ${project.name}: ${getErrorMessage(error)}`));
+      }
+    };
+    if (concurrency === 1)
+      for (const project of projectsToSync)
+        await processSyncProject(project);
+    else {
+      const queue = [...projectsToSync], active = [];
+      for (; queue.length > 0 || active.length > 0; ) {
+        for (; active.length < concurrency && queue.length > 0; ) {
+          const project = queue.shift(), wrapped = processSyncProject(project).then(() => {
+            const idx = active.indexOf(wrapped);
+            idx !== -1 && active.splice(idx, 1);
+          });
+          active.push(wrapped);
+        }
+        active.length > 0 && await Promise.race(active);
+      }
+    }
+    const allSucceeded = allResults.every((r) => r.status === "success" || r.status === "partial");
+    if (useJson)
+      console.log(JSON.stringify({
+        status: allSucceeded ? "ok" : "error",
+        code: allSucceeded ? 0 : 1,
+        projects: allResults,
+        synced: allResults.filter((r) => r.status === "success").length,
+        failed: allResults.filter((r) => r.status === "error").length,
+        auto_committed: options.autoCommit
+      }));
+    else {
+      const synced = allResults.filter((r) => r.status === "success").length;
+      allSucceeded && handleSuccess(`Synced ${synced}/${projectsToSync.length} project(s)`);
+    }
+    if (options.output) {
+      const { writeFile } = await import("../utils/file-io.js");
+      await writeFile(options.output, JSON.stringify({
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        farm_root: farmRoot,
+        projects: allResults
+      }, null, 2)), useJson || handleInfo(`Report written to ${options.output}`);
+    }
+    span && endSpan(span), allSucceeded || process.exit(1);
+  } catch (error) {
+    options.format === "json" || isJson() ? console.log(JSON.stringify({
+      status: "error",
+      code: 2,
+      message: getErrorMessage(error)
+    })) : console.error(ansis.red(`Error: ${getErrorMessage(error)}`)), span && endSpan(span), process.exit(2);
+  }
+}
+function farmCommands(program) {
+  const farmGroup = program.command("farm").description("Manage model farms");
+  farmGroup.command("init").description("Initialize a new farm").option("--name <name>", "Farm name").option("--platform-view", "Enable platform-view support for cross-model aggregation").option("--format <format>", "Output format: text, json", "text").addHelpText("after", `
+Examples:
+  $ dr farm init
+  $ dr farm init --name "My Architecture Farm"
+  $ dr farm init --platform-view
+  $ dr farm init --format json
+
+Notes:
+  When using --platform-view, create a project named exactly "platform-view" to serve as
+  the aggregation hub. When validating this project with 'dr farm validate --project platform-view',
+  the CLI will automatically resolve cross-model references from all farm projects.`).action(async (options) => {
+    await farmInitCommand(options);
+  }), farmGroup.command("add <name>").description("Add a project to the farm").option("--remote <url>", "Git remote URL to clone").option("--codebase <path>", "Path to codebase folder, relative to the farm root (defaults to project name; may point outside the farm root unless --remote is used)").option("--model <path>", "Register an existing model at this path (relative to the farm root) instead of detecting or scaffolding one").option("--new-model", "Always scaffold a fresh <name>-model, even when the codebase already carries a model").option("--format <format>", "Output format: text, json", "text").addHelpText("after", `
+Examples:
+  $ dr farm add my-service
+  $ dr farm add my-service --remote https://github.com/org/my-service.git
+  $ dr farm add my-service --codebase ./services/my-service
+  $ dr farm add my-service --codebase ../my-service   # sibling checkout outside the farm root
+  $ dr farm add my-service --codebase ../my-service --new-model
+  $ dr farm add my-service --model ../shared-models/my-service
+  $ dr farm add my-service --format json
+
+Model detection:
+  If the codebase already holds a model (documentation-robotics/model/manifest.yaml, model/manifest.yaml
+  or manifest.yaml at the codebase path itself), that model is adopted in place and nothing is
+  created; farm.yaml records its path (which may lie outside the farm root). Use --new-model to
+  scaffold a separate <name>-model regardless, or --model to point at a model explicitly.`).action(async (name, options) => {
+    await farmAddCommand(name, options);
+  }), farmGroup.command("remove <name>").description("Remove a project from the farm").option("--delete-model", "Also delete the model folder").option("--format <format>", "Output format: text, json", "text").addHelpText("after", `
+Examples:
+  $ dr farm remove my-service
+  $ dr farm remove my-service --delete-model
+  $ dr farm remove my-service --format json`).action(async (name, options) => {
+    await farmRemoveCommand(name, options);
+  }), farmGroup.command("status").description("Show farm status and registered projects").option("--format <format>", "Output format: text, json", "text").addHelpText("after", `
+Examples:
+  $ dr farm status
+  $ dr farm status --format json`).action(async (options) => {
+    await farmStatusCommand(options);
+  }), farmGroup.command("validate").description("Validate farm projects using composed scope (cross-model references)").option("--project <name>", "Validate only a specific project (default: all)").option("--verbose", "Show verbose validation output").option("--quiet", "Suppress success messages").option("--output <path>", "Export validation report to file (JSON/Markdown)").option("--format <format>", "Output format: text, json", "text").addHelpText("after", `
+Examples:
+  $ dr farm validate
+  $ dr farm validate --project my-service
+  $ dr farm validate --verbose
+  $ dr farm validate --format json
+  $ dr farm validate --output report.json
+
+Notes:
+  For platform-view aggregation: Use 'dr farm validate --project platform-view' to validate
+  a platform-view project. The project name must be exactly 'platform-view' and the farm
+  must have platform-view enabled (set during 'dr farm init --platform-view').`).action(async (options) => {
+    await farmValidateCommand(options);
+  }), farmGroup.command("pull").description("Pull latest changes from remote for farm projects").option("--project <name>", "Pull only a specific project (default: all)").option("--verbose", "Show verbose output").option("--format <format>", "Output format: text, json", "text").addHelpText("after", `
+Examples:
+  $ dr farm pull
+  $ dr farm pull --project my-service
+  $ dr farm pull --verbose
+  $ dr farm pull --format json`).action(async (options) => {
+    await farmPullCommand(options);
+  }), farmGroup.command("sync").description("Sync farm projects with their models (generates staged changesets)").option("--project <name>", "Sync only a specific project (default: all)").option("--verbose", "Show verbose output").option("--dry-run", "Preview without creating changesets").option("--force", "Proceed despite ambiguous file-to-element mappings").option("--output <path>", "Export sync report to file (.json only)").option("--format <format>", "Output format: text, json", "text").option("--auto-commit", "Automatically commit changes (bypasses staged review)").option("--concurrency <n>", "Process multiple projects in parallel (default: 1)", "1").addHelpText("after", `
+Examples:
+  $ dr farm sync
+  $ dr farm sync --project my-service
+  $ dr farm sync --verbose --output sync-report.json
+  $ dr farm sync --dry-run
+  $ dr farm sync --format json --auto-commit
+  $ dr farm sync --concurrency 4
+
+Automation (cron/CI):
+  $ dr farm sync --format json --auto-commit --output sync-report.json
+  $ dr farm sync --format json --concurrency 4 --output sync-report.json
+
+Note: --auto-commit and --concurrency > 1 cannot be used together (race condition risk).
+Use --concurrency 1 (default) with --auto-commit for automated syncs.`).action(async (options) => {
+    await farmSyncCommand(options);
+  }), farmGroup.showSuggestionAfterError();
+}
+export {
+  farmAddCommand,
+  farmCommands,
+  farmInitCommand,
+  farmPullCommand,
+  farmRemoveCommand,
+  farmStatusCommand,
+  farmSyncCommand,
+  farmValidateCommand
+};
+//# sourceMappingURL=farm.js.map