@forge-ts/cli 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as citty from 'citty';
 import { AuditEvent, BypassRecord } from '@forge-ts/core';
 import { SSGTarget } from '@forge-ts/gen';
+import * as consola from 'consola';
 
 /**
  * Central output layer for forge-ts CLI.
@@ -578,6 +579,134 @@ declare const docsDevCommand: citty.CommandDef<{
     };
 }>;
 
+/**
+ * Status of a single doctor check.
+ * @public
+ */
+type DoctorCheckStatus = "pass" | "warn" | "error" | "info";
+/**
+ * Result of a single doctor check.
+ *
+ * @public
+ */
+interface DoctorCheckResult {
+    /** Name of the check. */
+    name: string;
+    /** Status of the check. */
+    status: DoctorCheckStatus;
+    /** Human-readable message. */
+    message: string;
+    /** Whether this issue can be auto-fixed with --fix. */
+    fixable: boolean;
+}
+/**
+ * Result of the `doctor` command.
+ *
+ * @example
+ * ```typescript
+ * import { runDoctor } from "@forge-ts/cli/commands/doctor";
+ * const output = await runDoctor({ cwd: process.cwd() });
+ * console.log(output.data.summary.passed); // number of passed checks
+ * ```
+ * @public
+ */
+interface DoctorResult {
+    /** Whether all checks passed without errors. */
+    success: boolean;
+    /** Individual check results. */
+    checks: DoctorCheckResult[];
+    /** Summary counts. */
+    summary: {
+        passed: number;
+        warnings: number;
+        errors: number;
+        info: number;
+    };
+    /** Files that were fixed (only populated when --fix is used). */
+    fixed: string[];
+}
+/**
+ * Arguments for the `doctor` command.
+ * @internal
+ */
+interface DoctorArgs {
+    /** Project root directory (default: cwd). */
+    cwd?: string;
+    /** Auto-fix resolvable issues. */
+    fix?: boolean;
+    /** MVI verbosity level for structured output. */
+    mvi?: string;
+}
+/**
+ * Runs the doctor integrity check flow.
+ *
+ * Checks:
+ * 1. forge-ts.config.ts — exists and loadable
+ * 2. tsdoc.json — exists and extends @forge-ts/core/tsdoc-preset
+ * 3. @forge-ts/core — installed in node_modules
+ * 4. TypeScript — installed
+ * 5. tsconfig.json — exists and has strict mode
+ * 6. biome.json — exists (informational)
+ * 7. .forge-lock.json — exists, valid, matches config
+ * 8. .forge-audit.jsonl — exists and event count
+ * 9. .forge-bypass.json — exists and active bypasses
+ * 10. Git hooks — forge-ts check in pre-commit
+ *
+ * @param args - CLI arguments for the doctor command.
+ * @returns A typed `CommandOutput<DoctorResult>`.
+ * @example
+ * ```typescript
+ * import { runDoctor } from "@forge-ts/cli/commands/doctor";
+ * const output = await runDoctor({ cwd: process.cwd(), fix: false });
+ * console.log(output.data.summary); // { passed: 7, warnings: 2, errors: 1, info: 0 }
+ * ```
+ * @public
+ */
+declare function runDoctor(args: DoctorArgs): Promise<CommandOutput<DoctorResult>>;
+/**
+ * Citty command definition for `forge-ts doctor`.
+ *
+ * Performs project integrity checks and optionally auto-fixes
+ * resolvable issues with `--fix`.
+ *
+ * @example
+ * ```typescript
+ * import { doctorCommand } from "@forge-ts/cli/commands/doctor";
+ * // Registered as a top-level subcommand of `forge-ts`
+ * ```
+ * @public
+ */
+declare const doctorCommand: citty.CommandDef<{
+    readonly cwd: {
+        readonly type: "string";
+        readonly description: "Project root directory";
+    };
+    readonly fix: {
+        readonly type: "boolean";
+        readonly description: "Auto-fix resolvable issues";
+        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";
+    };
+}>;
+
 /**
  * Result of the `init docs` command.
  *
@@ -766,6 +895,123 @@ declare const initHooksCommand: citty.CommandDef<{
     };
 }>;
 
+/**
+ * Detected project environment from Step 1 of the init flow.
+ *
+ * @public
+ */
+interface InitProjectEnvironment {
+    /** Whether package.json exists. */
+    packageJsonExists: boolean;
+    /** Whether tsconfig.json exists. */
+    tsconfigExists: boolean;
+    /** Whether biome.json or biome.jsonc exists. */
+    biomeDetected: boolean;
+    /** TypeScript version from dependencies, or null if not found. */
+    typescriptVersion: string | null;
+    /** Detected hook manager. */
+    hookManager: "husky" | "lefthook" | "none";
+    /** Whether the project is a monorepo. */
+    monorepo: boolean;
+    /** Monorepo type if detected. */
+    monorepoType: "pnpm" | "npm/yarn" | null;
+}
+/**
+ * Result of the `init` (project setup) command.
+ *
+ * @example
+ * ```typescript
+ * import { runInitProject } from "@forge-ts/cli/commands/init-project";
+ * const output = await runInitProject({ cwd: process.cwd() });
+ * console.log(output.data.created); // list of created files
+ * ```
+ * @public
+ */
+interface InitProjectResult {
+    /** Whether the init succeeded. */
+    success: boolean;
+    /** Files that were created. */
+    created: string[];
+    /** Files that already existed and were skipped. */
+    skipped: string[];
+    /** Warning messages collected during init. */
+    warnings: string[];
+    /** Detected project environment. */
+    environment: InitProjectEnvironment;
+    /** Next steps for the user. */
+    nextSteps: string[];
+}
+/**
+ * Arguments for the `init` (project setup) command.
+ * @internal
+ */
+interface InitProjectArgs {
+    /** Project root directory (default: cwd). */
+    cwd?: string;
+    /** MVI verbosity level for structured output. */
+    mvi?: string;
+}
+/**
+ * Runs the full project init flow.
+ *
+ * Steps:
+ * 1. Detect project environment
+ * 2. Write forge-ts.config.ts (if not exists)
+ * 3. Write tsdoc.json (if not exists)
+ * 4. Validate tsconfig.json strictness
+ * 5. Validate package.json
+ * 6. Report summary
+ *
+ * @param args - CLI arguments for the init command.
+ * @returns A typed `CommandOutput<InitProjectResult>`.
+ * @example
+ * ```typescript
+ * import { runInitProject } from "@forge-ts/cli/commands/init-project";
+ * const output = await runInitProject({ cwd: process.cwd() });
+ * console.log(output.data.created); // ["forge-ts.config.ts", "tsdoc.json"]
+ * ```
+ * @public
+ */
+declare function runInitProject(args: InitProjectArgs): Promise<CommandOutput<InitProjectResult>>;
+/**
+ * Citty command definition for `forge-ts init` (bare — full project setup).
+ *
+ * Detects the project environment, writes default configuration files,
+ * validates tsconfig/package.json, and reports a summary.
+ *
+ * @example
+ * ```typescript
+ * import { initProjectCommand } from "@forge-ts/cli/commands/init-project";
+ * // Registered as the default handler for `forge-ts init`
+ * ```
+ * @public
+ */
+declare const initProjectCommand: citty.CommandDef<{
+    readonly cwd: {
+        readonly type: "string";
+        readonly description: "Project root directory";
+    };
+    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
@@ -1087,45 +1333,63 @@ declare const unlockCommand: citty.CommandDef<{
 }>;
 
 /**
- * Simple TTY-aware logger for forge-ts CLI output.
+ * Forge-ts branded logger built on consola from the UnJS ecosystem.
  *
- * Uses ANSI escape codes directly — no external colour library.
+ * Provides a singleton logger instance (`forgeLogger`) and a configuration
+ * function (`configureLogger`) that respects CLI flags (`--quiet`, `--json`,
+ * `--verbose`) and TTY detection.
  *
  * @packageDocumentation
  * @internal
  */
 /**
- * A minimal structured logger used throughout the CLI commands.
+ * Pre-configured consola instance branded for forge-ts.
+ *
+ * @example
+ * ```typescript
+ * import { forgeLogger } from "./forge-logger.js";
+ * forgeLogger.info("Checking 42 files...");
+ * forgeLogger.success("All checks passed");
+ * forgeLogger.warn("Deprecated import detected");
+ * forgeLogger.error("Build failed");
+ * forgeLogger.debug("Resolved config from forge-ts.config.ts");
+ * ```
  * @internal
  */
-interface Logger {
-    /** Print an informational message. */
-    info(msg: string): void;
-    /** Print a success message (green ✓ prefix when colours are on). */
-    success(msg: string): void;
-    /** Print a warning message (yellow prefix when colours are on). */
-    warn(msg: string): void;
-    /** Print an error message (red ✗ prefix when colours are on). */
-    error(msg: string): void;
-    /**
-     * Print a build-step line.
-     *
-     * @param label    - Short category label (e.g. "API", "Gen").
-     * @param detail   - Description of what was produced.
-     * @param duration - Optional wall-clock time in milliseconds.
-     */
-    step(label: string, detail: string, duration?: number): void;
+declare const forgeLogger: consola.ConsolaInstance;
+/**
+ * Options for configuring the forge-ts logger at CLI startup.
+ *
+ * @internal
+ */
+interface ForgeLoggerOptions {
+    /** Suppress all consola output (--quiet flag). */
+    quiet?: boolean;
+    /** JSON output mode (--json flag). LAFS handles JSON; suppress consola. */
+    json?: boolean;
+    /** Enable debug-level output (--verbose flag). */
+    verbose?: boolean;
 }
 /**
- * Creates a {@link Logger} instance.
+ * Configures the global {@link forgeLogger} based on CLI flags.
+ *
+ * Call this once at the start of a command's `run()` handler to align
+ * consola's output level with the user's intent:
+ *
+ * - `quiet` or `json` sets level to 0 (silent) so only LAFS output appears.
+ * - `verbose` sets level to 4 (debug) for maximum detail.
+ * - Default level is 3 (info) which covers info, warn, error, and success.
  *
- * @param options - Optional configuration.
- * @param options.colors - Emit ANSI colour codes.  Defaults to `process.stdout.isTTY`.
- * @returns A configured logger.
+ * @param options - Flag-driven configuration.
+ *
+ * @example
+ * ```typescript
+ * import { configureLogger, forgeLogger } from "./forge-logger.js";
+ * configureLogger({ quiet: args.quiet, json: args.json, verbose: args.verbose });
+ * forgeLogger.info("This respects the configured level");
+ * ```
  * @internal
  */
-declare function createLogger(options?: {
-    colors?: boolean;
-}): Logger;
+declare function configureLogger(options: ForgeLoggerOptions): void;
 
-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 };
+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 DoctorCheckResult, type DoctorCheckStatus, type DoctorResult, type ForgeCliError, type ForgeCliWarning, type ForgeLoggerOptions, type HookManager, type InitDocsResult, type InitHooksResult, type InitProjectEnvironment, type InitProjectResult, type LockResult, type OutputFlags, type PrepublishResult, type TestFailure, type TestResult, type UnlockResult, auditCommand, buildCommand, bypassCommand, checkCommand, configureLogger, docsDevCommand, doctorCommand, emitResult, forgeLogger, initDocsCommand, initHooksCommand, initProjectCommand, lockCommand, prepublishCommand, resolveExitCode, runBypassCreate, runBypassStatus, runDocsDev, runDoctor, runInitHooks, runInitProject, runLock, runPrepublish, runUnlock, testCommand, unlockCommand };