padrone 1.8.2 → 2.0.0

package/dist/extension/stdin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdin.mjs","names":[],"sources":["../../src/extension/stdin.ts"],"sourcesContent":["import { applyValues, isArrayField, isAsyncStreamField } from '../core/args.ts';\nimport { resolveStdin, resolveStdinAlways } from '../core/default-runtime.ts';\nimport { defineInterceptor } from '../core/interceptors.ts';\nimport type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext } from '../types/index.ts';\nimport { createStdinStream } from '../util/stream.ts';\n\n// ── Interceptor ─────────────────────────────────────────────────────────\n\nconst stdinInterceptor = defineInterceptor({ id: 'padrone:stdin', name: 'padrone:stdin', order: -1001 }, () => ({\n  validate(ctx: InterceptorValidateContext, next) {\n    const stdinField = ctx.command.meta?.stdin;\n    if (!stdinField) return next();\n\n    // Skip if the field was already provided via CLI flags\n    if (stdinField in ctx.rawArgs && ctx.rawArgs[stdinField] !== undefined) return next();\n\n    const streamInfo = isAsyncStreamField(ctx.command.argsSchema, stdinField);\n    if (streamInfo) {\n      const stdinForStream = resolveStdinAlways(ctx.runtime as any);\n      const mergedRawArgs = applyValues(ctx.rawArgs, { [stdinField]: createStdinStream(stdinForStream, streamInfo.itemSchema) });\n      return next({ rawArgs: mergedRawArgs });\n    }\n\n    const stdin = resolveStdin(ctx.runtime as any);\n    if (!stdin) return next();\n\n    if (isArrayField(ctx.command.argsSchema, stdinField)) {\n      return (async () => {\n        const lines: string[] = [];\n        for await (const line of stdin.lines()) {\n          lines.push(line);\n        }\n        const mergedRawArgs = applyValues(ctx.rawArgs, { [stdinField]: lines });\n        return next({ rawArgs: mergedRawArgs });\n      })();\n    }\n\n    return stdin.text().then((text) => {\n      if (!text) return next();\n      const mergedRawArgs = applyValues(ctx.rawArgs, { [stdinField]: text });\n      return next({ rawArgs: mergedRawArgs });\n    });\n  },\n}));\n\n// ── Extension ────────────────────────────────────────────────────────────\n\n/**\n * Extension that reads stdin data into the argument field specified by `meta.stdin`.\n * Included by default via `createPadrone()`.\n *\n * Read mode is inferred from the schema type:\n * - `string` field → reads all stdin as a single string\n * - `string[]` field → reads stdin line-by-line into an array\n * - `AsyncIterable` field → returns a stream for line-by-line async consumption\n *\n * Stdin is only read when piped (not a TTY) and the field wasn't already provided via CLI flags.\n */\nexport function padroneStdin(options?: { disabled?: boolean }): <T extends CommandTypesBase>(builder: T) => T {\n  const interceptor = options?.disabled ? defineInterceptor({ ...stdinInterceptor, disabled: true }, () => ({})) : stdinInterceptor;\n  return ((builder: AnyPadroneBuilder) => builder.intercept(interceptor)) as any;\n}\n"],"mappings":";;;;;AAQA,MAAM,mBAAmB,kBAAkB;CAAE,IAAI;CAAiB,MAAM;CAAiB,OAAO;AAAM,UAAU,EAC9G,SAAS,KAAiC,MAAM;CAC9C,MAAM,aAAa,IAAI,QAAQ,MAAM;CACrC,IAAI,CAAC,YAAY,OAAO,KAAK;CAG7B,IAAI,cAAc,IAAI,WAAW,IAAI,QAAQ,gBAAgB,KAAA,GAAW,OAAO,KAAK;CAEpF,MAAM,aAAa,mBAAmB,IAAI,QAAQ,YAAY,UAAU;CACxE,IAAI,YAAY;EACd,MAAM,iBAAiB,mBAAmB,IAAI,OAAc;EAE5D,OAAO,KAAK,EAAE,SADQ,YAAY,IAAI,SAAS,GAAG,aAAa,kBAAkB,gBAAgB,WAAW,UAAU,EAAE,CACrF,EAAE,CAAC;CACxC;CAEA,MAAM,QAAQ,aAAa,IAAI,OAAc;CAC7C,IAAI,CAAC,OAAO,OAAO,KAAK;CAExB,IAAI,aAAa,IAAI,QAAQ,YAAY,UAAU,GACjD,QAAQ,YAAY;EAClB,MAAM,QAAkB,CAAC;EACzB,WAAW,MAAM,QAAQ,MAAM,MAAM,GACnC,MAAM,KAAK,IAAI;EAGjB,OAAO,KAAK,EAAE,SADQ,YAAY,IAAI,SAAS,GAAG,aAAa,MAAM,CAClC,EAAE,CAAC;CACxC,EAAA,CAAG;CAGL,OAAO,MAAM,KAAK,CAAC,CAAC,MAAM,SAAS;EACjC,IAAI,CAAC,MAAM,OAAO,KAAK;EAEvB,OAAO,KAAK,EAAE,SADQ,YAAY,IAAI,SAAS,GAAG,aAAa,KAAK,CACjC,EAAE,CAAC;CACxC,CAAC;AACH,EACF,EAAE;;;;;;;;;;;;AAeF,SAAgB,aAAa,SAAiF;CAC5G,MAAM,cAAc,SAAS,WAAW,kBAAkB;EAAE,GAAG;EAAkB,UAAU;CAAK,UAAU,CAAC,EAAE,IAAI;CACjH,SAAS,YAA+B,QAAQ,UAAU,WAAW;AACvE"}

package/dist/extension/suggestions.d.mts

@@ -0,0 +1,6 @@
+import { CommandTypesBase } from "../types/command.mjs";
+//#region src/extension/suggestions.d.ts
+declare function padroneSuggestions(): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+export { padroneSuggestions };
+//# sourceMappingURL=suggestions.d.mts.map

package/dist/extension/suggestions.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestions.d.mts","names":[],"sources":["../../src/extension/suggestions.ts"],"mappings":";;iBA+GgB,kBAAA,eAAiC,gBAAA,EAAkB,OAAA,EAAS,CAAA,KAAM,CAAA"}

package/dist/extension/suggestions.mjs

