padrone 1.5.0 → 1.7.0

package/src/types/schema.ts

@@ -0,0 +1,19 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
+
+/**
+ * A schema that supports both validation (StandardSchemaV1) and JSON schema generation (StandardJSONSchemaV1).
+ * This is the type required for command arguments in Padrone.
+ */
+export type PadroneSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output> & StandardJSONSchemaV1<Input, Output>;
+
+/**
+ * A schema branded as async. When passed to `.arguments()`, `.configFile()`, or `.env()`,
+ * the command is automatically marked as async, causing `parse()` and `cli()` to return Promises.
+ *
+ * Use the `asyncSchema()` helper to brand an existing schema:
+ * ```ts
+ * import { asyncSchema } from 'padrone';
+ * const schema = asyncSchema(z.object({ name: z.string() }).check(async (v) => { ... }));
+ * ```
+ */
+export type AsyncPadroneSchema<Input = unknown, Output = Input> = PadroneSchema<Input, Output> & { '~async': true };

package/src/util/dotenv.ts

@@ -0,0 +1,244 @@
+// ── File resolution ─────────────────────────────────────────────────────
+
+/** Returns ordered list of `.env` file names to load (no fs access). */
+export function resolveEnvFiles(modes: string[] = [], local = true, base = true): string[] {
+  const files: string[] = [];
+  if (base) {
+    files.push('.env');
+    if (local) files.push('.env.local');
+  }
+  for (const mode of modes) {
+    files.push(`.env.${mode}`);
+    if (local) files.push(`.env.${mode}.local`);
+  }
+  return files;
+}
+
+// ── Parser ──────────────────────────────────────────────────────────────
+
+/** Parse a `.env` file string into key-value pairs. */
+export function parseEnvFile(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  const lines = content.split('\n');
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i]!.trim();
+    i++;
+
+    // Skip empty lines and comments
+    if (!line || line.startsWith('#')) continue;
+
+    // Strip optional `export ` prefix
+    const stripped = line.startsWith('export ') ? line.slice(7) : line;
+
+    const eqIndex = stripped.indexOf('=');
+    if (eqIndex === -1) continue;
+
+    const key = stripped.slice(0, eqIndex).trim();
+    let raw = stripped.slice(eqIndex + 1);
+
+    // Detect quoted values
+    const trimmedRaw = raw.trimStart();
+    const quote = trimmedRaw[0];
+
+    if (quote === '"' || quote === "'" || quote === '`') {
+      let value = trimmedRaw.slice(1);
+
+      // Check for closing quote on the same line
+      const closeIndex = findClosingQuote(value, quote);
+      if (closeIndex !== -1) {
+        value = value.slice(0, closeIndex);
+      } else {
+        // Multiline: accumulate until closing quote
+        while (i < lines.length) {
+          const nextLine = lines[i]!;
+          i++;
+          const ci = findClosingQuote(nextLine, quote);
+          if (ci !== -1) {
+            value += `\n${nextLine.slice(0, ci)}`;
+            break;
+          }
+          value += `\n${nextLine}`;
+        }
+      }
+
+      if (quote === '"') value = unescapeDoubleQuoted(value);
+      result[key] = value;
+    } else {
+      // Unquoted: strip inline comments, trim
+      const commentIndex = raw.indexOf(' #');
+      if (commentIndex !== -1) raw = raw.slice(0, commentIndex);
+      result[key] = raw.trim();
+    }
+  }
+
+  return result;
+}
+
+function findClosingQuote(s: string, quote: string): number {
+  let i = 0;
+  while (i < s.length) {
+    if (s[i] === '\\' && quote === '"') {
+      i += 2; // skip escaped char
+      continue;
+    }
+    if (s[i] === quote) return i;
+    i++;
+  }
+  return -1;
+}
+
+function unescapeDoubleQuoted(s: string): string {
+  return s.replace(/\\n/g, '\n').replace(/\\r/g, '\r').replace(/\\t/g, '\t').replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+}
+
+// ── Variable expansion ──────────────────────────────────────────────────
+
+/**
+ * Expand `$VAR`, `${VAR}`, `${VAR:-default}`, `${VAR-default}` in a string.
+ * Escaped `\$` produces a literal `$`. Undefined variables resolve to `""`.
+ */
+export function expandVariables(value: string, env: Record<string, string | undefined>): string {
+  let result = '';
+  let i = 0;
+
+  while (i < value.length) {
+    if (value[i] === '\\' && value[i + 1] === '$') {
+      result += '$';
+      i += 2;
+      continue;
+    }
+
+    if (value[i] === '$') {
+      i++;
+      if (i >= value.length) {
+        result += '$';
+        break;
+      }
+
+      if (value[i] === '{') {
+        // ${VAR}, ${VAR:-default}, ${VAR-default}
+        i++;
+        const closeIdx = value.indexOf('}', i);
+        if (closeIdx === -1) {
+          result += `\${${value.slice(i)}`;
+          break;
+        }
+
+        const expr = value.slice(i, closeIdx);
+        i = closeIdx + 1;
+
+        const colonDashIdx = expr.indexOf(':-');
+        const dashIdx = colonDashIdx === -1 ? expr.indexOf('-') : -1;
+
+        if (colonDashIdx !== -1) {
+          // ${VAR:-default} — use default if unset or empty
+          const varName = expr.slice(0, colonDashIdx);
+          const fallback = expr.slice(colonDashIdx + 2);
+          const val = env[varName];
+          result += val ? val : expandVariables(fallback, env);
+        } else if (dashIdx !== -1) {
+          // ${VAR-default} — use default only if unset
+          const varName = expr.slice(0, dashIdx);
+          const fallback = expr.slice(dashIdx + 1);
+          const val = env[varName];
+          result += val !== undefined ? val : expandVariables(fallback, env);
+        } else {
+          result += env[expr] ?? '';
+        }
+      } else {
+        // $VAR — collect word chars
+        let varName = '';
+        while (i < value.length && /[\w]/.test(value[i]!)) {
+          varName += value[i];
+          i++;
+        }
+        if (varName) {
+          result += env[varName] ?? '';
+        } else {
+          result += '$';
+        }
+      }
+      continue;
+    }
+
+    result += value[i];
+    i++;
+  }
+
+  return result;
+}
+
+// ── File loading ────────────────────────────────────────────────────────
+
+export type LoadEnvFilesOptions = {
+  dir?: string;
+  modes?: string[];
+  local?: boolean;
+  override?: boolean;
+  base?: boolean;
+};
+
+/**
+ * Load and merge `.env` files, returning the combined key-value map.
+ * Variable expansion uses the merged file values + process env as lookup.
+ *
+ * Returns synchronously when `node:fs`/`node:path` are already cached (typical),
+ * or a Promise on the very first call.
+ */
+export function loadEnvFiles(
+  options: LoadEnvFilesOptions,
+  processEnv: Record<string, string | undefined>,
+): Record<string, string> | Promise<Record<string, string>> {
+  if (typeof process === 'undefined') return {};
+
+  try {
+    if (_fs && _path) return loadEnvFilesSync(_fs, _path, options, processEnv);
+    return initNodeModules()
+      .then(() => loadEnvFilesSync(_fs!, _path!, options, processEnv))
+      .catch(() => ({}) as Record<string, string>);
+  } catch {
+    return {};
+  }
+}
+
+// ── Internals ───────────────────────────────────────────────────────────
+
+let _fs: typeof import('node:fs') | undefined;
+let _path: typeof import('node:path') | undefined;
+
+async function initNodeModules(): Promise<void> {
+  if (_fs && _path) return;
+  _fs = await import('node:fs');
+  _path = await import('node:path');
+}
+
+if (typeof process !== 'undefined') initNodeModules();
+
+function loadEnvFilesSync(
+  fs: typeof import('node:fs'),
+  path: typeof import('node:path'),
+  options: LoadEnvFilesOptions,
+  processEnv: Record<string, string | undefined>,
+): Record<string, string> {
+  const dir = options.dir ?? process.cwd();
+  const fileNames = resolveEnvFiles(options.modes, options.local ?? true, options.base ?? true);
+  const merged: Record<string, string> = {};
+
+  for (const name of fileNames) {
+    const filePath = path.resolve(dir, name);
+    if (!fs.existsSync(filePath)) continue;
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const parsed = parseEnvFile(content);
+    Object.assign(merged, parsed);
+  }
+
+  // Expand variables: file values + processEnv as lookup (processEnv wins in lookup unless override)
+  const lookup = options.override ? { ...processEnv, ...merged } : { ...merged, ...processEnv };
+  for (const key of Object.keys(merged)) {
+    merged[key] = expandVariables(merged[key]!, lookup);
+  }
+
+  return merged;
+}

