@forge-ts/cli 0.8.0 → 0.14.0

package/dist/index.js

@@ -2,52 +2,15 @@
 
 // src/index.ts
 import { createRequire } from "module";
-import { defineCommand as defineCommand6, runMain } from "citty";
+import { defineCommand as defineCommand12, runMain } from "citty";
 
-// src/commands/build.ts
-import { generateApi } from "@forge-ts/api";
-import { loadConfig } from "@forge-ts/core";
-import { generate } from "@forge-ts/gen";
+// src/commands/audit.ts
+import {
+  formatAuditEvent,
+  readAuditLog
+} from "@forge-ts/core";
 import { defineCommand } 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/output.ts
 import { randomUUID } from "crypto";
 import {
@@ -114,6 +77,146 @@ function resolveExitCode(output) {
   return 1;
 }
 
+// src/commands/audit.ts
+function runAudit(args) {
+  const rootDir = args.cwd ?? process.cwd();
+  const limit = args.limit ?? 20;
+  const events = readAuditLog(rootDir, {
+    limit,
+    eventType: args.type
+  });
+  const data = {
+    success: true,
+    count: events.length,
+    events
+  };
+  return {
+    operation: "audit",
+    success: true,
+    data
+  };
+}
+function formatAuditHuman(data) {
+  if (data.count === 0) {
+    return "forge-ts audit: no events found.";
+  }
+  const lines = [];
+  lines.push(`forge-ts audit: ${data.count} event(s)
+`);
+  for (const event of data.events) {
+    lines.push(`  ${formatAuditEvent(event)}`);
+  }
+  return lines.join("\n");
+}
+var VALID_EVENT_TYPES = [
+  "config.lock",
+  "config.unlock",
+  "config.drift",
+  "bypass.create",
+  "bypass.expire",
+  "rule.change"
+];
+var auditCommand = defineCommand({
+  meta: {
+    name: "audit",
+    description: "Display the forge-ts audit trail"
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root directory"
+    },
+    limit: {
+      type: "string",
+      description: "Maximum events to display (default: 20)"
+    },
+    type: {
+      type: "string",
+      description: "Filter by event type (config.lock, config.unlock, config.drift, bypass.create, bypass.expire, rule.change)"
+    },
+    json: {
+      type: "boolean",
+      description: "Output as LAFS JSON envelope (agent-friendly)",
+      default: false
+    },
+    human: {
+      type: "boolean",
+      description: "Output as formatted text (default for TTY)",
+      default: false
+    },
+    quiet: {
+      type: "boolean",
+      description: "Suppress non-essential output",
+      default: false
+    }
+  },
+  run({ args }) {
+    const eventType = args.type;
+    if (eventType && !VALID_EVENT_TYPES.includes(eventType)) {
+      console.error(
+        `Error: invalid event type "${eventType}". Valid types: ${VALID_EVENT_TYPES.join(", ")}`
+      );
+      process.exit(1);
+    }
+    const output = runAudit({
+      cwd: args.cwd,
+      limit: args.limit ? Number.parseInt(args.limit, 10) : void 0,
+      type: eventType
+    });
+    const flags = {
+      json: args.json,
+      human: args.human,
+      quiet: args.quiet
+    };
+    emitResult(output, flags, (data) => formatAuditHuman(data));
+    process.exit(resolveExitCode(output));
+  }
+});
+
+// src/commands/build.ts
+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);
@@ -217,7 +320,7 @@ async function runBuild(args) {
     duration: totalMs
   };
 }
