@turboforge/cli-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 turboforge-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @turboforge/cli-kit
+
+Build monorepo-aware CLIs without rewriting config loading, workspace detection, and logging every time.
+
+<p className="flex gap-2">
+  <a href="https://github.com/turboforge-dev/turboforge/actions/workflows/ci.yml" rel="noopener noreferrer">
+    <img alt="CI" src="https://github.com/turboforge-dev/turboforge/actions/workflows/ci.yml/badge.svg" />
+  </a>
+  <a href="https://codecov.io/gh/turboforge-dev/turboforge/tree/main/packages/@turboforge/cli-kit" rel="noopener noreferrer">
+    <img alt="codecov" src="https://codecov.io/gh/turboforge-dev/turboforge/graph/badge.svg?flag=@turboforge/cli-kit" />
+  </a>
+  <a href="https://npmjs.com/package/@turboforge/cli-kit" rel="noopener noreferrer">
+    <img alt="npm version" src="https://img.shields.io/npm/v/@turboforge/cli-kit" />
+  </a>
+  <a href="https://npmjs.com/package/@turboforge/cli-kit" rel="noopener noreferrer">
+    <img alt="npm downloads" src="https://img.shields.io/npm/d18m/@turboforge/cli-kit" />
+  </a>
+  <a href="https://npmjs.com/package/@turboforge/cli-kit" rel="noopener noreferrer">
+    <img alt="npm bundle size" src="https://img.shields.io/bundlephobia/minzip/@turboforge/cli-kit" />
+  </a>
+  <img alt="license" src="https://img.shields.io/npm/l/@turboforge/cli-kit" />
+</p>
+
+`@turboforge/cli-kit` exists because internal tooling usually starts as one script, then turns into five slightly different scripts with different root-detection rules, different config formats, and no shared mental model. This package gives Turboforge and downstream tools a common foundation.
+
+Part of the Turboforge system:
+
+- use [`@turboforge/sync`](/c:/Users/G/web/open-source/turbo-forge/packages/forge-sync/README.md) when the problem is keeping a repo aligned with its upstream shape
+- use `@turboforge/cli-kit` when the problem is building the repo-aware tools that operate inside that shape
+
+## Highlights
+
+- Resolve layered config from defaults, files, env, and CLI input.
+- Detect project roots and workspace packages without repo-specific glue code.
+- Share one logging and runtime foundation across multiple repo tools.
+
+## Why It Exists
+
+Most CLI helpers are either too generic to understand monorepos or too entangled with one app to reuse cleanly.
+
+`@turboforge/cli-kit` focuses on the boring parts every serious repo tool needs:
+
+- find the real project root
+- discover workspace packages
+- load layered config from the right place
+- log in a way that works for both humans and automation
+
+## Real Example
+
+You are building `repo doctor`, `release check`, and `docs sync` commands for the same workspace.
+
+Without a shared kit, each command re-implements:
+
+- "where is the repo root?"
+- "which packages belong to this workspace?"
+- "which config wins: default, file, env, or CLI flag?"
+
+With `@turboforge/cli-kit`, those decisions become shared infrastructure instead of repeated code.
+
+## When To Use It
+
+- You are building internal or OSS CLIs that need monorepo awareness.
+- You want layered config resolution without writing a config loader from scratch.
+- You need a small foundation, not a full CLI framework.
+
+## When Not To Use It
+
+- You only need argument parsing.
+- Your tool does not care about workspaces, repo roots, or shared config.
+- You want a batteries-included command framework with prompts, subcommands, and plugin loading out of the box.
+
+## 📦 Installation
+
+```bash
+pnpm add @turboforge/cli-kit
+```
+
+**_or_**
+
+```bash
+$ npm install @turboforge/cli-kit
+```
+
+**_or_**
+
+```bash
+$ yarn add @turboforge/cli-kit
+```
+
+### Optional Peer Dependencies
+
+```bash
+pnpm add -D jiti defu
+```
+
+- `jiti` lets you load TypeScript config files at runtime.
+- `defu` gives you richer object merge behavior.
+
+## Example
+
+```ts
+import {
+  createLogger,
+  findProjectRoot,
+  getWorkspacePackages,
+  resolveConfig,
+} from "@turboforge/cli-kit";
+
+const logger = createLogger({ level: "info", name: "repo-doctor" });
+const root = await findProjectRoot();
+const packages = await getWorkspacePackages(root);
+
+const config = await resolveConfig({
+  name: "repo-doctor",
+  defaults: { fix: false },
+});
+
+logger.info(`checking ${packages.length} packages`, config.fix);
+```
+
+## What You Get
+
+- `resolveConfig`: layered config for repo tools
+- `findProjectRoot`: stable root detection
+- `getWorkspacePackages`: workspace discovery
+- `createLogger`: structured output for local use and automation
+
+## Ecosystem Fit
+
+If Turboforge is about keeping a monorepo coherent, `@turboforge/cli-kit` is the layer you build that coherence on top of.

package/dist/index.d.mts

