padrone 1.4.0 → 1.6.0

package/src/core/interceptors.ts

@@ -0,0 +1,302 @@
+import type {
+  AnyPadroneCommand,
+  AnyPadroneProgram,
+  InterceptorDefBuilder,
+  InterceptorErrorContext,
+  InterceptorErrorResult,
+  InterceptorFactory,
+  InterceptorMeta,
+  InterceptorShutdownContext,
+  InterceptorStartContext,
+  PadroneInterceptorFn,
+  RegisteredInterceptor,
+  ResolvedInterceptor,
+} from '../types/index.ts';
+import { thenMaybe } from './results.ts';
+import type { ResolvedPadroneRuntime } from './runtime.ts';
+
+// ---------------------------------------------------------------------------
+// defineInterceptor — creates a single-value distributable interceptor
+// ---------------------------------------------------------------------------
+
+function buildInterceptorFn(meta: InterceptorMeta, factory: InterceptorFactory<any, any, any>): PadroneInterceptorFn<any, any, any> {
+  Object.defineProperty(factory, 'name', { value: meta.name, configurable: true });
+  if (meta.id !== undefined) (factory as any).id = meta.id;
+  if (meta.order !== undefined) (factory as any).order = meta.order;
+  if (meta.disabled !== undefined) (factory as any).disabled = meta.disabled;
+  if (meta.inherit !== undefined) (factory as any).inherit = meta.inherit;
+  (factory as any).provides = () => factory;
+  (factory as any).requires = () => factory;
+  return factory as PadroneInterceptorFn<any, any, any>;
+}
+
+/**
+ * Creates a self-contained interceptor value by attaching static metadata to the factory function.
+ * The returned value can be passed directly to `.intercept()` or exported from a package.
+ *
+ * Two-arg form — define metadata and factory in one call:
+ * ```ts
+ * export const myInterceptor = defineInterceptor(
+ *   { name: 'my-interceptor', order: 10 },
+ *   () => ({
+ *     execute(ctx, next) { return next(); },
+ *   }),
+ * );
+ * ```
+ *
+ * Single-arg form — chain `.requires<T>()` for typed context, then `.factory()`:
+ * ```ts
+ * export const myInterceptor = defineInterceptor({ name: 'with-db' })
+ *   .requires<{ db: DB }>()
+ *   .factory(() => ({
+ *     execute(ctx, next) {
+ *       ctx.context.db; // typed!
+ *       return next();
+ *     },
+ *   }));
+ * ```
+ */
+export function defineInterceptor<TArgs = unknown, TResult = unknown>(
+  meta: InterceptorMeta,
+  factory: InterceptorFactory<TArgs, TResult>,
+): PadroneInterceptorFn<TArgs, TResult>;
+export function defineInterceptor(meta: InterceptorMeta): InterceptorDefBuilder;
+export function defineInterceptor(
+  meta: InterceptorMeta,
+  factory?: InterceptorFactory<any, any, any>,
+): PadroneInterceptorFn<any, any, any> | InterceptorDefBuilder {
+  if (factory) return buildInterceptorFn(meta, factory);
+  const builder: InterceptorDefBuilder = {
+    requires: () => builder as any,
+    factory: (f) => buildInterceptorFn(meta, f) as any,
+  };
+  return builder;
+}
+
+// ---------------------------------------------------------------------------
+// Registration normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalizes an interceptor input (single-value form or two-arg form) into the internal
+ * `RegisteredInterceptor` storage format.
+ */
+export function toRegisteredInterceptor(
+  metaOrFn: InterceptorMeta | PadroneInterceptorFn<any, any, any>,
+  factory?: InterceptorFactory<any, any, any>,
+): RegisteredInterceptor {
+  if (typeof metaOrFn === 'function') {
+    // Single-value form: PadroneInterceptorFn (factory with meta as own properties)
+    return {
+      meta: { name: metaOrFn.name, id: metaOrFn.id, order: metaOrFn.order, disabled: metaOrFn.disabled, inherit: metaOrFn.inherit },
+      factory: metaOrFn,
+    };
+  }
+  // Two-arg form: (meta, factory)
+  return { meta: metaOrFn, factory: factory! };
+}
+
+// ---------------------------------------------------------------------------
+// Factory resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves registered interceptors by calling their factories and merging the resulting
+ * phase handlers with the static metadata. Uses a cache to ensure each factory is called
+ * at most once per execution (so root interceptor closures are shared across all phases).
+ */
+export function resolveRegisteredInterceptors(
+  registered: RegisteredInterceptor[],
+  cache: Map<RegisteredInterceptor, ResolvedInterceptor>,
+): ResolvedInterceptor[] {
+  return registered.map((reg) => {
+    let resolved = cache.get(reg);
+    if (!resolved) {
+      resolved = { ...reg.meta, ...reg.factory() };
+      cache.set(reg, resolved);
+    }
+    return resolved;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Interceptor chain runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Deduplicates interceptors by `id`. When multiple interceptors share the same `id`,
+ * only the last one in the array is kept. Interceptors without an `id` are always kept.
+ */
+function deduplicateInterceptors(interceptors: ResolvedInterceptor[]): ResolvedInterceptor[] {
+  // Fast path: no ids at all
+  if (!interceptors.some((p) => p.id)) return interceptors;
+
+  // Find the last index for each id
+  const lastIndex = new Map<string, number>();
+  for (let i = 0; i < interceptors.length; i++) {
+    const id = interceptors[i]!.id;
+    if (id) lastIndex.set(id, i);
+  }
+
+  return interceptors.filter((p, i) => !p.id || lastIndex.get(p.id) === i);
+}
+
+/**
+ * Runs an interceptor chain for a given phase using the onion/middleware pattern.
+ * Interceptors are sorted by `order` (ascending, stable), then composed so that
+ * the first interceptor in sorted order is the outermost wrapper.
+ * If no interceptors handle this phase, `core` is called directly.
+ *
+ * Each interceptor's `next()` accepts optional partial overrides that are merged
+ * into the context before passing to the next interceptor or core function.
+ */
+export function runInterceptorChain<TCtx extends object, TResult>(
+  phase: 'start' | 'parse' | 'validate' | 'execute' | 'error' | 'shutdown',
+  interceptors: ResolvedInterceptor[],
+  ctx: TCtx,
+  core: (ctx: TCtx) => TResult | Promise<TResult>,
+): TResult | Promise<TResult> {
+  // Deduplicate by id (last wins), then filter to enabled interceptors that have a handler for this phase
+  const deduped = deduplicateInterceptors(interceptors);
+  const phaseInterceptors = deduped.filter((p) => p[phase] && !p.disabled);
+  if (phaseInterceptors.length === 0) return core(ctx);
+
+  // Stable sort by order (lower = outermost). Equal order preserves registration order.
+  phaseInterceptors.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+
+  // Build chain from inside out: last interceptor wraps core, first interceptor is outermost
+  let next: (currentCtx: TCtx) => TResult | Promise<TResult> = core;
+  for (let i = phaseInterceptors.length - 1; i >= 0; i--) {
+    const handler = phaseInterceptors[i]![phase]! as unknown as (
+      ctx: TCtx,
+      next: (overrides?: Record<string, unknown>) => TResult | Promise<TResult>,
+    ) => TResult | Promise<TResult>;
+    const prevNext = next;
+    next = (currentCtx: TCtx) =>
+      handler(currentCtx, (overrides?: Record<string, unknown>) =>
+        prevNext(overrides ? (Object.assign({}, currentCtx, overrides) as TCtx) : currentCtx),
+      );
+  }
+
+  return next(ctx);
+}
+
+/**
+ * Wraps a pipeline with start → error → shutdown lifecycle hooks.
+ * - `start` interceptors wrap the pipeline (onion pattern, root interceptors only).
+ * - On error: `error` interceptors run (can transform/suppress the error).
+ * - Always: `shutdown` interceptors run (success or failure).
+ */
+export function wrapWithLifecycle<T>(
+  interceptors: ResolvedInterceptor[],
+  command: AnyPadroneCommand,
+  input: string | undefined,
+  pipeline: (signal: AbortSignal, context: unknown) => T | Promise<T>,
+  wrapErrorResult?: (result: unknown) => T,
+  signal?: AbortSignal,
+  context?: unknown,
+  runtime?: ResolvedPadroneRuntime,
+  program?: AnyPadroneProgram,
+  caller: 'cli' | 'eval' | 'run' | 'repl' | 'serve' | 'mcp' | 'tool' = 'eval',
+  pipelineState?: { rawArgs?: Record<string, unknown>; positionalArgs?: string[]; args?: unknown },
+): T | Promise<T> {
+  const defaultSignal = typeof AbortSignal !== 'undefined' ? AbortSignal.abort() : (undefined as unknown as AbortSignal);
+  const hasStart = interceptors.some((p) => p.start);
+  const hasError = interceptors.some((p) => p.error);
+  const hasShutdown = interceptors.some((p) => p.shutdown);
+
+  // Fast path: no lifecycle interceptors
+  if (!hasStart && !hasError && !hasShutdown) return pipeline(signal ?? defaultSignal, context);
+  // Mutable refs: start-phase interceptors can override signal and context (e.g., signal extension, auth),
+  // and the overrides propagate to error/shutdown contexts.
+  let effectiveSignal = signal ?? defaultSignal;
+  let effectiveContext = context;
+
+  const runShutdown = (error?: unknown, result?: unknown) => {
+    if (!hasShutdown) return;
+    const ctx: InterceptorShutdownContext = {
+      command,
+      input,
+      error,
+      result,
+      signal: effectiveSignal,
+      context: effectiveContext,
+      runtime: runtime!,
+      program: program!,
+      caller,
+      ...pipelineState,
+    };
+    return runInterceptorChain('shutdown', interceptors, ctx, () => {});
+  };
+
+  const runError = (error: unknown): T | Promise<T> => {
+    if (!hasError) {
+      const s = runShutdown(error);
+      if (s instanceof Promise)
+        return s.then(() => {
+          throw error;
+        });
+      throw error;
+    }
+    const ctx: InterceptorErrorContext = {
+      command,
+      input,
+      error,
+      signal: effectiveSignal,
+      context: effectiveContext,
+      runtime: runtime!,
+      program: program!,
+      caller,
+      ...pipelineState,
+    };
+    const errorResult = runInterceptorChain('error', interceptors, ctx, (): InterceptorErrorResult => ({ error }));
+    return thenMaybe(errorResult, (er) => {
+      if (er.error !== undefined) {
+        const s = runShutdown(er.error);
+        return thenMaybe(s as void | Promise<void>, () => {
+          throw er.error;
+        });
+      }
+      const wrapped = wrapErrorResult ? wrapErrorResult(er.result) : (er.result as T);
+      const s = runShutdown(undefined, wrapped);
+      return thenMaybe(s as void | Promise<void>, () => wrapped);
+    });
+  };
+
+  const handleSuccess = (result: T): T | Promise<T> => {
+    const s = runShutdown(undefined, result);
+    if (s instanceof Promise) return s.then(() => result);
+    return result;
+  };
+
+  const startCtx: InterceptorStartContext = {
+    command,
+    signal: effectiveSignal,
+    context: effectiveContext,
+    runtime: runtime!,
+    program: program!,
+    input,
+    caller,
+  };
+  let result: T | Promise<T>;
+  try {
+    result = (
+      hasStart
+        ? runInterceptorChain('start', interceptors, startCtx, (ctx) => {
+            // Capture overrides from start-phase interceptors so downstream phases see them.
+            effectiveSignal = ctx.signal;
+            effectiveContext = ctx.context;
+            return pipeline(ctx.signal, ctx.context);
+          })
+        : pipeline(effectiveSignal, effectiveContext)
+    ) as T | Promise<T>;
+  } catch (e) {
+    return runError(e);
+  }
+
+  if (result instanceof Promise) {
+    return result.then(handleSuccess, runError);
+  }
+
+  return handleSuccess(result);
+}

package/src/{parse.ts → core/parse.ts}

@@ -44,14 +44,16 @@ type ParseParts = {
 
 type ParsePart = ParseParts[keyof ParseParts];
 
+type QuoteChar = '"' | "'" | '`';
+
 /**
- * Tokenizes input string respecting quoted strings and bracket arrays.
- * Supports single quotes, double quotes, backticks, and square brackets.
+ * Split a string by a delimiter, respecting quoted segments and optional bracket nesting.
+ * Handles escape sequences within quotes (\\" and \\\\).
  */
-function tokenizeInput(input: string): string[] {
-  const tokens: string[] = [];
+function splitQuoteAware(input: string, delimiter: ' ' | ',', opts?: { brackets?: boolean; trim?: boolean }): string[] {
+  const results: string[] = [];
   let current = '';
-  let inQuote: '"' | "'" | '`' | null = null;
+  let inQuote: QuoteChar | null = null;
   let bracketDepth = 0;
   let i = 0;
 
@@ -59,39 +61,32 @@ function tokenizeInput(input: string): string[] {
     const char = input[i];
 
     if (inQuote) {
-      // Check for escape sequences within quotes
       if (char === '\\' && i + 1 < input.length) {
         const nextChar = input[i + 1];
-        // Handle escape sequences
         if (nextChar === inQuote || nextChar === '\\') {
           current += nextChar;
           i += 2;
           continue;
         }
       }
-
       if (char === inQuote) {
-        // End of quoted string
         inQuote = null;
       } else {
         current += char;
       }
-    } else if (char === '[') {
+    } else if (opts?.brackets && char === '[') {
       bracketDepth++;
       current += char;
-    } else if (char === ']') {
+    } else if (opts?.brackets && char === ']') {
       bracketDepth = Math.max(0, bracketDepth - 1);
       current += char;
     } else if (bracketDepth > 0) {
-      // Inside brackets - include everything including spaces
       current += char;
     } else if (char === '"' || char === "'" || char === '`') {
-      // Start of quoted string
       inQuote = char;
-    } else if (char === ' ' || char === '\t') {
-      // Whitespace outside quotes and brackets - end current token
-      if (current) {
-        tokens.push(current);
+    } else if (char === delimiter || (delimiter === ' ' && char === '\t')) {
+      if (delimiter === ' ' ? current : true) {
+        results.push(opts?.trim ? current.trim() : current);
         current = '';
       }
     } else {
@@ -100,19 +95,20 @@ function tokenizeInput(input: string): string[] {
     i++;
   }
 
-  // Add the last token if any
-  if (current) {
-    tokens.push(current);
+  if (delimiter === ' ' ? current : current || results.length > 0) {
+    results.push(opts?.trim ? current.trim() : current);
   }
 
-  return tokens;
+  return results;
 }
 
 export function parseCliInputToParts(input: string): ParsePart[] {
-  const parts = tokenizeInput(input.trim());
+  const parts = splitQuoteAware(input.trim(), ' ', { brackets: true });
   const result: ParsePart[] = [];
 
-  let pendingValue: ParseParts['named'] | ParseParts['alias'] | undefined;
+  // Index into `result` of the last part that can accept a pending value (-1 = none)
+  let pendingIdx = -1;
+  // Once a non-term positional arg appears, all subsequent bare values become args
   let allowTerm = true;
   let afterDoubleDash = false;
 
@@ -121,7 +117,7 @@ export function parseCliInputToParts(input: string): ParsePart[] {
 
     // Bare `--` separator: everything after is a literal positional arg
     if (part === '--' && !afterDoubleDash) {
-      if (pendingValue) pendingValue = undefined;
+      pendingIdx = -1;
       afterDoubleDash = true;
       allowTerm = false;
       continue;
@@ -132,22 +128,18 @@ export function parseCliInputToParts(input: string): ParsePart[] {
       continue;
     }
 
-    const wasPending = pendingValue;
-    pendingValue = undefined;
+    const hadPending = pendingIdx;
+    pendingIdx = -1;
 
     if (part.startsWith('--no-') && part.length > 5) {
       // Negated boolean arg (--no-verbose or --no-config.debug)
-      const keyStr = part.slice(5);
-      const key = keyStr.split('.');
-      const p = { type: 'named' as const, key, value: undefined, negated: true };
-      result.push(p);
+      const key = part.slice(5).split('.');
+      result.push({ type: 'named', key, value: undefined, negated: true });
     } else if (part.startsWith('--')) {
       const [keyStr = '', value] = splitNamedArgValue(part.slice(2));
       const key = keyStr.split('.');
-
-      const p = { type: 'named' as const, key, value };
-      if (typeof value === 'undefined') pendingValue = p;
-      result.push(p);
+      result.push({ type: 'named', key, value });
+      if (typeof value === 'undefined') pendingIdx = result.length - 1;
     } else if (part.startsWith('-') && part.length > 1 && !/^-\d/.test(part)) {
       // Short flag(s) (but not negative numbers like -5)
       // Supports flag stacking: -abc → -a -b -c (last flag can take a value)
@@ -156,25 +148,23 @@ export function parseCliInputToParts(input: string): ParsePart[] {
       if (keyStr.length > 1 && typeof value === 'undefined') {
         // Flag stacking: -abc → -a, -b, -c (all set to true except last which can take next arg's value)
         for (let ci = 0; ci < keyStr.length - 1; ci++) {
-          result.push({ type: 'alias' as const, key: [keyStr[ci]!], value: undefined });
+          result.push({ type: 'alias', key: [keyStr[ci]!], value: undefined });
         }
-        const lastFlag = { type: 'alias' as const, key: [keyStr[keyStr.length - 1]!], value: undefined as string | string[] | undefined };
-        pendingValue = lastFlag;
-        result.push(lastFlag);
+        result.push({ type: 'alias', key: [keyStr[keyStr.length - 1]!], value: undefined });
+        pendingIdx = result.length - 1;
       } else if (keyStr.length > 1 && typeof value !== 'undefined') {
         // -abc=val → -a, -b, -c=val (stacked with value on last)
         for (let ci = 0; ci < keyStr.length - 1; ci++) {
-          result.push({ type: 'alias' as const, key: [keyStr[ci]!], value: undefined });
+          result.push({ type: 'alias', key: [keyStr[ci]!], value: undefined });
         }
-        result.push({ type: 'alias' as const, key: [keyStr[keyStr.length - 1]!], value });
+        result.push({ type: 'alias', key: [keyStr[keyStr.length - 1]!], value });
       } else {
         // Single char: -v or -v=value
-        const p = { type: 'alias' as const, key: [keyStr], value };
-        if (typeof value === 'undefined') pendingValue = p;
-        result.push(p);
+        result.push({ type: 'alias', key: [keyStr], value });
+        if (typeof value === 'undefined') pendingIdx = result.length - 1;
       }
-    } else if (wasPending) {
-      wasPending.value = part;
+    } else if (hadPending >= 0) {
+      result[hadPending]!.value = part;
     } else if (/^[a-zA-Z0-9_-]+$/.test(part) && allowTerm) {
       result.push({ type: 'term', value: part });
     } else {
@@ -209,8 +199,7 @@ function splitNamedArgValue(str: string): [string, string | string[] | undefined
   if (value.startsWith('[') && value.endsWith(']')) {
     const inner = value.slice(1, -1);
     if (inner === '') return [key, []];
-    const items = parseArrayItems(inner);
-    return [key, items];
+    return [key, splitQuoteAware(inner, ',', { trim: true })];
   }
 
   return [key, value];
@@ -252,45 +241,3 @@ export function getNestedValue(obj: Record<string, unknown>, path: string[]): un
 
   return current;
 }
-
-/**
- * Parse comma-separated items, respecting quotes within items.
- */
-function parseArrayItems(input: string): string[] {
-  const items: string[] = [];
-  let current = '';
-  let inQuote: '"' | "'" | '`' | null = null;
-  let i = 0;
-
-  while (i < input.length) {
-    const char = input[i];
-
-    if (inQuote) {
-      if (char === '\\' && i + 1 < input.length && input[i + 1] === inQuote) {
-        current += input[i + 1];
-        i += 2;
-        continue;
-      }
-      if (char === inQuote) {
-        inQuote = null;
-      } else {
-        current += char;
-      }
-    } else if (char === '"' || char === "'" || char === '`') {
-      inQuote = char;
-    } else if (char === ',') {
-      items.push(current.trim());
-      current = '';
-    } else {
-      current += char;
-    }
-    i++;
-  }
-
-  // Add the last item
-  if (current || items.length > 0) {
-    items.push(current.trim());
-  }
-
-  return items;
-}