-var buildCommand = defineCommand({
+var buildCommand = defineCommand2({
   meta: {
     name: "build",
     description: "Generate API reference and documentation"
@@ -297,10 +400,180 @@ var buildCommand = defineCommand({
   }
 });
 
+// src/commands/bypass.ts
+import {
+  createBypass,
+  expireOldBypasses,
+  getActiveBypasses,
+  getRemainingBudget,
+  loadConfig as loadConfig2
+} from "@forge-ts/core";
+import { defineCommand as defineCommand3 } from "citty";
+async function runBypassCreate(args) {
+  const config = await loadConfig2(args.cwd);
+  const rootDir = config.rootDir;
+  expireOldBypasses(rootDir);
+  try {
+    const bypass = createBypass(rootDir, args.reason, args.rule, config.bypass);
+    const remainingBudget = getRemainingBudget(rootDir, config.bypass);
+    return {
+      operation: "bypass",
+      success: true,
+      data: {
+        success: true,
+        bypass,
+        remainingBudget,
+        dailyBudget: config.bypass.dailyBudget
+      },
+      duration: 0
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      operation: "bypass",
+      success: false,
+      data: {
+        success: false,
+        bypass: {},
+        remainingBudget: 0,
+        dailyBudget: config.bypass.dailyBudget
+      },
+      errors: [
+        {
+          code: "FORGE_BYPASS_BUDGET_EXHAUSTED",
+          message
+        }
+      ],
+      duration: 0
+    };
+  }
+}
+async function runBypassStatus(args) {
+  const config = await loadConfig2(args.cwd);
+  const rootDir = config.rootDir;
+  const expiredRemoved = expireOldBypasses(rootDir);
+  const activeBypasses = getActiveBypasses(rootDir);
+  const remainingBudget = getRemainingBudget(rootDir, config.bypass);
+  return {
+    operation: "bypass",
+    success: true,
+    data: {
+      success: true,
+      activeBypasses,
+      remainingBudget,
+      dailyBudget: config.bypass.dailyBudget,
+      expiredRemoved
+    },
+    duration: 0
+  };
+}
+function formatBypassCreateHuman(result) {
+  const lines = [];
+  if (!result.success) {
+    lines.push("forge-ts bypass: FAILED\n");
+    lines.push("  Daily bypass budget exhausted.");
+    lines.push(`  Budget: 0/${result.dailyBudget} remaining`);
+    return lines.join("\n");
+  }
+  lines.push("forge-ts bypass: created\n");
+  lines.push(`  ID:      ${result.bypass.id}`);
+  lines.push(`  Rule:    ${result.bypass.rule}`);
+  lines.push(`  Reason:  ${result.bypass.reason}`);
+  lines.push(`  Expires: ${result.bypass.expiresAt}`);
+  lines.push(`  User:    ${result.bypass.user}`);
+  lines.push(`
+  Budget:  ${result.remainingBudget}/${result.dailyBudget} remaining today`);
+  return lines.join("\n");
+}
+function formatBypassStatusHuman(result) {
+  const lines = [];
+  lines.push("forge-ts bypass: status\n");
+  lines.push(`  Budget: ${result.remainingBudget}/${result.dailyBudget} remaining today`);
+  if (result.expiredRemoved > 0) {
+    lines.push(`  Cleaned up ${result.expiredRemoved} expired bypass(es)`);
+  }
+  if (result.activeBypasses.length === 0) {
+    lines.push("\n  No active bypasses.");
+  } else {
+    lines.push(`
+  Active bypasses (${result.activeBypasses.length}):`);
+    for (const b of result.activeBypasses) {
+      lines.push(`    - [${b.rule}] ${b.reason} (expires ${b.expiresAt})`);
+    }
+  }
+  return lines.join("\n");
+}
+var bypassCommand = defineCommand3({
+  meta: {
+    name: "bypass",
+    description: "Create or inspect temporary rule bypasses"
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root directory"
+    },
+    reason: {
+      type: "string",
+      description: "Mandatory justification for bypassing rules"
+    },
+    rule: {
+      type: "string",
+      description: 'Specific rule code to bypass (e.g., "E009"). Defaults to "all"'
+    },
+    status: {
+      type: "boolean",
+      description: "Show active bypasses and remaining budget",
+      default: false
+    },
+    json: {
+      type: "boolean",
+      description: "Output as LAFS JSON envelope (agent-friendly)",
+      default: false
+    },
+    human: {
+      type: "boolean",
+      description: "Output as formatted text (default for TTY)",
+      default: false
+    },
+    quiet: {
+      type: "boolean",
+      description: "Suppress non-essential output",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const flags = {
+      json: args.json,
+      human: args.human,
+      quiet: args.quiet
+    };
+    if (args.status) {
+      const output2 = await runBypassStatus({ cwd: args.cwd });
+      emitResult(output2, flags, (data) => formatBypassStatusHuman(data));
+      process.exit(resolveExitCode(output2));
+      return;
+    }
+    if (!args.reason) {
+      console.error(
+        "[forge-ts] error: --reason is required. Provide a justification for the bypass."
+      );
+      process.exit(1);
+    }
+    const output = await runBypassCreate({
+      cwd: args.cwd,
+      reason: args.reason,
+      rule: args.rule
+    });
+    emitResult(output, flags, (data) => formatBypassCreateHuman(data));
+    process.exit(resolveExitCode(output));
+  }
+});
+
 // src/commands/check.ts
-import { loadConfig as loadConfig2 } from "@forge-ts/core";
+import { loadConfig as loadConfig3 } from "@forge-ts/core";
 import { enforce } from "@forge-ts/enforcer";
-import { defineCommand as defineCommand2 } from "citty";
+import { defineCommand as defineCommand4 } from "citty";
 var RULE_NAMES = {
   E001: "require-summary",
   E002: "require-param",
@@ -455,7 +728,7 @@ function buildCheckResult(rawErrors, rawWarnings, exportedSymbolCount, duration,
   return result;
 }
 async function runCheck(args) {
-  const config = await loadConfig2(args.cwd);
+  const config = await loadConfig3(args.cwd);
   if (args.strict !== void 0) {
     config.enforce.strict = args.strict;
   }
@@ -554,7 +827,7 @@ function formatCheckHuman(result) {
       }
     }
   }
-  if (result.page && result.page.hasMore) {
+  if (result.page?.hasMore) {
     lines.push(
       `
   Showing ${result.page.offset + 1}-${result.page.offset + (result.byFile?.length ?? 0)} of ${result.page.total} file(s). Use --offset ${result.page.offset + result.page.limit} to see more.`
@@ -566,7 +839,7 @@ function formatCheckHuman(result) {
   }
   return lines.join("\n");
 }
-var checkCommand = defineCommand2({
+var checkCommand = defineCommand4({
   meta: {
     name: "check",
     description: "Lint TSDoc coverage on exported symbols"
@@ -647,12 +920,12 @@ var checkCommand = defineCommand2({
 // src/commands/docs-dev.ts
 import { spawn } from "child_process";
 import { resolve } from "path";
-import { loadConfig as loadConfig3 } from "@forge-ts/core";
+import { loadConfig as loadConfig4 } from "@forge-ts/core";
 import { DEFAULT_TARGET, getAdapter } from "@forge-ts/gen";
-import { defineCommand as defineCommand3 } from "citty";
+import { defineCommand as defineCommand5 } from "citty";
 async function runDocsDev(args) {
   const logger = createLogger();
-  const config = await loadConfig3(args.cwd);
+  const config = await loadConfig4(args.cwd);
   const target = args.target ?? config.gen.ssgTarget ?? DEFAULT_TARGET;
   const adapter = getAdapter(target);
   const outDir = resolve(config.outDir);
@@ -682,7 +955,7 @@ async function runDocsDev(args) {
     proc.on("error", reject);
   });
 }
-var docsDevCommand = defineCommand3({
+var docsDevCommand = defineCommand5({
   meta: {
     name: "dev",
     description: "Start a local doc preview server"
@@ -707,15 +980,16 @@ var docsDevCommand = defineCommand3({
 });
 
 // src/commands/init-docs.ts
+import { existsSync } from "fs";
 import { mkdir, writeFile } from "fs/promises";
 import { join, resolve as resolve2 } from "path";
-import { loadConfig as loadConfig4 } from "@forge-ts/core";
+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 defineCommand4 } from "citty";
+import { defineCommand as defineCommand6 } from "citty";
 async function runInitDocs(args) {
   const start = Date.now();
   const rawTarget = args.target ?? DEFAULT_TARGET2;
@@ -741,7 +1015,7 @@ async function runInitDocs(args) {
   }
   const target = rawTarget;
   const adapter = getAdapter2(target);
-  const config = await loadConfig4(args.cwd);
+  const config = await loadConfig5(args.cwd);
   const outDir = args.outDir ? resolve2(args.outDir) : config.outDir;
   const alreadyExists = await adapter.detectExisting(outDir);
   if (alreadyExists && !args.force) {
@@ -792,6 +1066,28 @@ async function runInitDocs(args) {
     await writeFile(filePath, file.content, "utf8");
     writtenFiles.push(file.path);
   }
+  if (config.tsdoc.writeConfig) {
+    const tsdocPath = join(config.rootDir, "tsdoc.json");
+    if (existsSync(tsdocPath)) {
+      warnings.push({
+        code: "INIT_TSDOC_EXISTS",
+        message: "tsdoc.json already exists \u2014 skipping. Remove it and re-run to regenerate."
+      });
+    } else {
+      const tsdocContent = JSON.stringify(
+        {
+          $schema: "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+          extends: ["@forge-ts/tsdoc-config/tsdoc.json"]
+        },
+        null,
+        "	"
+      );
+      await mkdir(config.rootDir, { recursive: true });
+      await writeFile(tsdocPath, `${tsdocContent}
+`, "utf8");
+      writtenFiles.push("tsdoc.json");
+    }
+  }
   const depCount = Object.keys(manifest.dependencies).length + Object.keys(manifest.devDependencies).length;
   const scriptCount = Object.keys(manifest.scripts).length;
   const data = {
@@ -849,7 +1145,7 @@ function formatInitDocsHuman(result) {
   );
   return lines.join("\n");
 }
-var initDocsCommand = defineCommand4({
+var initDocsCommand = defineCommand6({
   meta: {
     name: "init",
     description: "Scaffold a documentation site"
@@ -918,7 +1214,7 @@ var initDocsCommand = defineCommand4({
     process.exit(resolveExitCode(output));
   }
 });
-var initCommand = defineCommand4({
+var initCommand = defineCommand6({
   meta: {
     name: "init",
     description: "Scaffold project artefacts"
@@ -928,15 +1224,492 @@ var initCommand = defineCommand4({
   }
 });
 
-// src/commands/test.ts
-import { loadConfig as loadConfig5 } from "@forge-ts/core";
-import { doctest } from "@forge-ts/doctest";
-import { defineCommand as defineCommand5 } from "citty";
-async function runTest(args) {
-  const config = await loadConfig5(args.cwd);
-  const result = await doctest(config);
-  const mviLevel = args.mvi ?? "standard";
-  const failCount = result.errors.length;
+// 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";
+function detectHookManager(rootDir) {
+  const huskyDir = join2(rootDir, ".husky");
+  if (existsSync2(huskyDir)) {
+    return "husky";
+  }
+  const lefthookYml = join2(rootDir, "lefthook.yml");
+  if (existsSync2(lefthookYml)) {
+    return "lefthook";
+  }
+  const pkgJsonPath = join2(rootDir, "package.json");
+  if (existsSync2(pkgJsonPath)) {
+    try {
+      const raw = readFileSync(pkgJsonPath, "utf8");
+      const pkg2 = JSON.parse(raw);
+      const allDeps = { ...pkg2.dependencies, ...pkg2.devDependencies };
+      if ("husky" in allDeps) return "husky";
+      if ("lefthook" in allDeps) return "lefthook";
+    } catch {
+    }
+  }
+  return "none";
+}
+var HUSKY_PRE_COMMIT = `#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx forge-ts check
+`;
+var LEFTHOOK_BLOCK = `pre-commit:
+  commands:
+    forge-ts-check:
+      run: npx forge-ts check
+`;
+async function runInitHooks(args) {
+  const start = Date.now();
+  const rootDir = args.cwd ?? process.cwd();
+  const hookManager = detectHookManager(rootDir);
+  const writtenFiles = [];
+  const skippedFiles = [];
+  const warnings = [];
+  const instructions = [];
+  if (hookManager === "husky" || hookManager === "none") {
+    const huskyDir = join2(rootDir, ".husky");
+    const hookPath = join2(huskyDir, "pre-commit");
+    const relativePath = ".husky/pre-commit";
+    if (existsSync2(hookPath) && !args.force) {
+      const existing = await readFile(hookPath, "utf8");
+      if (existing.includes("forge-ts check")) {
+        skippedFiles.push(relativePath);
+        warnings.push({
+          code: "HOOKS_ALREADY_EXISTS",
+          message: `${relativePath} already contains forge-ts check \u2014 skipping. Use --force to overwrite.`
+        });
+      } else {
+        const appended = `${existing.trimEnd()}
+
+npx forge-ts check
+`;
+        await writeFile2(hookPath, appended, { mode: 493 });
+        writtenFiles.push(relativePath);
+      }
+    } else {
+      await mkdir2(huskyDir, { recursive: true });
+      await writeFile2(hookPath, HUSKY_PRE_COMMIT, { mode: 493 });
+      writtenFiles.push(relativePath);
+    }
+    if (hookManager === "none") {
+      instructions.push(
+        "No hook manager detected. Wrote .husky/pre-commit as a starting point.",
+        "Install husky to activate: npx husky-init && npm install (or pnpm dlx husky-init && pnpm install)"
+      );
+    } else {
+      instructions.push("Husky pre-commit hook configured to run forge-ts check.");
+    }
+  } else if (hookManager === "lefthook") {
+    const lefthookPath = join2(rootDir, "lefthook.yml");
+    const relativePath = "lefthook.yml";
+    if (existsSync2(lefthookPath)) {
+      const existing = await readFile(lefthookPath, "utf8");
+      if (existing.includes("forge-ts check") && !args.force) {
+        skippedFiles.push(relativePath);
+        warnings.push({
+          code: "HOOKS_ALREADY_EXISTS",
+          message: `${relativePath} already contains forge-ts check \u2014 skipping. Use --force to overwrite.`
+        });
+      } else if (existing.includes("pre-commit:") && !args.force) {
+        const appended = `${existing.trimEnd()}
+    forge-ts-check:
+      run: npx forge-ts check
+`;
+        await writeFile2(lefthookPath, appended, "utf8");
+        writtenFiles.push(relativePath);
+      } else {
+        const appended = `${existing.trimEnd()}
+
+${LEFTHOOK_BLOCK}`;
+        await writeFile2(lefthookPath, appended, "utf8");
+        writtenFiles.push(relativePath);
+      }
+    } else {
+      await writeFile2(lefthookPath, LEFTHOOK_BLOCK, "utf8");
+      writtenFiles.push(relativePath);
+    }
+    instructions.push("Lefthook pre-commit hook configured to run forge-ts check.");
+  }
+  const data = {
+    success: true,
+    hookManager,
+    summary: {
+      filesWritten: writtenFiles.length,
+      filesSkipped: skippedFiles.length
+    },
+    files: writtenFiles,
+    instructions
+  };
+  return {
+    operation: "init.hooks",
+    success: true,
+    data,
+    warnings: warnings.length > 0 ? warnings : void 0,
+    duration: Date.now() - start
+  };
+}
+function formatInitHooksHuman(result) {
+  const lines = [];
+  const managerName = result.hookManager === "none" ? "husky (default)" : result.hookManager;
+  lines.push(`
+  Configuring git hooks (${managerName})...
+`);
+  for (const file of result.files) {
+    lines.push(`  \u2713 ${file}`);
+  }
+  if (result.summary.filesSkipped > 0) {
+    lines.push(`  (${result.summary.filesSkipped} file(s) skipped \u2014 already configured)`);
+  }
+  if (result.instructions.length > 0) {
+    lines.push("\n  Next steps:");
+    for (const [idx, inst] of result.instructions.entries()) {
+      lines.push(`    ${idx + 1}. ${inst}`);
+    }
+  }
+  lines.push(`
+  ${result.summary.filesWritten} file(s) written.`);
+  return lines.join("\n");
+}
+var initHooksCommand = defineCommand7({
+  meta: {
+    name: "hooks",
+    description: "Scaffold git hook integration (husky/lefthook)"
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root directory"
+    },
+    force: {
+      type: "boolean",
+      description: "Overwrite existing hook files",
+      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 runInitHooks({
+      cwd: args.cwd,
+      force: args.force,
+      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) {
+        const logger = createLogger();
+        const msg = cmd.errors?.[0]?.message ?? "Hook scaffolding failed";
+        logger.error(msg);
+        return "";
+      }
+      return formatInitHooksHuman(data);
+    });
+    process.exit(resolveExitCode(output));
+  }
+});
+
+// src/commands/lock.ts
+import {
+  appendAuditEvent,
+  createLockManifest,
+  loadConfig as loadConfig6,
+  readLockFile,
+  writeLockFile
+} from "@forge-ts/core";
+import { defineCommand as defineCommand8 } from "citty";
+async function runLock(args) {
+  const config = await loadConfig6(args.cwd);
+  const rootDir = config.rootDir;
+  const existingLock = readLockFile(rootDir);
+  const manifest = createLockManifest(config);
+  writeLockFile(rootDir, manifest);
+  appendAuditEvent(rootDir, {
+    timestamp: manifest.lockedAt,
+    event: "config.lock",
+    user: manifest.lockedBy,
+    details: {
+      rules: Object.keys(manifest.config.rules).length,
+      tsconfig: manifest.config.tsconfig !== void 0,
+      biome: manifest.config.biome !== void 0,
+      overwrote: existingLock !== null
+    }
+  });
+  const lockFile = `${rootDir}/.forge-lock.json`;
+  const data = {
+    success: true,
+    lockFile,
+    lockedAt: manifest.lockedAt,
+    lockedBy: manifest.lockedBy,
+    locked: {
+      rules: Object.keys(manifest.config.rules).length,
+      tsconfig: manifest.config.tsconfig !== void 0,
+      biome: manifest.config.biome !== void 0
+    },
+    overwrote: existingLock !== null
+  };
+  return {
+    operation: "lock",
+    success: true,
+    data,
+    duration: 0
+  };
+}
+function formatLockHuman(result) {
+  const lines = [];
+  if (result.overwrote) {
+    lines.push("forge-ts lock: updated existing lock\n");
+  } else {
+    lines.push("forge-ts lock: created .forge-lock.json\n");
+  }
+  lines.push(`  Locked ${result.locked.rules} enforce rule(s)`);
+  if (result.locked.tsconfig) {
+    lines.push("  Locked tsconfig guard settings");
+  }
+  if (result.locked.biome) {
+    lines.push("  Locked biome guard settings");
+  }
+  lines.push(`
+  Locked by: ${result.lockedBy}`);
+  lines.push(`  Locked at: ${result.lockedAt}`);
+  lines.push(`
+  To modify locked settings, run: forge-ts unlock --reason="..."`);
+  return lines.join("\n");
+}
+var lockCommand = defineCommand8({
+  meta: {
+    name: "lock",
+    description: "Lock current config to prevent silent weakening"
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root directory"
+    },
+    json: {
+      type: "boolean",
+      description: "Output as LAFS JSON envelope (agent-friendly)",
+      default: false
+    },
+    human: {
+      type: "boolean",
+      description: "Output as formatted text (default for TTY)",
+      default: false
+    },
+    quiet: {
+      type: "boolean",
+      description: "Suppress non-essential output",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const output = await runLock({ cwd: args.cwd });
+    const flags = {
+      json: args.json,
+      human: args.human,
+      quiet: args.quiet
+    };
+    emitResult(output, flags, (data) => formatLockHuman(data));
+    process.exit(resolveExitCode(output));
+  }
+});
+
+// src/commands/prepublish.ts
+import { defineCommand as defineCommand9 } from "citty";
+async function runPrepublish(args) {
+  const start = Date.now();
+  const allErrors = [];
+  const checkOutput = await runCheck({
+    cwd: args.cwd,
+    strict: args.strict,
+    mvi: args.mvi
+  });
+  const checkDuration = checkOutput.duration ?? 0;
+  if (!checkOutput.success) {
+    const data2 = {
+      success: false,
+      summary: {
+        steps: 1,
+        passed: 0,
+        failed: 1,
+        duration: Date.now() - start
+      },
+      check: {
+        success: false,
+        errors: checkOutput.data.summary.errors,
+        warnings: checkOutput.data.summary.warnings,
+        duration: checkDuration
+      },
+      skippedReason: "Check failed \u2014 build step skipped."
+    };
+    if (checkOutput.errors) {
+      allErrors.push(...checkOutput.errors);
+    }
+    return {
+      operation: "prepublish",
+      success: false,
+      data: data2,
+      errors: allErrors.length > 0 ? allErrors : void 0,
+      duration: Date.now() - start
+    };
+  }
+  const buildOutput = await runBuild({
+    cwd: args.cwd,
+    mvi: args.mvi
+  });
+  const buildDuration = buildOutput.duration ?? 0;
+  const buildSuccess = buildOutput.success;
+  const overallSuccess = buildSuccess;
+  if (buildOutput.errors) {
+    allErrors.push(...buildOutput.errors);
+  }
+  const data = {
+    success: overallSuccess,
+    summary: {
+      steps: 2,
+      passed: (checkOutput.success ? 1 : 0) + (buildSuccess ? 1 : 0),
+      failed: (checkOutput.success ? 0 : 1) + (buildSuccess ? 0 : 1),
+      duration: Date.now() - start
+    },
+    check: {
+      success: checkOutput.success,
+      errors: checkOutput.data.summary.errors,
+      warnings: checkOutput.data.summary.warnings,
+      duration: checkDuration
+    },
+    build: {
+      success: buildSuccess,
+      steps: buildOutput.data.summary.steps,
+      succeeded: buildOutput.data.summary.succeeded,
+      failed: buildOutput.data.summary.failed,
+      duration: buildDuration
+    }
+  };
+  return {
+    operation: "prepublish",
+    success: overallSuccess,
+    data,
+    errors: allErrors.length > 0 ? allErrors : void 0,
+    duration: Date.now() - start
+  };
+}
+function formatPrepublishHuman(result) {
+  const lines = [];
+  lines.push(`
+  forge-ts prepublish: ${result.success ? "PASSED" : "FAILED"}
+`);
+  const checkIcon = result.check.success ? "\u2713" : "\u2717";
+  lines.push(
+    `  ${checkIcon} check: ${result.check.errors} error(s), ${result.check.warnings} warning(s) (${result.check.duration}ms)`
+  );
+  if (result.build) {
+    const buildIcon = result.build.success ? "\u2713" : "\u2717";
+    lines.push(
+      `  ${buildIcon} build: ${result.build.succeeded}/${result.build.steps} steps succeeded (${result.build.duration}ms)`
+    );
+  } else if (result.skippedReason) {
+    lines.push(`  - build: skipped (${result.skippedReason})`);
+  }
+  lines.push(
+    `
+  ${result.summary.passed}/${result.summary.steps} steps passed in ${result.summary.duration}ms`
+  );
+  if (!result.success) {
+    lines.push("\n  Publish blocked. Fix the above issues and re-run forge-ts prepublish.");
+  }
+  return lines.join("\n");
+}
+var prepublishCommand = defineCommand9({
+  meta: {
+    name: "prepublish",
+    description: "Safety gate: check + build before npm publish"
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root directory"
+    },
+    strict: {
+      type: "boolean",
+      description: "Treat warnings as errors during check",
+      default: false
+    },
+    json: {
+      type: "boolean",
+      description: "Output as LAFS JSON envelope (agent-friendly)",
+      default: false
+    },
+    human: {
+      type: "boolean",
+      description: "Output as formatted text (default for TTY)",
+      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 runPrepublish({
+      cwd: args.cwd,
+      strict: args.strict,
+      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) {
+        const logger = createLogger();
+        logger.error("Prepublish gate failed");
+      }
+      return formatPrepublishHuman(data);
+    });
+    process.exit(resolveExitCode(output));
+  }
+});
+
+// src/commands/test.ts
+import { loadConfig as loadConfig7 } from "@forge-ts/core";
+import { doctest } from "@forge-ts/doctest";
+import { defineCommand as defineCommand10 } from "citty";
+async function runTest(args) {
+  const config = await loadConfig7(args.cwd);
+  const result = await doctest(config);
+  const mviLevel = args.mvi ?? "standard";
+  const failCount = result.errors.length;
   const totalSymbols = result.symbols.length;
   const passCount = totalSymbols - failCount > 0 ? totalSymbols - failCount : 0;
   const summary = {
@@ -974,7 +1747,7 @@ async function runTest(args) {
     duration: result.duration
   };
 }
-var testCommand = defineCommand5({
+var testCommand = defineCommand10({
   meta: {
     name: "test",
     description: "Run @example blocks as doctests"
@@ -1027,10 +1800,155 @@ var testCommand = defineCommand5({
   }
 });
 
+// src/commands/unlock.ts
+import {
+  appendAuditEvent as appendAuditEvent2,
+  getCurrentUser,
+  loadConfig as loadConfig8,
+  readLockFile as readLockFile2,
+  removeLockFile
+} from "@forge-ts/core";
+import { defineCommand as defineCommand11 } from "citty";
+async function runUnlock(args) {
+  const config = await loadConfig8(args.cwd);
+  const rootDir = config.rootDir;
+  const existingLock = readLockFile2(rootDir);
+  if (!existingLock) {
+    return {
+      operation: "unlock",
+      success: false,
+      data: {
+        success: false,
+        reason: args.reason,
+        previousLockedBy: null,
+        previousLockedAt: null
+      },
+      errors: [
+        {
+          code: "FORGE_NO_LOCK",
+          message: "No .forge-lock.json found. Nothing to unlock."
+        }
+      ],
+      duration: 0
+    };
+  }
+  const removed = removeLockFile(rootDir);
+  if (!removed) {
+    return {
+      operation: "unlock",
+      success: false,
+      data: {
+        success: false,
+        reason: args.reason,
+        previousLockedBy: existingLock.lockedBy,
+        previousLockedAt: existingLock.lockedAt
+      },
+      errors: [
+        {
+          code: "FORGE_UNLOCK_FAILED",
+          message: "Failed to remove .forge-lock.json. Check file permissions."
+        }
+      ],
+      duration: 0
+    };
+  }
+  appendAuditEvent2(rootDir, {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    event: "config.unlock",
+    user: getCurrentUser(),
+    reason: args.reason,
+    details: {
+      previousLockedBy: existingLock.lockedBy,
+      previousLockedAt: existingLock.lockedAt
+    }
+  });
+  return {
+    operation: "unlock",
+    success: true,
+    data: {
+      success: true,
+      reason: args.reason,
+      previousLockedBy: existingLock.lockedBy,
+      previousLockedAt: existingLock.lockedAt
+    },
+    duration: 0
+  };
+}
+function formatUnlockHuman(result) {
+  const lines = [];
+  if (!result.success) {
+    lines.push("forge-ts unlock: FAILED\n");
+    lines.push("  No .forge-lock.json found. Nothing to unlock.");
+    return lines.join("\n");
+  }
+  lines.push("forge-ts unlock: removed .forge-lock.json\n");
+  lines.push(`  Reason: ${result.reason}`);
+  if (result.previousLockedBy) {
+    lines.push(`  Previously locked by: ${result.previousLockedBy}`);
+  }
+  if (result.previousLockedAt) {
+    lines.push(`  Previously locked at: ${result.previousLockedAt}`);
+  }
+  lines.push("\n  Config settings can now be modified freely.");
+  lines.push("  Run `forge-ts lock` to re-lock after changes.");
+  return lines.join("\n");
+}
+var unlockCommand = defineCommand11({
+  meta: {
+    name: "unlock",
+    description: "Remove config lock (requires --reason)"
+  },
+  args: {
+    cwd: {
+      type: "string",
+      description: "Project root directory"
+    },
+    reason: {
+      type: "string",
+      description: "Mandatory reason for unlocking (audit trail)",
+      required: true
+    },
+    json: {
+      type: "boolean",
+      description: "Output as LAFS JSON envelope (agent-friendly)",
+      default: false
+    },
+    human: {
+      type: "boolean",
+      description: "Output as formatted text (default for TTY)",
+      default: false
+    },
+    quiet: {
+      type: "boolean",
+      description: "Suppress non-essential output",
+      default: false
+    }
+  },
+  async run({ args }) {
+    if (!args.reason) {
+      console.error(
+        "[forge-ts] error: --reason is required. Provide a reason for unlocking the config."
+      );
+      process.exit(1);
+    }
+    const output = await runUnlock({
+      cwd: args.cwd,
+      reason: args.reason
+    });
+    const flags = {
+      json: args.json,
+      human: args.human,
+      quiet: args.quiet
+    };
+    emitResult(output, flags, (data) => formatUnlockHuman(data));
+    process.exit(resolveExitCode(output));
+  }
+});
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
-var docsCommand = defineCommand6({
+var docsCommand = defineCommand12({
   meta: {
     name: "docs",
     description: "Documentation site management"
@@ -1040,7 +1958,17 @@ var docsCommand = defineCommand6({
     dev: docsDevCommand
   }
 });
-var main = defineCommand6({
+var initCommand2 = defineCommand12({
+  meta: {
+    name: "init",
+    description: "Scaffold project artefacts"
+  },
+  subCommands: {
+    docs: initDocsCommand,
+    hooks: initHooksCommand
+  }
+});
+var main = defineCommand12({
   meta: {
     name: "forge-ts",
     version: pkg.version,
@@ -1050,19 +1978,37 @@ var main = defineCommand6({
     check: checkCommand,
     test: testCommand,
     build: buildCommand,
-    docs: docsCommand
+    docs: docsCommand,
+    init: initCommand2,
+    lock: lockCommand,
+    unlock: unlockCommand,
+    bypass: bypassCommand,
+    audit: auditCommand,
+    prepublish: prepublishCommand
   }
 });
 runMain(main);
 export {
+  auditCommand,
   buildCommand,
+  bypassCommand,
   checkCommand,
   createLogger,
   docsDevCommand,
   emitResult,
   initDocsCommand,
+  initHooksCommand,
+  lockCommand,
+  prepublishCommand,
   resolveExitCode,
+  runBypassCreate,
+  runBypassStatus,
   runDocsDev,
-  testCommand
+  runInitHooks,
+  runLock,
+  runPrepublish,
+  runUnlock,
+  testCommand,
+  unlockCommand
 };
 //# sourceMappingURL=index.js.map