@@ -0,0 +1,251 @@
+import { exec, execFile } from 'node:child_process';
+
+interface ResolveConfigOptions<T> {
+    name: string;
+    cwd?: string;
+    defaults?: T;
+    envVars?: Partial<T>;
+    cliArgs?: Partial<T>;
+    configFile?: string;
+    /** If true, throws on configuration parsing errors. */
+    strict?: boolean;
+}
+/**
+ * Resolves configuration by walking up the tree and merging files.
+ */
+declare const resolveConfig: <T>({ name, cwd, defaults, envVars, cliArgs, configFile, strict, }: ResolveConfigOptions<T>) => Promise<T>;
+/**
+ * Type helper for defining config.
+ */
+declare const defineConfig: <T>(config: T) => T;
+
+/**
+ * Log severity levels.
+ *
+ * Ordered from lowest → highest severity.
+ * This ordering allows efficient numeric filtering.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Logger configuration.
+ */
+interface LoggerConfig {
+    /**
+     * Minimum severity level to output.
+     *
+     * Logs below this level will be ignored.
+     */
+    level: LogLevel;
+    /**
+     * Optional file path to append logs to.
+     *
+     * If provided, logs will be written to both terminal and file.
+     */
+    logFile?: string;
+    /**
+     * Log format.
+     *
+     * `text` - Human-readable format
+     * `json` - JSON format for machine parsing
+     *
+     * @default "text"
+     */
+    logFormat?: "text" | "json";
+    /**
+     * Optional name to prepend to all log messages.
+     * Useful for identifying the source of logs in multi-process environments.
+     */
+    name?: string;
+}
+/**
+ * Logger interface.
+ */
+interface Logger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    /**
+     * Flushes and closes the file stream if active.
+     *
+     * Safe to call multiple times.
+     */
+    close: () => void;
+}
+/**
+ * Creates a minimal structured logger.
+ *
+ * Features:
+ * - Level-based filtering
+ * - Colored terminal output
+ * - Optional file logging
+ * - Automatic stream cleanup on process exit
+ *
+ * Designed for:
+ * - CLI tools
+ * - developer utilities
+ * - small Node services
+ *
+ * Example:
+ *
+ * ```ts
+ * const logger = createLogger({ level: "info", logFile: "./app.log" })
+ *
+ * logger.info("Server started", port)
+ * logger.warn("Cache miss")
+ * logger.error("Unhandled error", err)
+ * ```
+ */
+declare const createLogger: (config: LoggerConfig) => Logger;
+
+/**
+ * Finds the project root directory based on common markers.
+ * Priority: .git > .changeset > pnpm-workspace.yaml > package.json (with workspaces)
+ */
+declare const findProjectRoot: (cwd?: string) => Promise<string>;
+
+/**
+ * Minimal YAML parser with fallback.
+ * Uses `yaml` package if available, else falls back to regex-based parsing
+ * for common monorepo config patterns (like pnpm-workspace.yaml).
+ */
+declare function parseYaml<T>(content: string): Promise<T>;
+
+/**
+ * Promisified version of `child_process.exec`.
+ * Executes a command in a shell and buffers the output.
+ *
+ * @param command - The shell command to execute.
+ * @returns Promise resolving with `{ stdout, stderr }`.
+ */
+declare const execAsync: typeof exec.__promisify__;
+/**
+ * Promisified version of `child_process.execFile`.
+ * Executes an executable directly without spawning a shell.
+ *
+ * @param file - Path to executable.
+ * @param args - CLI arguments.
+ * @returns Promise resolving with `{ stdout, stderr }`.
+ */
+declare const execFileAsync: typeof execFile.__promisify__;
+/**
+ * Checks if a file or directory exists.
+ *
+ * Uses `fs.promises.access` for non-blocking I/O.
+ *
+ * Only `ENOENT` is interpreted as "does not exist".
+ * Other filesystem errors are rethrown.
+ *
+ * @param p - File system path to check.
+ */
+declare const existsAsync: (p: string) => Promise<boolean>;
+/**
+ * Recursively walks up the directory tree from `startDir`
+ * searching for a directory containing any of the `markers`.
+ *
+ * Results are cached to avoid redundant filesystem traversal.
+ *
+ * @param startDir - Directory to begin searching from.
+ * @param markers - File or directory names to detect.
+ *
+ * @returns Directory containing the marker, or `null`.
+ */
+declare const findUp: (startDir: string, markers: string[]) => Promise<string | null>;
+/**
+ * Options for parsing operations.
+ */
+interface ParsingOptions {
+    /**
+     * Throw on syntax/import errors.
+     *
+     * @default false
+     */
+    strict?: boolean;
+}
+/**
+ * Reads and parses a JSON file safely.
+ *
+ * Returns `null` if the file does not exist or parsing fails
+ * (unless `strict` mode is enabled).
+ *
+ * @param p - JSON file path.
+ */
+declare const readJson: <T = unknown>(p: string, options?: ParsingOptions) => Promise<T | null>;
+/**
+ * Attempts to import a module.
+ *
+ * Supports:
+ * - Native dynamic `import()`
+ * - TypeScript configs via `jiti` (if available)
+ *
+ * @param p - Module
+ */
+declare const tryImport: <T = unknown>(p: string, options?: ParsingOptions) => Promise<T | null>;
+/**
+ * Deep merges two objects.
+ *
+ * Arrays are overwritten rather than concatenated.
+ * Guards against prototype pollution.
+ */
+declare const deepMerge: (target: any, source: any) => any;
+/**
+ * Atomically writes a file using a temp-file + rename strategy.
+ *
+ * Guarantees readers never observe partially written files.
+ *
+ * Strategy:
+ * 1. Write data to a temporary file in the same directory.
+ * 2. Rename temp file to target (atomic on same filesystem).
+ *
+ * Why this matters:
+ * - Prevents partially written files.
+ * - Ensures readers never observe truncated JSON.
+ * - Safe under concurrent writers (last-writer-wins).
+ *
+ * Concurrency Model:
+ * - Each invocation uses a `randomUUID()` temp filename
+ *   to avoid cross-process collisions.
+ * - Rename is atomic on the same filesystem.
+ * - No locking is performed here.
+ *
+ * Limitations:
+ * - Does not prevent logical race conditions.
+ * - If two processes write simultaneously, the last rename wins.
+ * - Both temp and target must reside on the same filesystem
+ *   for atomic guarantees.
+ *
+ * @param path Target file path.
+ * @param data UTF-8 string content.
+ */
+declare const atomicWrite: (path: string, data: string) => Promise<void>;
+/**
+ * Safely renames a file or directory.
+ *
+ * Handles common Windows rename issues where the target
+ * already exists.
+ *
+ * @param from Source
+ * @param to Target
+ */
+declare const safeRename: (from: string, to: string) => Promise<void>;
+/**
+ * Creates a minimal promise concurrency limiter.
+ *
+ * Ensures no more than `concurrency` async tasks run simultaneously.
+ * Additional tasks are queued FIFO.
+ *
+ * @param concurrency - Maximum concurrent tasks (must be ≥1).
+ */
+declare const createLimiter: (concurrency: number) => <T>(task: () => Promise<T>) => Promise<T>;
+
+/**
+ * Detects workspace packages in a monorepo.
+ * Supports `package.json` workspaces and `pnpm-workspace.yaml`.
+ */
+declare const getWorkspacePackages: (root: string) => Promise<string[]>;
+/**
+ * Check if the current directory is inside a monorepo
+ */
+declare const isMonorepo: (cwd?: string) => Promise<boolean>;
+
+export { type LogLevel, type Logger, type LoggerConfig, type ParsingOptions, type ResolveConfigOptions, atomicWrite, createLimiter, createLogger, deepMerge, defineConfig, execAsync, execFileAsync, existsAsync, findProjectRoot, findUp, getWorkspacePackages, isMonorepo, parseYaml, readJson, resolveConfig, safeRename, tryImport };

