@forge-ts/cli 0.15.0 → 0.16.0

package/dist/chunk-CNINN7IQ.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+// src/forge-logger.ts
+import { createConsola } from "consola";
+var forgeLogger = createConsola({
+  defaults: { tag: "forge-ts" }
+});
+function configureLogger(options) {
+  if (options.quiet) {
+    forgeLogger.level = 0;
+    return;
+  }
+  if (options.json) {
+    forgeLogger.level = 0;
+    return;
+  }
+  if (options.verbose) {
+    forgeLogger.level = 4;
+    return;
+  }
+  forgeLogger.level = 3;
+}
+
+export {
+  forgeLogger,
+  configureLogger
+};
+//# sourceMappingURL=chunk-CNINN7IQ.js.map

package/dist/chunk-CNINN7IQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/forge-logger.ts"],"sourcesContent":["/**\n * Forge-ts branded logger built on consola from the UnJS ecosystem.\n *\n * Provides a singleton logger instance (`forgeLogger`) and a configuration\n * function (`configureLogger`) that respects CLI flags (`--quiet`, `--json`,\n * `--verbose`) and TTY detection.\n *\n * @packageDocumentation\n * @internal\n */\n\nimport { createConsola } from \"consola\";\n\n// ---------------------------------------------------------------------------\n// Singleton logger\n// ---------------------------------------------------------------------------\n\n/**\n * Pre-configured consola instance branded for forge-ts.\n *\n * @example\n * ```typescript\n * import { forgeLogger } from \"./forge-logger.js\";\n * forgeLogger.info(\"Checking 42 files...\");\n * forgeLogger.success(\"All checks passed\");\n * forgeLogger.warn(\"Deprecated import detected\");\n * forgeLogger.error(\"Build failed\");\n * forgeLogger.debug(\"Resolved config from forge-ts.config.ts\");\n * ```\n * @internal\n */\nexport const forgeLogger = createConsola({\n\tdefaults: { tag: \"forge-ts\" },\n});\n\n// ---------------------------------------------------------------------------\n// Configuration\n// ---------------------------------------------------------------------------\n\n/**\n * Options for configuring the forge-ts logger at CLI startup.\n *\n * @internal\n */\nexport interface ForgeLoggerOptions {\n\t/** Suppress all consola output (--quiet flag). */\n\tquiet?: boolean;\n\t/** JSON output mode (--json flag). LAFS handles JSON; suppress consola. */\n\tjson?: boolean;\n\t/** Enable debug-level output (--verbose flag). */\n\tverbose?: boolean;\n}\n\n/**\n * Configures the global {@link forgeLogger} based on CLI flags.\n *\n * Call this once at the start of a command's `run()` handler to align\n * consola's output level with the user's intent:\n *\n * - `quiet` or `json` sets level to 0 (silent) so only LAFS output appears.\n * - `verbose` sets level to 4 (debug) for maximum detail.\n * - Default level is 3 (info) which covers info, warn, error, and success.\n *\n * @param options - Flag-driven configuration.\n *\n * @example\n * ```typescript\n * import { configureLogger, forgeLogger } from \"./forge-logger.js\";\n * configureLogger({ quiet: args.quiet, json: args.json, verbose: args.verbose });\n * forgeLogger.info(\"This respects the configured level\");\n * ```\n * @internal\n */\nexport function configureLogger(options: ForgeLoggerOptions): void {\n\tif (options.quiet) {\n\t\tforgeLogger.level = 0;\n\t\treturn;\n\t}\n\tif (options.json) {\n\t\t// LAFS handles JSON output — suppress consola's informal logging\n\t\tforgeLogger.level = 0;\n\t\treturn;\n\t}\n\tif (options.verbose) {\n\t\tforgeLogger.level = 4; // debug\n\t\treturn;\n\t}\n\t// Default: info level (covers info, warn, error, success)\n\tforgeLogger.level = 3;\n}\n"],"mappings":";;;AAWA,SAAS,qBAAqB;AAoBvB,IAAM,cAAc,cAAc;AAAA,EACxC,UAAU,EAAE,KAAK,WAAW;AAC7B,CAAC;AAwCM,SAAS,gBAAgB,SAAmC;AAClE,MAAI,QAAQ,OAAO;AAClB,gBAAY,QAAQ;AACpB;AAAA,EACD;AACA,MAAI,QAAQ,MAAM;AAEjB,gBAAY,QAAQ;AACpB;AAAA,EACD;AACA,MAAI,QAAQ,SAAS;AACpB,gBAAY,QAAQ;AACpB;AAAA,EACD;AAEA,cAAY,QAAQ;AACrB;","names":[]}

