padrone 1.1.0 → 1.2.0

package/src/update-check.ts

@@ -0,0 +1,244 @@
+import type { ResolvedPadroneRuntime } from './runtime.ts';
+
+/**
+ * Configuration for the update check feature.
+ */
+export type UpdateCheckConfig = {
+  /**
+   * The npm package name to check. Defaults to the program name.
+   */
+  packageName?: string;
+  /**
+   * Registry to check for updates.
+   * - `'npm'` — checks the npm registry (default)
+   * - A URL string — custom registry endpoint that returns JSON with a `version` or `dist-tags.latest` field
+   */
+  registry?: 'npm' | string;
+  /**
+   * How often to check for updates. Accepts shorthand like `'1d'`, `'12h'`, `'30m'`.
+   * Defaults to `'1d'` (once per day).
+   */
+  interval?: string;
+  /**
+   * Path to the cache file for storing the last check timestamp and latest version.
+   * Defaults to `~/.config/<programName>-update-check.json`.
+   */
+  cache?: string;
+  /**
+   * Environment variable name to disable update checks (e.g. `'MYAPP_NO_UPDATE_CHECK'`).
+   * When set to a truthy value, update checks are skipped.
+   * Defaults to `'<PROGRAM_NAME>_NO_UPDATE_CHECK'` (uppercased, hyphens to underscores).
+   */
+  disableEnvVar?: string;
+};
+
+type CacheData = {
+  lastCheck: number;
+  latestVersion: string;
+};
+
+/**
+ * Parses an interval string like '1d', '12h', '30m', '1w' into milliseconds.
+ */
+export function parseInterval(interval: string): number {
+  const match = interval.match(/^(\d+)\s*(ms|s|m|h|d|w)$/);
+  if (!match) return 86_400_000; // default 1d
+
+  const value = parseInt(match[1]!, 10);
+  const unit = match[2]!;
+
+  switch (unit) {
+    case 'ms':
+      return value;
+    case 's':
+      return value * 1000;
+    case 'm':
+      return value * 60_000;
+    case 'h':
+      return value * 3_600_000;
+    case 'd':
+      return value * 86_400_000;
+    case 'w':
+      return value * 604_800_000;
+    default:
+      return 86_400_000;
+  }
+}
+
+/**
+ * Compares two semver version strings.
+ * Returns true if `latest` is newer than `current`.
+ */
+export function isNewerVersion(current: string, latest: string): boolean {
+  const parse = (v: string) => {
+    const cleaned = v.replace(/^v/, '');
+    const parts = cleaned.split('-');
+    const nums = parts[0]!.split('.').map(Number);
+    return { major: nums[0] ?? 0, minor: nums[1] ?? 0, patch: nums[2] ?? 0, prerelease: parts[1] };
+  };
+
+  const c = parse(current);
+  const l = parse(latest);
+
+  // Don't notify about pre-release versions unless user is already on a pre-release
+  if (l.prerelease && !c.prerelease) return false;
+
+  if (l.major !== c.major) return l.major > c.major;
+  if (l.minor !== c.minor) return l.minor > c.minor;
+  if (l.patch !== c.patch) return l.patch > c.patch;
+  return false;
+}
+
+/**
+ * Reads the update check cache file.
+ */
+function readCache(cachePath: string): CacheData | undefined {
+  try {
+    const { existsSync, readFileSync } = require('node:fs') as typeof import('node:fs');
+    if (!existsSync(cachePath)) return undefined;
+    const data = JSON.parse(readFileSync(cachePath, 'utf-8'));
+    if (typeof data.lastCheck === 'number' && typeof data.latestVersion === 'string') {
+      return data as CacheData;
+    }
+  } catch {
+    // Ignore errors
+  }
+  return undefined;
+}
+
+/**
+ * Writes the update check cache file.
+ */
+function writeCache(cachePath: string, data: CacheData): void {
+  try {
+    const { existsSync, mkdirSync, writeFileSync } = require('node:fs') as typeof import('node:fs');
+    const { dirname } = require('node:path') as typeof import('node:path');
+    const dir = dirname(cachePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(cachePath, JSON.stringify(data), 'utf-8');
+  } catch {
+    // Ignore errors — cache is best-effort
+  }
+}
+
+/**
+ * Resolves the cache path, expanding `~` to the home directory.
+ */
+function resolveCachePath(cachePath: string): string {
+  const { homedir } = require('node:os') as typeof import('node:os');
+  const { resolve } = require('node:path') as typeof import('node:path');
+  if (cachePath.startsWith('~')) {
+    return cachePath.replace('~', homedir());
+  }
+  return resolve(cachePath);
+}
+
+/**
+ * Fetches the latest version from the registry.
+ */
+async function fetchLatestVersion(packageName: string, registry: string): Promise<string | undefined> {
+  const url = registry === 'npm' ? `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest` : registry;
+
+  try {
+    const response = await fetch(url);
+    if (!response.ok) return undefined;
+    const data = (await response.json()) as Record<string, unknown>;
+
+    // npm registry returns { version: "x.y.z" }
+    if (typeof data.version === 'string') return data.version;
+
+    // Custom endpoint may return { "dist-tags": { latest: "x.y.z" } }
+    const distTags = data['dist-tags'] as Record<string, string> | undefined;
+    if (distTags?.latest) return distTags.latest;
+  } catch {
+    // Network errors are expected (offline, firewall, etc.)
+  }
+  return undefined;
+}
+
+/**
+ * Formats the update notification message.
+ */
+export function formatUpdateMessage(currentVersion: string, latestVersion: string, packageName: string): string {
+  const updateCommand = `npm update -g ${packageName}`;
+  return `\n  Update available: ${currentVersion} \u2192 ${latestVersion}\n  Run "${updateCommand}" to update\n`;
+}
+
+/**
+ * Checks for updates in the background. Returns a function that, when called,
+ * prints the update notification if a newer version was found.
+ *
+ * This is designed to be non-blocking: the check starts immediately but the
+ * result is only consumed after command execution completes.
+ */
+export function createUpdateChecker(
+  programName: string,
+  currentVersion: string,
+  config: UpdateCheckConfig,
+  runtime: ResolvedPadroneRuntime,
+): () => void {
+  const packageName = config.packageName ?? programName;
+  const registry = config.registry ?? 'npm';
+  const intervalMs = parseInterval(config.interval ?? '1d');
+  const disableEnvVar = config.disableEnvVar ?? `${programName.toUpperCase().replace(/-/g, '_')}_NO_UPDATE_CHECK`;
+
+  const defaultCachePath = `~/.config/${programName}-update-check.json`;
+  const cachePath = resolveCachePath(config.cache ?? defaultCachePath);
+
+  // Check if disabled
+  const env = runtime.env();
+  if (env.CI || env.CONTINUOUS_INTEGRATION) return noop;
+  if (env[disableEnvVar]) return noop;
+  if (typeof process !== 'undefined' && !process.stdout?.isTTY) return noop;
+
+  // Check cache — if we checked recently, use cached result
+  const cached = readCache(cachePath);
+  if (cached && Date.now() - cached.lastCheck < intervalMs) {
+    // Use cached version for display
+    if (isNewerVersion(currentVersion, cached.latestVersion)) {
+      return () => {
+        runtime.error(formatUpdateMessage(currentVersion, cached.latestVersion, packageName));
+      };
+    }
+    return noop;
+  }
+
+  // Start background fetch
+  const fetchPromise = fetchLatestVersion(packageName, registry).then((latestVersion) => {
+    if (latestVersion) {
+      writeCache(cachePath, { lastCheck: Date.now(), latestVersion });
+      if (isNewerVersion(currentVersion, latestVersion)) {
+        return latestVersion;
+      }
+    }
+    return undefined;
+  });
+
+  // Return a function that blocks on the result (briefly — the fetch should be done by now)
+  let resolved: string | undefined | null = null; // null = not yet resolved
+  fetchPromise.then(
+    (v) => {
+      resolved = v;
+    },
+    () => {
+      resolved = undefined;
+    },
+  );
+
+  return () => {
+    // If the fetch already resolved, use the result synchronously
+    if (resolved !== null) {
+      if (resolved) {
+        runtime.error(formatUpdateMessage(currentVersion, resolved, packageName));
+      }
+      return;
+    }
+
+    // Otherwise, we can't block — just skip this time.
+    // The cache will be written when the promise resolves, so next invocation will show the message.
+  };
+}
+
+function noop() {}

package/src/wrap.ts

@@ -1,16 +1,17 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { ValidationError } from './errors.ts';
 import type { PadroneSchema } from './types.ts';
 
 /**
- * Configuration options for wrapping an external CLI tool.
+ * Configuration for wrapping an external CLI tool.
  */
-export type WrapConfig<TCommandOpts extends PadroneSchema = PadroneSchema, TWrapOpts extends PadroneSchema = TCommandOpts> = {
+export type WrapConfig<TCommandArgs extends PadroneSchema = PadroneSchema, TWrapArgs extends PadroneSchema = TCommandArgs> = {
   /**
    * The command to execute (e.g., 'git', 'docker', 'npm').
    */
   command: string;
   /**
-   * Optional fixed arguments that always precede the options (e.g., ['commit'] for 'git commit').
+   * Optional fixed arguments that always precede the arguments (e.g., ['commit'] for 'git commit').
    */
   args?: string[];
   /**
@@ -24,12 +25,12 @@ export type WrapConfig<TCommandOpts extends PadroneSchema = PadroneSchema, TWrap
    */
   inheritStdio?: boolean;
   /**
-   * Optional schema that transforms command options to external CLI arguments.
-   * The schema's input type should match the command options, and its output type defines
+   * Optional schema that transforms command arguments to external CLI arguments.
+   * The schema's input type should match the command arguments, and its output type defines
    * the arguments expected by the external command.
-   * If not provided, command options are passed through as-is.
+   * If not provided, command arguments are passed through as-is.
    */
-  schema?: TWrapOpts | ((commandOptions: TCommandOpts) => TWrapOpts);
+  schema?: TWrapArgs | ((commandArguments: TCommandArgs) => TWrapArgs);
 };
 
 /**
@@ -55,28 +56,28 @@ export type WrapResult = {
 };
 
 /**
- * Converts parsed options to CLI arguments for an external command.
+ * Converts parsed arguments to CLI arguments for an external command.
  */
-function optionsToArgs(options: Record<string, unknown> | undefined, positional: string[] = []): string[] {
+function argsToCliArgs(input: Record<string, unknown> | undefined, positional: string[] = []): string[] {
   const args: string[] = [];
 
-  // Handle undefined or null options
-  if (!options) return args;
+  // Handle undefined or null input
+  if (!input) return args;
 
   const positionalValues: Record<string, unknown> = {};
-  const regularOptions: Record<string, unknown> = {};
+  const regularArguments: Record<string, unknown> = {};
 
-  // Separate positional and regular options
-  for (const [key, value] of Object.entries(options)) {
+  // Separate positional and regular arguments
+  for (const [key, value] of Object.entries(input)) {
     if (positional.includes(key) || positional.includes(`...${key}`)) {
       positionalValues[key] = value;
     } else {
-      regularOptions[key] = value;
+      regularArguments[key] = value;
     }
   }
 
-  // Add regular options first
-  for (const [key, value] of Object.entries(regularOptions)) {
+  // Add regular arguments first
+  for (const [key, value] of Object.entries(regularArguments)) {
     if (value === undefined || value === null) continue;
 
     // Use the key as-is with -- prefix
@@ -115,38 +116,41 @@ function optionsToArgs(options: Record<string, unknown> | undefined, positional:
 /**
  * Creates an action handler that wraps an external CLI tool.
  * @param config - Configuration for wrapping the external command (includes optional schema)
- * @param commandOptions - The command's options schema
+ * @param commandArguments - The command's arguments schema
  * @param commandPositional - Default positional config from the wrapping command
  */
-export function createWrapHandler<TCommandOpts extends PadroneSchema, TWrapOpts extends PadroneSchema>(
-  config: WrapConfig<TCommandOpts, TWrapOpts>,
-  commandOptions: TCommandOpts,
+export function createWrapHandler<TCommandArgs extends PadroneSchema, TWrapArgs extends PadroneSchema>(
+  config: WrapConfig<TCommandArgs, TWrapArgs>,
+  commandArguments: TCommandArgs,
   commandPositional?: string[],
-): (options: StandardSchemaV1.InferOutput<TCommandOpts>) => Promise<WrapResult> {
-  return async (options: StandardSchemaV1.InferOutput<TCommandOpts>): Promise<WrapResult> => {
+): (args: StandardSchemaV1.InferOutput<TCommandArgs>) => Promise<WrapResult> {
+  return async (args: StandardSchemaV1.InferOutput<TCommandArgs>): Promise<WrapResult> => {
     const { command, args: fixedArgs = [], inheritStdio = true, positional = commandPositional, schema: wrapSchema } = config;
 
     // Get the wrap schema (handle function or direct schema)
-    const schema = wrapSchema ? (typeof wrapSchema === 'function' ? wrapSchema(commandOptions) : wrapSchema) : commandOptions;
+    const schema = wrapSchema ? (typeof wrapSchema === 'function' ? wrapSchema(commandArguments) : wrapSchema) : commandArguments;
 
-    // Transform command options to external CLI options using the wrap schema
-    const result = schema['~standard'].validate(options);
-    if (result instanceof Promise) {
-      throw new Error('Async validation is not supported. Wrap schema validate() must return a synchronous result.');
-    }
-    if (result.issues) {
-      const issueMessages = result.issues
-        .map((i) => `  - ${(i.path as (string | number)[] | undefined)?.join('.') || 'root'}: ${i.message}`)
-        .join('\n');
-      throw new Error(`Wrap schema validation failed:\n${issueMessages}`);
-    }
-    const externalOptions = result.value;
+    // Transform command arguments to external CLI arguments using the wrap schema
+    const validationResult = schema['~standard'].validate(args);
+
+    const processResult = (result: StandardSchemaV1.Result<unknown>) => {
+      if (result.issues) {
+        const issueMessages = result.issues
+          .map((i: StandardSchemaV1.Issue) => `  - ${(i.path as (string | number)[] | undefined)?.join('.') || 'root'}: ${i.message}`)
+          .join('\n');
+        throw new ValidationError(`Wrap schema validation failed:\n${issueMessages}`, result.issues as any);
+      }
+      return result.value;
+    };
+
+    const externalArguments =
+      validationResult instanceof Promise ? await validationResult.then(processResult) : processResult(validationResult);
 
-    // Convert options to CLI arguments
-    const optionArgs = optionsToArgs(externalOptions as Record<string, unknown>, positional);
+    // Convert arguments to CLI arguments
+    const regularArgs = argsToCliArgs(externalArguments as Record<string, unknown>, positional);
 
-    // Combine fixed args and option args
-    const allArgs = [...fixedArgs, ...optionArgs];
+    // Combine fixed args and regular args
+    const allArgs = [...fixedArgs, ...regularArgs];
 
     // Execute the external command
     const proc = Bun.spawn([command, ...allArgs], {

package/src/zod.d.ts

@@ -1,5 +1,5 @@
-import type { PadroneOptionsMeta } from './options.ts';
+import type { PadroneFieldMeta } from './args.ts';
 
 declare module 'zod/v4/core' {
-  export interface GlobalMeta extends PadroneOptionsMeta {}
+  export interface GlobalMeta extends PadroneFieldMeta {}
 }

package/src/options.ts

@@ -1,180 +0,0 @@
-import type { StandardJSONSchemaV1 } from '@standard-schema/spec';
-
-export interface PadroneOptionsMeta {
-  description?: string;
-  alias?: string[] | string;
-  deprecated?: boolean | string;
-  hidden?: boolean;
-  examples?: unknown[];
-}
-
-type PositionalArgs<TObj> =
-  TObj extends Record<string, any>
-    ? {
-        [K in keyof TObj]: TObj[K] extends Array<any> ? `...${K & string}` : K & string;
-      }[keyof TObj]
-    : string;
-
-/**
- * Meta configuration for options including positional arguments.
- * The `positional` array defines which options are positional arguments and their order.
- * Use '...name' prefix to indicate variadic (rest) arguments, matching JS/TS rest syntax.
- *
- * @example
- * ```ts
- * .arguments(schema, {
- *   positional: ['source', '...files', 'dest'],  // '...files' is variadic
- * })
- * ```
- */
-export interface PadroneMeta<TObj = Record<string, any>> {
-  /**
-   * Array of option names that should be treated as positional arguments.
-   * Order in array determines position. Use '...name' prefix for variadic args.
-   * @example ['source', '...files', 'dest'] - 'files' captures multiple values
-   */
-  positional?: PositionalArgs<TObj>[];
-  /**
-   * Per-option metadata.
-   */
-  options?: { [K in keyof TObj]?: PadroneOptionsMeta };
-}
-
-/**
- * Parse positional configuration to extract names and variadic info.
- */
-export function parsePositionalConfig(positional: string[]): { name: string; variadic: boolean }[] {
-  return positional.map((p) => {
-    const isVariadic = p.startsWith('...');
-    const name = isVariadic ? p.slice(3) : p;
-    return { name, variadic: isVariadic };
-  });
-}
-
-/**
- * Result type for extractSchemaMetadata function.
- */
-interface SchemaMetadataResult {
-  aliases: Record<string, string>;
-}
-
-/**
- * Extract all option metadata from schema and meta in a single pass.
- * This consolidates aliases, env bindings, and config keys extraction.
- */
-export function extractSchemaMetadata(
-  schema: StandardJSONSchemaV1,
-  meta?: Record<string, PadroneOptionsMeta | undefined>,
-): SchemaMetadataResult {
-  const aliases: Record<string, string> = {};
-
-  // Extract from meta object
-  if (meta) {
-    for (const [key, value] of Object.entries(meta)) {
-      if (!value) continue;
-
-      // Extract aliases
-      if (value.alias) {
-        const list = typeof value.alias === 'string' ? [value.alias] : value.alias;
-        for (const aliasKey of list) {
-          if (typeof aliasKey === 'string' && aliasKey && aliasKey !== key) {
-            aliases[aliasKey] = key;
-          }
-        }
-      }
-    }
-  }
-
-  // Extract from JSON schema properties
-  try {
-    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
-    if (jsonSchema.type === 'object' && jsonSchema.properties) {
-      for (const [propertyName, propertySchema] of Object.entries(jsonSchema.properties as Record<string, any>)) {
-        if (!propertySchema) continue;
-
-        // Extract aliases from schema
-        const propAlias = propertySchema.alias;
-        if (propAlias) {
-          const list = typeof propAlias === 'string' ? [propAlias] : propAlias;
-          if (Array.isArray(list)) {
-            for (const aliasKey of list) {
-              if (typeof aliasKey === 'string' && aliasKey && aliasKey !== propertyName && !(aliasKey in aliases)) {
-                aliases[aliasKey] = propertyName;
-              }
-            }
-          }
-        }
-      }
-    }
-  } catch {
-    // Ignore errors from JSON schema generation
-  }
-
-  return { aliases };
-}
-
-function preprocessAliases(data: Record<string, unknown>, aliases: Record<string, string>): Record<string, unknown> {
-  const result = { ...data };
-
-  for (const [aliasKey, fullOptionName] of Object.entries(aliases)) {
-    if (aliasKey in data && aliasKey !== fullOptionName) {
-      const aliasValue = data[aliasKey];
-      // Prefer full option name if it exists
-      if (!(fullOptionName in result)) result[fullOptionName] = aliasValue;
-      delete result[aliasKey];
-    }
-  }
-
-  return result;
-}
-
-interface ParseOptionsContext {
-  aliases?: Record<string, string>;
-  envData?: Record<string, unknown>;
-  configData?: Record<string, unknown>;
-}
-
-/**
- * Apply values directly to options.
- * CLI values take precedence over the provided values.
- */
-function applyValues(data: Record<string, unknown>, values: Record<string, unknown>): Record<string, unknown> {
-  const result = { ...data };
-
-  for (const [key, value] of Object.entries(values)) {
-    // Only apply value if option wasn't already set
-    if (key in result && result[key] !== undefined) continue;
-    if (value !== undefined) {
-      result[key] = value;
-    }
-  }
-
-  return result;
-}
-
-/**
- * Combined preprocessing of options with all features.
- * Precedence order (highest to lowest): CLI args > env vars > config file
- */
-export function preprocessOptions(data: Record<string, unknown>, ctx: ParseOptionsContext): Record<string, unknown> {
-  let result = { ...data };
-
-  // 1. Apply aliases first
-  if (ctx.aliases && Object.keys(ctx.aliases).length > 0) {
-    result = preprocessAliases(result, ctx.aliases);
-  }
-
-  // 2. Apply environment variables (higher precedence than config)
-  // These only apply if CLI didn't set the option
-  if (ctx.envData) {
-    result = applyValues(result, ctx.envData);
-  }
-
-  // 3. Apply config file values (lowest precedence)
-  // These only apply if neither CLI nor env set the option
-  if (ctx.configData) {
-    result = applyValues(result, ctx.configData);
-  }
-
-  return result;
-}