feat(completion): add in-process JS resolver for dynamic value completion

.changeset/dynamic-completion-resolver.md

@@ -0,0 +1,7 @@
+---
+"politty": minor
+---
+
+Add `completion.custom.resolve` for in-process JS dynamic completion. The resolver receives a `DynamicCompletionContext` (current word, shell, other parsed arg values, previously supplied values) and returns candidates synchronously or via Promise. Static shell scripts (bash/zsh/fish) now delegate to `<program> __complete --shell <shell>` whenever a field uses `resolve`; the generated bash delegate stays compatible with Bash 3.2. Specifying more than one of `choices`, `shellCommand`, `resolve`, or `expand` on the same field throws.
+
+Type-level note: `generateCandidates(context, { shell })` now returns `Promise<CandidateResult>` and takes a required second argument. `__complete`'s internal `run` is async. Callers using only the high-level `withCompletionCommand` flow are unaffected.

.changeset/expand-completion.md

@@ -0,0 +1,5 @@
+---
+"politty": patch
+---
+
+Add `completion.custom.expand` for value completion that is pre-enumerated at script-generation time and baked into the static shell script. The user supplies `dependsOn` (sibling arg names that must have static `choices` or an enum schema) and `enumerate(deps)`; politty walks the cartesian product of the dependsOn values, calls `enumerate` for each combination, and emits Bash 3.2-compatible scalar variables, a hoisted associative array (zsh), or an inline switch (fish) keyed on those values. No Node process is spawned at TAB time — the shell dispatches via a case lookup or indirect-expansion lookup, taking the same `<10ms` path as static `choices`. Specifying more than one of `choices`, `shellCommand`, `resolve`, or `expand` on the same field throws.

docs/api-reference.md

