@forge-ts/cli 0.8.0 → 0.13.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as citty from 'citty';
+import { AuditEvent, BypassRecord } from '@forge-ts/core';
 import { SSGTarget } from '@forge-ts/gen';
 
 /**
@@ -93,6 +94,54 @@ declare function emitResult<T>(output: CommandOutput<T>, flags: OutputFlags, hum
  */
 declare function resolveExitCode(output: CommandOutput<unknown>): number;
 
+/**
+ * Typed result for the `audit` command.
+ *
+ * @public
+ */
+interface AuditResult {
+    /** Whether the audit log was read successfully. */
+    success: boolean;
+    /** Number of events returned. */
+    count: number;
+    /** The audit events, newest first. */
+    events: AuditEvent[];
+}
+/**
+ * Citty command definition for `forge-ts audit`.
+ *
+ * @public
+ */
+declare const auditCommand: citty.CommandDef<{
+    readonly cwd: {
+        readonly type: "string";
+        readonly description: "Project root directory";
+    };
+    readonly limit: {
+        readonly type: "string";
+        readonly description: "Maximum events to display (default: 20)";
+    };
+    readonly type: {
+        readonly type: "string";
+        readonly description: "Filter by event type (config.lock, config.unlock, config.drift, bypass.create, bypass.expire, rule.change)";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output as LAFS JSON envelope (agent-friendly)";
+        readonly default: false;
+    };
+    readonly human: {
+        readonly type: "boolean";
+        readonly description: "Output as formatted text (default for TTY)";
+        readonly default: false;
+    };
+    readonly quiet: {
+        readonly type: "boolean";
+        readonly description: "Suppress non-essential output";
+        readonly default: false;
+    };
+}>;
+
 /**
  * A single step in the build pipeline.
  * @public
@@ -177,6 +226,113 @@ declare const buildCommand: citty.CommandDef<{
     };
 }>;
 
+/**
+ * Typed result for the `bypass` command when creating a bypass.
+ * @public
+ */
+interface BypassCreateResult {
+    /** Whether the bypass was successfully created. */
+    success: boolean;
+    /** The bypass record that was created. */
+    bypass: BypassRecord;
+    /** Number of remaining bypass slots for today after creation. */
+    remainingBudget: number;
+    /** The configured daily budget. */
+    dailyBudget: number;
+}
+/**
+ * Typed result for the `bypass --status` command.
+ * @public
+ */
+interface BypassStatusResult {
+    /** Always true for status queries. */
+    success: boolean;
+    /** Active (non-expired) bypass records. */
+    activeBypasses: BypassRecord[];
+    /** Number of remaining bypass slots for today. */
+    remainingBudget: number;
+    /** The configured daily budget. */
+    dailyBudget: number;
+    /** Number of expired bypasses that were cleaned up. */
+    expiredRemoved: number;
+}
+/**
+ * Runs the bypass creation: creates a new bypass record with budget enforcement.
+ *
+ * @param args - CLI arguments for the bypass command.
+ * @returns A typed `CommandOutput<BypassCreateResult>`.
+ * @example
+ * ```typescript
+ * import { runBypassCreate } from "@forge-ts/cli/commands/bypass";
+ * const output = await runBypassCreate({
+ *   cwd: process.cwd(),
+ *   reason: "hotfix for release",
+ *   rule: "E009",
+ * });
+ * console.log(output.data.remainingBudget);
+ * ```
+ * @public
+ */
+declare function runBypassCreate(args: {
+    cwd?: string;
+    reason: string;
+    rule?: string;
+}): Promise<CommandOutput<BypassCreateResult>>;
+/**
+ * Runs the bypass status query: shows active bypasses and remaining budget.
+ *
+ * @param args - CLI arguments for the bypass status command.
+ * @returns A typed `CommandOutput<BypassStatusResult>`.
+ * @example
+ * ```typescript
+ * import { runBypassStatus } from "@forge-ts/cli/commands/bypass";
+ * const output = await runBypassStatus({ cwd: process.cwd() });
+ * console.log(output.data.activeBypasses.length);
+ * ```
+ * @public
+ */
+declare function runBypassStatus(args: {
+    cwd?: string;
+}): Promise<CommandOutput<BypassStatusResult>>;
+/**
+ * Citty command definition for `forge-ts bypass`.
+ * @public
+ */
+declare const bypassCommand: citty.CommandDef<{
+    readonly cwd: {
+        readonly type: "string";
+        readonly description: "Project root directory";
+    };
+    readonly reason: {
+        readonly type: "string";
+        readonly description: "Mandatory justification for bypassing rules";
+    };
+    readonly rule: {
+        readonly type: "string";
+        readonly description: "Specific rule code to bypass (e.g., \"E009\"). Defaults to \"all\"";
+    };
+    readonly status: {
+        readonly type: "boolean";
+        readonly description: "Show active bypasses and remaining budget";
+        readonly default: false;
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output as LAFS JSON envelope (agent-friendly)";
+        readonly default: false;
+    };
+    readonly human: {
+        readonly type: "boolean";
+        readonly description: "Output as formatted text (default for TTY)";
+        readonly default: false;
+    };
+    readonly quiet: {
+        readonly type: "boolean";
+        readonly description: "Suppress non-essential output";
+        readonly default: false;
+    };
+}>;
+
 /**
  * A single error entry within a file group.
  * @public
@@ -504,6 +660,305 @@ declare const initDocsCommand: citty.CommandDef<{
     };
 }>;
 
+/**
+ * Detected hook manager in the project.
+ * @public
+ */
+type HookManager = "husky" | "lefthook" | "none";
+/**
+ * Result of the `init hooks` command.
+ *
+ * @example
+ * ```typescript
+ * import { runInitHooks } from "@forge-ts/cli/commands/init-hooks";
+ * const output = await runInitHooks({ cwd: process.cwd() });
+ * console.log(output.data.hookManager); // "husky" | "lefthook" | "none"
+ * ```
+ * @public
+ */
+interface InitHooksResult {
+    /** Whether the hook scaffolding succeeded. */
+    success: boolean;
+    /** The detected or chosen hook manager. */
+    hookManager: HookManager;
+    /** Summary of what was created. */
+    summary: {
+        /** Number of files written or updated. */
+        filesWritten: number;
+        /** Number of files skipped (already existed). */
+        filesSkipped: number;
+    };
+    /** Relative paths of all files written. */
+    files: string[];
+    /** Post-scaffold instructions for the user. */
+    instructions: string[];
+}
+/**
+ * Arguments for the `init hooks` command.
+ * @internal
+ */
+interface InitHooksArgs {
+    /** Project root directory (default: cwd). */
+    cwd?: string;
+    /** Force overwrite existing hook files. */
+    force?: boolean;
+    /** MVI verbosity level for structured output. */
+    mvi?: string;
+}
+/**
+ * Scaffolds git hook integration for the project.
+ *
+ * Detects the hook manager (husky or lefthook), generates appropriate
+ * hook files, and reports what was written.
+ *
+ * @param args - CLI arguments for the init hooks command.
+ * @returns A typed `CommandOutput<InitHooksResult>`.
+ * @example
+ * ```typescript
+ * import { runInitHooks } from "@forge-ts/cli/commands/init-hooks";
+ * const output = await runInitHooks({ cwd: "/my/project" });
+ * console.log(output.data.files); // [".husky/pre-commit"]
+ * ```
+ * @public
+ */
+declare function runInitHooks(args: InitHooksArgs): Promise<CommandOutput<InitHooksResult>>;
+/**
+ * Citty command definition for `forge-ts init hooks`.
+ *
+ * Scaffolds git hook integration for the project by detecting the
+ * hook manager (husky or lefthook) and generating pre-commit hooks.
+ *
+ * @example
+ * ```typescript
+ * import { initHooksCommand } from "@forge-ts/cli/commands/init-hooks";
+ * // Registered as a subcommand of `forge-ts init`
+ * ```
+ * @public
+ */
+declare const initHooksCommand: citty.CommandDef<{
+    readonly cwd: {
+        readonly type: "string";
+        readonly description: "Project root directory";
+    };
+    readonly force: {
+        readonly type: "boolean";
+        readonly description: "Overwrite existing hook files";
+        readonly default: false;
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output as LAFS JSON envelope";
+        readonly default: false;
+    };
+    readonly human: {
+        readonly type: "boolean";
+        readonly description: "Output as formatted text";
+        readonly default: false;
+    };
+    readonly quiet: {
+        readonly type: "boolean";
+        readonly description: "Suppress non-essential output";
+        readonly default: false;
+    };
+    readonly mvi: {
+        readonly type: "string";
+        readonly description: "MVI verbosity level: minimal, standard, full";
+    };
+}>;
+
+/**
+ * Typed result for the `lock` command.
+ * @public
+ */
+interface LockResult {
+    /** Whether the lock was successfully created. */
+    success: boolean;
+    /** Path to the lock file that was written. */
+    lockFile: string;
+    /** ISO-8601 timestamp when the lock was created. */
+    lockedAt: string;
+    /** Identifier of who created the lock. */
+    lockedBy: string;
+    /** Summary of what was locked. */
+    locked: {
+        /** Number of enforce rules captured. */
+        rules: number;
+        /** Whether tsconfig guard settings were captured. */
+        tsconfig: boolean;
+        /** Whether biome guard settings were captured. */
+        biome: boolean;
+    };
+    /** Whether a previous lock file was overwritten. */
+    overwrote: boolean;
+}
+/**
+ * Runs the lock command: reads current config and creates `.forge-lock.json`.
+ *
+ * @param args - CLI arguments for the lock command.
+ * @returns A typed `CommandOutput<LockResult>`.
+ * @example
+ * ```typescript
+ * import { runLock } from "@forge-ts/cli/commands/lock";
+ * const output = await runLock({ cwd: process.cwd() });
+ * console.log(output.data.locked.rules); // number of rules locked
+ * ```
+ * @public
+ */
+declare function runLock(args: {
+    cwd?: string;
+}): Promise<CommandOutput<LockResult>>;
+/**
+ * Citty command definition for `forge-ts lock`.
+ * @public
+ */
+declare const lockCommand: citty.CommandDef<{
+    readonly cwd: {
+        readonly type: "string";
+        readonly description: "Project root directory";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output as LAFS JSON envelope (agent-friendly)";
+        readonly default: false;
+    };
+    readonly human: {
+        readonly type: "boolean";
+        readonly description: "Output as formatted text (default for TTY)";
+        readonly default: false;
+    };
+    readonly quiet: {
+        readonly type: "boolean";
+        readonly description: "Suppress non-essential output";
+        readonly default: false;
+    };
+}>;
+
+/**
+ * Typed result for the `prepublish` command.
+ *
+ * @example
+ * ```typescript
+ * import { runPrepublish } from "@forge-ts/cli/commands/prepublish";
+ * const output = await runPrepublish({ cwd: process.cwd() });
+ * console.log(output.data.check.success); // true if check passed
+ * console.log(output.data.build?.success); // true if build passed
+ * ```
+ * @public
+ */
+interface PrepublishResult {
+    /** Whether both check and build passed. */
+    success: boolean;
+    /** Summary of the prepublish pipeline. */
+    summary: {
+        /** Number of pipeline steps run. */
+        steps: number;
+        /** Number of steps that passed. */
+        passed: number;
+        /** Number of steps that failed. */
+        failed: number;
+        /** Wall-clock duration of the entire pipeline in milliseconds. */
+        duration: number;
+    };
+    /** Result of the check step. */
+    check: {
+        /** Whether the check passed. */
+        success: boolean;
+        /** Error count from the check. */
+        errors: number;
+        /** Warning count from the check. */
+        warnings: number;
+        /** Duration of the check step in milliseconds. */
+        duration: number;
+    };
+    /** Result of the build step (absent if check failed and build was skipped). */
+    build?: {
+        /** Whether the build passed. */
+        success: boolean;
+        /** Number of build pipeline steps. */
+        steps: number;
+        /** Number of build steps that succeeded. */
+        succeeded: number;
+        /** Number of build steps that failed. */
+        failed: number;
+        /** Duration of the build step in milliseconds. */
+        duration: number;
+    };
+    /** If check failed, the reason build was skipped. */
+    skippedReason?: string;
+}
+/**
+ * Arguments for the `prepublish` command.
+ * @internal
+ */
+interface PrepublishArgs {
+    /** Project root directory (default: cwd). */
+    cwd?: string;
+    /** Treat warnings as errors during the check step. */
+    strict?: boolean;
+    /** MVI verbosity level for structured output. */
+    mvi?: string;
+}
+/**
+ * Runs the prepublish safety gate: check then build.
+ *
+ * If the check step fails, the build step is skipped entirely.
+ * Both steps use the same project root (cwd).
+ *
+ * @param args - CLI arguments for the prepublish command.
+ * @returns A typed `CommandOutput<PrepublishResult>`.
+ * @example
+ * ```typescript
+ * import { runPrepublish } from "@forge-ts/cli/commands/prepublish";
+ * const output = await runPrepublish({ cwd: process.cwd() });
+ * if (!output.success) process.exit(1);
+ * ```
+ * @public
+ */
+declare function runPrepublish(args: PrepublishArgs): Promise<CommandOutput<PrepublishResult>>;
+/**
+ * Citty command definition for `forge-ts prepublish`.
+ *
+ * Runs check then build as a publish safety gate. Add to package.json as:
+ * `"prepublishOnly": "forge-ts prepublish"`
+ *
+ * @example
+ * ```typescript
+ * import { prepublishCommand } from "@forge-ts/cli/commands/prepublish";
+ * // Registered as `forge-ts prepublish`
+ * ```
+ * @public
+ */
+declare const prepublishCommand: citty.CommandDef<{
+    readonly cwd: {
+        readonly type: "string";
+        readonly description: "Project root directory";
+    };
+    readonly strict: {
+        readonly type: "boolean";
+        readonly description: "Treat warnings as errors during check";
+        readonly default: false;
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output as LAFS JSON envelope (agent-friendly)";
+        readonly default: false;
+    };
+    readonly human: {
+        readonly type: "boolean";
+        readonly description: "Output as formatted text (default for TTY)";
+        readonly default: false;
+    };
+    readonly quiet: {
+        readonly type: "boolean";
+        readonly description: "Suppress non-essential output";
+        readonly default: false;
+    };
+    readonly mvi: {
+        readonly type: "string";
+        readonly description: "MVI verbosity level: minimal, standard, full";
+    };
+}>;
+
 /**
  * A single test failure entry, included at standard and full MVI levels.
  * @public
@@ -569,6 +1024,68 @@ declare const testCommand: citty.CommandDef<{
     };
 }>;
 
+/**
+ * Typed result for the `unlock` command.
+ * @public
+ */
+interface UnlockResult {
+    /** Whether the unlock was successful. */
+    success: boolean;
+    /** The reason provided for unlocking. */
+    reason: string;
+    /** Who originally locked the config, if known. */
+    previousLockedBy: string | null;
+    /** When the config was originally locked, if known. */
+    previousLockedAt: string | null;
+}
+/**
+ * Runs the unlock command: removes `.forge-lock.json` with a mandatory reason.
+ *
+ * @param args - CLI arguments for the unlock command.
+ * @returns A typed `CommandOutput<UnlockResult>`.
+ * @example
+ * ```typescript
+ * import { runUnlock } from "@forge-ts/cli/commands/unlock";
+ * const output = await runUnlock({ cwd: process.cwd(), reason: "Relaxing rules for migration" });
+ * console.log(output.data.success); // true
+ * ```
+ * @public
+ */
+declare function runUnlock(args: {
+    cwd?: string;
+    reason: string;
+}): Promise<CommandOutput<UnlockResult>>;
+/**
+ * Citty command definition for `forge-ts unlock`.
+ * @public
+ */
+declare const unlockCommand: citty.CommandDef<{
+    readonly cwd: {
+        readonly type: "string";
+        readonly description: "Project root directory";
+    };
+    readonly reason: {
+        readonly type: "string";
+        readonly description: "Mandatory reason for unlocking (audit trail)";
+        readonly required: true;
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output as LAFS JSON envelope (agent-friendly)";
+        readonly default: false;
+    };
+    readonly human: {
+        readonly type: "boolean";
+        readonly description: "Output as formatted text (default for TTY)";
+        readonly default: false;
+    };
+    readonly quiet: {
+        readonly type: "boolean";
+        readonly description: "Suppress non-essential output";
+        readonly default: false;
+    };
+}>;
+
 /**
  * Simple TTY-aware logger for forge-ts CLI output.
  *
@@ -611,4 +1128,4 @@ declare function createLogger(options?: {
     colors?: boolean;
 }): Logger;
 
-export { type BuildResult, type BuildStep, type CheckFileError, type CheckFileGroup, type CheckFileWarning, type CheckPage, type CheckResult, type CheckRuleCount, type CheckTriage, type CommandOutput, type ForgeCliError, type ForgeCliWarning, type InitDocsResult, type Logger, type OutputFlags, type TestFailure, type TestResult, buildCommand, checkCommand, createLogger, docsDevCommand, emitResult, initDocsCommand, resolveExitCode, runDocsDev, testCommand };
+export { type AuditResult, type BuildResult, type BuildStep, type BypassCreateResult, type BypassStatusResult, type CheckFileError, type CheckFileGroup, type CheckFileWarning, type CheckPage, type CheckResult, type CheckRuleCount, type CheckTriage, type CommandOutput, type ForgeCliError, type ForgeCliWarning, type HookManager, type InitDocsResult, type InitHooksResult, type LockResult, type Logger, type OutputFlags, type PrepublishResult, type TestFailure, type TestResult, type UnlockResult, auditCommand, buildCommand, bypassCommand, checkCommand, createLogger, docsDevCommand, emitResult, initDocsCommand, initHooksCommand, lockCommand, prepublishCommand, resolveExitCode, runBypassCreate, runBypassStatus, runDocsDev, runInitHooks, runLock, runPrepublish, runUnlock, testCommand, unlockCommand };