refactor!: move ink integration to padrone/ink entry point (#15)

Co-authored-by: Claude <noreply@anthropic.com>

Author: gkurt

.changeset/split-optional-entry-points.md

@@ -0,0 +1,12 @@
+---
+'padrone': major
+---
+
+Optional integrations are now exported from dedicated subpath entry points so bundlers that don't tree-shake re-exports keep their dependencies out of the main bundle. Update imports as follows:
+
+- `padroneInk`, `isReactElement`, `InkOptions` → `'padrone/ink'`
+- `padroneMcp`, `WithMcp`, `PadroneMcpPreferences` → `'padrone/mcp'`
+- `padroneServe`, `WithServe` → `'padrone/serve'`
+- `padroneTracing`, `WithTracing`, `PadroneTracer`, `PadroneTracingConfig`, `OtelSpan`, `OtelTracer`, `OtelTracerProvider` → `'padrone/tracing'`
+- `padroneCompletion`, `WithCompletion` → `'padrone/completion'`
+- `padroneMan`, `WithMan` → `'padrone/man'`

AGENTS.md

@@ -83,7 +83,7 @@ When asked to commit with a changeset, create a concise changeset suitable for a
 
 **Interceptor system**: Onion model with 7 phases: start → parse → route → validate → execute → (error) → shutdown. `collectInterceptors()` in `exec.ts` walks the parent chain (root outermost, subcommand innermost). Start/parse use root interceptors only. Route/validate/execute use the full collected chain (root + command). Error/shutdown run in two layers: command-level interceptors first (for validate/execute failures), then root-level interceptors (for all failures including parse). All interceptor phase contexts include `caller` (the invocation method: 'cli', 'eval', 'run', etc.) and `signal` (AbortSignal for cancellation). `defineInterceptor(meta, factory)` is the recommended API — the factory is called fresh per execution, enabling cross-phase state sharing via closures. Supports `.provides<T>()` and `.requires<T>()` for typed context (type-level only). Interceptors with the same `id` are deduplicated (last wins). Signal handling is implemented as a start-phase interceptor (`padroneSignalHandling`) that creates an AbortController and propagates it via `next({ signal })`. Error help display (routing/validation errors in CLI mode) is handled by the help extension's error phase, not hardcoded in exec.ts.
 
-**Extension system**: Build-time composition via `.extend(extension)`. A `PadroneExtension` is a function that receives the builder and returns a modified builder, enabling reusable command/config bundles. Unlike interceptors (which hook into runtime phases), extensions operate at definition time to compose commands, arguments, and configuration. Built-in extensions are included by default via `createPadrone()`: help (-1000), version (-1000), repl (-1000), color (-1001), suggestions (-500), signal (-2000), autoOutput (-1100), stdin (-1001), interactive (-999). Numbers are interceptor `order` values (lower = outermost). User-facing builtins (help, version, repl) can be individually disabled via `{ builtins: { help: false } }`. Advanced opt-in extensions: completion, logger, timing, progress, man, mcp, serve, update-check, tracing, ink, env, config.
+**Extension system**: Build-time composition via `.extend(extension)`. A `PadroneExtension` is a function that receives the builder and returns a modified builder, enabling reusable command/config bundles. Unlike interceptors (which hook into runtime phases), extensions operate at definition time to compose commands, arguments, and configuration. Built-in extensions are included by default via `createPadrone()`: help (-1000), version (-1000), repl (-1000), color (-1001), suggestions (-500), signal (-2000), autoOutput (-1100), stdin (-1001), interactive (-999). Numbers are interceptor `order` values (lower = outermost). User-facing builtins (help, version, repl) can be individually disabled via `{ builtins: { help: false } }`. Advanced opt-in extensions imported from `'padrone'`: logger, timing, progress, update-check, env, config. Optional integrations with heavier transitive surfaces live in their own subpath entry points so the main bundle stays lean: `padrone/ink`, `padrone/mcp`, `padrone/serve`, `padrone/tracing`, `padrone/completion`, `padrone/man`.
 
 **Flags vs aliases vs negatives**: `flags` = single-char short flags (`-v`), stackable. `alias` = multi-char alternative long names (`--dry-run`). `autoAlias` (default: true) auto-generates kebab-case aliases for camelCase option names. `negative` = custom negation keyword(s) for booleans (`negative: 'remote'` makes `--remote` set the arg to `false` and disables `--no-` prefix). Set to `''` or `[]` to only disable the prefix.
 

docs/src/content/docs/guides/plugins.md

@@ -41,15 +41,15 @@ Additional opt-in extensions are available for advanced features:
 | `padroneEnv(schema)` | `'padrone'` | Parse environment variables into args |
 | `padroneConfig(options)` | `'padrone'` | Load args from config files |
 | `padroneProgress(config)` | `'padrone'` | Auto-managed progress indicators |
-| `padroneCompletion()` | `'padrone'` | Shell completion generation |
 | `padroneLogger(options)` | `'padrone'` | Structured logging with levels |
 | `padroneTiming()` | `'padrone'` | Execution timing |
-| `padroneMan()` | `'padrone'` | Man page generation |
 | `padroneUpdateCheck(config)` | `'padrone'` | Background version checking |
-| `padroneMcp()` | `'padrone'` | MCP server integration |
-| `padroneServe()` | `'padrone'` | REST server integration |
-| `padroneTracing(config)` | `'padrone'` | OpenTelemetry tracing |
-| `padroneInk()` | `'padrone'` | React (Ink) rendering support |
+| `padroneInk()` | `'padrone/ink'` | React (Ink) rendering support |
+| `padroneMcp()` | `'padrone/mcp'` | MCP server integration |
+| `padroneServe()` | `'padrone/serve'` | REST server integration |
+| `padroneTracing(config)` | `'padrone/tracing'` | OpenTelemetry tracing |
+| `padroneCompletion()` | `'padrone/completion'` | Shell completion generation |
+| `padroneMan()` | `'padrone/man'` | Man page generation |
 
 ## Extensions
 

docs/src/content/docs/reference/api.md

@@ -1187,15 +1187,20 @@ These extensions are available as named exports from `'padrone'`:
 | `padroneEnv(schema)` | Parse environment variables into args |
 | `padroneConfig(options)` | Load args from config files |
 | `padroneProgress(config)` | Auto-managed progress indicators |
-| `padroneCompletion()` | Shell completion generation |
 | `padroneLogger(options)` | Structured logging with levels |
 | `padroneTiming()` | Execution timing |
-| `padroneMan()` | Man page generation |
 | `padroneUpdateCheck(config)` | Background version checking |
-| `padroneMcp()` | MCP server integration |
-| `padroneServe()` | REST server integration |
-| `padroneTracing(config)` | OpenTelemetry tracing |
-| `padroneInk()` | React (Ink) rendering support |
+
+The following extensions live in their own subpath imports to keep optional dependencies and large transitive surfaces out of the main bundle:
+
+| Export | Import from | Purpose |
+|--------|-------------|---------|
+| `padroneInk()` | `'padrone/ink'` | React (Ink) rendering support |
+| `padroneMcp()` | `'padrone/mcp'` | MCP server integration |
+| `padroneServe()` | `'padrone/serve'` | REST server integration |
+| `padroneTracing(config)` | `'padrone/tracing'` | OpenTelemetry tracing |
+| `padroneCompletion()` | `'padrone/completion'` | Shell completion generation |
+| `padroneMan()` | `'padrone/man'` | Man page generation |
 
 The following extensions are applied automatically by `createPadrone()` and can be disabled via `builtins`:
 

examples/padrone-example/src/tasks.ts

@@ -1,4 +1,5 @@
-import { createPadrone, defineInterceptor, padroneInk, padroneLogger, padroneProgress, padroneTiming } from 'padrone';
+import { createPadrone, defineInterceptor, padroneLogger, padroneProgress, padroneTiming } from 'padrone';
+import { padroneInk } from 'padrone/ink';
 import { zodAsyncStream } from 'padrone/zod';
 import * as z from 'zod/v4';
 import { addTask, getTask, getTasks, removeTask, setTaskStatus, updateTask } from './tasks-store.ts';

packages/padrone/package.json

@@ -68,16 +68,16 @@
     "./codegen": {
       "padrone@dev": "./src/codegen/index.ts",
       "import": {
-        "types": "./dist/codegen.d.mts",
-        "default": "./dist/codegen.mjs"
+        "types": "./dist/codegen/index.d.mts",
+        "default": "./dist/codegen/index.mjs"
       },
       "source": "./src/codegen/index.ts"
     },
     "./docs": {
       "padrone@dev": "./src/docs/index.ts",
       "import": {
-        "types": "./dist/docs.d.mts",
-        "default": "./dist/docs.mjs"
+        "types": "./dist/docs/index.d.mts",
+        "default": "./dist/docs/index.mjs"
       },
       "source": "./src/docs/index.ts"
     },
@@ -89,10 +89,58 @@
       },
       "source": "./src/zod.ts"
     },