package/dist/{chunk-CINQWGH7.js → chunk-DV33Y4E2.js}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
+import {
+  forgeLogger
+} from "./chunk-CNINN7IQ.js";
 import {
   emitResult,
   resolveExitCode
 } from "./chunk-ZFFY4AQX.js";
-import {
-  createLogger
-} from "./chunk-7UPSAG3L.js";
 
 // src/commands/init-project.ts
 import { existsSync, readFileSync } from "fs";
@@ -103,7 +103,7 @@ export default defineConfig({
 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"]
+    extends: ["@forge-ts/core/tsdoc-preset/tsdoc.json"]
   },
   null,
   "	"
@@ -166,9 +166,7 @@ async function runInitProject(args) {
     const tsconfig = readJsonSafe(tsconfigPath);
     if (tsconfig) {
       if (!tsconfig.compilerOptions || tsconfig.compilerOptions.strict !== true) {
-        warnings.push(
-          "tsconfig.json: 'strict' is not enabled. forge-ts recommends strict mode."
-        );
+        warnings.push("tsconfig.json: 'strict' is not enabled. forge-ts recommends strict mode.");
         cliWarnings.push({
           code: "INIT_TSCONFIG_NOT_STRICT",
           message: "tsconfig.json: 'strict' is not enabled. forge-ts recommends strict mode."
@@ -180,9 +178,7 @@ async function runInitProject(args) {
   const pkg = readJsonSafe(pkgPath);
   if (pkg) {
     if (pkg.type !== "module") {
-      warnings.push(
-        'package.json: missing "type": "module". forge-ts uses ESM.'
-      );
+      warnings.push('package.json: missing "type": "module". forge-ts uses ESM.');
       cliWarnings.push({
         code: "INIT_NO_ESM",
         message: 'package.json: missing "type": "module". forge-ts uses ESM.'
@@ -197,9 +193,7 @@ async function runInitProject(args) {
     }
     const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
     if (!("@forge-ts/cli" in allDeps)) {
-      warnings.push(
-        "package.json: @forge-ts/cli not in devDependencies (running via npx?)."
-      );
+      warnings.push("package.json: @forge-ts/cli not in devDependencies (running via npx?).");
       cliWarnings.push({
         code: "INIT_CLI_NOT_INSTALLED",
         message: "package.json: @forge-ts/cli not in devDependencies (running via npx?)."
@@ -258,12 +252,8 @@ function formatInitProjectHuman(result) {
   const env = result.environment;
   lines.push("");
   lines.push("  Environment:");
-  lines.push(
-    `    TypeScript: ${env.typescriptVersion ?? "not detected"}`
-  );
-  lines.push(
-    `    Biome: ${env.biomeDetected ? "detected" : "not detected"}`
-  );
+  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) {
@@ -325,9 +315,8 @@ var initProjectCommand = defineCommand({
     };
     emitResult(output, flags, (data, cmd) => {
       if (!cmd.success) {
-        const logger = createLogger();
         const msg = cmd.errors?.[0]?.message ?? "Init failed";
-        logger.error(msg);
+        forgeLogger.error(msg);
         return "";
       }
       return formatInitProjectHuman(data);
@@ -341,4 +330,4 @@ export {
   runInitProject,
   initProjectCommand
 };
-//# sourceMappingURL=chunk-CINQWGH7.js.map
+//# sourceMappingURL=chunk-DV33Y4E2.js.map

package/dist/chunk-DV33Y4E2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/init-project.ts"],"sourcesContent":["/**\n * `forge-ts init` command — full project setup.\n *\n * Detects the project environment, writes default config files, validates\n * tsconfig/package.json, and prints a summary with next steps.\n *\n * @packageDocumentation\n * @internal\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { mkdir, writeFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { defineCommand } from \"citty\";\nimport { forgeLogger } from \"../forge-logger.js\";\nimport {\n\ttype CommandOutput,\n\temitResult,\n\ttype ForgeCliError,\n\ttype ForgeCliWarning,\n\ttype OutputFlags,\n\tresolveExitCode,\n} from \"../output.js\";\n\n// ---------------------------------------------------------------------------\n// Public types\n// ---------------------------------------------------------------------------\n\n/**\n * Detected project environment from Step 1 of the init flow.\n *\n * @public\n */\nexport interface InitProjectEnvironment {\n\t/** Whether package.json exists. */\n\tpackageJsonExists: boolean;\n\t/** Whether tsconfig.json exists. */\n\ttsconfigExists: boolean;\n\t/** Whether biome.json or biome.jsonc exists. */\n\tbiomeDetected: boolean;\n\t/** TypeScript version from dependencies, or null if not found. */\n\ttypescriptVersion: string | null;\n\t/** Detected hook manager. */\n\thookManager: \"husky\" | \"lefthook\" | \"none\";\n\t/** Whether the project is a monorepo. */\n\tmonorepo: boolean;\n\t/** Monorepo type if detected. */\n\tmonorepoType: \"pnpm\" | \"npm/yarn\" | null;\n}\n\n/**\n * Result of the `init` (project setup) command.\n *\n * @example\n * ```typescript\n * import { runInitProject } from \"@forge-ts/cli/commands/init-project\";\n * const output = await runInitProject({ cwd: process.cwd() });\n * console.log(output.data.created); // list of created files\n * ```\n * @public\n */\nexport interface InitProjectResult {\n\t/** Whether the init succeeded. */\n\tsuccess: boolean;\n\t/** Files that were created. */\n\tcreated: string[];\n\t/** Files that already existed and were skipped. */\n\tskipped: string[];\n\t/** Warning messages collected during init. */\n\twarnings: string[];\n\t/** Detected project environment. */\n\tenvironment: InitProjectEnvironment;\n\t/** Next steps for the user. */\n\tnextSteps: string[];\n}\n\n/**\n * Arguments for the `init` (project setup) command.\n * @internal\n */\nexport interface InitProjectArgs {\n\t/** Project root directory (default: cwd). */\n\tcwd?: string;\n\t/** MVI verbosity level for structured output. */\n\tmvi?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Reads and parses a package.json file.\n * @internal\n */\ninterface PackageJsonShape {\n\ttype?: string;\n\tengines?: { node?: string };\n\tdependencies?: Record<string, string>;\n\tdevDependencies?: Record<string, string>;\n\tworkspaces?: string[] | { packages: string[] };\n}\n\n/**\n * Safely reads and parses a JSON file.\n * @internal\n */\nfunction readJsonSafe<T>(filePath: string): T | null {\n\tif (!existsSync(filePath)) {\n\t\treturn null;\n\t}\n\ttry {\n\t\tconst raw = readFileSync(filePath, \"utf8\");\n\t\treturn JSON.parse(raw) as T;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// Environment detection\n// ---------------------------------------------------------------------------\n\n/**\n * Detects the project environment by checking for files and dependencies.\n *\n * @param rootDir - Absolute path to the project root.\n * @returns The detected environment.\n * @internal\n */\nexport function detectEnvironment(rootDir: string): InitProjectEnvironment {\n\tconst packageJsonPath = join(rootDir, \"package.json\");\n\tconst tsconfigPath = join(rootDir, \"tsconfig.json\");\n\tconst biomePath = join(rootDir, \"biome.json\");\n\tconst biomecPath = join(rootDir, \"biome.jsonc\");\n\tconst pnpmWorkspacePath = join(rootDir, \"pnpm-workspace.yaml\");\n\tconst huskyDir = join(rootDir, \".husky\");\n\tconst lefthookYml = join(rootDir, \"lefthook.yml\");\n\n\tconst packageJsonExists = existsSync(packageJsonPath);\n\tconst tsconfigExists = existsSync(tsconfigPath);\n\tconst biomeDetected = existsSync(biomePath) || existsSync(biomecPath);\n\n\t// TypeScript version detection\n\tlet typescriptVersion: string | null = null;\n\tif (packageJsonExists) {\n\t\tconst pkg = readJsonSafe<PackageJsonShape>(packageJsonPath);\n\t\tif (pkg) {\n\t\t\tconst tsVersion = pkg.devDependencies?.typescript ?? pkg.dependencies?.typescript ?? null;\n\t\t\ttypescriptVersion = tsVersion;\n\t\t}\n\t}\n\n\t// Hook manager detection\n\tlet hookManager: \"husky\" | \"lefthook\" | \"none\" = \"none\";\n\tif (existsSync(huskyDir)) {\n\t\thookManager = \"husky\";\n\t} else if (existsSync(lefthookYml)) {\n\t\thookManager = \"lefthook\";\n\t} else if (packageJsonExists) {\n\t\tconst pkg = readJsonSafe<PackageJsonShape>(packageJsonPath);\n\t\tif (pkg) {\n\t\t\tconst allDeps = { ...pkg.dependencies, ...pkg.devDependencies };\n\t\t\tif (\"husky\" in allDeps) {\n\t\t\t\thookManager = \"husky\";\n\t\t\t} else if (\"lefthook\" in allDeps) {\n\t\t\t\thookManager = \"lefthook\";\n\t\t\t}\n\t\t}\n\t}\n\n\t// Monorepo detection\n\tlet monorepo = false;\n\tlet monorepoType: \"pnpm\" | \"npm/yarn\" | null = null;\n\tif (existsSync(pnpmWorkspacePath)) {\n\t\tmonorepo = true;\n\t\tmonorepoType = \"pnpm\";\n\t} else if (packageJsonExists) {\n\t\tconst pkg = readJsonSafe<PackageJsonShape>(packageJsonPath);\n\t\tif (pkg?.workspaces) {\n\t\t\tmonorepo = true;\n\t\t\tmonorepoType = \"npm/yarn\";\n\t\t}\n\t}\n\n\treturn {\n\t\tpackageJsonExists,\n\t\ttsconfigExists,\n\t\tbiomeDetected,\n\t\ttypescriptVersion,\n\t\thookManager,\n\t\tmonorepo,\n\t\tmonorepoType,\n\t};\n}\n\n// ---------------------------------------------------------------------------\n// Config file content\n// ---------------------------------------------------------------------------\n\n/**\n * Default forge-ts.config.ts content for new projects.\n * @internal\n */\nconst DEFAULT_CONFIG_CONTENT = `import { defineConfig } from \"@forge-ts/core\";\n\nexport default defineConfig({\n  rootDir: \".\",\n  tsconfig: \"tsconfig.json\",\n  outDir: \"docs/generated\",\n  enforce: {\n    enabled: true,\n    minVisibility: \"public\",\n    strict: false,\n  },\n  gen: {\n    enabled: true,\n    formats: [\"mdx\"],\n    llmsTxt: true,\n    readmeSync: false,\n    ssgTarget: \"mintlify\",\n  },\n});\n`;\n\n/**\n * Default tsdoc.json content.\n * @internal\n */\nconst DEFAULT_TSDOC_CONTENT = JSON.stringify(\n\t{\n\t\t$schema: \"https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json\",\n\t\textends: [\"@forge-ts/core/tsdoc-preset/tsdoc.json\"],\n\t},\n\tnull,\n\t\"\\t\",\n);\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Runs the full project init flow.\n *\n * Steps:\n * 1. Detect project environment\n * 2. Write forge-ts.config.ts (if not exists)\n * 3. Write tsdoc.json (if not exists)\n * 4. Validate tsconfig.json strictness\n * 5. Validate package.json\n * 6. Report summary\n *\n * @param args - CLI arguments for the init command.\n * @returns A typed `CommandOutput<InitProjectResult>`.\n * @example\n * ```typescript\n * import { runInitProject } from \"@forge-ts/cli/commands/init-project\";\n * const output = await runInitProject({ cwd: process.cwd() });\n * console.log(output.data.created); // [\"forge-ts.config.ts\", \"tsdoc.json\"]\n * ```\n * @public\n */\nexport async function runInitProject(\n\targs: InitProjectArgs,\n): Promise<CommandOutput<InitProjectResult>> {\n\tconst start = Date.now();\n\tconst rootDir = args.cwd ?? process.cwd();\n\n\tconst created: string[] = [];\n\tconst skipped: string[] = [];\n\tconst warnings: string[] = [];\n\tconst cliWarnings: ForgeCliWarning[] = [];\n\n\t// -----------------------------------------------------------------------\n\t// Step 1: Detect project environment\n\t// -----------------------------------------------------------------------\n\n\tconst environment = detectEnvironment(rootDir);\n\n\tif (!environment.packageJsonExists) {\n\t\tconst err: ForgeCliError = {\n\t\t\tcode: \"INIT_NO_PACKAGE_JSON\",\n\t\t\tmessage: \"package.json not found. Run `npm init` or `pnpm init` first.\",\n\t\t};\n\t\treturn {\n\t\t\toperation: \"init\",\n\t\t\tsuccess: false,\n\t\t\tdata: {\n\t\t\t\tsuccess: false,\n\t\t\t\tcreated: [],\n\t\t\t\tskipped: [],\n\t\t\t\twarnings: [],\n\t\t\t\tenvironment,\n\t\t\t\tnextSteps: [],\n\t\t\t},\n\t\t\terrors: [err],\n\t\t\tduration: Date.now() - start,\n\t\t};\n\t}\n\n\tif (!environment.tsconfigExists) {\n\t\twarnings.push(\"tsconfig.json not found. forge-ts requires TypeScript.\");\n\t\tcliWarnings.push({\n\t\t\tcode: \"INIT_NO_TSCONFIG\",\n\t\t\tmessage: \"tsconfig.json not found. forge-ts requires TypeScript.\",\n\t\t});\n\t}\n\n\tif (!environment.biomeDetected) {\n\t\t// Informational — not a warning\n\t}\n\n\t// -----------------------------------------------------------------------\n\t// Step 2: Write forge-ts.config.ts\n\t// -----------------------------------------------------------------------\n\n\tconst configPath = join(rootDir, \"forge-ts.config.ts\");\n\tif (existsSync(configPath)) {\n\t\tskipped.push(\"forge-ts.config.ts\");\n\t} else {\n\t\tawait mkdir(rootDir, { recursive: true });\n\t\tawait writeFile(configPath, DEFAULT_CONFIG_CONTENT, \"utf8\");\n\t\tcreated.push(\"forge-ts.config.ts\");\n\t}\n\n\t// -----------------------------------------------------------------------\n\t// Step 3: Write tsdoc.json\n\t// -----------------------------------------------------------------------\n\n\tconst tsdocPath = join(rootDir, \"tsdoc.json\");\n\tif (existsSync(tsdocPath)) {\n\t\tskipped.push(\"tsdoc.json\");\n\t} else {\n\t\tawait writeFile(tsdocPath, `${DEFAULT_TSDOC_CONTENT}\\n`, \"utf8\");\n\t\tcreated.push(\"tsdoc.json\");\n\t}\n\n\t// -----------------------------------------------------------------------\n\t// Step 4: Validate tsconfig.json strictness\n\t// -----------------------------------------------------------------------\n\n\tif (environment.tsconfigExists) {\n\t\tconst tsconfigPath = join(rootDir, \"tsconfig.json\");\n\t\tconst tsconfig = readJsonSafe<{\n\t\t\tcompilerOptions?: { strict?: boolean };\n\t\t}>(tsconfigPath);\n\n\t\tif (tsconfig) {\n\t\t\tif (!tsconfig.compilerOptions || tsconfig.compilerOptions.strict !== true) {\n\t\t\t\twarnings.push(\"tsconfig.json: 'strict' is not enabled. forge-ts recommends strict mode.\");\n\t\t\t\tcliWarnings.push({\n\t\t\t\t\tcode: \"INIT_TSCONFIG_NOT_STRICT\",\n\t\t\t\t\tmessage: \"tsconfig.json: 'strict' is not enabled. forge-ts recommends strict mode.\",\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t}\n\n\t// -----------------------------------------------------------------------\n\t// Step 5: Validate package.json\n\t// -----------------------------------------------------------------------\n\n\tconst pkgPath = join(rootDir, \"package.json\");\n\tconst pkg = readJsonSafe<PackageJsonShape>(pkgPath);\n\n\tif (pkg) {\n\t\tif (pkg.type !== \"module\") {\n\t\t\twarnings.push('package.json: missing \"type\": \"module\". forge-ts uses ESM.');\n\t\t\tcliWarnings.push({\n\t\t\t\tcode: \"INIT_NO_ESM\",\n\t\t\t\tmessage: 'package.json: missing \"type\": \"module\". forge-ts uses ESM.',\n\t\t\t});\n\t\t}\n\n\t\tif (!pkg.engines?.node) {\n\t\t\twarnings.push(\"package.json: missing engines.node field.\");\n\t\t\tcliWarnings.push({\n\t\t\t\tcode: \"INIT_NO_ENGINES\",\n\t\t\t\tmessage: \"package.json: missing engines.node field.\",\n\t\t\t});\n\t\t}\n\n\t\tconst allDeps = { ...pkg.dependencies, ...pkg.devDependencies };\n\t\tif (!(\"@forge-ts/cli\" in allDeps)) {\n\t\t\twarnings.push(\"package.json: @forge-ts/cli not in devDependencies (running via npx?).\");\n\t\t\tcliWarnings.push({\n\t\t\t\tcode: \"INIT_CLI_NOT_INSTALLED\",\n\t\t\t\tmessage: \"package.json: @forge-ts/cli not in devDependencies (running via npx?).\",\n\t\t\t});\n\t\t}\n\t}\n\n\t// -----------------------------------------------------------------------\n\t// Step 6: Build result\n\t// -----------------------------------------------------------------------\n\n\tconst nextSteps: string[] = [\n\t\t\"Run: forge-ts check      (lint TSDoc coverage)\",\n\t\t\"Run: forge-ts init docs   (scaffold documentation site)\",\n\t\t\"Run: forge-ts init hooks  (scaffold pre-commit hooks)\",\n\t\t\"Run: forge-ts lock        (lock config to prevent drift)\",\n\t];\n\n\tconst data: InitProjectResult = {\n\t\tsuccess: true,\n\t\tcreated,\n\t\tskipped,\n\t\twarnings,\n\t\tenvironment,\n\t\tnextSteps,\n\t};\n\n\treturn {\n\t\toperation: \"init\",\n\t\tsuccess: true,\n\t\tdata,\n\t\twarnings: cliWarnings.length > 0 ? cliWarnings : undefined,\n\t\tduration: Date.now() - start,\n\t};\n}\n\n// ---------------------------------------------------------------------------\n// Human formatter\n// ---------------------------------------------------------------------------\n\n/**\n * Formats an InitProjectResult as human-readable text.\n * @internal\n */\nfunction formatInitProjectHuman(result: InitProjectResult): string {\n\tconst lines: string[] = [];\n\n\tlines.push(\"\\nforge-ts init: project setup complete\\n\");\n\n\t// Created files\n\tif (result.created.length > 0) {\n\t\tlines.push(\"  Created:\");\n\t\tfor (const file of result.created) {\n\t\t\tlines.push(`    ${file}`);\n\t\t}\n\t}\n\n\t// Skipped files\n\tif (result.skipped.length > 0) {\n\t\tlines.push(\"\");\n\t\tlines.push(\"  Already exists (skipped):\");\n\t\tfor (const file of result.skipped) {\n\t\t\tlines.push(`    ${file}`);\n\t\t}\n\t} else if (result.created.length > 0) {\n\t\tlines.push(\"\");\n\t\tlines.push(\"  Already exists (skipped):\");\n\t\tlines.push(\"    (none)\");\n\t}\n\n\t// Warnings\n\tif (result.warnings.length > 0) {\n\t\tlines.push(\"\");\n\t\tlines.push(\"  Warnings:\");\n\t\tfor (const warning of result.warnings) {\n\t\t\tlines.push(`    ${warning}`);\n\t\t}\n\t}\n\n\t// Environment\n\tconst env = result.environment;\n\tlines.push(\"\");\n\tlines.push(\"  Environment:\");\n\tlines.push(`    TypeScript: ${env.typescriptVersion ?? \"not detected\"}`);\n\tlines.push(`    Biome: ${env.biomeDetected ? \"detected\" : \"not detected\"}`);\n\n\tconst hookLabel = env.hookManager === \"none\" ? \"not detected\" : `${env.hookManager} detected`;\n\tlines.push(`    Git hooks: ${hookLabel}`);\n\n\tif (env.monorepo) {\n\t\tlines.push(\n\t\t\t`    Monorepo: ${env.monorepoType === \"pnpm\" ? \"pnpm workspaces\" : \"npm/yarn workspaces\"}`,\n\t\t);\n\t} else {\n\t\tlines.push(\"    Monorepo: no\");\n\t}\n\n\t// Next steps\n\tif (result.nextSteps.length > 0) {\n\t\tlines.push(\"\");\n\t\tlines.push(\"  Next steps:\");\n\t\tfor (const [idx, step] of result.nextSteps.entries()) {\n\t\t\tlines.push(`    ${idx + 1}. ${step}`);\n\t\t}\n\t}\n\n\treturn lines.join(\"\\n\");\n}\n\n// ---------------------------------------------------------------------------\n// Citty command definition\n// ---------------------------------------------------------------------------\n\n/**\n * Citty command definition for `forge-ts init` (bare — full project setup).\n *\n * Detects the project environment, writes default configuration files,\n * validates tsconfig/package.json, and reports a summary.\n *\n * @example\n * ```typescript\n * import { initProjectCommand } from \"@forge-ts/cli/commands/init-project\";\n * // Registered as the default handler for `forge-ts init`\n * ```\n * @public\n */\nexport const initProjectCommand = defineCommand({\n\tmeta: {\n\t\tname: \"init\",\n\t\tdescription: \"Full project setup for forge-ts\",\n\t},\n\targs: {\n\t\tcwd: {\n\t\t\ttype: \"string\",\n\t\t\tdescription: \"Project root directory\",\n\t\t},\n\t\tjson: {\n\t\t\ttype: \"boolean\",\n\t\t\tdescription: \"Output as LAFS JSON envelope\",\n\t\t\tdefault: false,\n\t\t},\n\t\thuman: {\n\t\t\ttype: \"boolean\",\n\t\t\tdescription: \"Output as formatted text\",\n\t\t\tdefault: false,\n\t\t},\n\t\tquiet: {\n\t\t\ttype: \"boolean\",\n\t\t\tdescription: \"Suppress non-essential output\",\n\t\t\tdefault: false,\n\t\t},\n\t\tmvi: {\n\t\t\ttype: \"string\",\n\t\t\tdescription: \"MVI verbosity level: minimal, standard, full\",\n\t\t},\n\t},\n\tasync run({ args }) {\n\t\tconst output = await runInitProject({\n\t\t\tcwd: args.cwd,\n\t\t\tmvi: args.mvi,\n\t\t});\n\n\t\tconst flags: OutputFlags = {\n\t\t\tjson: args.json,\n\t\t\thuman: args.human,\n\t\t\tquiet: args.quiet,\n\t\t\tmvi: args.mvi,\n\t\t};\n\n\t\temitResult(output, flags, (data, cmd) => {\n\t\t\tif (!cmd.success) {\n\t\t\t\tconst msg = cmd.errors?.[0]?.message ?? \"Init failed\";\n\t\t\t\tforgeLogger.error(msg);\n\t\t\t\treturn \"\";\n\t\t\t}\n\t\t\treturn formatInitProjectHuman(data);\n\t\t});\n\n\t\tprocess.exit(resolveExitCode(output));\n\t},\n});\n"],"mappings":"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","names":[]}

package/dist/forge-logger-RTOBEKWH.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import {
+  configureLogger,
+  forgeLogger
+} from "./chunk-CNINN7IQ.js";
+export {
+  configureLogger,
+  forgeLogger
+};
+//# sourceMappingURL=forge-logger-RTOBEKWH.js.map

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.
@@ -521,6 +522,63 @@ declare const checkCommand: citty.CommandDef<{
     };
 }>;
 
+/**
+ * The `forge-ts docs dev` command — starts a local doc preview server.
+ *
+ * Reads the ssgTarget from forge-ts config, looks up the adapter,
+ * and spawns the correct dev server automatically.
+ *
+ * @packageDocumentation
+ * @public
+ */
+/**
+ * Starts the local dev server for the configured SSG target.
+ *
+ * Reads `gen.ssgTarget` from the forge-ts config, resolves the adapter,
+ * and spawns the platform's dev server in the output directory.
+ *
+ * @param args - Command arguments.
+ * @returns A promise that resolves when the server exits.
+ *
+ * @example
+ * ```typescript
+ * import { runDocsDev } from "@forge-ts/cli";
+ * await runDocsDev({ cwd: "./my-project" });
+ * ```
+ * @public
+ */
+declare function runDocsDev(args: {
+    /** Project root directory. */
+    cwd?: string;
+    /** Override the SSG target from config. */
+    target?: string;
+    /** Port to run the dev server on. */
+    port?: string;
+}): Promise<void>;
+/**
+ * Citty command definition for `forge-ts docs dev`.
+ *
+ * @example
+ * ```typescript
+ * import { docsDevCommand } from "@forge-ts/cli";
+ * ```
+ * @public
+ */
+declare const docsDevCommand: citty.CommandDef<{
+    readonly cwd: {
+        readonly type: "string";
+        readonly description: "Project root directory";
+    };
+    readonly target: {
+        readonly type: "string";
+        readonly description: "SSG target override (reads from config by default)";
+    };
+    readonly port: {
+        readonly type: "string";
+        readonly description: "Port for the dev server";
+    };
+}>;
+
 /**
  * Status of a single doctor check.
  * @public
@@ -584,8 +642,8 @@ interface DoctorArgs {
  *
  * 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
+ * 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)
@@ -649,63 +707,6 @@ declare const doctorCommand: citty.CommandDef<{
     };
 }>;
 
-/**
- * The `forge-ts docs dev` command — starts a local doc preview server.
- *
- * Reads the ssgTarget from forge-ts config, looks up the adapter,
- * and spawns the correct dev server automatically.
- *
- * @packageDocumentation
- * @public
- */
-/**
- * Starts the local dev server for the configured SSG target.
- *
- * Reads `gen.ssgTarget` from the forge-ts config, resolves the adapter,
- * and spawns the platform's dev server in the output directory.
- *
- * @param args - Command arguments.
- * @returns A promise that resolves when the server exits.
- *
- * @example
- * ```typescript
- * import { runDocsDev } from "@forge-ts/cli";
- * await runDocsDev({ cwd: "./my-project" });
- * ```
- * @public
- */
-declare function runDocsDev(args: {
-    /** Project root directory. */
-    cwd?: string;
-    /** Override the SSG target from config. */
-    target?: string;
-    /** Port to run the dev server on. */
-    port?: string;
-}): Promise<void>;
-/**
- * Citty command definition for `forge-ts docs dev`.
- *
- * @example
- * ```typescript
- * import { docsDevCommand } from "@forge-ts/cli";
- * ```
- * @public
- */
-declare const docsDevCommand: citty.CommandDef<{
-    readonly cwd: {
-        readonly type: "string";
-        readonly description: "Project root directory";
-    };
-    readonly target: {
-        readonly type: "string";
-        readonly description: "SSG target override (reads from config by default)";
-    };
-    readonly port: {
-        readonly type: "string";
-        readonly description: "Port for the dev server";
-    };
-}>;
-
 /**
  * Result of the `init docs` command.
  *
@@ -1332,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
+ */
+declare const forgeLogger: consola.ConsolaInstance;
+/**
+ * Options for configuring the forge-ts logger at CLI startup.
+ *
  * @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;
+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 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 };
+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 };