@@ -0,0 +1,113 @@
+import { resolveCommand, suggestSimilar } from "../core/commands.mjs";
+import { thenMaybe } from "../core/results.mjs";
+import { defineInterceptor } from "../core/interceptors.mjs";
+import { RoutingError } from "../core/errors.mjs";
+import { getKnownOptionNames } from "../core/validate.mjs";
+//#region src/extension/suggestions.ts
+function formatSuggestions(names, prefix = "") {
+	if (names.length === 0) return "";
+	const quoted = names.map((n) => `"${prefix}${n}"`);
+	if (quoted.length === 1) return `Did you mean ${quoted[0]}?`;
+	return `Did you mean ${quoted.slice(0, -1).join(", ")} or ${quoted.at(-1)}?`;
+}
+function findSourceCommand(commandPath, root) {
+	if (!commandPath || commandPath === root.name || commandPath === root.path) return root;
+	const parts = commandPath.split(" ");
+	let current = root;
+	for (const part of parts) {
+		const found = current.commands?.find((c) => {
+			resolveCommand(c);
+			return c.name === part || c.aliases?.includes(part);
+		});
+		if (found) current = found;
+		else break;
+	}
+	return current;
+}
+function enrichRoutingError(err, rootCommand) {
+	if (!(err instanceof RoutingError)) return err;
+	const unknownMatch = err.message.match(/^Unknown command: (\S+)/);
+	const unexpectedMatch = err.message.match(/^Unexpected arguments for '[^']+': (\S+)/);
+	const term = unknownMatch?.[1] ?? unexpectedMatch?.[1];
+	if (!term) return err;
+	const sourceCmd = findSourceCommand(err.command, rootCommand);
+	const candidateNames = [];
+	if (sourceCmd.commands) for (const cmd of sourceCmd.commands) {
+		resolveCommand(cmd);
+		if (!cmd.hidden) {
+			candidateNames.push(cmd.name);
+			if (cmd.aliases) candidateNames.push(...cmd.aliases);
+		}
+	}
+	const suggestionText = formatSuggestions(suggestSimilar(term, candidateNames));
+	if (!suggestionText) return err;
+	const suggestions = [suggestionText];
+	return new RoutingError(`${err.message}\n\n  ${suggestionText}`, {
+		suggestions,
+		command: err.command
+	});
+}
+function enrichIssuesWithSuggestions(issues, knownOptions) {
+	return issues.map((i) => {
+		const unknownMatch = i.message?.match(/^Unknown option: "([^"]+)"$/);
+		if (unknownMatch) {
+			const similar = suggestSimilar(unknownMatch[1], knownOptions());
+			if (similar.length) {
+				const hint = formatSuggestions(similar, "--");
+				return {
+					...i,
+					message: `${i.message} ${hint}`
+				};
+			}
+			return i;
+		}
+		const keys = i.keys ?? i.message?.match(/[Uu]nrecognized key(?:s)?[^"]*"([^"]+)"/)?.slice(1);
+		if (!keys?.length) return i;
+		const hints = keys.flatMap((k) => {
+			const similar = suggestSimilar(k, knownOptions());
+			return similar.length ? [formatSuggestions(similar, "--")] : [];
+		});
+		if (!hints.length) return i;
+		return {
+			...i,
+			message: `${i.message} ${hints.join(" ")}`
+		};
+	});
+}
+const suggestionsInterceptor = defineInterceptor({
+	id: "padrone:suggestions",
+	name: "padrone:suggestions",
+	order: -500
+}, () => ({
+	parse(ctx, next) {
+		try {
+			const result = next();
+			if (result instanceof Promise) return result.catch((err) => {
+				throw enrichRoutingError(err, ctx.command);
+			});
+			return result;
+		} catch (err) {
+			throw enrichRoutingError(err, ctx.command);
+		}
+	},
+	validate(ctx, next) {
+		return thenMaybe(next(), (v) => {
+			if (!v.argsResult?.issues?.length) return v;
+			const enriched = enrichIssuesWithSuggestions(v.argsResult.issues, () => getKnownOptionNames(ctx.command));
+			return {
+				...v,
+				argsResult: {
+					...v.argsResult,
+					issues: enriched
+				}
+			};
+		});
+	}
+}));
+function padroneSuggestions() {
+	return ((builder) => builder.intercept(suggestionsInterceptor));
+}
+//#endregion
+export { padroneSuggestions };
+
+//# sourceMappingURL=suggestions.mjs.map

package/dist/extension/suggestions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggestions.mjs","names":[],"sources":["../../src/extension/suggestions.ts"],"sourcesContent":["import { resolveCommand, suggestSimilar } from '../core/commands.ts';\nimport { RoutingError } from '../core/errors.ts';\nimport { defineInterceptor } from '../core/interceptors.ts';\nimport { thenMaybe } from '../core/results.ts';\nimport { getKnownOptionNames } from '../core/validate.ts';\nimport type { AnyPadroneBuilder, AnyPadroneCommand, CommandTypesBase } from '../types/index.ts';\n\nfunction formatSuggestions(names: string[], prefix = ''): string {\n  if (names.length === 0) return '';\n  const quoted = names.map((n) => `\"${prefix}${n}\"`);\n  if (quoted.length === 1) return `Did you mean ${quoted[0]}?`;\n  return `Did you mean ${quoted.slice(0, -1).join(', ')} or ${quoted.at(-1)}?`;\n}\n\nfunction findSourceCommand(commandPath: string | undefined, root: AnyPadroneCommand): AnyPadroneCommand {\n  if (!commandPath || commandPath === root.name || commandPath === root.path) return root;\n  const parts = commandPath.split(' ');\n  let current = root;\n  for (const part of parts) {\n    const found = current.commands?.find((c) => {\n      resolveCommand(c);\n      return c.name === part || c.aliases?.includes(part);\n    });\n    if (found) current = found;\n    else break;\n  }\n  return current;\n}\n\nfunction enrichRoutingError(err: unknown, rootCommand: AnyPadroneCommand): unknown {\n  if (!(err instanceof RoutingError)) return err;\n\n  const unknownMatch = err.message.match(/^Unknown command: (\\S+)/);\n  const unexpectedMatch = err.message.match(/^Unexpected arguments for '[^']+': (\\S+)/);\n  const term = unknownMatch?.[1] ?? unexpectedMatch?.[1];\n  if (!term) return err;\n\n  const sourceCmd = findSourceCommand(err.command, rootCommand);\n\n  const candidateNames: string[] = [];\n  if (sourceCmd.commands) {\n    for (const cmd of sourceCmd.commands) {\n      resolveCommand(cmd);\n      if (!cmd.hidden) {\n        candidateNames.push(cmd.name);\n        if (cmd.aliases) candidateNames.push(...cmd.aliases);\n      }\n    }\n  }\n\n  const similar = suggestSimilar(term, candidateNames);\n  const suggestionText = formatSuggestions(similar);\n  if (!suggestionText) return err;\n\n  const suggestions = [suggestionText];\n  const enrichedMsg = `${err.message}\\n\\n  ${suggestionText}`;\n  return new RoutingError(enrichedMsg, { suggestions, command: err.command });\n}\n\nfunction enrichIssuesWithSuggestions(\n  issues: readonly { path?: readonly unknown[]; message: string }[],\n  knownOptions: () => string[],\n): typeof issues {\n  return issues.map((i: any) => {\n    // Handle direct unknown option detection (from checkUnknownArgs)\n    const unknownMatch = i.message?.match(/^Unknown option: \"([^\"]+)\"$/);\n    if (unknownMatch) {\n      const similar = suggestSimilar(unknownMatch[1], knownOptions());\n      if (similar.length) {\n        const hint = formatSuggestions(similar, '--');\n        return { ...i, message: `${i.message} ${hint}` };\n      }\n      return i;\n    }\n\n    // Handle Zod strict schema errors (Unrecognized key(s) in object: \"foo\")\n    const keys: string[] | undefined = i.keys ?? i.message?.match(/[Uu]nrecognized key(?:s)?[^\"]*\"([^\"]+)\"/)?.slice(1);\n    if (!keys?.length) return i;\n    const hints = keys.flatMap((k: string) => {\n      const similar = suggestSimilar(k, knownOptions());\n      return similar.length ? [formatSuggestions(similar, '--')] : [];\n    });\n    if (!hints.length) return i;\n    return { ...i, message: `${i.message} ${hints.join(' ')}` };\n  });\n}\n\nconst suggestionsInterceptor = defineInterceptor({ id: 'padrone:suggestions', name: 'padrone:suggestions', order: -500 }, () => ({\n  parse(ctx, next) {\n    try {\n      const result = next();\n      if (result instanceof Promise) {\n        return result.catch((err: unknown) => {\n          throw enrichRoutingError(err, ctx.command);\n        });\n      }\n      return result;\n    } catch (err) {\n      throw enrichRoutingError(err, ctx.command);\n    }\n  },\n  validate(ctx, next) {\n    const result = next();\n    return thenMaybe(result, (v) => {\n      if (!v.argsResult?.issues?.length) return v;\n      const enriched = enrichIssuesWithSuggestions(v.argsResult.issues, () => getKnownOptionNames(ctx.command));\n      return { ...v, argsResult: { ...v.argsResult, issues: enriched } } as typeof v;\n    });\n  },\n}));\n\nexport function padroneSuggestions(): <T extends CommandTypesBase>(builder: T) => T {\n  return ((builder: AnyPadroneBuilder) => builder.intercept(suggestionsInterceptor)) as any;\n}\n"],"mappings":"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"}

package/dist/extension/timing.d.mts

@@ -0,0 +1,27 @@
+import { CommandTypesBase } from "../types/command.mjs";
+//#region src/extension/timing.d.ts
+interface PadroneTimingOptions {
+  /** Enable timing by default without requiring `--time` flag. Default: `false`. */
+  enabled?: boolean;
+}
+/**
+ * Extension that tracks command execution time.
+ *
+ * - `--time` / `--timing` → enables timing output
+ * - `--no-time` / `--no-timing` → disables timing output
+ *
+ * Pass `{ enabled: true }` to enable timing by default (can be disabled via `--no-time`).
+ *
+ * Usage:
+ * ```ts
+ * // Opt-in via flag
+ * createPadrone('my-cli').extend(padroneTiming())
+ *
+ * // Always on, opt-out via --no-time
+ * createPadrone('my-cli').extend(padroneTiming({ enabled: true }))
+ * ```
+ */
+declare function padroneTiming(options?: PadroneTimingOptions): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+export { PadroneTimingOptions, padroneTiming };
+//# sourceMappingURL=timing.d.mts.map

package/dist/extension/timing.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.mts","names":[],"sources":["../../src/extension/timing.ts"],"mappings":";;UAwDiB,oBAAA;;EAEf,OAAO;AAAA;;;;AAAA;AAoBT;;;;;;;;;;;;;iBAAgB,aAAA,CAAc,OAAA,GAAU,oBAAA,cAAkC,gBAAA,EAAkB,OAAA,EAAS,CAAA,KAAM,CAAA"}

package/dist/extension/timing.mjs

@@ -0,0 +1,71 @@
+import { thenMaybe } from "../core/results.mjs";
+import { defineInterceptor } from "../core/interceptors.mjs";
+//#region src/extension/timing.ts
+function formatDuration(ms) {
+	if (ms < 1e3) return `${ms.toFixed(0)}ms`;
+	if (ms < 6e4) return `${(ms / 1e3).toFixed(2)}s`;
+	return `${Math.floor(ms / 6e4)}m ${(ms % 6e4 / 1e3).toFixed(2)}s`;
+}
+const timingMeta = {
+	id: "padrone:timing",
+	name: "padrone:timing",
+	order: -1002
+};
+function createTimingInterceptor(enabledByDefault) {
+	return defineInterceptor(timingMeta, () => {
+		let enabled = enabledByDefault;
+		let startTime = 0;
+		return {
+			parse(_ctx, next) {
+				return thenMaybe(next(), (res) => {
+					if ("timing" in res.rawArgs) {
+						enabled = res.rawArgs.timing !== false;
+						delete res.rawArgs.timing;
+					}
+					if ("time" in res.rawArgs) {
+						enabled = res.rawArgs.time !== false;
+						delete res.rawArgs.time;
+					}
+					return res;
+				});
+			},
+			start(_ctx, next) {
+				startTime = performance.now();
+				return next();
+			},
+			shutdown(ctx, next) {
+				return thenMaybe(next(), (res) => {
+					if (enabled) {
+						const elapsed = performance.now() - startTime;
+						ctx.runtime.error(`\nDone in ${formatDuration(elapsed)}`);
+					}
+					return res;
+				});
+			}
+		};
+	});
+}
+/**
+* Extension that tracks command execution time.
+*
+* - `--time` / `--timing` → enables timing output
+* - `--no-time` / `--no-timing` → disables timing output
+*
+* Pass `{ enabled: true }` to enable timing by default (can be disabled via `--no-time`).
+*
+* Usage:
+* ```ts
+* // Opt-in via flag
+* createPadrone('my-cli').extend(padroneTiming())
+*
+* // Always on, opt-out via --no-time
+* createPadrone('my-cli').extend(padroneTiming({ enabled: true }))
+* ```
+*/
+function padroneTiming(options) {
+	return ((builder) => builder.intercept(createTimingInterceptor(options?.enabled ?? false)));
+}
+//#endregion
+export { padroneTiming };
+
+//# sourceMappingURL=timing.mjs.map

package/dist/extension/timing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.mjs","names":[],"sources":["../../src/extension/timing.ts"],"sourcesContent":["import { defineInterceptor } from '../core/interceptors.ts';\nimport { thenMaybe } from '../core/results.ts';\nimport type { AnyPadroneBuilder, CommandTypesBase } from '../types/index.ts';\n\n// ── Helpers ─────────────────────────────────────────────────────────────\n\nfunction formatDuration(ms: number): string {\n  if (ms < 1000) return `${ms.toFixed(0)}ms`;\n  if (ms < 60_000) return `${(ms / 1000).toFixed(2)}s`;\n  const mins = Math.floor(ms / 60_000);\n  const secs = ((ms % 60_000) / 1000).toFixed(2);\n  return `${mins}m ${secs}s`;\n}\n\n// ── Interceptor ─────────────────────────────────────────────────────────\n\nconst timingMeta = { id: 'padrone:timing', name: 'padrone:timing', order: -1002 } as const;\n\nfunction createTimingInterceptor(enabledByDefault: boolean) {\n  return defineInterceptor(timingMeta, () => {\n    let enabled = enabledByDefault;\n    let startTime = 0;\n\n    return {\n      parse(_ctx, next) {\n        return thenMaybe(next(), (res) => {\n          if ('timing' in res.rawArgs) {\n            enabled = res.rawArgs.timing !== false;\n            delete res.rawArgs.timing;\n          }\n          if ('time' in res.rawArgs) {\n            enabled = res.rawArgs.time !== false;\n            delete res.rawArgs.time;\n          }\n          return res;\n        });\n      },\n      start(_ctx, next) {\n        startTime = performance.now();\n        return next();\n      },\n      shutdown(ctx, next) {\n        return thenMaybe(next(), (res) => {\n          if (enabled) {\n            const elapsed = performance.now() - startTime;\n            ctx.runtime.error(`\\nDone in ${formatDuration(elapsed)}`);\n          }\n          return res;\n        });\n      },\n    };\n  });\n}\n\n// ── Extension ───────────────────────────────────────────────────────────\n\nexport interface PadroneTimingOptions {\n  /** Enable timing by default without requiring `--time` flag. Default: `false`. */\n  enabled?: boolean;\n}\n\n/**\n * Extension that tracks command execution time.\n *\n * - `--time` / `--timing` → enables timing output\n * - `--no-time` / `--no-timing` → disables timing output\n *\n * Pass `{ enabled: true }` to enable timing by default (can be disabled via `--no-time`).\n *\n * Usage:\n * ```ts\n * // Opt-in via flag\n * createPadrone('my-cli').extend(padroneTiming())\n *\n * // Always on, opt-out via --no-time\n * createPadrone('my-cli').extend(padroneTiming({ enabled: true }))\n * ```\n */\nexport function padroneTiming(options?: PadroneTimingOptions): <T extends CommandTypesBase>(builder: T) => T {\n  return ((builder: AnyPadroneBuilder) => builder.intercept(createTimingInterceptor(options?.enabled ?? false))) as any;\n}\n"],"mappings":";;;AAMA,SAAS,eAAe,IAAoB;CAC1C,IAAI,KAAK,KAAM,OAAO,GAAG,GAAG,QAAQ,CAAC,EAAE;CACvC,IAAI,KAAK,KAAQ,OAAO,IAAI,KAAK,IAAA,CAAM,QAAQ,CAAC,EAAE;CAGlD,OAAO,GAFM,KAAK,MAAM,KAAK,GAEhB,EAAE,KADA,KAAK,MAAU,IAAA,CAAM,QAAQ,CACtB,EAAE;AAC1B;AAIA,MAAM,aAAa;CAAE,IAAI;CAAkB,MAAM;CAAkB,OAAO;AAAM;AAEhF,SAAS,wBAAwB,kBAA2B;CAC1D,OAAO,kBAAkB,kBAAkB;EACzC,IAAI,UAAU;EACd,IAAI,YAAY;EAEhB,OAAO;GACL,MAAM,MAAM,MAAM;IAChB,OAAO,UAAU,KAAK,IAAI,QAAQ;KAChC,IAAI,YAAY,IAAI,SAAS;MAC3B,UAAU,IAAI,QAAQ,WAAW;MACjC,OAAO,IAAI,QAAQ;KACrB;KACA,IAAI,UAAU,IAAI,SAAS;MACzB,UAAU,IAAI,QAAQ,SAAS;MAC/B,OAAO,IAAI,QAAQ;KACrB;KACA,OAAO;IACT,CAAC;GACH;GACA,MAAM,MAAM,MAAM;IAChB,YAAY,YAAY,IAAI;IAC5B,OAAO,KAAK;GACd;GACA,SAAS,KAAK,MAAM;IAClB,OAAO,UAAU,KAAK,IAAI,QAAQ;KAChC,IAAI,SAAS;MACX,MAAM,UAAU,YAAY,IAAI,IAAI;MACpC,IAAI,QAAQ,MAAM,aAAa,eAAe,OAAO,GAAG;KAC1D;KACA,OAAO;IACT,CAAC;GACH;EACF;CACF,CAAC;AACH;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,cAAc,SAA+E;CAC3G,SAAS,YAA+B,QAAQ,UAAU,wBAAwB,SAAS,WAAW,KAAK,CAAC;AAC9G"}

package/dist/extension/tracing.d.mts

@@ -0,0 +1,85 @@
+import { WithInterceptor } from "../util/type-utils.mjs";
+import { CommandTypesBase } from "../types/command.mjs";
+//#region src/extension/tracing.d.ts
+/** Minimal subset of OTEL `SpanStatusCode`. */
+type SpanStatusCode = 0 | 1 | 2;
+/** Minimal subset of OTEL `SpanStatus`. */
+type SpanStatus = {
+  code: SpanStatusCode;
+  message?: string;
+};
+/** Minimal subset of OTEL `Span`. */
+interface OtelSpan {
+  setAttribute(key: string, value: string | number | boolean): this;
+  addEvent(name: string, attributes?: Record<string, string | number | boolean>): this;
+  setStatus(status: SpanStatus): this;
+  recordException(error: unknown): this;
+  end(): void;
+  spanContext(): {
+    traceId: string;
+    spanId: string;
+  };
+}
+/** Minimal subset of OTEL `Tracer`. */
+interface OtelTracer {
+  startSpan(name: string): OtelSpan;
+}
+/** Minimal subset of OTEL `TracerProvider`. */
+interface OtelTracerProvider {
+  getTracer(name: string, version?: string): OtelTracer;
+}
+/** Tracing handle injected into the command context. */
+type PadroneTracer = {
+  /** The underlying OTEL tracer. */tracer: OtelTracer; /** Root span covering the full command execution. */
+  rootSpan: OtelSpan; /** Run `fn` inside a child span that is automatically ended when `fn` returns (or rejects). */
+  span: <T>(name: string, fn: (span: OtelSpan) => T) => T;
+};
+/** Configuration for the tracing extension. */
+type PadroneTracingConfig = {
+  /** OTEL `TracerProvider`. Required — there is no global fallback. */provider: OtelTracerProvider; /** Service / tracer name. Defaults to the CLI program name. */
+  serviceName?: string;
+};
+/** Builder/program type after applying `padroneTracing()`. Adds `{ tracing: PadroneTracer }` to the command context. */
+type WithTracing<T> = WithInterceptor<T, {
+  tracing: PadroneTracer;
+}>;
+/**
+ * Extension that adds OpenTelemetry tracing to command execution.
+ *
+ * Creates a root span for each command invocation and provides a `PadroneTracer`
+ * on the command context for creating child spans in action handlers.
+ *
+ * When used with `padroneLogger()`, the logger automatically emits span events
+ * for each log call — no extra configuration needed. The logger detects the
+ * tracing context and bridges log output to span events.
+ *
+ * Uses minimal OTEL-compatible interfaces — pass any `TracerProvider` that
+ * implements `getTracer()`. Works with `@opentelemetry/api` or compatible
+ * libraries.
+ *
+ * Provides `{ tracing: PadroneTracer }` on the command context.
+ * Access it in action handlers as `ctx.context.tracing`.
+ *
+ * Usage:
+ * ```ts
+ * import { trace } from '@opentelemetry/api';
+ * import { createPadrone, padroneLogger } from 'padrone';
+ * import { padroneTracing } from 'padrone/tracing';
+ *
+ * createPadrone('my-cli')
+ *   .extend(padroneTracing({ provider: trace.getTracerProvider() }))
+ *   .extend(padroneLogger())
+ *   .command('deploy', (c) =>
+ *     c.action((_args, ctx) => {
+ *       ctx.context.logger.info('deploying');  // also emits a span event
+ *       ctx.context.tracing.span('build', (span) => {
+ *         span.setAttribute('target', 'production');
+ *       });
+ *     })
+ *   )
+ * ```
+ */
+declare function padroneTracing<T extends CommandTypesBase>(config: PadroneTracingConfig): (builder: T) => WithTracing<T>;
+//#endregion
+export { OtelSpan, OtelTracer, OtelTracerProvider, PadroneTracer, PadroneTracingConfig, WithTracing, padroneTracing };
+//# sourceMappingURL=tracing.d.mts.map

package/dist/extension/tracing.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.mts","names":[],"sources":["../../src/extension/tracing.ts"],"mappings":";;;;KAWK,cAAA;;KAGA,UAAA;EAAe,IAAA,EAAM,cAAc;EAAE,OAAA;AAAA;AAHvB;AAAA,UAMF,QAAA;EACf,YAAA,CAAa,GAAA,UAAa,KAAA;EAC1B,QAAA,CAAS,IAAA,UAAc,UAAA,GAAa,MAAA;EACpC,SAAA,CAAU,MAAA,EAAQ,UAAU;EAC5B,eAAA,CAAgB,KAAA;EAChB,GAAA;EACA,WAAA;IAAiB,OAAA;IAAiB,MAAA;EAAA;AAAA;;UAInB,UAAA;EACf,SAAA,CAAU,IAAA,WAAe,QAAQ;AAAA;;UAIlB,kBAAA;EACf,SAAA,CAAU,IAAA,UAAc,OAAA,YAAmB,UAAU;AAAA;;KAI3C,aAAA;EAjBQ,kCAmBlB,MAAA,EAAQ,UAAA,EAlBR;EAoBA,QAAA,EAAU,QAAA,EAnBV;EAqBA,IAAA,MAAU,IAAA,UAAc,EAAA,GAAK,IAAA,EAAM,QAAA,KAAa,CAAA,KAAM,CAAA;AAAA;;KAI5C,oBAAA;EAxB8B,qEA0BxC,QAAA,EAAU,kBAAkB,EAtBH;EAwBzB,WAAA;AAAA;;KAIU,WAAA,MAAiB,eAAA,CAAgB,CAAA;EAAK,OAAA,EAAS,aAAA;AAAA;AA3BxB;AAInC;;;;;;;;;AACuD;AAIvD;;;;;;;;;;;;;;;;;;;;;;;AAMyD;AAIzD;AAnBmC,iBA8InB,cAAA,WAAyB,gBAAA,EAAkB,MAAA,EAAQ,oBAAA,IAAwB,OAAA,EAAS,CAAA,KAAM,WAAA,CAAY,CAAA"}

package/dist/extension/tracing.mjs

@@ -0,0 +1,107 @@
+import { thenMaybe } from "../core/results.mjs";
+import { defineInterceptor } from "../core/interceptors.mjs";
+//#region src/extension/tracing.ts
+const OTEL_ERROR = 2;
+function tracingInterceptor(config) {
+	return defineInterceptor({
+		id: "padrone:tracing",
+		name: "padrone:tracing",
+		order: -1
+	}, () => {
+		let rootSpan;
+		let tracer;
+		return {
+			start(ctx, next) {
+				tracer = config.provider.getTracer(config.serviceName ?? ctx.command.name);
+				return next();
+			},
+			execute(ctx, next) {
+				rootSpan = tracer.startSpan(`cli ${ctx.command.name}`);
+				return next({ context: { tracing: {
+					tracer,
+					rootSpan,
+					span(name, fn) {
+						const child = tracer.startSpan(name);
+						try {
+							const result = fn(child);
+							if (result != null && typeof result.then === "function") return result.then((v) => {
+								child.end();
+								return v;
+							}, (err) => {
+								child.recordException(err);
+								child.setStatus({ code: OTEL_ERROR });
+								child.end();
+								throw err;
+							});
+							child.end();
+							return result;
+						} catch (err) {
+							child.recordException(err);
+							child.setStatus({ code: OTEL_ERROR });
+							child.end();
+							throw err;
+						}
+					}
+				} } });
+			},
+			error(ctx, next) {
+				rootSpan?.recordException(ctx.error);
+				rootSpan?.setStatus({ code: OTEL_ERROR });
+				return next();
+			},
+			shutdown(_ctx, next) {
+				return thenMaybe(next(), (res) => {
+					rootSpan?.end();
+					return res;
+				});
+			}
+		};
+	});
+}
+/**
+* Extension that adds OpenTelemetry tracing to command execution.
+*
+* Creates a root span for each command invocation and provides a `PadroneTracer`
+* on the command context for creating child spans in action handlers.
+*
+* When used with `padroneLogger()`, the logger automatically emits span events
+* for each log call — no extra configuration needed. The logger detects the
+* tracing context and bridges log output to span events.
+*
+* Uses minimal OTEL-compatible interfaces — pass any `TracerProvider` that
+* implements `getTracer()`. Works with `@opentelemetry/api` or compatible
+* libraries.
+*
+* Provides `{ tracing: PadroneTracer }` on the command context.
+* Access it in action handlers as `ctx.context.tracing`.
+*
+* Usage:
+* ```ts
+* import { trace } from '@opentelemetry/api';
+* import { createPadrone, padroneLogger } from 'padrone';
+* import { padroneTracing } from 'padrone/tracing';
+*
+* createPadrone('my-cli')
+*   .extend(padroneTracing({ provider: trace.getTracerProvider() }))
+*   .extend(padroneLogger())
+*   .command('deploy', (c) =>
+*     c.action((_args, ctx) => {
+*       ctx.context.logger.info('deploying');  // also emits a span event
+*       ctx.context.tracing.span('build', (span) => {
+*         span.setAttribute('target', 'production');
+*       });
+*     })
+*   )
+* ```
+*/
+function padroneTracing(config) {
+	const resolved = {
+		provider: config.provider,
+		serviceName: config.serviceName
+	};
+	return ((builder) => builder.intercept(tracingInterceptor(resolved)));
+}
+//#endregion
+export { padroneTracing };
+
+//# sourceMappingURL=tracing.mjs.map

package/dist/extension/tracing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.mjs","names":[],"sources":["../../src/extension/tracing.ts"],"sourcesContent":["import { defineInterceptor } from '#src/core/interceptors.ts';\nimport { thenMaybe } from '#src/core/results.ts';\nimport type { AnyPadroneBuilder, CommandTypesBase } from '#src/types/index.ts';\nimport type { WithInterceptor } from '#src/util/type-utils.ts';\n\n// ---------------------------------------------------------------------------\n// Types — minimal OTEL-compatible interfaces so we don't hard-depend on\n// `@opentelemetry/api`. Users pass their real Tracer / Span instances.\n// ---------------------------------------------------------------------------\n\n/** Minimal subset of OTEL `SpanStatusCode`. */\ntype SpanStatusCode = 0 | 1 | 2;\n\n/** Minimal subset of OTEL `SpanStatus`. */\ntype SpanStatus = { code: SpanStatusCode; message?: string };\n\n/** Minimal subset of OTEL `Span`. */\nexport interface OtelSpan {\n  setAttribute(key: string, value: string | number | boolean): this;\n  addEvent(name: string, attributes?: Record<string, string | number | boolean>): this;\n  setStatus(status: SpanStatus): this;\n  recordException(error: unknown): this;\n  end(): void;\n  spanContext(): { traceId: string; spanId: string };\n}\n\n/** Minimal subset of OTEL `Tracer`. */\nexport interface OtelTracer {\n  startSpan(name: string): OtelSpan;\n}\n\n/** Minimal subset of OTEL `TracerProvider`. */\nexport interface OtelTracerProvider {\n  getTracer(name: string, version?: string): OtelTracer;\n}\n\n/** Tracing handle injected into the command context. */\nexport type PadroneTracer = {\n  /** The underlying OTEL tracer. */\n  tracer: OtelTracer;\n  /** Root span covering the full command execution. */\n  rootSpan: OtelSpan;\n  /** Run `fn` inside a child span that is automatically ended when `fn` returns (or rejects). */\n  span: <T>(name: string, fn: (span: OtelSpan) => T) => T;\n};\n\n/** Configuration for the tracing extension. */\nexport type PadroneTracingConfig = {\n  /** OTEL `TracerProvider`. Required — there is no global fallback. */\n  provider: OtelTracerProvider;\n  /** Service / tracer name. Defaults to the CLI program name. */\n  serviceName?: string;\n};\n\n/** Builder/program type after applying `padroneTracing()`. Adds `{ tracing: PadroneTracer }` to the command context. */\nexport type WithTracing<T> = WithInterceptor<T, { tracing: PadroneTracer }>;\n\n// ---------------------------------------------------------------------------\n// Interceptor\n// ---------------------------------------------------------------------------\n\nconst OTEL_ERROR: SpanStatusCode = 2;\n\ntype ResolvedTracingConfig = { provider: OtelTracerProvider; serviceName: string | undefined };\n\nfunction tracingInterceptor(config: ResolvedTracingConfig) {\n  return defineInterceptor({ id: 'padrone:tracing', name: 'padrone:tracing', order: -1 }, () => {\n    let rootSpan: OtelSpan;\n    let tracer: OtelTracer;\n\n    return {\n      start(ctx, next) {\n        tracer = config.provider.getTracer(config.serviceName ?? ctx.command.name);\n        return next();\n      },\n\n      execute(ctx, next) {\n        rootSpan = tracer.startSpan(`cli ${ctx.command.name}`);\n\n        const padroneTracer: PadroneTracer = {\n          tracer,\n          rootSpan,\n          span(name, fn) {\n            const child = tracer.startSpan(name);\n            try {\n              const result = fn(child);\n              if (result != null && typeof (result as any).then === 'function') {\n                return (result as any).then(\n                  (v: any) => {\n                    child.end();\n                    return v;\n                  },\n                  (err: unknown) => {\n                    child.recordException(err);\n                    child.setStatus({ code: OTEL_ERROR });\n                    child.end();\n                    throw err;\n                  },\n                );\n              }\n              child.end();\n              return result;\n            } catch (err) {\n              child.recordException(err);\n              child.setStatus({ code: OTEL_ERROR });\n              child.end();\n              throw err;\n            }\n          },\n        };\n\n        return next({ context: { tracing: padroneTracer } });\n      },\n\n      error(ctx, next) {\n        rootSpan?.recordException(ctx.error);\n        rootSpan?.setStatus({ code: OTEL_ERROR });\n        return next();\n      },\n\n      shutdown(_ctx, next) {\n        return thenMaybe(next(), (res) => {\n          rootSpan?.end();\n          return res;\n        });\n      },\n    };\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Extension\n// ---------------------------------------------------------------------------\n\n/**\n * Extension that adds OpenTelemetry tracing to command execution.\n *\n * Creates a root span for each command invocation and provides a `PadroneTracer`\n * on the command context for creating child spans in action handlers.\n *\n * When used with `padroneLogger()`, the logger automatically emits span events\n * for each log call — no extra configuration needed. The logger detects the\n * tracing context and bridges log output to span events.\n *\n * Uses minimal OTEL-compatible interfaces — pass any `TracerProvider` that\n * implements `getTracer()`. Works with `@opentelemetry/api` or compatible\n * libraries.\n *\n * Provides `{ tracing: PadroneTracer }` on the command context.\n * Access it in action handlers as `ctx.context.tracing`.\n *\n * Usage:\n * ```ts\n * import { trace } from '@opentelemetry/api';\n * import { createPadrone, padroneLogger } from 'padrone';\n * import { padroneTracing } from 'padrone/tracing';\n *\n * createPadrone('my-cli')\n *   .extend(padroneTracing({ provider: trace.getTracerProvider() }))\n *   .extend(padroneLogger())\n *   .command('deploy', (c) =>\n *     c.action((_args, ctx) => {\n *       ctx.context.logger.info('deploying');  // also emits a span event\n *       ctx.context.tracing.span('build', (span) => {\n *         span.setAttribute('target', 'production');\n *       });\n *     })\n *   )\n * ```\n */\nexport function padroneTracing<T extends CommandTypesBase>(config: PadroneTracingConfig): (builder: T) => WithTracing<T> {\n  const resolved: ResolvedTracingConfig = {\n    provider: config.provider,\n    serviceName: config.serviceName,\n  };\n  return ((builder: AnyPadroneBuilder) => builder.intercept(tracingInterceptor(resolved))) as any;\n}\n"],"mappings":";;;AA6DA,MAAM,aAA6B;AAInC,SAAS,mBAAmB,QAA+B;CACzD,OAAO,kBAAkB;EAAE,IAAI;EAAmB,MAAM;EAAmB,OAAO;CAAG,SAAS;EAC5F,IAAI;EACJ,IAAI;EAEJ,OAAO;GACL,MAAM,KAAK,MAAM;IACf,SAAS,OAAO,SAAS,UAAU,OAAO,eAAe,IAAI,QAAQ,IAAI;IACzE,OAAO,KAAK;GACd;GAEA,QAAQ,KAAK,MAAM;IACjB,WAAW,OAAO,UAAU,OAAO,IAAI,QAAQ,MAAM;IAkCrD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS;KA/BhC;KACA;KACA,KAAK,MAAM,IAAI;MACb,MAAM,QAAQ,OAAO,UAAU,IAAI;MACnC,IAAI;OACF,MAAM,SAAS,GAAG,KAAK;OACvB,IAAI,UAAU,QAAQ,OAAQ,OAAe,SAAS,YACpD,OAAQ,OAAe,MACpB,MAAW;QACV,MAAM,IAAI;QACV,OAAO;OACT,IACC,QAAiB;QAChB,MAAM,gBAAgB,GAAG;QACzB,MAAM,UAAU,EAAE,MAAM,WAAW,CAAC;QACpC,MAAM,IAAI;QACV,MAAM;OACR,CACF;OAEF,MAAM,IAAI;OACV,OAAO;MACT,SAAS,KAAK;OACZ,MAAM,gBAAgB,GAAG;OACzB,MAAM,UAAU,EAAE,MAAM,WAAW,CAAC;OACpC,MAAM,IAAI;OACV,MAAM;MACR;KACF;IAG4C,EAAE,EAAE,CAAC;GACrD;GAEA,MAAM,KAAK,MAAM;IACf,UAAU,gBAAgB,IAAI,KAAK;IACnC,UAAU,UAAU,EAAE,MAAM,WAAW,CAAC;IACxC,OAAO,KAAK;GACd;GAEA,SAAS,MAAM,MAAM;IACnB,OAAO,UAAU,KAAK,IAAI,QAAQ;KAChC,UAAU,IAAI;KACd,OAAO;IACT,CAAC;GACH;EACF;CACF,CAAC;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,SAAgB,eAA2C,QAA8D;CACvH,MAAM,WAAkC;EACtC,UAAU,OAAO;EACjB,aAAa,OAAO;CACtB;CACA,SAAS,YAA+B,QAAQ,UAAU,mBAAmB,QAAQ,CAAC;AACxF"}

package/dist/extension/update-check.d.mts

@@ -0,0 +1,20 @@
+import { CommandTypesBase } from "../types/command.mjs";
+import { UpdateCheckConfig } from "../feature/update-check.mjs";
+
+//#region src/extension/update-check.d.ts
+/**
+ * Extension that adds background update checking:
+ * - Checks for newer versions on npm (or custom registry) in the background
+ * - Shows an update notification after command execution
+ * - Respects `--no-update-check` flag to suppress
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .extend(padroneUpdateCheck({ packageName: 'my-cli' }))
+ * ```
+ */
+declare function padroneUpdateCheck(config?: UpdateCheckConfig): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+export { padroneUpdateCheck };
+//# sourceMappingURL=update-check.d.mts.map

package/dist/extension/update-check.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.mts","names":[],"sources":["../../src/extension/update-check.ts"],"mappings":";;;;;;;AA0EA;;;;;;;;;iBAAgB,kBAAA,CAAmB,MAAA,GAAQ,iBAAA,cAAoC,gBAAA,EAAkB,OAAA,EAAS,CAAA,KAAM,CAAA"}

package/dist/extension/update-check.mjs

@@ -0,0 +1,62 @@
+import { thenMaybe } from "../core/results.mjs";
+import { defineInterceptor } from "../core/interceptors.mjs";
+import { getVersion } from "../util/utils.mjs";
+//#region src/extension/update-check.ts
+function createUpdateCheckInterceptor(config) {
+	return defineInterceptor({
+		id: "padrone:update-check",
+		name: "padrone:update-check",
+		order: 1e3
+	}, () => {
+		let checkPromise;
+		let suppressed = false;
+		return {
+			start(ctx, next) {
+				const rootCommand = ctx.command;
+				const runtime = ctx.runtime;
+				checkPromise = Promise.resolve(getVersion(rootCommand.version)).then((currentVersion) => import("../feature/update-check.mjs").then(({ createUpdateChecker }) => createUpdateChecker(rootCommand.name, currentVersion, config, runtime)));
+				return next();
+			},
+			parse(_ctx, next) {
+				return thenMaybe(next(), (res) => {
+					if ("update-check" in res.rawArgs) {
+						if (res.rawArgs["update-check"] === false) suppressed = true;
+						delete res.rawArgs["update-check"];
+					}
+					return res;
+				});
+			},
+			shutdown(_ctx, next) {
+				const result = next();
+				if (suppressed || !checkPromise) return result;
+				let resolved = null;
+				checkPromise.then((fn) => {
+					resolved = fn;
+				}, () => {
+					resolved = void 0;
+				});
+				if (resolved !== null) resolved?.();
+				return result;
+			}
+		};
+	});
+}
+/**
+* Extension that adds background update checking:
+* - Checks for newer versions on npm (or custom registry) in the background
+* - Shows an update notification after command execution
+* - Respects `--no-update-check` flag to suppress
+*
+* Usage:
+* ```ts
+* createPadrone('my-cli')
+*   .extend(padroneUpdateCheck({ packageName: 'my-cli' }))
+* ```
+*/
+function padroneUpdateCheck(config = {}) {
+	return ((builder) => builder.intercept(createUpdateCheckInterceptor(config)));
+}
+//#endregion
+export { padroneUpdateCheck };
+
+//# sourceMappingURL=update-check.mjs.map

package/dist/extension/update-check.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.mjs","names":[],"sources":["../../src/extension/update-check.ts"],"sourcesContent":["import { thenMaybe } from '#src/core/results.ts';\nimport { defineInterceptor } from '../core/interceptors.ts';\nimport type { UpdateCheckConfig } from '../feature/update-check.ts';\nimport type { AnyPadroneBuilder, CommandTypesBase } from '../types/index.ts';\nimport { getVersion } from '../util/utils.ts';\n\n// ── Interceptor ─────────────────────────────────────────────────────────\n\nfunction createUpdateCheckInterceptor(config: UpdateCheckConfig) {\n  return defineInterceptor({ id: 'padrone:update-check', name: 'padrone:update-check', order: 1000 }, () => {\n    let checkPromise: Promise<(() => void) | undefined> | undefined;\n    let suppressed = false;\n\n    return {\n      start(ctx, next) {\n        const rootCommand = ctx.command;\n        const runtime = ctx.runtime;\n\n        checkPromise = Promise.resolve(getVersion(rootCommand.version)).then((currentVersion) =>\n          import('../feature/update-check.ts').then(({ createUpdateChecker }) =>\n            createUpdateChecker(rootCommand.name, currentVersion, config, runtime),\n          ),\n        );\n\n        return next();\n      },\n      parse(_ctx, next) {\n        return thenMaybe(next(), (res) => {\n          if ('update-check' in res.rawArgs) {\n            if (res.rawArgs['update-check'] === false) suppressed = true;\n            delete res.rawArgs['update-check'];\n          }\n          return res;\n        });\n      },\n      shutdown(_ctx, next) {\n        const result = next();\n        if (suppressed || !checkPromise) return result;\n\n        // Try to show notification synchronously if the check already resolved\n        let resolved: (() => void) | undefined | null = null;\n        checkPromise.then(\n          (fn) => {\n            resolved = fn;\n          },\n          () => {\n            resolved = undefined;\n          },\n        );\n\n        if (resolved !== null) {\n          (resolved as (() => void) | undefined)?.();\n        }\n\n        return result;\n      },\n    };\n  });\n}\n\n// ── Extension ────────────────────────────────────────────────────────────\n\n/**\n * Extension that adds background update checking:\n * - Checks for newer versions on npm (or custom registry) in the background\n * - Shows an update notification after command execution\n * - Respects `--no-update-check` flag to suppress\n *\n * Usage:\n * ```ts\n * createPadrone('my-cli')\n *   .extend(padroneUpdateCheck({ packageName: 'my-cli' }))\n * ```\n */\nexport function padroneUpdateCheck(config: UpdateCheckConfig = {}): <T extends CommandTypesBase>(builder: T) => T {\n  return ((builder: AnyPadroneBuilder) => builder.intercept(createUpdateCheckInterceptor(config))) as any;\n}\n"],"mappings":";;;;AAQA,SAAS,6BAA6B,QAA2B;CAC/D,OAAO,kBAAkB;EAAE,IAAI;EAAwB,MAAM;EAAwB,OAAO;CAAK,SAAS;EACxG,IAAI;EACJ,IAAI,aAAa;EAEjB,OAAO;GACL,MAAM,KAAK,MAAM;IACf,MAAM,cAAc,IAAI;IACxB,MAAM,UAAU,IAAI;IAEpB,eAAe,QAAQ,QAAQ,WAAW,YAAY,OAAO,CAAC,CAAC,CAAC,MAAM,mBACpE,OAAO,8BAA6B,CAAC,MAAM,EAAE,0BAC3C,oBAAoB,YAAY,MAAM,gBAAgB,QAAQ,OAAO,CACvE,CACF;IAEA,OAAO,KAAK;GACd;GACA,MAAM,MAAM,MAAM;IAChB,OAAO,UAAU,KAAK,IAAI,QAAQ;KAChC,IAAI,kBAAkB,IAAI,SAAS;MACjC,IAAI,IAAI,QAAQ,oBAAoB,OAAO,aAAa;MACxD,OAAO,IAAI,QAAQ;KACrB;KACA,OAAO;IACT,CAAC;GACH;GACA,SAAS,MAAM,MAAM;IACnB,MAAM,SAAS,KAAK;IACpB,IAAI,cAAc,CAAC,cAAc,OAAO;IAGxC,IAAI,WAA4C;IAChD,aAAa,MACV,OAAO;KACN,WAAW;IACb,SACM;KACJ,WAAW,KAAA;IACb,CACF;IAEA,IAAI,aAAa,MACf,WAAyC;IAG3C,OAAO;GACT;EACF;CACF,CAAC;AACH;;;;;;;;;;;;;AAgBA,SAAgB,mBAAmB,SAA4B,CAAC,GAAkD;CAChH,SAAS,YAA+B,QAAQ,UAAU,6BAA6B,MAAM,CAAC;AAChG"}

package/dist/extension/utils.mjs

@@ -0,0 +1,43 @@
+//#region src/extension/utils.ts
+/** Minimal Standard Schema that passes through known fields, ignoring unknown ones. */
+function passthroughSchema(fields) {
+	return { "~standard": {
+		version: 1,
+		vendor: "padrone",
+		jsonSchema: {
+			input: () => ({}),
+			output: () => ({})
+		},
+		validate: (value) => {
+			const input = value && typeof value === "object" ? value : {};
+			const result = {};
+			for (const [name, type] of Object.entries(fields)) {
+				const v = input[name];
+				if (v === void 0) continue;
+				if (type === "string[]") {
+					if (Array.isArray(v)) result[name] = v.map(String);
+					else if (typeof v === "string") result[name] = [v];
+				} else if (type === "string") {
+					if (typeof v === "string") result[name] = v;
+					else if (Array.isArray(v) && v.length > 0) result[name] = String(v[0]);
+				} else if (type === "boolean") result[name] = v === true || v === "true";
+			}
+			return { value: result };
+		}
+	} };
+}
+/** Find a command by space-separated name in the command tree. */
+function findCommandInTree(name, rootCommand) {
+	const parts = name.split(" ").filter(Boolean);
+	let current = rootCommand;
+	for (const part of parts) {
+		const found = current.commands?.find((c) => c.name === part || c.aliases?.includes(part));
+		if (!found) return void 0;
+		current = found;
+	}
+	return current;
+}
+//#endregion
+export { findCommandInTree, passthroughSchema };
+
+//# sourceMappingURL=utils.mjs.map

package/dist/extension/utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.mjs","names":[],"sources":["../../src/extension/utils.ts"],"sourcesContent":["import type { AnyPadroneCommand, PadroneSchema } from '../types/index.ts';\n\ntype SchemaShape = Record<string, 'string' | 'string[]' | 'boolean'>;\n\ntype InferPassthroughSchema<T extends SchemaShape> = {\n  [K in keyof T]: T[K] extends 'string' ? string : T[K] extends 'string[]' ? string[] : T[K] extends 'boolean' ? boolean : never;\n};\n\n/** Minimal Standard Schema that passes through known fields, ignoring unknown ones. */\nexport function passthroughSchema<TShape extends SchemaShape>(fields: TShape): PadroneSchema<InferPassthroughSchema<TShape>> {\n  return {\n    '~standard': {\n      version: 1 as const,\n      vendor: 'padrone' as const,\n      jsonSchema: {\n        input: () => ({}),\n        output: () => ({}),\n      },\n      validate: (value) => {\n        const input = value && typeof value === 'object' ? (value as Record<string, unknown>) : {};\n        const result: Record<string, unknown> = {};\n        for (const [name, type] of Object.entries(fields)) {\n          const v = input[name];\n          if (v === undefined) continue;\n          if (type === 'string[]') {\n            if (Array.isArray(v)) result[name] = v.map(String);\n            else if (typeof v === 'string') result[name] = [v];\n          } else if (type === 'string') {\n            if (typeof v === 'string') result[name] = v;\n            else if (Array.isArray(v) && v.length > 0) result[name] = String(v[0]);\n          } else if (type === 'boolean') {\n            result[name] = v === true || v === 'true';\n          }\n        }\n        return { value: result as InferPassthroughSchema<TShape> };\n      },\n    },\n  };\n}\n\n/** Find a command by space-separated name in the command tree. */\nexport function findCommandInTree(name: string, rootCommand: AnyPadroneCommand): AnyPadroneCommand | undefined {\n  const parts = name.split(' ').filter(Boolean);\n  let current = rootCommand;\n  for (const part of parts) {\n    const found = current.commands?.find((c) => c.name === part || c.aliases?.includes(part));\n    if (!found) return undefined;\n    current = found;\n  }\n  return current;\n}\n"],"mappings":";;AASA,SAAgB,kBAA8C,QAA+D;CAC3H,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,YAAY;GACV,cAAc,CAAC;GACf,eAAe,CAAC;EAClB;EACA,WAAW,UAAU;GACnB,MAAM,QAAQ,SAAS,OAAO,UAAU,WAAY,QAAoC,CAAC;GACzF,MAAM,SAAkC,CAAC;GACzC,KAAK,MAAM,CAAC,MAAM,SAAS,OAAO,QAAQ,MAAM,GAAG;IACjD,MAAM,IAAI,MAAM;IAChB,IAAI,MAAM,KAAA,GAAW;IACrB,IAAI,SAAS;SACP,MAAM,QAAQ,CAAC,GAAG,OAAO,QAAQ,EAAE,IAAI,MAAM;UAC5C,IAAI,OAAO,MAAM,UAAU,OAAO,QAAQ,CAAC,CAAC;IAAA,OAC5C,IAAI,SAAS;SACd,OAAO,MAAM,UAAU,OAAO,QAAQ;UACrC,IAAI,MAAM,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,QAAQ,OAAO,EAAE,EAAE;IAAA,OAChE,IAAI,SAAS,WAClB,OAAO,QAAQ,MAAM,QAAQ,MAAM;GAEvC;GACA,OAAO,EAAE,OAAO,OAAyC;EAC3D;CACF,EACF;AACF;;AAGA,SAAgB,kBAAkB,MAAc,aAA+D;CAC7G,MAAM,QAAQ,KAAK,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO;CAC5C,IAAI,UAAU;CACd,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,QAAQ,QAAQ,UAAU,MAAM,MAAM,EAAE,SAAS,QAAQ,EAAE,SAAS,SAAS,IAAI,CAAC;EACxF,IAAI,CAAC,OAAO,OAAO,KAAA;EACnB,UAAU;CACZ;CACA,OAAO;AACT"}

package/dist/extension/version.d.mts

@@ -0,0 +1,20 @@
+import { PadroneSchema } from "../types/schema.mjs";
+import { WithCommand } from "../util/type-utils.mjs";
+import { CommandTypesBase, PadroneCommand } from "../types/command.mjs";
+//#region src/extension/version.d.ts
+type VersionCommand = PadroneCommand<'version', '', PadroneSchema<void>, string, [], [], false>;
+type WithVersion<T> = WithCommand<T, 'version', VersionCommand>;
+/**
+ * Extension that adds version support:
+ * - `version` command
+ * - `--version` / `-v` / `-V` flags (root command only)
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneVersion())
+ * ```
+ */
+declare function padroneVersion(): <T extends CommandTypesBase>(builder: T) => WithVersion<T>;
+//#endregion
+export { VersionCommand, WithVersion, padroneVersion };
+//# sourceMappingURL=version.d.mts.map