package/dist/index.d.ts

@@ -0,0 +1,251 @@
+import { exec, execFile } from 'node:child_process';
+
+interface ResolveConfigOptions<T> {
+    name: string;
+    cwd?: string;
+    defaults?: T;
+    envVars?: Partial<T>;
+    cliArgs?: Partial<T>;
+    configFile?: string;
+    /** If true, throws on configuration parsing errors. */
+    strict?: boolean;
+}
+/**
+ * Resolves configuration by walking up the tree and merging files.
+ */
+declare const resolveConfig: <T>({ name, cwd, defaults, envVars, cliArgs, configFile, strict, }: ResolveConfigOptions<T>) => Promise<T>;
+/**
+ * Type helper for defining config.
+ */
+declare const defineConfig: <T>(config: T) => T;
+
+/**
+ * Log severity levels.
+ *
+ * Ordered from lowest → highest severity.
+ * This ordering allows efficient numeric filtering.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Logger configuration.
+ */
+interface LoggerConfig {
+    /**
+     * Minimum severity level to output.
+     *
+     * Logs below this level will be ignored.
+     */
+    level: LogLevel;
+    /**
+     * Optional file path to append logs to.
+     *
+     * If provided, logs will be written to both terminal and file.
+     */
+    logFile?: string;
+    /**
+     * Log format.
+     *
+     * `text` - Human-readable format
+     * `json` - JSON format for machine parsing
+     *
+     * @default "text"
+     */
+    logFormat?: "text" | "json";
+    /**
+     * Optional name to prepend to all log messages.
+     * Useful for identifying the source of logs in multi-process environments.
+     */
+    name?: string;
+}
+/**
+ * Logger interface.
+ */
+interface Logger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    /**
+     * Flushes and closes the file stream if active.
+     *
+     * Safe to call multiple times.
+     */
+    close: () => void;
+}
+/**
+ * Creates a minimal structured logger.
+ *
+ * Features:
+ * - Level-based filtering
+ * - Colored terminal output
+ * - Optional file logging
+ * - Automatic stream cleanup on process exit
+ *
+ * Designed for:
+ * - CLI tools
+ * - developer utilities
+ * - small Node services
+ *
+ * Example:
+ *
+ * ```ts
+ * const logger = createLogger({ level: "info", logFile: "./app.log" })
+ *
+ * logger.info("Server started", port)
+ * logger.warn("Cache miss")
+ * logger.error("Unhandled error", err)
+ * ```
+ */
+declare const createLogger: (config: LoggerConfig) => Logger;
+
+/**
+ * Finds the project root directory based on common markers.
+ * Priority: .git > .changeset > pnpm-workspace.yaml > package.json (with workspaces)
+ */
+declare const findProjectRoot: (cwd?: string) => Promise<string>;
+
+/**
+ * Minimal YAML parser with fallback.
+ * Uses `yaml` package if available, else falls back to regex-based parsing
+ * for common monorepo config patterns (like pnpm-workspace.yaml).
+ */
+declare function parseYaml<T>(content: string): Promise<T>;
+
+/**
+ * Promisified version of `child_process.exec`.
+ * Executes a command in a shell and buffers the output.
+ *
+ * @param command - The shell command to execute.
+ * @returns Promise resolving with `{ stdout, stderr }`.
+ */
+declare const execAsync: typeof exec.__promisify__;
+/**
+ * Promisified version of `child_process.execFile`.
+ * Executes an executable directly without spawning a shell.
+ *
+ * @param file - Path to executable.
+ * @param args - CLI arguments.
+ * @returns Promise resolving with `{ stdout, stderr }`.
+ */
+declare const execFileAsync: typeof execFile.__promisify__;
+/**
+ * Checks if a file or directory exists.
+ *
+ * Uses `fs.promises.access` for non-blocking I/O.
+ *
+ * Only `ENOENT` is interpreted as "does not exist".
+ * Other filesystem errors are rethrown.
+ *
+ * @param p - File system path to check.
+ */
+declare const existsAsync: (p: string) => Promise<boolean>;
+/**
+ * Recursively walks up the directory tree from `startDir`
+ * searching for a directory containing any of the `markers`.
+ *
+ * Results are cached to avoid redundant filesystem traversal.
+ *
+ * @param startDir - Directory to begin searching from.
+ * @param markers - File or directory names to detect.
+ *
+ * @returns Directory containing the marker, or `null`.
+ */
+declare const findUp: (startDir: string, markers: string[]) => Promise<string | null>;
+/**
+ * Options for parsing operations.
+ */
+interface ParsingOptions {
+    /**
+     * Throw on syntax/import errors.
+     *
+     * @default false
+     */
+    strict?: boolean;
+}
+/**
+ * Reads and parses a JSON file safely.
+ *
+ * Returns `null` if the file does not exist or parsing fails
+ * (unless `strict` mode is enabled).
+ *
+ * @param p - JSON file path.
+ */
+declare const readJson: <T = unknown>(p: string, options?: ParsingOptions) => Promise<T | null>;
+/**
+ * Attempts to import a module.
+ *
+ * Supports:
+ * - Native dynamic `import()`
+ * - TypeScript configs via `jiti` (if available)
+ *
+ * @param p - Module
+ */
+declare const tryImport: <T = unknown>(p: string, options?: ParsingOptions) => Promise<T | null>;
+/**
+ * Deep merges two objects.
+ *
+ * Arrays are overwritten rather than concatenated.
+ * Guards against prototype pollution.
+ */
+declare const deepMerge: (target: any, source: any) => any;
+/**
+ * Atomically writes a file using a temp-file + rename strategy.
+ *
+ * Guarantees readers never observe partially written files.
+ *
+ * Strategy:
+ * 1. Write data to a temporary file in the same directory.
+ * 2. Rename temp file to target (atomic on same filesystem).
+ *
+ * Why this matters:
+ * - Prevents partially written files.
+ * - Ensures readers never observe truncated JSON.
+ * - Safe under concurrent writers (last-writer-wins).
+ *
+ * Concurrency Model:
+ * - Each invocation uses a `randomUUID()` temp filename
+ *   to avoid cross-process collisions.
+ * - Rename is atomic on the same filesystem.
+ * - No locking is performed here.
+ *
+ * Limitations:
+ * - Does not prevent logical race conditions.
+ * - If two processes write simultaneously, the last rename wins.
+ * - Both temp and target must reside on the same filesystem
+ *   for atomic guarantees.
+ *
+ * @param path Target file path.
+ * @param data UTF-8 string content.
+ */
+declare const atomicWrite: (path: string, data: string) => Promise<void>;
+/**
+ * Safely renames a file or directory.
+ *
+ * Handles common Windows rename issues where the target
+ * already exists.
+ *
+ * @param from Source
+ * @param to Target
+ */
+declare const safeRename: (from: string, to: string) => Promise<void>;
+/**
+ * Creates a minimal promise concurrency limiter.
+ *
+ * Ensures no more than `concurrency` async tasks run simultaneously.
+ * Additional tasks are queued FIFO.
+ *
+ * @param concurrency - Maximum concurrent tasks (must be ≥1).
+ */
+declare const createLimiter: (concurrency: number) => <T>(task: () => Promise<T>) => Promise<T>;
+
+/**
+ * Detects workspace packages in a monorepo.
+ * Supports `package.json` workspaces and `pnpm-workspace.yaml`.
+ */
+declare const getWorkspacePackages: (root: string) => Promise<string[]>;
+/**
+ * Check if the current directory is inside a monorepo
+ */
+declare const isMonorepo: (cwd?: string) => Promise<boolean>;
+
+export { type LogLevel, type Logger, type LoggerConfig, type ParsingOptions, type ResolveConfigOptions, atomicWrite, createLimiter, createLogger, deepMerge, defineConfig, execAsync, execFileAsync, existsAsync, findProjectRoot, findUp, getWorkspacePackages, isMonorepo, parseYaml, readJson, resolveConfig, safeRename, tryImport };

