padrone 1.4.0 → 1.6.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/util/stream.ts

@@ -0,0 +1,101 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { PadroneSchema } from '../types/index.ts';
+
+export interface AsyncStreamMeta {
+  [x: string]: unknown;
+  readonly asyncStream: number;
+  readonly itemSchema?: StandardSchemaV1;
+}
+
+let asyncStreamIdCounter = 1;
+export const asyncStreamRegistry = new Map<number, AsyncStreamMeta>();
+
+/**
+ * Returns metadata to mark a schema field as an async stream via `.meta()`.
+ *
+ * When used with `stdin`, padrone pipes stdin data as an `AsyncIterable` instead of
+ * buffering it. Each line is validated against the item schema (if provided) as it arrives.
+ *
+ * @param itemSchema - Optional item schema for per-item validation.
+ *   Non-string schemas cause each stdin line to be `JSON.parse`'d before validation.
+ *
+ * @example
+ * ```ts
+ * import { asyncStream } from 'padrone';
+ *
+ * // String lines
+ * z.object({ lines: z.custom<AsyncIterable<string>>().meta(asyncStream()) })
+ *
+ * // Typed items — each line JSON.parse'd and validated
+ * z.object({ records: z.custom<AsyncIterable<{ name: string }>>().meta(asyncStream(recordSchema)) })
+ * ```
+ */
+export function asyncStream<T = string>(itemSchema?: PadroneSchema<T>): AsyncStreamMeta {
+  const id = asyncStreamIdCounter++;
+  const meta: AsyncStreamMeta = itemSchema ? { asyncStream: id, itemSchema } : { asyncStream: id };
+  asyncStreamRegistry.set(id, meta);
+  return meta;
+}
+
+/** Stdin interface matching PadroneRuntime.stdin */
+interface StdinSource {
+  isTTY?: boolean;
+  text(): Promise<string>;
+  lines(): AsyncIterable<string>;
+}
+
+/**
+ * Creates an `AsyncIterable` from a stdin source, optionally validating each item.
+ * When no stdin is available (TTY / undefined), yields nothing.
+ *
+ * - No item schema: yields raw string lines
+ * - With item schema: `JSON.parse`s each line, validates, then yields
+ */
+export function createStdinStream(stdin: StdinSource | undefined, itemSchema?: StandardSchemaV1): AsyncIterable<unknown> {
+  if (!stdin) return emptyAsyncIterable;
+
+  if (!itemSchema) return stdin.lines();
+
+  return {
+    async *[Symbol.asyncIterator]() {
+      for await (const line of stdin.lines()) {
+        const result = itemSchema['~standard'].validate(line);
+        const resolved = result instanceof Promise ? await result : result;
+        if ('issues' in resolved && resolved.issues) {
+          throw new Error(`Stream item validation failed: ${resolved.issues.map((i) => i.message).join(', ')}`);
+        }
+        yield (resolved as { value: unknown }).value;
+      }
+    },
+  };
+}
+
+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.