@forge-ts/cli 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -521,6 +521,134 @@ declare const checkCommand: 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/tsdoc-config
+ * 3. @forge-ts/tsdoc-config — 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";
+    };
+}>;
+
 /**
  * The `forge-ts docs dev` command — starts a local doc preview server.
  *
@@ -766,6 +894,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
@@ -1128,4 +1373,4 @@ declare function createLogger(options?: {
     colors?: boolean;
 }): Logger;
 
-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 HookManager, type InitDocsResult, type InitHooksResult, type InitProjectEnvironment, type InitProjectResult, type LockResult, type Logger, type OutputFlags, type PrepublishResult, type TestFailure, type TestResult, type UnlockResult, auditCommand, buildCommand, bypassCommand, checkCommand, createLogger, docsDevCommand, doctorCommand, emitResult, initDocsCommand, initHooksCommand, initProjectCommand, lockCommand, prepublishCommand, resolveExitCode, runBypassCreate, runBypassStatus, runDocsDev, runDoctor, runInitHooks, runInitProject, runLock, runPrepublish, runUnlock, testCommand, unlockCommand };