+    "./ink": {
+      "padrone@dev": "./src/ink.ts",
+      "import": {
+        "types": "./dist/ink.d.mts",
+        "default": "./dist/ink.mjs"
+      },
+      "source": "./src/ink.ts"
+    },
+    "./mcp": {
+      "padrone@dev": "./src/mcp.ts",
+      "import": {
+        "types": "./dist/mcp.d.mts",
+        "default": "./dist/mcp.mjs"
+      },
+      "source": "./src/mcp.ts"
+    },
+    "./serve": {
+      "padrone@dev": "./src/serve.ts",
+      "import": {
+        "types": "./dist/serve.d.mts",
+        "default": "./dist/serve.mjs"
+      },
+      "source": "./src/serve.ts"
+    },
+    "./tracing": {
+      "padrone@dev": "./src/tracing.ts",
+      "import": {
+        "types": "./dist/tracing.d.mts",
+        "default": "./dist/tracing.mjs"
+      },
+      "source": "./src/tracing.ts"
+    },
+    "./completion": {
+      "padrone@dev": "./src/completion.ts",
+      "import": {
+        "types": "./dist/completion.d.mts",
+        "default": "./dist/completion.mjs"
+      },
+      "source": "./src/completion.ts"
+    },
+    "./man": {
+      "padrone@dev": "./src/man.ts",
+      "import": {
+        "types": "./dist/man.d.mts",
+        "default": "./dist/man.mjs"
+      },
+      "source": "./src/man.ts"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsdown src/index.ts src/test.ts src/zod.ts src/codegen/index.ts src/docs/index.ts --dts --sourcemap",
+    "build": "tsdown src/index.ts src/test.ts src/zod.ts src/ink.ts src/mcp.ts src/serve.ts src/tracing.ts src/completion.ts src/man.ts src/codegen/index.ts src/docs/index.ts --dts --sourcemap --unbundle",
     "start": "bun --conditions=padrone@dev src/cli/index.ts",
     "dev": "bun --conditions=padrone@dev --watch src/cli/index.ts",
     "test": "bun test --conditions=padrone@dev",

packages/padrone/src/completion.ts

@@ -0,0 +1,2 @@
+export type { WithCompletion } from './extension/completion.ts';
+export { padroneCompletion } from './extension/completion.ts';

packages/padrone/src/extension/completion.ts

@@ -21,6 +21,9 @@ export type WithCompletion<T> = WithCommand<T, 'completion', CompletionCommand>;
  *
  * Usage:
  * ```ts
+ * import { createPadrone } from 'padrone';
+ * import { padroneCompletion } from 'padrone/completion';
+ *
  * createPadrone('my-cli').extend(padroneCompletion())
  * ```
  */

packages/padrone/src/extension/index.ts

@@ -2,23 +2,15 @@ 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';
-export type { WithCompletion } from './completion.ts';
-export { padroneCompletion } from './completion.ts';
 export type { PadroneConfigOptions } from './config.ts';
 export { padroneConfig } from './config.ts';
 export type { PadroneEnvOptions } from './env.ts';
 export { padroneEnv } from './env.ts';
 export type { HelpCommand, WithHelp } from './help.ts';
 export { padroneHelp } from './help.ts';
-export type { InkOptions } from './ink.ts';
-export { isReactElement, padroneInk } from './ink.ts';
 export { padroneInteractive } from './interactive.ts';
 export type { PadroneLogger, PadroneLoggerConfig, PadroneLogLevel, WithLogger } from './logger.ts';
 export { padroneLogger } from './logger.ts';
-export type { WithMan } from './man.ts';
-export { padroneMan } from './man.ts';
-export type { WithMcp } from './mcp.ts';
-export { padroneMcp } from './mcp.ts';
 export type {
   PadroneProgressConfig,
   PadroneProgressDefaults,
@@ -31,15 +23,11 @@ export type { PadroneProgressRenderer } from './progress-renderer.ts';
 export { createTerminalProgress } from './progress-renderer.ts';
 export type { WithRepl } from './repl.ts';
 export { padroneRepl } from './repl.ts';
-export type { WithServe } from './serve.ts';
-export { padroneServe } from './serve.ts';
 export { padroneSignalHandling } from './signal.ts';
 export { padroneStdin } from './stdin.ts';
 export { padroneSuggestions } from './suggestions.ts';
 export type { PadroneTimingOptions } from './timing.ts';
 export { padroneTiming } from './timing.ts';
-export type { OtelSpan, OtelTracer, OtelTracerProvider, PadroneTracer, PadroneTracingConfig, WithTracing } from './tracing.ts';
-export { padroneTracing } from './tracing.ts';
 export { padroneUpdateCheck } from './update-check.ts';
 export type { VersionCommand, WithVersion } from './version.ts';
 export { padroneVersion } from './version.ts';

packages/padrone/src/extension/ink.ts

@@ -78,7 +78,8 @@ function createInkInterceptor(rawOptions?: InkOptions) {
  * Requires `ink` and `react` as peer dependencies.
  *
  * ```ts
- * import { createPadrone, padroneInk } from 'padrone';
+ * import { createPadrone } from 'padrone';
+ * import { padroneInk } from 'padrone/ink';
  *
  * const program = createPadrone('my-tui')
  *   .extend(padroneInk())