package/src/{shell-utils.ts → util/shell-utils.ts}

@@ -1,10 +1,19 @@
+/**
+ * Convert a camelCase string to kebab-case.
+ * Returns null if the string has no uppercase letters (no conversion needed).
+ */
+export function camelToKebab(str: string): string | null {
+  if (!/[A-Z]/.test(str)) return null;
+  return str.replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`);
+}
+
 export type ShellType = 'bash' | 'zsh' | 'fish' | 'powershell';
 
 /**
  * Detects the current shell from environment variables and process info.
  * @returns The detected shell type, or undefined if unknown
  */
-export function detectShell(): ShellType | undefined {
+export async function detectShell(): Promise<ShellType | undefined> {
   if (typeof process === 'undefined') return undefined;
 
   // Method 1: Check SHELL environment variable (most common)
@@ -22,7 +31,7 @@ export function detectShell(): ShellType | undefined {
   try {
     const ppid = process.ppid;
     if (ppid) {
-      const { execSync } = require('node:child_process') as typeof import('node:child_process');
+      const { execSync } = (await import('node:child_process')) as typeof import('node:child_process');
       const processName = execSync(`ps -p ${ppid} -o comm=`, {
         encoding: 'utf-8',
         stdio: ['pipe', 'pipe', 'ignore'],
@@ -39,9 +48,9 @@ export function detectShell(): ShellType | undefined {
   return undefined;
 }
 
-export function getRcFile(shell: ShellType, home?: string): string | null {
-  const { homedir } = require('node:os') as typeof import('node:os');
-  const { join } = require('node:path') as typeof import('node:path');
+export async function getRcFile(shell: ShellType, home?: string): Promise<string | null> {
+  const { homedir } = await import('node:os');
+  const { join } = await import('node:path');
   const h = home ?? homedir();
   switch (shell) {
     case 'bash':
@@ -51,7 +60,10 @@ export function getRcFile(shell: ShellType, home?: string): string | null {
     case 'fish':
       return join(h, '.config', 'fish', 'config.fish');
     case 'powershell':
-      return process.env.PROFILE || join(h, 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1');
+      return (
+        (typeof process !== 'undefined' ? process.env.PROFILE : undefined) ||
+        join(h, 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1')
+      );
     default:
       return null;
   }
@@ -65,9 +77,14 @@ export function escapeRegExp(str: string): string {
  * Writes a snippet to a shell config file using begin/end markers for idempotency.
  * If a block with the same begin marker exists, it is replaced. Otherwise the snippet is appended.
  */
-export function writeToRcFile(rcFile: string, snippet: string, beginMarker: string, endMarker: string): { file: string; updated: boolean } {
-  const { existsSync, mkdirSync, readFileSync, writeFileSync } = require('node:fs') as typeof import('node:fs');
-  const { dirname } = require('node:path') as typeof import('node:path');
+export async function writeToRcFile(
+  rcFile: string,
+  snippet: string,
+  beginMarker: string,
+  endMarker: string,
+): Promise<{ file: string; updated: boolean }> {
+  const { existsSync, mkdirSync, readFileSync, writeFileSync } = await import('node:fs');
+  const { dirname } = await import('node:path');
   const existing = existsSync(rcFile) ? readFileSync(rcFile, 'utf-8') : '';
 
   if (existing.includes(beginMarker)) {

package/src/{stream.ts → util/stream.ts}

@@ -1,5 +1,5 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import type { PadroneSchema } from './types.ts';
+import type { PadroneSchema } from '../types/index.ts';
 
 export interface AsyncStreamMeta {
   [x: string]: unknown;
@@ -73,3 +73,29 @@ export function createStdinStream(stdin: StdinSource | undefined, itemSchema?: S
 const emptyAsyncIterable: AsyncIterable<never> = {
   async *[Symbol.asyncIterator]() {},
 };
+
+const textEncoder = /* @__PURE__ */ new TextEncoder();
+const textDecoder = /* @__PURE__ */ new TextDecoder();
+
+/** Concatenate multiple `Uint8Array` chunks into a single array. */
+export function concatBytes(chunks: Uint8Array[]): Uint8Array {
+  if (chunks.length === 1) return chunks[0]!;
+  let totalLength = 0;
+  for (const chunk of chunks) totalLength += chunk.byteLength;
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}
+
+/** Read an async iterable of chunks into a UTF-8 string. */
+export async function readStreamAsText(stream: AsyncIterable<Uint8Array | string>): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of stream) {
+    chunks.push(typeof chunk === 'string' ? textEncoder.encode(chunk) : chunk);
+  }
+  return textDecoder.decode(concatBytes(chunks));
+}

package/src/{type-helpers.ts → util/type-helpers.ts}

@@ -1,5 +1,11 @@
+import type {
+  AnyPadroneCommand,
+  AnyPadroneProgram,
+  PadroneCommand,
+  PadroneContextInterceptor,
+  PadroneInterceptorFn,
+} from '../types/index.ts';
 import type { PickCommandByName, PossibleCommands } from './type-utils.ts';
-import type { AnyPadroneCommand, AnyPadroneProgram, PadroneCommand, PadroneSchema } from './types.ts';
 
 /**
  * Extracts the input type of the arguments schema from a command.
@@ -20,43 +26,44 @@ export type InferArgsInput<T extends AnyPadroneCommand> = T['~types']['argsInput
 export type InferArgsOutput<T extends AnyPadroneCommand> = T['~types']['argsOutput'];
 
 /**
- * Extracts the input type of the config schema from a command.
+ * Extracts the user-defined context type from a command (excludes interceptor-provided context).
  * @example
  * ```ts
- * type Config = InferConfigInput<typeof myCommand>;
+ * type Ctx = InferContext<typeof myCommand>;
  * ```
  */
-export type InferConfigInput<T extends AnyPadroneCommand> = T['configSchema'] extends PadroneSchema<infer I, any> ? I : never;
+export type InferContext<T extends AnyPadroneCommand> = T['~types']['context'];
 
 /**
- * Extracts the output type of the config schema from a command.
- * This is the type after transformation, which should match the arguments shape.
+ * Extracts the interceptor-provided context type from a command.
  * @example
  * ```ts
- * type ConfigOutput = InferConfigOutput<typeof myCommand>;
+ * type Provided = InferContextProvided<typeof myCommand>;
  * ```
  */
-export type InferConfigOutput<T extends AnyPadroneCommand> = T['configSchema'] extends PadroneSchema<any, infer O> ? O : never;
+export type InferContextProvided<T extends AnyPadroneCommand> = T['~types']['contextProvided'];
 
 /**
- * Extracts the input type of the env schema from a command.
- * This represents the raw environment variables shape (e.g., { PORT: string }).
+ * Extracts the context type that a context-providing interceptor injects.
  * @example
  * ```ts
- * type EnvInput = InferEnvInput<typeof myCommand>;
+ * type AuthCtx = InferInterceptorContext<typeof withAuth>;
  * ```
  */
-export type InferEnvInput<T extends AnyPadroneCommand> = T['envSchema'] extends PadroneSchema<infer I, any> ? I : never;
+export type InferInterceptorContext<T extends PadroneContextInterceptor<any>> = T['~context'];
 
 /**
- * Extracts the output type of the env schema from a command.
- * This is the type after transformation, which should match the arguments shape.
+ * Extracts the required context type from an interceptor with `.requires()`.
  * @example
  * ```ts
- * type EnvOutput = InferEnvOutput<typeof myCommand>;
+ * type Requires = InferInterceptorRequires<typeof withAuth>;
  * ```
  */
-export type InferEnvOutput<T extends AnyPadroneCommand> = T['envSchema'] extends PadroneSchema<any, infer O> ? O : never;
+export type InferInterceptorRequires<T extends PadroneInterceptorFn & { '~contextRequires': any }> = T['~contextRequires'] extends (
+  ctx: infer R,
+) => void
+  ? R
+  : unknown;
 
 /**
  * Gets a command type by its path from a program or command tree.

package/src/{type-utils.ts → util/type-utils.ts}

@@ -1,4 +1,6 @@
-import type { AnyPadroneCommand, PadroneCommand } from './types.ts';
+import type { PadroneBuilder, PadroneProgram } from '../types/builder.ts';
+import type { AnyPadroneCommand, PadroneCommand } from '../types/index.ts';
+import type { PadroneSchema } from '../types/schema.ts';
 
 /**
  * Use this type instead of `any` when you intend to fix it later
@@ -137,40 +139,76 @@ type GetCommandPathsAndAliases<TCommand extends AnyPadroneCommand> = TCommand['~
 /**
  * Find a direct child command in a tuple by name.
  * Unlike PickCommandByName, this does NOT flatten — it only checks direct children by their `name` field.
+ * Uses indexed access (O(1) depth) instead of recursive tuple walking.
  */
-export type FindDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = TCommands extends [
-  infer First extends AnyPadroneCommand,
-  ...infer Rest extends AnyPadroneCommand[],
-]
-  ? First['~types']['name'] extends TName
-    ? First
-    : FindDirectChild<Rest, TName>
-  : never;
+export type FindDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = Extract<
+  TCommands[number],
+  { '~types': { name: TName } }
+>;
 
 /**
  * Replace a command in a tuple by name, or append if not found.
  * Used by `.command()` override semantics: re-registering a name replaces that entry.
+ * Uses mapped type (O(1) depth) instead of recursive tuple walking.
  */
 export type ReplaceOrAppendCommand<TCommands extends [...AnyPadroneCommand[]], TName extends string, TNew extends AnyPadroneCommand> =
   HasDirectChild<TCommands, TName> extends true ? ReplaceInTuple<TCommands, TName, TNew> : [...TCommands, TNew];
 
-type HasDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = TCommands extends [
-  infer First extends AnyPadroneCommand,
-  ...infer Rest extends AnyPadroneCommand[],
-]
-  ? First['~types']['name'] extends TName
-    ? true
-    : HasDirectChild<Rest, TName>
+type HasDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = TName extends TCommands[number]['~types']['name']
+  ? true
   : false;
 
-type ReplaceInTuple<TCommands extends AnyPadroneCommand[], TName extends string, TNew extends AnyPadroneCommand> = TCommands extends [
-  infer First extends AnyPadroneCommand,
-  ...infer Rest extends AnyPadroneCommand[],
-]
-  ? First['~types']['name'] extends TName
-    ? [TNew, ...Rest]
-    : [First, ...ReplaceInTuple<Rest, TName, TNew>]
-  : [];
+type ReplaceInTuple<TCommands extends AnyPadroneCommand[], TName extends string, TNew extends AnyPadroneCommand> = {
+  [K in keyof TCommands]: TCommands[K] extends AnyPadroneCommand
+    ? TCommands[K]['~types']['name'] extends TName
+      ? TNew
+      : TCommands[K]
+    : TCommands[K];
+};
+
+/**
+ * Utility type for extensions that add a command to a builder/program.
+ * Replaces the boilerplate `With*<T>` pattern used across all extension files.
+ */
+export type WithCommand<T, TName extends string, TCmd extends AnyPadroneCommand> = T extends {
+  '~types': {
+    programName: infer PN extends string;
+    name: infer N extends string;
+    parentName: infer PaN extends string;
+    argsSchema: infer A extends PadroneSchema;
+    result: infer R;
+    commands: infer C extends [...AnyPadroneCommand[]];
+    async: infer AS extends boolean;
+    context: infer CTX;
+    contextProvided: infer CTXP;
+  };
+}
+  ? T extends { run: any }
+    ? PadroneProgram<PN, N, PaN, A, R, ReplaceOrAppendCommand<C, TName, TCmd>, any, AS, CTX, CTXP>
+    : PadroneBuilder<PN, N, PaN, A, R, ReplaceOrAppendCommand<C, TName, TCmd>, any, AS, CTX, CTXP>
+  : T;
+
+/**
+ * Utility type for extensions that register a context-providing interceptor.
+ * Extends `TContextProvided` with `TProvides` while preserving all other builder/program type params.
+ */
+export type WithInterceptor<T, TProvides> = T extends {
+  '~types': {
+    programName: infer PN extends string;
+    name: infer N extends string;
+    parentName: infer PaN extends string;
+    argsSchema: infer A extends PadroneSchema;
+    result: infer R;
+    commands: infer C extends [...AnyPadroneCommand[]];
+    async: infer AS extends boolean;
+    context: infer CTX;
+    contextProvided: infer CTXP;
+  };
+}
+  ? T extends { run: any }
+    ? PadroneProgram<PN, N, PaN, A, R, C, any, AS, CTX, CTXP & TProvides>
+    : PadroneBuilder<PN, N, PaN, A, R, C, any, AS, CTX, CTXP & TProvides>
+  : T;
 
 export type PickCommandByName<
   TCommands extends AnyPadroneCommand[],
@@ -187,13 +225,13 @@ export type PickCommandByName<
 
 export type FlattenCommands<TCommands extends AnyPadroneCommand[]> = TCommands extends []
   ? never
-  : TCommands extends [infer FirstCommand, ...infer RestCommands]
-    ?
-        | (RestCommands extends AnyPadroneCommand[] ? FlattenCommands<RestCommands> : never)
-        | (FirstCommand extends AnyPadroneCommand ? FlattenCommands<FirstCommand['~types']['commands']> | FirstCommand : never)
-    : IsAny<TCommands[number]> extends true
+  : number extends TCommands['length']
+    ? IsAny<TCommands[number]> extends true
       ? never
-      : TCommands[number];
+      : TCommands[number]
+    : TCommands[number] extends infer Cmd extends AnyPadroneCommand
+      ? Cmd | FlattenCommands<Cmd['~types']['commands']>
+      : never;
 
 /**
  * Get all command paths including alias paths for all commands.
@@ -258,9 +296,9 @@ type RepathCommand<TCommand extends AnyPadroneCommand, TNewParentName extends st
   TCommand['~types']['result'],
   RepathCommands<TCommand['~types']['commands'], FullCommandName<TCommand['~types']['name'], TNewParentName>>,
   TCommand['~types']['aliases'],
-  TCommand['~types']['configSchema'],
-  TCommand['~types']['envSchema'],
-  TCommand['~types']['async']
+  TCommand['~types']['async'],
+  TCommand['~types']['context'],
+  TCommand['~types']['contextProvided']
 >;
 
 export type PickCommandByPossibleCommands<

package/src/util/utils.ts

@@ -0,0 +1,51 @@
+import type { AnyPadroneCommand } from '../types/index.ts';
+
+export function getRootCommand(cmd: AnyPadroneCommand): AnyPadroneCommand {
+  let current = cmd;
+  while (current.parent) current = current.parent;
+  return current;
+}
+
+async function readVersionFromPackageJson(): Promise<string> {
+  try {
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    let dir = process.cwd();
+
+    // Walk up the directory tree looking for package.json
+    for (let i = 0; i < 10; i++) {
+      const pkgPath = path.join(dir, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        if (pkg.version) return pkg.version;
+      }
+      const parentDir = path.dirname(dir);
+      if (parentDir === dir) break; // Reached root
+      dir = parentDir;
+    }
+  } catch {
+    // Ignore errors (e.g., fs not available in browser)
+  }
+  return '0.0.0';
+}
+
+/**
+ * Attempts to get the version from various sources:
+ * 1. Explicit version set on the command
+ * 2. npm_package_version environment variable (set by npm/yarn/pnpm when running scripts)
+ * 3. package.json in current or parent directories
+ *
+ * Returns synchronously when an explicit version or env var is available.
+ * Falls back to async package.json discovery otherwise.
+ */
+export function getVersion(explicitVersion?: string): string | Promise<string> {
+  if (explicitVersion) return explicitVersion;
+
+  if (typeof process !== 'undefined' && process.env?.npm_package_version) {
+    return process.env.npm_package_version;
+  }
+
+  if (typeof process !== 'undefined') return readVersionFromPackageJson();
+
+  return '0.0.0';
+}