package/dist/index.js

@@ -0,0 +1,3 @@
+"use strict";var X=Object.create;var v=Object.defineProperty;var H=Object.getOwnPropertyDescriptor;var K=Object.getOwnPropertyNames;var Q=Object.getPrototypeOf,Z=Object.prototype.hasOwnProperty;var rr=(r,t)=>{for(var e in t)v(r,e,{get:t[e],enumerable:!0})},_=(r,t,e,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of K(t))!Z.call(r,n)&&n!==e&&v(r,n,{get:()=>t[n],enumerable:!(o=H(t,n))||o.enumerable});return r};var T=(r,t,e)=>(e=r!=null?X(Q(r)):{},_(t||!r||!r.__esModule?v(e,"default",{value:r,enumerable:!0}):e,r)),tr=r=>_(v({},"__esModule",{value:!0}),r);var lr={};rr(lr,{atomicWrite:()=>nr,createLimiter:()=>J,createLogger:()=>ar,deepMerge:()=>R,defineConfig:()=>ir,execAsync:()=>er,execFileAsync:()=>or,existsAsync:()=>m,findProjectRoot:()=>M,findUp:()=>D,getWorkspacePackages:()=>cr,isMonorepo:()=>pr,parseYaml:()=>O,readJson:()=>h,resolveConfig:()=>sr,safeRename:()=>Y,tryImport:()=>I});module.exports=tr(lr);var G=require("fs/promises"),b=T(require("path"));var P=T(require("path"));var L=require("child_process"),U=require("crypto"),f=require("fs/promises"),u=require("path"),N=require("util");async function O(r){try{let n=await import("yaml").then(i=>i.default||i).catch(()=>null);if(n&&typeof n.parse=="function")return n.parse(r)}catch{}let t={},o=r.replace(/#.*$/gm,"").match(/packages:\s*\n((?:\s*-\s*.*\n?)*)/);if(o?.[1]){let n=[],i=/^\s*-\s*["']?([^"'\s]+)["']?/gm,a;for(;(a=i.exec(o[1]))!==null;)n.push(a[1]);t.packages=n}return t}var er=(0,N.promisify)(L.exec),or=(0,N.promisify)(L.execFile),m=async r=>{try{return await(0,f.access)(r),!0}catch(t){if(t.code==="ENOENT")return!1;throw t}},y=new Map,W=200,D=async(r,t)=>{let e=(0,u.resolve)(r),o=`${e}:${[...t].sort().join(",")}`;if(y.has(o))return y.get(o);let n=e,{root:i}=(0,u.parse)(n);for(;;){for(let a of t)if(await m((0,u.join)(n,a)))return y.set(o,n),y.size>W&&y.clear(),n;if(n===i)break;n=(0,u.dirname)(n)}return y.set(o,null),y.size>W&&y.clear(),null},h=async(r,t={})=>{try{let e=await(0,f.readFile)(r,"utf-8");return JSON.parse(e)}catch(e){if(e.code==="ENOENT")return null;if(t.strict)throw e;return null}},I=async(r,t={})=>{if(!await m(r))return null;try{let e=await import("jiti"),n=(e.createJiti?e.createJiti(process.cwd()):e.default(process.cwd()))(r);return n.default??n}catch{try{let e=await import(r);return e.default??e}catch(e){if(t.strict)throw/\.(ts|mts)$/.test(r)?new Error(`Failed to load TypeScript config at ${r}. Install 'jiti' to load TS configs. Original error: ${e}`):e;return null}}},R=(r,t)=>{if(typeof r!="object"||r===null||typeof t!="object"||t===null||Array.isArray(r)&&Array.isArray(t))return t;let e={...r};for(let o of Object.keys(t))o==="__proto__"||o==="constructor"||o==="prototype"||Object.hasOwn(t,o)&&(e[o]=o in r?R(r[o],t[o]):t[o]);return e},nr=async(r,t)=>{let e=(0,u.join)((0,u.dirname)(r),`${(0,U.randomUUID)()}.tmp`);try{await(0,f.writeFile)(e,t,"utf-8"),await Y(e,r)}catch(o){throw await(0,f.rm)(e,{force:!0}).catch(()=>{}),o}},Y=async(r,t)=>{if(await m(r))try{await(0,f.rename)(r,t)}catch(e){let o=e;if(o.code==="EEXIST"||o.code==="EPERM"){await(0,f.rm)(t,{recursive:!0,force:!0}),await(0,f.rename)(r,t);return}throw e}},J=r=>{if(r<1)throw new Error("createLimiter: concurrency must be >= 1");let t=0,e=[],o=()=>{t--,e.shift()?.()};return async n=>{t>=r&&await new Promise(i=>e.push(i)),t++;try{return await n()}finally{o()}}};var $=new Map,M=async(r=process.cwd())=>{let t=P.default.resolve(r);if($.has(t))return $.get(t);let e=await D(t,[".git",".changeset","pnpm-workspace.yaml"]);if(e)return $.set(t,e),e;let o=P.default.resolve(r),{root:n}=P.default.parse(o);for(;;){let i=P.default.join(o,"package.json"),a=await h(i);if(a?.workspaces&&Array.isArray(a.workspaces))return $.set(t,o),o;if(o===n)break;o=P.default.dirname(o)}return $.set(t,t),t};var sr=async({name:r,cwd:t=process.cwd(),defaults:e={},envVars:o={},cliArgs:n={},configFile:i,strict:a=!1})=>{let E=await M(t),l=[];if(i)l.push(b.default.resolve(t,i));else{let s=b.default.resolve(t),g=new RegExp(`^${r}\\.config\\.(ts|mts|js|mjs|json)$`);for(;;){try{let j=(await(0,G.readdir)(s)).find(F=>g.test(F));j&&l.push(b.default.join(s,j))}catch{}if(s===E)break;let x=b.default.dirname(s);if(x===s)break;s=x}}let c=[];for(let s of l.reverse())if(s.endsWith(".json")){let g=await h(s,{strict:a});g&&c.push(g)}else{let g=await I(s,{strict:a});g&&c.push(g)}let d=R;try{let s=await import("defu");s?.defu&&(d=(g,x)=>s.defu(x,g))}catch{}let p=e;for(let s of c)p=d(p,s);return p=d(p,o),p=d(p,n),p},ir=r=>r;var B=require("fs"),V=T(require("os")),k="\x1B[",A={gray:r=>`${k}90m${r}${k}39m`,blue:r=>`${k}34m${r}${k}39m`,yellow:r=>`${k}33m${r}${k}39m`,red:r=>`${k}31m${r}${k}39m`},q={debug:20,info:30,warn:40,error:50},z={debug:A.gray,info:A.blue,warn:A.yellow,error:A.red},ar=r=>{let t=q[r.level],e=r.logFormat??"text",o=r.name,n=o?{debug:`${o}:DEBUG`,info:`${o}:INFO`,warn:`${o}:WARN`,error:`${r.name}:ERROR`}:{debug:"DEBUG",info:"INFO",warn:"WARN",error:"ERROR"},i=null,a=!1,E=process.stdout.isTTY&&!process.env.NO_COLOR||!!process.env.FORCE_COLOR;if(r.logFile)try{i=(0,B.createWriteStream)(r.logFile,{flags:"a"}),i.on("error",()=>{i=null})}catch{i=null}let l=()=>{if(!a&&(a=!0,i)){try{i.end()}catch{}i=null}};process.once("exit",l),process.once("SIGINT",()=>{l(),process.exit(0)}),process.once("SIGTERM",()=>{l(),process.exit(0)});let c=process.pid,d=V.default.hostname(),p=(s,...g)=>{if(q[s]<t)return;let x=new Date().toISOString(),C=g.map(String).join(" "),j=e==="json"?JSON.stringify({ts:x,level:s,message:C,pid:c,hostname:d,name:o}):`[${x}] [${n[s]}] ${C}`,F=E&&z[s]?z[s](j):j;if((s==="warn"||s==="error"?process.stderr:process.stdout).write(`${F}
+`),i)try{i.write(`${j}
+`)}catch{i=null}};return{debug:(...s)=>p("debug",...s),info:(...s)=>p("info",...s),warn:(...s)=>p("warn",...s),error:(...s)=>p("error",...s),close:l}};var S=require("fs/promises"),w=T(require("path"));var cr=async r=>{let t=[],e=w.default.join(r,"package.json"),o=await h(e);o?.workspaces&&(Array.isArray(o.workspaces)?t.push(...o.workspaces):Array.isArray(o.workspaces.packages)&&t.push(...o.workspaces.packages));let n=w.default.join(r,"pnpm-workspace.yaml");if(await m(n))try{let l=await(0,S.readFile)(n,"utf-8"),c=await O(l);c?.packages&&t.push(...c.packages)}catch{}let i=J(10),a=[],E=[...new Set(t)];return await Promise.all(E.map(l=>i(async()=>{if(l.endsWith("/*")){let c=w.default.join(r,l.slice(0,-2));if(await m(c))try{let d=await(0,S.readdir)(c,{withFileTypes:!0});for(let p of d)p.isDirectory()&&await m(w.default.join(c,p.name,"package.json"))&&a.push(w.default.join(c,p.name))}catch{}}else{let c=w.default.join(r,l);await m(w.default.join(c,"package.json"))&&a.push(c)}}))),[...new Set(a)]},pr=async(r=process.cwd())=>{let t=w.default.join(r,"package.json");return!!((await h(t))?.workspaces||await m(w.default.join(r,"pnpm-workspace.yaml")))};0&&(module.exports={atomicWrite,createLimiter,createLogger,deepMerge,defineConfig,execAsync,execFileAsync,existsAsync,findProjectRoot,findUp,getWorkspacePackages,isMonorepo,parseYaml,readJson,resolveConfig,safeRename,tryImport});

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import{readdir as H}from"fs/promises";import P from"path";import T from"path";import{exec as W,execFile as U}from"child_process";import{randomUUID as Y}from"crypto";import{access as G,readFile as q,rename as L,rm as A,writeFile as z}from"fs/promises";import{dirname as S,join as C,parse as B,resolve as V}from"path";import{promisify as F}from"util";async function v(r){try{let s=await import("yaml").then(i=>i.default||i).catch(()=>null);if(s&&typeof s.parse=="function")return s.parse(r)}catch{}let t={},e=r.replace(/#.*$/gm,"").match(/packages:\s*\n((?:\s*-\s*.*\n?)*)/);if(e?.[1]){let s=[],i=/^\s*-\s*["']?([^"'\s]+)["']?/gm,a;for(;(a=i.exec(e[1]))!==null;)s.push(a[1]);t.packages=s}return t}var cr=F(W),pr=F(U),g=async r=>{try{return await G(r),!0}catch(t){if(t.code==="ENOENT")return!1;throw t}},w=new Map,R=200,N=async(r,t)=>{let o=V(r),e=`${o}:${[...t].sort().join(",")}`;if(w.has(e))return w.get(e);let s=o,{root:i}=B(s);for(;;){for(let a of t)if(await g(C(s,a)))return w.set(e,s),w.size>R&&w.clear(),s;if(s===i)break;s=S(s)}return w.set(e,null),w.size>R&&w.clear(),null},h=async(r,t={})=>{try{let o=await q(r,"utf-8");return JSON.parse(o)}catch(o){if(o.code==="ENOENT")return null;if(t.strict)throw o;return null}},D=async(r,t={})=>{if(!await g(r))return null;try{let o=await import("jiti"),s=(o.createJiti?o.createJiti(process.cwd()):o.default(process.cwd()))(r);return s.default??s}catch{try{let o=await import(r);return o.default??o}catch(o){if(t.strict)throw/\.(ts|mts)$/.test(r)?new Error(`Failed to load TypeScript config at ${r}. Install 'jiti' to load TS configs. Original error: ${o}`):o;return null}}},O=(r,t)=>{if(typeof r!="object"||r===null||typeof t!="object"||t===null||Array.isArray(r)&&Array.isArray(t))return t;let o={...r};for(let e of Object.keys(t))e==="__proto__"||e==="constructor"||e==="prototype"||Object.hasOwn(t,e)&&(o[e]=e in r?O(r[e],t[e]):t[e]);return o},lr=async(r,t)=>{let o=C(S(r),`${Y()}.tmp`);try{await z(o,t,"utf-8"),await X(o,r)}catch(e){throw await A(o,{force:!0}).catch(()=>{}),e}},X=async(r,t)=>{if(await g(r))try{await L(r,t)}catch(o){let e=o;if(e.code==="EEXIST"||e.code==="EPERM"){await A(t,{recursive:!0,force:!0}),await L(r,t);return}throw o}},I=r=>{if(r<1)throw new Error("createLimiter: concurrency must be >= 1");let t=0,o=[],e=()=>{t--,o.shift()?.()};return async s=>{t>=r&&await new Promise(i=>o.push(i)),t++;try{return await s()}finally{e()}}};var j=new Map,J=async(r=process.cwd())=>{let t=T.resolve(r);if(j.has(t))return j.get(t);let o=await N(t,[".git",".changeset","pnpm-workspace.yaml"]);if(o)return j.set(t,o),o;let e=T.resolve(r),{root:s}=T.parse(e);for(;;){let i=T.join(e,"package.json"),a=await h(i);if(a?.workspaces&&Array.isArray(a.workspaces))return j.set(t,e),e;if(e===s)break;e=T.dirname(e)}return j.set(t,t),t};var xr=async({name:r,cwd:t=process.cwd(),defaults:o={},envVars:e={},cliArgs:s={},configFile:i,strict:a=!1})=>{let x=await J(t),l=[];if(i)l.push(P.resolve(t,i));else{let n=P.resolve(t),f=new RegExp(`^${r}\\.config\\.(ts|mts|js|mjs|json)$`);for(;;){try{let k=(await H(n)).find(b=>f.test(b));k&&l.push(P.join(n,k))}catch{}if(n===x)break;let y=P.dirname(n);if(y===n)break;n=y}}let c=[];for(let n of l.reverse())if(n.endsWith(".json")){let f=await h(n,{strict:a});f&&c.push(f)}else{let f=await D(n,{strict:a});f&&c.push(f)}let m=O;try{let n=await import("defu");n?.defu&&(m=(f,y)=>n.defu(y,f))}catch{}let p=o;for(let n of c)p=m(p,n);return p=m(p,e),p=m(p,s),p},Tr=r=>r;import{createWriteStream as K}from"fs";import Q from"os";var d="\x1B[",E={gray:r=>`${d}90m${r}${d}39m`,blue:r=>`${d}34m${r}${d}39m`,yellow:r=>`${d}33m${r}${d}39m`,red:r=>`${d}31m${r}${d}39m`},M={debug:20,info:30,warn:40,error:50},_={debug:E.gray,info:E.blue,warn:E.yellow,error:E.red},$r=r=>{let t=M[r.level],o=r.logFormat??"text",e=r.name,s=e?{debug:`${e}:DEBUG`,info:`${e}:INFO`,warn:`${e}:WARN`,error:`${r.name}:ERROR`}:{debug:"DEBUG",info:"INFO",warn:"WARN",error:"ERROR"},i=null,a=!1,x=process.stdout.isTTY&&!process.env.NO_COLOR||!!process.env.FORCE_COLOR;if(r.logFile)try{i=K(r.logFile,{flags:"a"}),i.on("error",()=>{i=null})}catch{i=null}let l=()=>{if(!a&&(a=!0,i)){try{i.end()}catch{}i=null}};process.once("exit",l),process.once("SIGINT",()=>{l(),process.exit(0)}),process.once("SIGTERM",()=>{l(),process.exit(0)});let c=process.pid,m=Q.hostname(),p=(n,...f)=>{if(M[n]<t)return;let y=new Date().toISOString(),$=f.map(String).join(" "),k=o==="json"?JSON.stringify({ts:y,level:n,message:$,pid:c,hostname:m,name:e}):`[${y}] [${s[n]}] ${$}`,b=x&&_[n]?_[n](k):k;if((n==="warn"||n==="error"?process.stderr:process.stdout).write(`${b}
+`),i)try{i.write(`${k}
+`)}catch{i=null}};return{debug:(...n)=>p("debug",...n),info:(...n)=>p("info",...n),warn:(...n)=>p("warn",...n),error:(...n)=>p("error",...n),close:l}};import{readdir as Z,readFile as rr}from"fs/promises";import u from"path";var Rr=async r=>{let t=[],o=u.join(r,"package.json"),e=await h(o);e?.workspaces&&(Array.isArray(e.workspaces)?t.push(...e.workspaces):Array.isArray(e.workspaces.packages)&&t.push(...e.workspaces.packages));let s=u.join(r,"pnpm-workspace.yaml");if(await g(s))try{let l=await rr(s,"utf-8"),c=await v(l);c?.packages&&t.push(...c.packages)}catch{}let i=I(10),a=[],x=[...new Set(t)];return await Promise.all(x.map(l=>i(async()=>{if(l.endsWith("/*")){let c=u.join(r,l.slice(0,-2));if(await g(c))try{let m=await Z(c,{withFileTypes:!0});for(let p of m)p.isDirectory()&&await g(u.join(c,p.name,"package.json"))&&a.push(u.join(c,p.name))}catch{}}else{let c=u.join(r,l);await g(u.join(c,"package.json"))&&a.push(c)}}))),[...new Set(a)]},Ar=async(r=process.cwd())=>{let t=u.join(r,"package.json");return!!((await h(t))?.workspaces||await g(u.join(r,"pnpm-workspace.yaml")))};export{lr as atomicWrite,I as createLimiter,$r as createLogger,O as deepMerge,Tr as defineConfig,cr as execAsync,pr as execFileAsync,g as existsAsync,J as findProjectRoot,N as findUp,Rr as getWorkspacePackages,Ar as isMonorepo,v as parseYaml,h as readJson,xr as resolveConfig,X as safeRename,D as tryImport};

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@turboforge/cli-kit",
+  "author": "Mayank Kumar Chaudhari <https://mayankchaudhari.com>",
+  "private": false,
+  "version": "1.0.0",
+  "description": "Low-level utilities and configuration resolution for building high-performance CLI tools in monorepos.",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "forge": {
+    "icon": "Terminal",
+    "description": "CLI & Config Utilities",
+    "aliases": [
+      "@turbo-forge/cli-kit"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/turboforge-dev/turboforge",
+    "directory": "packages/cli-kit"
+  },
+  "bugs": "https://github.com/turboforge-dev/turboforge/issues",
+  "homepage": "https://github.com/turboforge-dev/turboforge/blob/main/packages/cli-kit/README.md",
+  "sideEffects": false,
+  "files": [
+    "dist/**"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "defu": "^6.1.4",
+    "jiti": "^2.6.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/turboforge-dev"
+    },
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/mayank1513"
+    }
+  ],
+  "peerDependencies": {
+    "defu": "^6.0.0",
+    "jiti": "^2.0.0",
+    "yaml": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "defu": {
+      "optional": true
+    },
+    "jiti": {
+      "optional": true
+    },
+    "yaml": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "turboforge",
+    "cli",
+    "monorepo",
+    "config-loader",
+    "workspace-detection",
+    "logger",
+    "typescript",
+    "node-js",
+    "tooling"
+  ],
+  "scripts": {
+    "build": "tsup && gzip -c dist/index.js | wc -c",
+    "clean": "rm -rf dist",
+    "dev": "tsup --watch"
+  }
+}