@forge-ts/cli 0.13.0 → 0.15.0

package/dist/index.js

@@ -1,8 +1,19 @@
 #!/usr/bin/env node
+import {
+  initProjectCommand,
+  runInitProject
+} from "./chunk-CINQWGH7.js";
+import {
+  emitResult,
+  resolveExitCode
+} from "./chunk-ZFFY4AQX.js";
+import {
+  createLogger
+} from "./chunk-7UPSAG3L.js";
 
 // src/index.ts
 import { createRequire } from "module";
-import { defineCommand as defineCommand12, runMain } from "citty";
+import { defineCommand as defineCommand13, runMain } from "citty";
 
 // src/commands/audit.ts
 import {
@@ -10,74 +21,6 @@ import {
   readAuditLog
 } from "@forge-ts/core";
 import { defineCommand } from "citty";
-
-// src/output.ts
-import { randomUUID } from "crypto";
-import {
-  createEnvelope,
-  resolveFlags
-} from "@cleocode/lafs-protocol";
-function emitResult(output, flags, humanFormatter) {
-  const flagInput = {
-    json: flags.json,
-    human: flags.human,
-    quiet: flags.quiet,
-    mvi: flags.mvi,
-    // LAFS 1.8.0: TTY detection drives the default format.
-    // Terminals get human output, pipes/agents get JSON.
-    tty: process.stdout.isTTY ?? false
-  };
-  const resolved = resolveFlags(flagInput);
-  const format = resolved.format.format;
-  const quiet = resolved.format.quiet;
-  if (quiet) {
-    return;
-  }
-  const meta = {
-    operation: `forge-ts.${output.operation}`,
-    requestId: randomUUID(),
-    transport: "cli",
-    mvi: flags.mvi ?? "full"
-  };
-  const resultData = output.data;
-  if (output.warnings && output.warnings.length > 0) {
-    resultData._warnings = output.warnings.map((w) => ({
-      code: w.code,
-      message: w.message
-    }));
-  }
-  const envelope = output.success ? createEnvelope({
-    success: true,
-    result: resultData,
-    meta
-  }) : createEnvelope({
-    success: false,
-    result: resultData,
-    error: {
-      code: output.errors?.[0]?.code ?? "FORGE_CHECK_FAILED",
-      message: output.errors?.[0]?.message ?? "Check failed \u2014 see result for actionable fixes",
-      category: "VALIDATION",
-      retryable: true,
-      retryAfterMs: null
-    },
-    meta
-  });
-  if (format === "json") {
-    process.stdout.write(`${JSON.stringify(envelope, null, 2)}
-`);
-  } else {
-    const formatted = humanFormatter(output.data, output);
-    if (formatted) {
-      console.log(formatted);
-    }
-  }
-}
-function resolveExitCode(output) {
-  if (output.success) return 0;
-  return 1;
-}
-
-// src/commands/audit.ts
 function runAudit(args) {
   const rootDir = args.cwd ?? process.cwd();
   const limit = args.limit ?? 20;
@@ -178,46 +121,6 @@ import { generateApi } from "@forge-ts/api";
 import { loadConfig } from "@forge-ts/core";
 import { generate } from "@forge-ts/gen";
 import { defineCommand as defineCommand2 } from "citty";
-
-// src/logger.ts
-var GREEN = "\x1B[32m";
-var YELLOW = "\x1B[33m";
-var RED = "\x1B[31m";
-var BOLD = "\x1B[1m";
-var RESET = "\x1B[0m";
-function createLogger(options) {
-  const useColors = options?.colors ?? process.stdout.isTTY ?? false;
-  function colorize(text, code) {
-    return useColors ? `${code}${text}${RESET}` : text;
-  }
-  function bold(text) {
-    return useColors ? `${BOLD}${text}${RESET}` : text;
-  }
-  return {
-    info(msg) {
-      console.log(msg);
-    },
-    success(msg) {
-      const prefix = colorize("\u2713", GREEN);
-      console.log(`${prefix} ${msg}`);
-    },
-    warn(msg) {
-      const prefix = colorize("warn", YELLOW);
-      console.warn(`${bold(prefix)} ${msg}`);
-    },
-    error(msg) {
-      const prefix = colorize("error", RED);
-      console.error(`${bold(prefix)} ${msg}`);
-    },
-    step(label, detail, duration) {
-      const check = colorize("\u2713", GREEN);
-      const durationStr = duration !== void 0 ? ` (${duration}ms)` : "";
-      console.log(`  ${check} ${bold(label)}: ${detail}${durationStr}`);
-    }
-  };
-}
-
-// src/commands/build.ts
 async function runBuild(args) {
   const config = await loadConfig(args.cwd);
   const buildStart = Date.now();
@@ -917,12 +820,486 @@ var checkCommand = defineCommand4({
   }
 });
 
+// src/commands/doctor.ts
+import { existsSync, readFileSync } from "fs";
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { defineCommand as defineCommand5 } from "citty";
+function readJsonSafe(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_CONFIG_CONTENT = `import { defineConfig } from "@forge-ts/core";
+
+export default defineConfig({
+  rootDir: ".",
+  tsconfig: "tsconfig.json",
+  outDir: "docs/generated",
+  enforce: {
+    enabled: true,
+    minVisibility: "public",
+    strict: false,
+  },
+  gen: {
+    enabled: true,
+    formats: ["mdx"],
+    llmsTxt: true,
+    readmeSync: false,
+    ssgTarget: "mintlify",
+  },
+});
+`;
+var DEFAULT_TSDOC_CONTENT = JSON.stringify(
+  {
+    $schema: "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+    extends: ["@forge-ts/tsdoc-config/tsdoc.json"]
+  },
+  null,
+  "	"
+);
+async function runDoctor(args) {
+  const start = Date.now();
+  const rootDir = args.cwd ?? process.cwd();
+  const fix = args.fix ?? false;
+  const checks = [];
+  const fixed = [];
+  const configPath = join(rootDir, "forge-ts.config.ts");
+  const configJsPath = join(rootDir, "forge-ts.config.js");
+  if (existsSync(configPath) || existsSync(configJsPath)) {
+    const which = existsSync(configPath) ? "forge-ts.config.ts" : "forge-ts.config.js";
+    checks.push({
+      name: "forge-ts.config",
+      status: "pass",
+      message: `${which} \u2014 found`,
+      fixable: false
+    });
+  } else if (fix) {
+    await mkdir(rootDir, { recursive: true });
+    await writeFile(configPath, DEFAULT_CONFIG_CONTENT, "utf8");
+    fixed.push("forge-ts.config.ts");
+    checks.push({
+      name: "forge-ts.config",
+      status: "pass",
+      message: "forge-ts.config.ts \u2014 created by --fix",
+      fixable: true
+    });
+  } else {
+    checks.push({
+      name: "forge-ts.config",
+      status: "error",
+      message: "forge-ts.config.ts \u2014 MISSING (run forge-ts init or forge-ts doctor --fix)",
+      fixable: true
+    });
+  }
+  const tsdocPath = join(rootDir, "tsdoc.json");
+  if (existsSync(tsdocPath)) {
+    const tsdoc = readJsonSafe(tsdocPath);
+    if (tsdoc?.extends && tsdoc.extends.includes("@forge-ts/tsdoc-config/tsdoc.json")) {
+      checks.push({
+        name: "tsdoc.json",
+        status: "pass",
+        message: "tsdoc.json \u2014 extends @forge-ts/tsdoc-config",
+        fixable: false
+      });
+    } else {
+      checks.push({
+        name: "tsdoc.json",
+        status: "warn",
+        message: "tsdoc.json \u2014 does not extend @forge-ts/tsdoc-config",
+        fixable: false
+      });
+    }
+  } else if (fix) {
+    await writeFile(tsdocPath, `${DEFAULT_TSDOC_CONTENT}
+`, "utf8");
+    fixed.push("tsdoc.json");
+    checks.push({
+      name: "tsdoc.json",
+      status: "pass",
+      message: "tsdoc.json \u2014 created by --fix",
+      fixable: true
+    });
+  } else {
+    checks.push({
+      name: "tsdoc.json",
+      status: "error",
+      message: "tsdoc.json \u2014 MISSING (run forge-ts init or forge-ts doctor --fix)",
+      fixable: true
+    });
+  }
+  const tsdocConfigModulePath = join(
+    rootDir,
+    "node_modules",
+    "@forge-ts",
+    "tsdoc-config",
+    "package.json"
+  );
+  if (existsSync(tsdocConfigModulePath)) {
+    const tsdocPkg = readJsonSafe(
+      tsdocConfigModulePath
+    );
+    const version = tsdocPkg?.version ?? "unknown";
+    checks.push({
+      name: "@forge-ts/tsdoc-config",
+      status: "pass",
+      message: `@forge-ts/tsdoc-config \u2014 installed (${version})`,
+      fixable: false
+    });
+  } else {
+    checks.push({
+      name: "@forge-ts/tsdoc-config",
+      status: "warn",
+      message: "@forge-ts/tsdoc-config \u2014 MISSING (run npm install @forge-ts/tsdoc-config)",
+      fixable: false
+    });
+  }
+  const tsPkgPath = join(
+    rootDir,
+    "node_modules",
+    "typescript",
+    "package.json"
+  );
+  if (existsSync(tsPkgPath)) {
+    const tsPkg = readJsonSafe(tsPkgPath);
+    const version = tsPkg?.version ?? "unknown";
+    checks.push({
+      name: "TypeScript",
+      status: "pass",
+      message: `TypeScript \u2014 ${version}`,
+      fixable: false
+    });
+  } else {
+    const pkgPath = join(rootDir, "package.json");
+    const pkg2 = readJsonSafe(pkgPath);
+    const allDeps = {
+      ...pkg2?.dependencies,
+      ...pkg2?.devDependencies
+    };
+    if ("typescript" in allDeps) {
+      checks.push({
+        name: "TypeScript",
+        status: "warn",
+        message: `TypeScript \u2014 in package.json (${allDeps.typescript}) but not in node_modules`,
+        fixable: false
+      });
+    } else {
+      checks.push({
+        name: "TypeScript",
+        status: "error",
+        message: "TypeScript \u2014 MISSING (run npm install -D typescript)",
+        fixable: false
+      });
+    }
+  }
+  const tsconfigPath = join(rootDir, "tsconfig.json");
+  if (existsSync(tsconfigPath)) {
+    const tsconfig = readJsonSafe(tsconfigPath);
+    if (tsconfig?.compilerOptions?.strict === true) {
+      checks.push({
+        name: "tsconfig.json",
+        status: "pass",
+        message: "tsconfig.json \u2014 strict mode enabled",
+        fixable: false
+      });
+    } else {
+      const missingFlags = ["strict"];
+      if (!tsconfig?.compilerOptions?.strictNullChecks) {
+        missingFlags.push("strictNullChecks");
+      }
+      if (!tsconfig?.compilerOptions?.noImplicitAny) {
+        missingFlags.push("noImplicitAny");
+      }
+      checks.push({
+        name: "tsconfig.json",
+        status: "warn",
+        message: `tsconfig.json \u2014 strict mode not fully enabled (missing ${missingFlags.join(", ")})`,
+        fixable: false
+      });
+    }
+  } else {
+    checks.push({
+      name: "tsconfig.json",
+      status: "warn",
+      message: "tsconfig.json \u2014 not found",
+      fixable: false
+    });
+  }
+  const biomePath = join(rootDir, "biome.json");
+  const biomecPath = join(rootDir, "biome.jsonc");
+  if (existsSync(biomePath) || existsSync(biomecPath)) {
+    checks.push({
+      name: "biome.json",
+      status: "pass",
+      message: "biome.json \u2014 found",
+      fixable: false
+    });
+  } else {
+    checks.push({
+      name: "biome.json",
+      status: "info",
+      message: "biome.json \u2014 not found (optional)",
+      fixable: false
+    });
+  }
+  const lockPath = join(rootDir, ".forge-lock.json");
+  if (existsSync(lockPath)) {
+    const lock = readJsonSafe(lockPath);
+    if (lock?.lockedAt) {
+      checks.push({
+        name: ".forge-lock.json",
+        status: "pass",
+        message: `.forge-lock.json \u2014 locked at ${lock.lockedAt}`,
+        fixable: false
+      });
+    } else {
+      checks.push({
+        name: ".forge-lock.json",
+        status: "warn",
+        message: ".forge-lock.json \u2014 invalid format (run forge-ts lock to regenerate)",
+        fixable: false
+      });
+    }
+  } else {
+    checks.push({
+      name: ".forge-lock.json",
+      status: "warn",
+      message: ".forge-lock.json \u2014 not locked (run forge-ts lock)",
+      fixable: false
+    });
+  }
+  const auditPath = join(rootDir, ".forge-audit.jsonl");
+  if (existsSync(auditPath)) {
+    try {
+      const raw = readFileSync(auditPath, "utf8");
+      const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+      checks.push({
+        name: ".forge-audit.jsonl",
+        status: "info",
+        message: `.forge-audit.jsonl \u2014 ${lines.length} event${lines.length !== 1 ? "s" : ""}`,
+        fixable: false
+      });
+    } catch {
+      checks.push({
+        name: ".forge-audit.jsonl",
+        status: "warn",
+        message: ".forge-audit.jsonl \u2014 exists but unreadable",
+        fixable: false
+      });
+    }
+  } else {
+    checks.push({
+      name: ".forge-audit.jsonl",
+      status: "info",
+      message: ".forge-audit.jsonl \u2014 no audit trail",
+      fixable: false
+    });
+  }
+  const bypassPath = join(rootDir, ".forge-bypass.json");
+  if (existsSync(bypassPath)) {
+    const records = readJsonSafe(bypassPath);
+    if (records && Array.isArray(records)) {
+      const now = /* @__PURE__ */ new Date();
+      const active = records.filter(
+        (r) => r.expiresAt && new Date(r.expiresAt) > now
+      );
+      const expired = records.length - active.length;
+      if (active.length > 0) {
+        checks.push({
+          name: ".forge-bypass.json",
+          status: "info",
+          message: `.forge-bypass.json \u2014 ${active.length} active bypass${active.length !== 1 ? "es" : ""}`,
+          fixable: false
+        });
+      } else if (expired > 0) {
+        checks.push({
+          name: ".forge-bypass.json",
+          status: "info",
+          message: `.forge-bypass.json \u2014 ${expired} expired bypass${expired !== 1 ? "es" : ""} (run cleanup)`,
+          fixable: false
+        });
+      } else {
+        checks.push({
+          name: ".forge-bypass.json",
+          status: "pass",
+          message: ".forge-bypass.json \u2014 no active bypasses",
+          fixable: false
+        });
+      }
+    } else {
+      checks.push({
+        name: ".forge-bypass.json",
+        status: "warn",
+        message: ".forge-bypass.json \u2014 invalid format",
+        fixable: false
+      });
+    }
+  } else {
+    checks.push({
+      name: ".forge-bypass.json",
+      status: "pass",
+      message: ".forge-bypass.json \u2014 no active bypasses",
+      fixable: false
+    });
+  }
+  const huskyPreCommit = join(rootDir, ".husky", "pre-commit");
+  const lefthookYml = join(rootDir, "lefthook.yml");
+  let hookConfigured = false;
+  let hookLocation = "";
+  if (existsSync(huskyPreCommit)) {
+    try {
+      const content = readFileSync(huskyPreCommit, "utf8");
+      if (content.includes("forge-ts check")) {
+        hookConfigured = true;
+        hookLocation = "husky pre-commit";
+      }
+    } catch {
+    }
+  }
+  if (!hookConfigured && existsSync(lefthookYml)) {
+    try {
+      const content = readFileSync(lefthookYml, "utf8");
+      if (content.includes("forge-ts check")) {
+        hookConfigured = true;
+        hookLocation = "lefthook";
+      }
+    } catch {
+    }
+  }
+  if (hookConfigured) {
+    checks.push({
+      name: "Git hooks",
+      status: "pass",
+      message: `Git hooks \u2014 forge-ts check in ${hookLocation}`,
+      fixable: false
+    });
+  } else {
+    checks.push({
+      name: "Git hooks",
+      status: "warn",
+      message: "Git hooks \u2014 forge-ts check not in pre-commit (run forge-ts init hooks)",
+      fixable: false
+    });
+  }
+  const summary = {
+    passed: checks.filter((c) => c.status === "pass").length,
+    warnings: checks.filter((c) => c.status === "warn").length,
+    errors: checks.filter((c) => c.status === "error").length,
+    info: checks.filter((c) => c.status === "info").length
+  };
+  const data = {
+    success: summary.errors === 0,
+    checks,
+    summary,
+    fixed
+  };
+  return {
+    operation: "doctor",
+    success: summary.errors === 0,
+    data,
+    duration: Date.now() - start
+  };
+}
+var STATUS_LABELS = {
+  pass: "[PASS]",
+  warn: "[WARN]",
+  error: "[FAIL]",
+  info: "[INFO]"
+};
+function formatDoctorHuman(result) {
+  const lines = [];
+  lines.push("\nforge-ts doctor: project health check\n");
+  for (const check of result.checks) {
+    const label = STATUS_LABELS[check.status];
+    lines.push(`  ${label} ${check.message}`);
+  }
+  if (result.fixed.length > 0) {
+    lines.push("");
+    lines.push("  Fixed:");
+    for (const file of result.fixed) {
+      lines.push(`    ${file}`);
+    }
+  }
+  lines.push("");
+  lines.push(
+    `  Summary: ${result.summary.passed} passed, ${result.summary.warnings} warning${result.summary.warnings !== 1 ? "s" : ""}, ${result.summary.errors} error${result.summary.errors !== 1 ? "s" : ""}`
+  );
+  if (result.summary.errors > 0 || result.summary.warnings > 0) {
+    lines.push(
+      "  Run: forge-ts doctor --fix   to auto-fix resolvable issues"
+    );
+  }
+  return lines.join("\n");
+}
+var doctorCommand = defineCommand5({
+  meta: {
+    name: "doctor",
+    description: "Project integrity check and repair"
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root directory"
+    },
+    fix: {
+      type: "boolean",
+      description: "Auto-fix resolvable issues",
+      default: false
+    },
+    json: {
+      type: "boolean",
+      description: "Output as LAFS JSON envelope",
+      default: false
+    },
+    human: {
+      type: "boolean",
+      description: "Output as formatted text",
+      default: false
+    },
+    quiet: {
+      type: "boolean",
+      description: "Suppress non-essential output",
+      default: false
+    },
+    mvi: {
+      type: "string",
+      description: "MVI verbosity level: minimal, standard, full"
+    }
+  },
+  async run({ args }) {
+    const output = await runDoctor({
+      cwd: args.cwd,
+      fix: args.fix,
+      mvi: args.mvi
+    });
+    const flags = {
+      json: args.json,
+      human: args.human,
+      quiet: args.quiet,
+      mvi: args.mvi
+    };
+    emitResult(output, flags, (data, cmd) => {
+      if (!cmd.success) {
+        return formatDoctorHuman(data);
+      }
+      return formatDoctorHuman(data);
+    });
+    process.exit(resolveExitCode(output));
+  }
+});
+
 // src/commands/docs-dev.ts
 import { spawn } from "child_process";
 import { resolve } from "path";
 import { loadConfig as loadConfig4 } from "@forge-ts/core";
 import { DEFAULT_TARGET, getAdapter } from "@forge-ts/gen";
-import { defineCommand as defineCommand5 } from "citty";
+import { defineCommand as defineCommand6 } from "citty";
 async function runDocsDev(args) {
   const logger = createLogger();
   const config = await loadConfig4(args.cwd);
@@ -955,7 +1332,7 @@ async function runDocsDev(args) {
     proc.on("error", reject);
   });
 }
-var docsDevCommand = defineCommand5({
+var docsDevCommand = defineCommand6({
   meta: {
     name: "dev",
     description: "Start a local doc preview server"
@@ -980,16 +1357,16 @@ var docsDevCommand = defineCommand5({
 });
 
 // src/commands/init-docs.ts
-import { existsSync } from "fs";
-import { mkdir, writeFile } from "fs/promises";
-import { join, resolve as resolve2 } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { join as join2, resolve as resolve2 } from "path";
 import { loadConfig as loadConfig5 } from "@forge-ts/core";
 import {
   DEFAULT_TARGET as DEFAULT_TARGET2,
   getAdapter as getAdapter2,
   getAvailableTargets
 } from "@forge-ts/gen";
-import { defineCommand as defineCommand6 } from "citty";
+import { defineCommand as defineCommand7 } from "citty";
 async function runInitDocs(args) {
   const start = Date.now();
   const rawTarget = args.target ?? DEFAULT_TARGET2;
@@ -1060,15 +1437,15 @@ async function runInitDocs(args) {
   const manifest = adapter.scaffold(context);
   const writtenFiles = [];
   for (const file of manifest.files) {
-    const filePath = join(outDir, file.path);
+    const filePath = join2(outDir, file.path);
     const fileDir = filePath.substring(0, filePath.lastIndexOf("/"));
-    await mkdir(fileDir, { recursive: true });
-    await writeFile(filePath, file.content, "utf8");
+    await mkdir2(fileDir, { recursive: true });
+    await writeFile2(filePath, file.content, "utf8");
     writtenFiles.push(file.path);
   }
   if (config.tsdoc.writeConfig) {
-    const tsdocPath = join(config.rootDir, "tsdoc.json");
-    if (existsSync(tsdocPath)) {
+    const tsdocPath = join2(config.rootDir, "tsdoc.json");
+    if (existsSync2(tsdocPath)) {
       warnings.push({
         code: "INIT_TSDOC_EXISTS",
         message: "tsdoc.json already exists \u2014 skipping. Remove it and re-run to regenerate."
@@ -1082,8 +1459,8 @@ async function runInitDocs(args) {
         null,
         "	"
       );
-      await mkdir(config.rootDir, { recursive: true });
-      await writeFile(tsdocPath, `${tsdocContent}
+      await mkdir2(config.rootDir, { recursive: true });
+      await writeFile2(tsdocPath, `${tsdocContent}
 `, "utf8");
       writtenFiles.push("tsdoc.json");
     }
@@ -1145,7 +1522,7 @@ function formatInitDocsHuman(result) {
   );
   return lines.join("\n");
 }
-var initDocsCommand = defineCommand6({
+var initDocsCommand = defineCommand7({
   meta: {
     name: "init",
     description: "Scaffold a documentation site"
@@ -1214,7 +1591,7 @@ var initDocsCommand = defineCommand6({
     process.exit(resolveExitCode(output));
   }
 });
-var initCommand = defineCommand6({
+var initCommand = defineCommand7({
   meta: {
     name: "init",
     description: "Scaffold project artefacts"
@@ -1225,23 +1602,23 @@ var initCommand = defineCommand6({
 });
 
 // src/commands/init-hooks.ts
-import { existsSync as existsSync2, readFileSync } from "fs";
-import { mkdir as mkdir2, readFile, writeFile as writeFile2 } from "fs/promises";
-import { join as join2 } from "path";
-import { defineCommand as defineCommand7 } from "citty";
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { mkdir as mkdir3, readFile, writeFile as writeFile3 } from "fs/promises";
+import { join as join3 } from "path";
+import { defineCommand as defineCommand8 } from "citty";
 function detectHookManager(rootDir) {
-  const huskyDir = join2(rootDir, ".husky");
-  if (existsSync2(huskyDir)) {
+  const huskyDir = join3(rootDir, ".husky");
+  if (existsSync3(huskyDir)) {
     return "husky";
   }
-  const lefthookYml = join2(rootDir, "lefthook.yml");
-  if (existsSync2(lefthookYml)) {
+  const lefthookYml = join3(rootDir, "lefthook.yml");
+  if (existsSync3(lefthookYml)) {
     return "lefthook";
   }
-  const pkgJsonPath = join2(rootDir, "package.json");
-  if (existsSync2(pkgJsonPath)) {
+  const pkgJsonPath = join3(rootDir, "package.json");
+  if (existsSync3(pkgJsonPath)) {
     try {
-      const raw = readFileSync(pkgJsonPath, "utf8");
+      const raw = readFileSync2(pkgJsonPath, "utf8");
       const pkg2 = JSON.parse(raw);
       const allDeps = { ...pkg2.dependencies, ...pkg2.devDependencies };
       if ("husky" in allDeps) return "husky";
@@ -1270,10 +1647,10 @@ async function runInitHooks(args) {
   const warnings = [];
   const instructions = [];
   if (hookManager === "husky" || hookManager === "none") {
-    const huskyDir = join2(rootDir, ".husky");
-    const hookPath = join2(huskyDir, "pre-commit");
+    const huskyDir = join3(rootDir, ".husky");
+    const hookPath = join3(huskyDir, "pre-commit");
     const relativePath = ".husky/pre-commit";
-    if (existsSync2(hookPath) && !args.force) {
+    if (existsSync3(hookPath) && !args.force) {
       const existing = await readFile(hookPath, "utf8");
       if (existing.includes("forge-ts check")) {
         skippedFiles.push(relativePath);
@@ -1286,12 +1663,12 @@ async function runInitHooks(args) {
 
 npx forge-ts check
 `;
-        await writeFile2(hookPath, appended, { mode: 493 });
+        await writeFile3(hookPath, appended, { mode: 493 });
         writtenFiles.push(relativePath);
       }
     } else {
-      await mkdir2(huskyDir, { recursive: true });
-      await writeFile2(hookPath, HUSKY_PRE_COMMIT, { mode: 493 });
+      await mkdir3(huskyDir, { recursive: true });
+      await writeFile3(hookPath, HUSKY_PRE_COMMIT, { mode: 493 });
       writtenFiles.push(relativePath);
     }
     if (hookManager === "none") {
@@ -1303,9 +1680,9 @@ npx forge-ts check
       instructions.push("Husky pre-commit hook configured to run forge-ts check.");
     }
   } else if (hookManager === "lefthook") {
-    const lefthookPath = join2(rootDir, "lefthook.yml");
+    const lefthookPath = join3(rootDir, "lefthook.yml");
     const relativePath = "lefthook.yml";
-    if (existsSync2(lefthookPath)) {
+    if (existsSync3(lefthookPath)) {
       const existing = await readFile(lefthookPath, "utf8");
       if (existing.includes("forge-ts check") && !args.force) {
         skippedFiles.push(relativePath);
@@ -1318,17 +1695,17 @@ npx forge-ts check
     forge-ts-check:
       run: npx forge-ts check
 `;
-        await writeFile2(lefthookPath, appended, "utf8");
+        await writeFile3(lefthookPath, appended, "utf8");
         writtenFiles.push(relativePath);
       } else {
         const appended = `${existing.trimEnd()}
 
 ${LEFTHOOK_BLOCK}`;
-        await writeFile2(lefthookPath, appended, "utf8");
+        await writeFile3(lefthookPath, appended, "utf8");
         writtenFiles.push(relativePath);
       }
     } else {
-      await writeFile2(lefthookPath, LEFTHOOK_BLOCK, "utf8");
+      await writeFile3(lefthookPath, LEFTHOOK_BLOCK, "utf8");
       writtenFiles.push(relativePath);
     }
     instructions.push("Lefthook pre-commit hook configured to run forge-ts check.");
@@ -1373,7 +1750,7 @@ function formatInitHooksHuman(result) {
   ${result.summary.filesWritten} file(s) written.`);
   return lines.join("\n");
 }
-var initHooksCommand = defineCommand7({
+var initHooksCommand = defineCommand8({
   meta: {
     name: "hooks",
     description: "Scaffold git hook integration (husky/lefthook)"
@@ -1441,7 +1818,7 @@ import {
   readLockFile,
   writeLockFile
 } from "@forge-ts/core";
-import { defineCommand as defineCommand8 } from "citty";
+import { defineCommand as defineCommand9 } from "citty";
 async function runLock(args) {
   const config = await loadConfig6(args.cwd);
   const rootDir = config.rootDir;
@@ -1500,7 +1877,7 @@ function formatLockHuman(result) {
   To modify locked settings, run: forge-ts unlock --reason="..."`);
   return lines.join("\n");
 }
-var lockCommand = defineCommand8({
+var lockCommand = defineCommand9({
   meta: {
     name: "lock",
     description: "Lock current config to prevent silent weakening"
@@ -1539,7 +1916,7 @@ var lockCommand = defineCommand8({
 });
 
 // src/commands/prepublish.ts
-import { defineCommand as defineCommand9 } from "citty";
+import { defineCommand as defineCommand10 } from "citty";
 async function runPrepublish(args) {
   const start = Date.now();
   const allErrors = [];
@@ -1643,7 +2020,7 @@ function formatPrepublishHuman(result) {
   }
   return lines.join("\n");
 }
-var prepublishCommand = defineCommand9({
+var prepublishCommand = defineCommand10({
   meta: {
     name: "prepublish",
     description: "Safety gate: check + build before npm publish"
@@ -1704,7 +2081,7 @@ var prepublishCommand = defineCommand9({
 // src/commands/test.ts
 import { loadConfig as loadConfig7 } from "@forge-ts/core";
 import { doctest } from "@forge-ts/doctest";
-import { defineCommand as defineCommand10 } from "citty";
+import { defineCommand as defineCommand11 } from "citty";
 async function runTest(args) {
   const config = await loadConfig7(args.cwd);
   const result = await doctest(config);
@@ -1747,7 +2124,7 @@ async function runTest(args) {
     duration: result.duration
   };
 }
-var testCommand = defineCommand10({
+var testCommand = defineCommand11({
   meta: {
     name: "test",
     description: "Run @example blocks as doctests"
@@ -1808,7 +2185,7 @@ import {
   readLockFile as readLockFile2,
   removeLockFile
 } from "@forge-ts/core";
-import { defineCommand as defineCommand11 } from "citty";
+import { defineCommand as defineCommand12 } from "citty";
 async function runUnlock(args) {
   const config = await loadConfig8(args.cwd);
   const rootDir = config.rootDir;
@@ -1893,7 +2270,7 @@ function formatUnlockHuman(result) {
   lines.push("  Run `forge-ts lock` to re-lock after changes.");
   return lines.join("\n");
 }
-var unlockCommand = defineCommand11({
+var unlockCommand = defineCommand12({
   meta: {
     name: "unlock",
     description: "Remove config lock (requires --reason)"
@@ -1948,7 +2325,7 @@ var unlockCommand = defineCommand11({
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
-var docsCommand = defineCommand12({
+var docsCommand = defineCommand13({
   meta: {
     name: "docs",
     description: "Documentation site management"
@@ -1958,17 +2335,120 @@ var docsCommand = defineCommand12({
     dev: docsDevCommand
   }
 });
-var initCommand2 = defineCommand12({
+var initCommand2 = defineCommand13({
   meta: {
     name: "init",
-    description: "Scaffold project artefacts"
+    description: "Full project setup (bare) or scaffold artefacts (with subcommand)"
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root directory"
+    },
+    json: {
+      type: "boolean",
+      description: "Output as LAFS JSON envelope",
+      default: false
+    },
+    human: {
+      type: "boolean",
+      description: "Output as formatted text",
+      default: false
+    },
+    quiet: {
+      type: "boolean",
+      description: "Suppress non-essential output",
+      default: false
+    },
+    mvi: {
+      type: "string",
+      description: "MVI verbosity level: minimal, standard, full"
+    }
   },
   subCommands: {
     docs: initDocsCommand,
-    hooks: initHooksCommand
+    hooks: initHooksCommand,
+    setup: initProjectCommand
+  },
+  async run({ rawArgs, args }) {
+    const subCommandNames = /* @__PURE__ */ new Set(["docs", "hooks", "setup"]);
+    const hasSubCommand = rawArgs.some((arg) => subCommandNames.has(arg));
+    if (hasSubCommand) {
+      return;
+    }
+    const { runInitProject: runInitProject2 } = await import("./init-project-5DESIZ73.js");
+    const { emitResult: emitResult2, resolveExitCode: resolveExitCode2 } = await import("./output-OSCHMPOX.js");
+    const { createLogger: createLogger3 } = await import("./logger-MMBBZG6U.js");
+    const output = await runInitProject2({
+      cwd: args.cwd,
+      mvi: args.mvi
+    });
+    const flags = {
+      json: args.json,
+      human: args.human,
+      quiet: args.quiet,
+      mvi: args.mvi
+    };
+    emitResult2(output, flags, (data, cmd) => {
+      if (!cmd.success) {
+        const logger = createLogger3();
+        const msg = cmd.errors?.[0]?.message ?? "Init failed";
+        logger.error(msg);
+        return "";
+      }
+      const lines = [];
+      lines.push("\nforge-ts init: project setup complete\n");
+      if (data.created.length > 0) {
+        lines.push("  Created:");
+        for (const file of data.created) {
+          lines.push(`    ${file}`);
+        }
+      }
+      if (data.skipped.length > 0) {
+        lines.push("");
+        lines.push("  Already exists (skipped):");
+        for (const file of data.skipped) {
+          lines.push(`    ${file}`);
+        }
+      } else if (data.created.length > 0) {
+        lines.push("");
+        lines.push("  Already exists (skipped):");
+        lines.push("    (none)");
+      }
+      if (data.warnings.length > 0) {
+        lines.push("");
+        lines.push("  Warnings:");
+        for (const warning of data.warnings) {
+          lines.push(`    ${warning}`);
+        }
+      }
+      const env = data.environment;
+      lines.push("");
+      lines.push("  Environment:");
+      lines.push(`    TypeScript: ${env.typescriptVersion ?? "not detected"}`);
+      lines.push(`    Biome: ${env.biomeDetected ? "detected" : "not detected"}`);
+      const hookLabel = env.hookManager === "none" ? "not detected" : `${env.hookManager} detected`;
+      lines.push(`    Git hooks: ${hookLabel}`);
+      if (env.monorepo) {
+        lines.push(
+          `    Monorepo: ${env.monorepoType === "pnpm" ? "pnpm workspaces" : "npm/yarn workspaces"}`
+        );
+      } else {
+        lines.push("    Monorepo: no");
+      }
+      if (data.nextSteps.length > 0) {
+        lines.push("");
+        lines.push("  Next steps:");
+        for (const [idx, step] of data.nextSteps.entries()) {
+          lines.push(`    ${idx + 1}. ${step}`);
+        }
+      }
+      return lines.join("\n");
+    });
+    process.exit(resolveExitCode2(output));
   }
 });
-var main = defineCommand12({
+var main = defineCommand13({
   meta: {
     name: "forge-ts",
     version: pkg.version,
@@ -1984,7 +2464,8 @@ var main = defineCommand12({
     unlock: unlockCommand,
     bypass: bypassCommand,
     audit: auditCommand,
-    prepublish: prepublishCommand
+    prepublish: prepublishCommand,
+    doctor: doctorCommand
   }
 });
 runMain(main);
@@ -1995,16 +2476,20 @@ export {
   checkCommand,
   createLogger,
   docsDevCommand,
+  doctorCommand,
   emitResult,
   initDocsCommand,
   initHooksCommand,
+  initProjectCommand,
   lockCommand,
   prepublishCommand,
   resolveExitCode,
   runBypassCreate,
   runBypassStatus,
   runDocsDev,
+  runDoctor,
   runInitHooks,
+  runInitProject,
   runLock,
   runPrepublish,
   runUnlock,