politty 0.3.1 → 0.3.3

package/README.md

@@ -256,8 +256,8 @@ CLI entry point. Handles signals and calls `process.exit()`.
 
 ```typescript
 runMain(command, {
-  version: "1.0.0",    // Displayed with --version flag
-  argv: process.argv,  // Custom argv
+  version: "1.0.0", // Displayed with --version flag
+  argv: process.argv, // Custom argv
 });
 ```
 
@@ -285,6 +285,88 @@ Attach metadata to an argument.
 | `description` | `string?`  | Argument description                 |
 | `placeholder` | `string?`  | Placeholder shown in help            |
 | `env`         | `string?`  | Environment variable name (fallback) |
+| `completion`  | `object?`  | Shell completion configuration       |
+
+## Shell Completion
+
+politty provides automatic shell completion generation for bash, zsh, and fish.
+
+### Quick Setup
+
+Use `withCompletionCommand` to add completion support to your CLI:
+
+```typescript
+import { defineCommand, runMain, withCompletionCommand } from "politty";
+
+const mainCommand = withCompletionCommand(
+  defineCommand({
+    name: "mycli",
+    subCommands: {
+      build: buildCommand,
+      test: testCommand,
+    },
+  }),
+);
+
+runMain(mainCommand);
+```
+
+Then users can enable completions:
+
+```bash
+# Bash
+eval "$(mycli completion bash)"
+
+# Zsh
+eval "$(mycli completion zsh)"
+
+# Fish
+mycli completion fish | source
+```
+
+### Value Completion
+
+Define completion hints for arguments:
+
+```typescript
+const command = defineCommand({
+  name: "build",
+  args: z.object({
+    // Auto-detected from z.enum()
+    format: arg(z.enum(["json", "yaml", "xml"]), {
+      alias: "f",
+      description: "Output format",
+    }),
+
+    // File completion
+    config: arg(z.string(), {
+      completion: { type: "file", extensions: ["json", "yaml"] },
+    }),
+
+    // Directory completion
+    outputDir: arg(z.string(), {
+      completion: { type: "directory" },
+    }),
+
+    // Custom shell command
+    branch: arg(z.string().optional(), {
+      completion: {
+        custom: { shellCommand: "git branch --format='%(refname:short)'" },
+      },
+    }),
+
+    // Static choices
+    environment: arg(z.string(), {
+      completion: {
+        custom: { choices: ["development", "staging", "production"] },
+      },
+    }),
+  }),
+  run: (args) => {
+    /* ... */
+  },
+});
+```
 
 ## Documentation
 

package/dist/{arg-registry-w5mMKJkZ.d.ts → arg-registry-B4a4Fj7f.d.cts}

@@ -1,6 +1,53 @@
 import { z } from "zod";
 
 //#region src/core/arg-registry.d.ts
+/**
+ * Built-in completion types
+ */
+type CompletionType = "file" | "directory" | "none";
+/**
+ * Custom completion specification
+ */
+interface CustomCompletion {
+  /** Static list of choices for completion */
+  choices?: string[];
+  /** Shell command to execute for dynamic completion */
+  shellCommand?: string;
+}
+/**
+ * Completion metadata for an argument
+ *
+ * @example
+ * ```ts
+ * // File completion with extension filter
+ * input: arg(z.string(), {
+ *   completion: { type: "file", extensions: ["json", "yaml"] }
+ * })
+ *
+ * // Directory completion
+ * outputDir: arg(z.string(), {
+ *   completion: { type: "directory" }
+ * })
+ *
+ * // Custom static choices
+ * logLevel: arg(z.string(), {
+ *   completion: { custom: { choices: ["debug", "info", "warn", "error"] } }
+ * })
+ *
+ * // Dynamic completion from shell command
+ * branch: arg(z.string(), {
+ *   completion: { custom: { shellCommand: "git branch --format='%(refname:short)'" } }
+ * })
+ * ```
+ */
+interface CompletionMeta {
+  /** Built-in completion type */
+  type?: CompletionType;
+  /** Custom completion (takes precedence over type if both specified) */
+  custom?: CustomCompletion;
+  /** File extension filter (only applies when type is "file") */
+  extensions?: string[];
+}
 /**
  * Base metadata shared by all argument types
  */
