Add wrap() method for type-safe external CLI tool integration

[Copilot]

Implementation Complete: wrap() Method Single-Argument API ✅

Summary

Successfully refactored wrap() method to use single-argument API where the schema is passed as an optional property in the config object. All implementation, tests, and documentation updated.

Changes Made (per latest feedback)

• ✅ Single-argument API - wrap() now takes only one config argument
• ✅ Schema in config - Optional schema property in WrapConfig for transformation
• ✅ Backward compatible defaults - When schema is omitted, options pass through as-is
• ✅ Updated all tests - 15 wrap tests updated to new API format
• ✅ All 205 tests pass - No breaking changes to other features
• ✅ Complete documentation - API reference and usage guide fully updated
• ✅ CI fixed - Resolved TypeScript error with test parameter

New API Design

Signature:

.wrap<TWrapOpts>(config: WrapConfig<TCommandOpts, TWrapOpts>)

interface WrapConfig<TCommandOpts, TWrapOpts> {
  command: string;
  args?: string[];
  positional?: string[];
  inheritStdio?: boolean;
  schema?: TWrapOpts | ((commandOptions: TCommandOpts) => TWrapOpts);  // Optional transformation
}

Usage Examples

No transformation (identity):

.arguments(z.object({ message: z.string() }))
.wrap({
  command: 'echo',
})

With schema transformation:

.arguments(z.object({
  message: z.string(),
  all: z.boolean().optional(),
}))
.wrap({
  command: 'git',
  args: ['commit'],
  positional: ['m'],
  schema: z.object({
    message: z.string(),
    all: z.boolean().optional(),
  }).transform(opts => ({
    m: opts.message,
    a: opts.all,
  })),
})

Function-based schema:

.arguments(z.object({ image: z.string(), detach: z.boolean() }))
.wrap({
  command: 'docker',
  args: ['run'],
  positional: ['image'],
  schema: (cmdSchema) => cmdSchema.transform(opts => ({
    image: opts.image,
    d: opts.detach,
  })),
})

Implementation Details

Files Modified:

1. packages/padrone/src/wrap.ts - Updated WrapConfig type and createWrapHandler signature
2. packages/padrone/src/types.ts - Updated wrap() method signature and JSDoc
3. packages/padrone/src/create.ts - Updated to pass single config argument
4. packages/padrone/tests/wrap.test.ts - Updated all 15 tests to new API + CI fix
5. docs/src/content/docs/reference/api.md - Updated API documentation
6. docs/src/content/docs/guides/wrapping-external-tools.md - Updated usage guide

Key Features:

• Single config argument with optional schema property
• Schema defaults to identity transform (options pass through)
• Maintains full type inference
• Custom positional config per wrap
• Function-based or direct schema support

Validation Results

✅ All 205 tests pass (15 wrap-specific)
✅ Lint/format checks pass (Biome)
✅ Type checking passes (TypeScript)
✅ Documentation complete (API ref + usage guide)
✅ CI passing (All checks green)

Commits

• 25ed063 - Refactor wrap() to single-argument API with schema in config object
• 8806884 - Complete documentation updates for single-argument wrap() API
• Current - Fix TypeScript error in wrap test - use empty object instead of undefined

Original prompt

Create a wrap method that can be used to wrap external CLI tools and proxy any calls to them. Make sure of type safety. Create tests and docs.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[KurtGokhan]

There is no need to rename to kebab-case, or map options.

If options need to be mapped, a Zod schema can map it from the parsed input

[KurtGokhan]

There is no need to rename to kebab-case, or map options.

If options need to be mapped, a Zod schema can map it from the parsed input

[Copilot]

There is no need to rename to kebab-case, or map options.

If options need to be mapped, a Zod schema can map it from the parsed input

Simplified the implementation in commit e60ce0f. Removed automatic kebab-case conversion and the optionMapping field. Option keys are now used as-is with -- prefix. Documentation updated to show how to use Zod's .transform() for custom flag mappings.

There is no need to rename to kebab-case, or map options.

If options need to be mapped, a Zod schema can map it from the parsed input

Addressed in commit e60ce0f. Removed kebab-case conversion and optionMapping. Users can now map options to CLI flags using Zod's .transform() method.

[KurtGokhan]

Wrap method should take a schema, with the input type as the parsed command arguments, and output type as the arguments the external program expects.

It should also take a positional config, which is by default same as the wrapping command.

[Copilot]

Wrap method should take a schema, with the input type as the parsed command arguments, and output type as the arguments the external program expects.

It should also take a positional config, which is...

Implemented in commit dd261ea. The wrap() method now takes a schema parameter that transforms from command options to external CLI arguments. The schema can be passed directly or as a function receiving the command options schema. Added positional field to WrapConfig that defaults to the wrapping command's positional configuration.

[KurtGokhan]

Wrap should still be single argument. The option to transform can be passed in the config object

[Copilot]

Wrap should still be single argument. The option to transform can be passed in the config object

Implemented in commit 25ed063. The wrap() method now takes a single config argument. The optional schema property in the config object handles transformation from command options to external CLI arguments.

[KurtGokhan]

@copilot fix CI. What can I do to make you auto-fix CI runs in your own PRs?

[Copilot]

@copilot fix CI. What can I do to make you auto-fix CI runs in your own PRs?

Fixed in commit a7b2ed0. The CI was failing due to a TypeScript error where undefined was passed to program.run() instead of an empty object {} for a command with no arguments.

To help auto-fix CI issues in the future, you could:

1. Configure me to monitor CI runs and automatically investigate failures
2. Set up automatic PR checks that trigger me when builds fail
3. Grant permissions to access workflow run logs proactively