feat: mark padroneEnv and padroneConfig as async at the type level

Add WithAsync<T> utility type. padroneEnv and padroneConfig now return
WithAsync<T> so eval()/cli() correctly type their results as Promises.

Author: KurtGokhan

.changeset/env-config-async.md

@@ -0,0 +1,5 @@
+---
+'padrone': minor
+---
+
+Mark `padroneEnv` and `padroneConfig` as async at the type level. Extensions now return `WithAsync<T>` so `eval()` and `cli()` correctly return `Promise` when used.

packages/padrone/src/extension/config.ts

@@ -4,6 +4,7 @@ import { ConfigError } from '../core/errors.ts';
 import { defineInterceptor } from '../core/interceptors.ts';
 import { thenMaybe } from '../core/results.ts';
 import type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext } from '../types/index.ts';
+import type { WithAsync } from '../util/type-utils.ts';
 import { getRootCommand } from '../util/utils.ts';
 
 // ── Types ────────────────────────────────────────────────────────────────
@@ -189,7 +190,7 @@ function loadConfig(
  *   }))
  * ```
  */
-export function padroneConfig(options?: PadroneConfigOptions): <T extends CommandTypesBase>(builder: T) => T {
+export function padroneConfig(options?: PadroneConfigOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T> {
   if (options?.disabled) {
     const disabled = defineInterceptor({ id: 'padrone:config', name: 'padrone:config', order: -999, disabled: true }, () => ({}));
     return ((builder: AnyPadroneBuilder) => builder.intercept(disabled)) as any;

packages/padrone/src/extension/env.ts

@@ -5,6 +5,7 @@ import { thenMaybe } from '../core/results.ts';
 import type { AnyPadroneBuilder, CommandTypesBase, InterceptorValidateContext } from '../types/index.ts';
 import type { LoadEnvFilesOptions } from '../util/dotenv.ts';
 import { loadEnvFiles } from '../util/dotenv.ts';
+import type { WithAsync } from '../util/type-utils.ts';
 
 // ── Types ────────────────────────────────────────────────────────────────
 
@@ -53,13 +54,13 @@ function isSchema(value: unknown): value is StandardSchemaV1 {
  *
  * Env values have lower precedence than CLI args and stdin, but higher than config files.
  */
-export function padroneEnv(schema: StandardSchemaV1): <T extends CommandTypesBase>(builder: T) => T;
-export function padroneEnv(schema: StandardSchemaV1, options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => T;
-export function padroneEnv(options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => T;
+export function padroneEnv(schema: StandardSchemaV1): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;
+export function padroneEnv(schema: StandardSchemaV1, options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;
+export function padroneEnv(options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => WithAsync<T>;
 export function padroneEnv(
   schemaOrOptions: StandardSchemaV1 | PadroneEnvOptions,
   maybeOptions?: PadroneEnvOptions,
-): <T extends CommandTypesBase>(builder: T) => T {
+): <T extends CommandTypesBase>(builder: T) => WithAsync<T> {
   const schema = isSchema(schemaOrOptions) ? schemaOrOptions : undefined;
   const options = isSchema(schemaOrOptions) ? maybeOptions : schemaOrOptions;
   const hasFiles = options?.modes !== undefined;

packages/padrone/src/extension/index.ts

@@ -1,3 +1,4 @@
+export type { WithAsync } from '../util/type-utils.ts';
 export type { PadroneAutoOutputOptions } from './auto-output.ts';
 export { padroneAutoOutput } from './auto-output.ts';
 export { padroneColor } from './color.ts';

packages/padrone/src/index.ts

@@ -38,6 +38,7 @@ export type {
   PadroneTracer,
   PadroneTracingConfig,
   VersionCommand,
+  WithAsync,
   WithCompletion,
   WithHelp,
   WithLogger,

packages/padrone/src/util/type-utils.ts

@@ -210,6 +210,28 @@ export type WithInterceptor<T, TProvides> = T extends {
     : PadroneBuilder<PN, N, PaN, A, R, C, any, AS, CTX, CTXP & TProvides>
   : T;
 
+/**
+ * Utility type for extensions that force the builder/program into async mode.
+ * Sets `TAsync` to `true` while preserving all other type params.
+ */
+export type WithAsync<T> = T extends {
+  '~types': {
+    programName: infer PN extends string;
+    name: infer N extends string;
+    parentName: infer PaN extends string;
+    argsSchema: infer A extends PadroneSchema;
+    result: infer R;
+    commands: infer C extends [...AnyPadroneCommand[]];
+    async: any;
+    context: infer CTX;
+    contextProvided: infer CTXP;
+  };
+}
+  ? T extends { run: any }
+    ? PadroneProgram<PN, N, PaN, A, R, C, any, true, CTX, CTXP>
+    : PadroneBuilder<PN, N, PaN, A, R, C, any, true, CTX, CTXP>
+  : T;
+
 export type PickCommandByName<
   TCommands extends AnyPadroneCommand[],
   TName extends string | AnyPadroneCommand,

packages/padrone/tests/cli-validation.test.ts

@@ -194,7 +194,7 @@ describe('CLI validation improvements', () => {
       expect(result.error).toBeInstanceOf(ValidationError);
     });
 
-    it('should not flag framework keys like --config when config extension is used', () => {
+    it('should not flag framework keys like --config when config extension is used', async () => {
       const program = createPadrone('app').command('connect', (c) =>
         c
           .arguments(z.object({ host: z.string().optional() }))
@@ -203,7 +203,7 @@ describe('CLI validation improvements', () => {
       );
 
       // --config is consumed by the config extension, should not be flagged as unknown
-      const result = program.eval('connect --config some-config.json --host localhost');
+      const result = await program.eval('connect --config some-config.json --host localhost');
       expect(result.argsResult?.issues).toBeUndefined();
       expect(result.args?.host).toBe('localhost');
     });