@@ -26,6 +73,8 @@ interface BaseArgMeta {
    * ```
    */
   env?: string | string[];
+  /** Completion configuration for shell tab-completion */
+  completion?: CompletionMeta;
 }
 /**
  * Metadata for regular arguments (non-builtin aliases)
@@ -84,5 +133,5 @@ type ValidateArgMeta<M> = M extends {
 declare function arg<T extends z.ZodType>(schema: T): T;
 declare function arg<T extends z.ZodType, M extends ArgMeta>(schema: T, meta: ValidateArgMeta<M>): T;
 //#endregion
-export { arg as n, ArgMeta as t };
-//# sourceMappingURL=arg-registry-w5mMKJkZ.d.ts.map
+export { arg as a, CustomCompletion as i, CompletionMeta as n, CompletionType as r, ArgMeta as t };
+//# sourceMappingURL=arg-registry-B4a4Fj7f.d.cts.map

package/dist/arg-registry-B4a4Fj7f.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-registry-B4a4Fj7f.d.cts","names":[],"sources":["../src/core/arg-registry.ts"],"mappings":";;;;;AAKA;KAAY,cAAA;;;;UAKK,gBAAA;EAAgB;EAE/B,OAAA;EAAA;EAEA,YAAA;AAAA;;;;;;;;;;;AAyCF;;;;;;;;;;;;AA6BA;;;;UAzCiB,cAAA;EAiDA;EA/Cf,IAAA,GAAO,cAAA;;EAEP,MAAA,GAAS,gBAAA;EA6CqC;EA3C9C,UAAA;AAAA;;;AAqDF;UA/CiB,WAAA;;EAEf,WAAA;EA6C2D;EA3C3D,UAAA;EA8EkB;EA5ElB,WAAA;EA4EwB;;;;;;;;;;;;;;EA7DxB,GAAA;EAiEO;EA/DP,UAAA,GAAa,cAAA;AAAA;;;;UAME,cAAA,SAAuB,WAAA;EA6DnC;EA3DH,KAAA;AAAA;;;;UAMe,sBAAA,SAA+B,WAAA;EAuDM;EArDpD,KAAA;EAqDkB;EAnDlB,oBAAA;AAAA;;;;KAMU,OAAA,GAAU,cAAA,GAAiB,sBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmClC,eAAA,MAAqB,CAAA;EAAY,KAAA;AAAA,IAClC,CAAA;EAAY,oBAAA;AAAA,IACV,CAAA,iBAEc,CAAA,GAAI,CAAA,CAAE,CAAA;EAElB,WAAA;AAAA,IAEJ,CAAA;AAAA,iBAEY,GAAA,WAAc,CAAA,CAAE,OAAA,CAAA,CAAS,MAAA,EAAQ,CAAA,GAAI,CAAA;AAAA,iBACrC,GAAA,WAAc,CAAA,CAAE,OAAA,YAAmB,OAAA,CAAA,CAAS,MAAA,EAAQ,CAAA,EAAG,IAAA,EAAM,eAAA,CAAgB,CAAA,IAAK,CAAA"}

package/dist/{arg-registry-i6SA4l-E.d.cts → arg-registry-C3GP-5C9.d.ts}

@@ -1,6 +1,53 @@
 import { z } from "zod";
 
 //#region src/core/arg-registry.d.ts
+/**
+ * Built-in completion types
+ */
+type CompletionType = "file" | "directory" | "none";
+/**
+ * Custom completion specification
+ */
+interface CustomCompletion {
+  /** Static list of choices for completion */
+  choices?: string[];
+  /** Shell command to execute for dynamic completion */
+  shellCommand?: string;
+}
+/**
+ * Completion metadata for an argument
+ *
+ * @example
+ * ```ts
+ * // File completion with extension filter
+ * input: arg(z.string(), {
+ *   completion: { type: "file", extensions: ["json", "yaml"] }
+ * })
+ *
+ * // Directory completion
+ * outputDir: arg(z.string(), {
+ *   completion: { type: "directory" }
+ * })
+ *
+ * // Custom static choices
+ * logLevel: arg(z.string(), {
+ *   completion: { custom: { choices: ["debug", "info", "warn", "error"] } }
+ * })
+ *
+ * // Dynamic completion from shell command
+ * branch: arg(z.string(), {
+ *   completion: { custom: { shellCommand: "git branch --format='%(refname:short)'" } }
+ * })
+ * ```
+ */
+interface CompletionMeta {
+  /** Built-in completion type */
+  type?: CompletionType;
+  /** Custom completion (takes precedence over type if both specified) */
+  custom?: CustomCompletion;
+  /** File extension filter (only applies when type is "file") */
+  extensions?: string[];
+}
 /**
  * Base metadata shared by all argument types
  */
@@ -26,6 +73,8 @@ interface BaseArgMeta {
    * ```
    */
   env?: string | string[];
+  /** Completion configuration for shell tab-completion */
+  completion?: CompletionMeta;
 }
 /**
  * Metadata for regular arguments (non-builtin aliases)
@@ -84,5 +133,5 @@ type ValidateArgMeta<M> = M extends {
 declare function arg<T extends z.ZodType>(schema: T): T;
 declare function arg<T extends z.ZodType, M extends ArgMeta>(schema: T, meta: ValidateArgMeta<M>): T;
 //#endregion
-export { arg as n, ArgMeta as t };
-//# sourceMappingURL=arg-registry-i6SA4l-E.d.cts.map
+export { arg as a, CustomCompletion as i, CompletionMeta as n, CompletionType as r, ArgMeta as t };
+//# sourceMappingURL=arg-registry-C3GP-5C9.d.ts.map

package/dist/arg-registry-C3GP-5C9.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-registry-C3GP-5C9.d.ts","names":[],"sources":["../src/core/arg-registry.ts"],"mappings":";;;;;AAKA;KAAY,cAAA;;;;UAKK,gBAAA;EAAgB;EAE/B,OAAA;EAAA;EAEA,YAAA;AAAA;;;;;;;;;;;AAyCF;;;;;;;;;;;;AA6BA;;;;UAzCiB,cAAA;EAiDA;EA/Cf,IAAA,GAAO,cAAA;;EAEP,MAAA,GAAS,gBAAA;EA6CqC;EA3C9C,UAAA;AAAA;;;AAqDF;UA/CiB,WAAA;;EAEf,WAAA;EA6C2D;EA3C3D,UAAA;EA8EkB;EA5ElB,WAAA;EA4EwB;;;;;;;;;;;;;;EA7DxB,GAAA;EAiEO;EA/DP,UAAA,GAAa,cAAA;AAAA;;;;UAME,cAAA,SAAuB,WAAA;EA6DnC;EA3DH,KAAA;AAAA;;;;UAMe,sBAAA,SAA+B,WAAA;EAuDM;EArDpD,KAAA;EAqDkB;EAnDlB,oBAAA;AAAA;;;;KAMU,OAAA,GAAU,cAAA,GAAiB,sBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmClC,eAAA,MAAqB,CAAA;EAAY,KAAA;AAAA,IAClC,CAAA;EAAY,oBAAA;AAAA,IACV,CAAA,iBAEc,CAAA,GAAI,CAAA,CAAE,CAAA;EAElB,WAAA;AAAA,IAEJ,CAAA;AAAA,iBAEY,GAAA,WAAc,CAAA,CAAE,OAAA,CAAA,CAAS,MAAA,EAAQ,CAAA,GAAI,CAAA;AAAA,iBACrC,GAAA,WAAc,CAAA,CAAE,OAAA,YAAmB,OAAA,CAAA,CAAS,MAAA,EAAQ,CAAA,EAAG,IAAA,EAAM,eAAA,CAAgB,CAAA,IAAK,CAAA"}

package/dist/augment.d.cts

@@ -1,4 +1,4 @@
-import { t as ArgMeta } from "./arg-registry-i6SA4l-E.cjs";
+import { t as ArgMeta } from "./arg-registry-B4a4Fj7f.cjs";
 
 //#region src/augment.d.ts
 declare module "zod" {

package/dist/augment.d.ts

@@ -1,4 +1,4 @@
-import { t as ArgMeta } from "./arg-registry-w5mMKJkZ.js";
+import { t as ArgMeta } from "./arg-registry-C3GP-5C9.js";
 
 //#region src/augment.d.ts
 declare module "zod" {