@@ -286,7 +286,7 @@ const mainCommand = withCompletionCommand(
 
 // Now includes:
 // - mycli completion bash|zsh|fish
-// - mycli __complete -- <args>
+// - mycli __complete --shell <shell> -- <args>
 
 runMain(mainCommand);
 ```
@@ -346,7 +346,11 @@ console.log(result.script);
 Creates the hidden `__complete` command for dynamic completion.
 
 ```typescript
-function createDynamicCompleteCommand(rootCommand: AnyCommand, programName?: string): Command;
+function createDynamicCompleteCommand(
+  rootCommand: AnyCommand,
+  programName?: string,
+  globalArgsSchema?: ArgsSchema,
+): Command;
 ```
 
 #### Usage
@@ -355,7 +359,7 @@ The `__complete` command is automatically added by `withCompletionCommand`. It c
 
 ```bash
 # Get completions for "mycli build --"
-mycli __complete -- build --
+mycli __complete --shell fish -- build --
 
 # Output (tab-separated: value\tdescription)
 --watch	Watch mode
@@ -377,7 +381,11 @@ The last line (`:N`) is a directive that tells the shell how to handle completio
 Parses a partial command line to determine what kind of completion is needed.
 
 ```typescript
-function parseCompletionContext(argv: string[], rootCommand: AnyCommand): CompletionContext;
+function parseCompletionContext(
+  argv: string[],
+  rootCommand: AnyCommand,
+  globalArgsSchema?: ArgsSchema,
+): CompletionContext;
 ```
 
 #### Return Value
@@ -395,6 +403,8 @@ interface CompletionContext {
   subcommands: string[]; // Available subcommands
   positionals: CompletablePositional[];
   usedOptions: Set<string>; // Already used options
+  parsedArgs: Record<string, unknown>; // Other arg values (for dynamic resolvers)
+  previousValues: string[]; // Prior values for the option/positional being completed
 }
 
 type CompletionType = "subcommand" | "option-name" | "option-value" | "positional";
@@ -404,10 +414,13 @@ type CompletionType = "subcommand" | "option-name" | "option-value" | "positiona
 
 ### `generateCandidates`
 
-Generates completion candidates based on context.
+Generates completion candidates based on context. Async because dynamic resolvers may return promises.
 
 ```typescript
-function generateCandidates(context: CompletionContext): CandidateResult;
+function generateCandidates(
+  context: CompletionContext,
+  options: { shell: "bash" | "zsh" | "fish" },
+): Promise<CandidateResult>;
 ```
 
 #### Return Value
@@ -435,18 +448,87 @@ Completion configuration for arguments.
 interface CompletionMeta {
   /** Completion type */
   type?: "file" | "directory" | "none";
-  /** Custom completion */
+  /** Custom completion (mutually exclusive: choices | shellCommand | resolve | expand) */
   custom?: {
     /** Static choices */
     choices?: string[];
     /** Shell command for dynamic values */
     shellCommand?: string;
+    /** In-process JS resolver (see DynamicCompletionResolver) */
+    resolve?: DynamicCompletionResolver;
+    /** Pre-enumerated completion baked into the static shell script (see ExpandCompletion) */
+    expand?: ExpandCompletion;
   };
   /** File extension filters (for type: "file") */
   extensions?: string[];
 }
 ```
 
+---
+
+### `DynamicCompletionResolver`
+
+Callback invoked at completion time inside the `__complete` command.
+
+```typescript
+type DynamicCompletionResolver = (
+  ctx: DynamicCompletionContext,
+) => DynamicCompletionResult | Promise<DynamicCompletionResult>;
+
+interface DynamicCompletionContext {
+  /** Word being completed (`--field=` inline prefix is stripped before this is set). */
+  currentWord: string;
+  /** Target shell formatting requested by the caller. */
+  shell: "bash" | "zsh" | "fish";
+  /** Best-effort parsed values of OTHER args (camelCase keys, raw strings). */
+  parsedArgs: Readonly<Record<string, unknown>>;
+  /** Values already supplied for the same option/positional being completed. */
+  previousValues: readonly string[];
+  /** Subcommand path from root (e.g. ["api"]). */
+  subcommandPath: readonly string[];
+}
+
+interface DynamicCompletionResult {
+  candidates: Array<string | { value: string; description?: string }>;
+  /** Optional override; defaults to FilterPrefix | NoFileCompletion. */
+  directive?: number;
+}
+```
+
+Specifying more than one of `choices`, `shellCommand`, `resolve`, or `expand` on the same field throws at command-definition time. Static shell scripts automatically delegate to `<program> __complete --shell <shell>` when a field uses `resolve`. With `expand`, the candidate table is computed at script-generation time and inlined into the script — TAB completion stays in-shell.
+
+---
+
+### `ExpandCompletion`
+
+Pre-enumerated value completion. Use when candidates can be computed up front from a finite set of sibling arg values (each must have a static `choices` or enum schema). politty walks the cartesian product of the `dependsOn` values at script-generation time, calls `enumerate` for each combination, and bakes the resulting table into the static shell script.
+
+```typescript
+interface ExpandCompletion {
+  /**
+   * Sibling arg names (camelCase, same command) whose runtime values
+   * drive the candidate set. Each must have a static `choices` or enum
+   * schema. Chaining `expand` specs is not supported.
+   */
+  dependsOn: readonly string[];
+  /**
+   * Pure function called once per combination of dependsOn values at
+   * script-generation time. Returns the candidates for that combination.
+   * Strings imply no description; objects carry an optional description
+   * surfaced by zsh and fish.
+   */
+  enumerate: (
+    deps: Readonly<Record<string, string>>,
+  ) => ReadonlyArray<string | { value: string; description?: string }>;
+}
+```
+
+Properties and constraints:
+
+- `dependsOn` must be non-empty and may not reference the field itself or any sibling without a static value set. Validation errors throw at command-definition time with the offending field name.
+- `enumerate` runs synchronously at the time the user invokes `<program> completion <shell>`. politty does not retain it for runtime use; if it throws, the error is wrapped with the field name and the offending `deps` snapshot.
+- bash emits one prefix-scalar variable per table entry (`<base>__<encKey>=<candidates>`) so the generated script runs on Bash 3.2 (macOS default `/bin/bash`) without associative arrays; zsh emits one global associative array per spec (`typeset -gA`); fish emits an inline `switch` (no associative arrays). bash drops descriptions; zsh uses `value:description` for `_describe`; fish uses tab-separated `value\tdescription`.
+
 #### Example
 
 ```typescript

docs/shell-completion.md

@@ -9,15 +9,22 @@ For quick setup, see the [README](../README.md#shell-completion). For type signa
 `withCompletionCommand` adds two subcommands to your CLI:
 
 - **`completion <shell>`** — Generates a shell script that users source in their shell config
-- **`__complete`** (hidden) — The dynamic completion engine, called on every TAB press
+- **`__complete`** (hidden) — The dynamic completion engine used by `completion.custom.resolve`
 
-The generated shell scripts are thin wrappers. When a user presses TAB, the shell calls:
+The generated shell scripts embed static metadata for subcommands, options,
+`choices`, file/directory completion, and `expand` tables. These paths stay
+inside the shell at TAB time.
+
+When a field uses `completion.custom.resolve`, the generated script delegates
+that value completion to the hidden command:
 
 ```
 mycli __complete --shell bash -- <partial-tokens>
 ```
 
-All logic runs in JavaScript: parsing the command line context, resolving candidates, and returning results with directives that tell the shell how to present them.
+That command runs in JavaScript: it parses the partial command line, calls the
+resolver, and returns candidates with directives that tell the shell how to
+present them.
 
 Command aliases defined via `aliases` in `defineCommand()` are automatically included in both static completion scripts and dynamic completion candidates.
 
@@ -61,6 +68,127 @@ branch: arg(z.string().optional(), {
 
 The command has a 5-second timeout. If it fails or times out, no candidates are shown (stderr is suppressed).
 
+### Resolve (in-process JS)
+
+Compute candidates in the same process from a TS callback that has access to **other arg values typed so far**. Useful when completion depends on prior context — e.g. fields valid for the chosen endpoint, or columns in the chosen table.
+
+```typescript
+field: arg(z.array(z.string()).default([]), {
+  alias: "f",
+  completion: {
+    custom: {
+      resolve: ({ parsedArgs, previousValues }) => {
+        const endpoint = parsedArgs.endpoint as string | undefined;
+        if (!endpoint) return { candidates: [] };
+        const all = lookupFieldsFor(endpoint);
+        // De-dup keys already supplied via earlier `--field key=value` flags.
+        const used = new Set(previousValues.map((v) => v.split("=")[0]));
+        return { candidates: all.filter((k) => !used.has(k)) };
+      },
+    },
+  },
+});
+```
+
+The callback receives a `DynamicCompletionContext`:
+
+| Field            | Description                                                                                                                                                                                                                                    |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `currentWord`    | Word being completed. Inline `--field=` prefix is stripped before this is set.                                                                                                                                                                 |
+| `shell`          | `"bash" \| "zsh" \| "fish"` — useful when output should differ between shells.                                                                                                                                                                 |
+| `parsedArgs`     | Best-effort parsed values of OTHER args on the same command, keyed by camelCase name. Includes positionals (string, or string[] for variadic) and options (string for scalars, string[] for array options). Zod validation is **NOT** applied. |
+| `previousValues` | Values already supplied for the option/positional being completed (for de-duping array options).                                                                                                                                               |
+| `subcommandPath` | Subcommand path leading here, e.g. `["api"]`.                                                                                                                                                                                                  |
+
+Return `{ candidates, directive? }` where `candidates` is an array of strings or `{ value, description }` objects. When `directive` is omitted it defaults to `FilterPrefix | NoFileCompletion` (matches `choices` behaviour).
+
+The resolver runs **inside the `__complete` command**, so:
+
+- Static shell scripts delegate to `<program> __complete --shell <shell>` whenever a field uses `resolve`. This is automatic — call `withCompletionCommand` and politty wires it up.
+- The resolver may be async (returning `Promise<DynamicCompletionResult>`).
+- If the resolver throws, completion silently returns no candidates (with `CompletionDirective.Error` set).
+- Dot-notation key descent (`labels.foo.bar`) and oneof exclusivity are the resolver's responsibility — politty just passes `currentWord` through and strips the `--field=` inline prefix.
+- `console.log` from inside the resolver pollutes the candidate stream; use `console.error` or a logger that writes to stderr instead.
+
+For local dev, set `MYCLI_BIN` (uppercase program name) to override the binary the static script invokes — useful when the CLI hasn't been installed on PATH yet.
+
+### Expand (pre-enumerated)
+
+When all of the candidates can be computed up front from a small, known set
+of sibling arg values, use `expand` instead of `resolve`. politty walks the
+cartesian product of the `dependsOn` values at script-generation time, calls
+`enumerate(deps)` once per combination, and bakes the resulting table into
+the shell script. At TAB time the shell dispatches via a case lookup keyed
+on the runtime values of those args — **no Node process is spawned**, so
+the latency matches static `choices` (typically <10ms).
+
+```typescript
+field: arg(z.array(z.string()).default([]), {
+  alias: "f",
+  completion: {
+    custom: {
+      expand: {
+        dependsOn: ["endpoint"],
+        enumerate: ({ endpoint }) => {
+          return getFieldsFor(endpoint).map((k) => ({
+            value: `${k}=`,
+            description: `Set ${k}`,
+          }));
+        },
+      },
+    },
+  },
+});
+```
+
+Requirements:
+
+- Every name in `dependsOn` must be a **sibling arg on the same command**
+  with a static value set (an explicit `completion.custom.choices` or an
+  enum schema). Chaining `expand` specs is not supported.
+- `enumerate` must be a pure function of `deps`. politty calls it once per
+  combination at the time the user runs `<program> completion <shell>`. If
+  it throws, the error is wrapped with the offending field name and the
+  `deps` snapshot.
+- Mixing `expand` with `choices`, `shellCommand`, or `resolve` on the same
+  field throws at command-definition time.
+- For multi-dimensional `dependsOn`, the runtime lookup key is the
+  concatenation of dep values joined by U+001F. Avoid sibling choices that
+  contain that byte (none in practice).
+
+Use this whenever the dependency graph collapses cleanly to a finite,
+build-time-known set. Reach for `resolve` when the candidates depend on
+process-local state the shell cannot observe (filesystem reads, network
+calls, parsing the schema-of-the-day, etc.).
+
+#### Array option deduplication (`-f key=value` repeats)
+
+When `expand` is attached to a repeatable **array option** (`z.array(...)`),
+the generated shell script automatically drops any candidate whose `key=`
+prefix has already been consumed on the same command line. That is, for the
+example above:
+
+```
+$ mycli api GetApplication -f workspaceId=foo -f <TAB>
+applicationName=    # workspaceId= is filtered out
+```
+
+The dedup logic:
+
+- Splits both the user-typed value and each candidate on the first `=`
+  and treats everything to the left of `=` as the slot key. There is no
+  configurable delimiter — `key=value` is the assumed shape.
+- Only fires for option fields with `valueType === "array"`. Scalar
+  options and positionals are not deduped (repeating them has different
+  semantics).
+- Candidates that contain no `=` pass through untouched (e.g. plain enum
+  values used as a repeatable list keep duplicating, since they don't
+  carry a slot key).
+
+If your CLI uses a different separator (e.g. `key:value`), this dedup
+won't engage — the candidates are still emitted correctly, you just
+won't get the automatic filtering.
+
 ### File Completion
 
 Delegate to the shell's native file completion. Optionally filter by extension:
@@ -105,7 +233,7 @@ This is useful for secrets or tokens where file suggestions would be noise.
 
 When multiple sources could provide completion values, the following priority applies:
 
-1. **Explicit `custom`** — `choices` or `shellCommand`
+1. **Explicit `custom`** — exactly one of `expand`, `resolve`, `choices`, or `shellCommand`. Specifying more than one throws at command-definition time.
 2. **Explicit `type`** — `file`, `directory`, or `none`
 3. **Auto-detected** — enum values from `z.enum()`
 
@@ -160,6 +288,12 @@ mycli completion bash > ~/.local/share/bash-completion/completions/mycli
 
 Reload with `source ~/.bashrc`.
 
+The generated bash script runs on **Bash 3.2 or newer**, including the
+default `/bin/bash` shipped with macOS. The completion machinery (both
+`completion.custom.expand` and `completion.custom.resolve`) avoids
+bash 4 builtins — associative arrays are replaced with prefix-scalar
+variables, and `mapfile` is replaced with a portable `while read` loop.
+
 ### Zsh
 
 ```bash