@politty/zod 0.0.0 → 0.1.1

package/README.md

@@ -475,7 +475,7 @@ politty integrates Node.js's on-disk compile cache (V8 code cache, Node >= 22.8.
 }
 ```
 
-`generate-shim` writes an executable shim that enables the cache and loads `--entry` (a specifier relative to the shim) with a dynamic import. The rest is derived from `package.json`: the output path from the `bin` path and the program name from the `bin` name; packages with multiple bins pass `--entry` once per bin, and `--entry` itself can be omitted when the entry sits next to the shim under a conventional name (`./cli.js`, `./index.js`, ...). See [Faster Startup (Compile Cache)](./docs/recipes.md#faster-startup-compile-cache) for the flags, the opt-out (`compileCache: false`), and the hand-written shim variant.
+`generate-shim` writes an executable shim that enables the cache and loads `--entry` (a specifier relative to the shim) with a dynamic import. The output path and program name come from `package.json` (the `bin` path and the `bin` name), and the shim imports the cache helper from the politty package whose `politty` bin you ran — the one you installed, so it resolves from your package. Packages with multiple bins pass `--entry` once per bin, and `--entry` itself can be omitted when the entry sits next to the shim under a conventional name (`./cli.js`, `./index.js`, ...). See [Faster Startup (Compile Cache)](./docs/recipes.md#faster-startup-compile-cache) for the flags, the opt-out (`compileCache: false`), and the hand-written shim variant.
 
 ## Skill Management
 

package/dist/{arg-registry-YaWTVu_x.d.ts → arg-registry-B8QvBM_Q.d.ts}

@@ -438,7 +438,7 @@ interface MainOptions {
    *
    * The `NODE_COMPILE_CACHE` environment variable always takes precedence.
    * Note: the entry module's static import graph is compiled before `runMain`
-   * runs and cannot be cached here — see `politty/compile-cache` for the
+   * runs and cannot be cached here — see the `compile-cache` subpath for the
    * bin-shim pattern that covers it.
    */
   compileCache?: boolean | string;

package/dist/augment.d.ts

@@ -1,4 +1,4 @@
-import { n as ArgMeta } from "./arg-registry-YaWTVu_x.js";
+import { n as ArgMeta } from "./arg-registry-B8QvBM_Q.js";
 //#region src/augment.d.ts
 declare module "zod" {
   interface ZodTypeDef {

package/dist/cli-main-BQfutJEX.js

@@ -0,0 +1,3 @@
+import { t as runPolittyCli } from "./cli-main-D4kkrRfX.js";
+
+export { runPolittyCli };

package/dist/{src-KzC0g5CS.js → cli-main-D4kkrRfX.js}

@@ -1,6 +1,6 @@
-import "./completion-gtWX3mwP.js";
-import "./runner-D72I7wvK.js";
-import "./logger-i_bb-Jhc.js";
+import { a as internalField, i as internalArgs } from "./schema-extractor-DMSozq40.js";
+import { n as defineCommand } from "./command-k-4yAz4J.js";
+import { n as runMain } from "./runner-DAGvxV2P.js";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,10 +10,14 @@ import { fileURLToPath } from "node:url";
 * Generator for compile-cache bin shims.
 *
 * Emits the minimal entry file described in docs/recipes.md ("Faster
-* Startup"): a shim that enables the Node.js on-disk compile cache via
-* `politty/compile-cache` and then loads the real CLI with a dynamic
-* import. Meant to be wired into a `postbuild` or `prepack` script via
-* `politty generate-shim` so the shim never has to live in source.
+* Startup"): a shim that enables the Node.js on-disk compile cache and then
+* loads the real CLI with a dynamic import. Meant to be wired into a
+* `postbuild` or `prepack` script via `politty generate-shim` so the shim
+* never has to live in source.
+*
+* Each politty package binds its own generator with
+* {@link createCompileCacheShimGenerator}, so the shim imports the cache
+* helper from the package that generated it.
 */
 /**
 * Marker identifying files this generator wrote (overwrite guard). Must be
@@ -87,7 +91,7 @@ function defaultEntry(outputPath) {
 		if (existsSync(join(dir, candidate))) return candidate;
 	}
 }
-function shimContent(program, entry) {
+function shimContent(program, entry, compileCacheSpecifier) {
 	return [
 		"#!/usr/bin/env node",
 		"",
@@ -96,11 +100,12 @@ function shimContent(program, entry) {
 		"// CLI module graph is compiled, so warm starts skip recompilation",
 		"// (Node >= 22.8.0; silent no-op otherwise).",
 		"try {",
-		"  const { enableCompileCache } = await import(\"politty/compile-cache\");",
+		`  const { enableCompileCache } = await import(${JSON.stringify(compileCacheSpecifier)});`,
 		`  enableCompileCache(${JSON.stringify(program)});`,
 		"} catch {",
-		"  // politty is not resolvable from here (e.g. a fully bundled CLI) —",
-		"  // start without the compile cache rather than failing the CLI.",
+		`  // ${compileCacheSpecifier} is not resolvable from here (e.g. a fully`,
+		"  // bundled CLI) — start without the compile cache rather than failing",
+		"  // the CLI.",
 		"}",
 		`await import(${JSON.stringify(entry)});`,
 		""
@@ -111,13 +116,24 @@ function toArray(value) {
 	return Array.isArray(value) ? value : [value];
 }
 /**
-* Generate executable compile-cache bin shims.
+* Build the shim generator for one politty package.
+*
+* `ownerPackage` is the npm name of the package the generator is exported
+* from (`@politty/zod`, `@politty/valibot`, `politty`), and the shim imports
+* `enableCompileCache` from its `compile-cache` subpath. Taking the name from
+* the owner rather than guessing it is what makes the specifier reliable:
+* reaching this generator at all — through that package's bin or through an
+* import of it — means the package is installed in the host, so the specifier
+* resolves from the shim that lands there. The alternative, reading the host's
+* `package.json`, could only guess which of the three politty packages was
+* meant.
 *
-* With no explicit paths, one shim is generated per `bin` entry of the
-* nearest `package.json`, each importing a conventional built module next
-* to it — so a bare `politty generate-shim` in a `postbuild` script is
-* usually enough. Explicit `entry` values are paired in order with the
-* `bin` entries (or with explicit `out` values of the same count).
+* The returned function generates executable shims. With no explicit paths,
+* one is generated per `bin` entry of the nearest `package.json`, each
+* importing a conventional built module next to it — so a bare
+* `politty generate-shim` in a `postbuild` script is usually enough. Explicit
+* `entry` values are paired in order with the `bin` entries (or with explicit
+* `out` values of the same count).
 *
 * The generated files are ESM (they use top-level `await import`), so `.js`
 * output requires `"type": "module"` in the package; use a `.mjs` extension
@@ -125,7 +141,10 @@ function toArray(value) {
 * a `bin` path still pointing at the real CLI entry fails loudly instead of
 * clobbering the build output.
 */
-function generateCompileCacheShim(options = {}) {
+function createCompileCacheShimGenerator(ownerPackage) {
+	return (options = {}) => generateShims(`${ownerPackage}/compile-cache`, options);
+}
+function generateShims(defaultCompileCacheSpecifier, options) {
 	const cwd = options.cwd ?? process.cwd();
 	const found = readNearestPackageJson(cwd);
 	const pkg = found?.pkg;
@@ -145,6 +164,8 @@ function generateCompileCacheShim(options = {}) {
 	const binNameByPath = /* @__PURE__ */ new Map();
 	if (found) for (const [name, path] of bins) binNameByPath.set(resolve(found.dir, path), name);
 	const warnings = [];
+	const compileCacheSpecifier = options.compileCacheSpecifier ?? defaultCompileCacheSpecifier;
+	if (/[\r\n\u2028\u2029]/.test(compileCacheSpecifier)) throw new Error(`Invalid compile-cache specifier ${JSON.stringify(compileCacheSpecifier)}: a module specifier cannot contain a line terminator.`);
 	const plans = outputPaths.map((outputPath, index) => {
 		const matchedBinName = binNameByPath.get(outputPath);
 		const program = options.program ?? matchedBinName ?? defaultProgramName(pkg);
@@ -168,13 +189,14 @@ function generateCompileCacheShim(options = {}) {
 		return {
 			outputPath,
 			program,
-			entry
+			entry,
+			compileCacheSpecifier
 		};
 	});
 	for (const warning of warnings) console.warn(warning);
 	for (const { outputPath, program, entry } of plans) {
 		mkdirSync(dirname(outputPath), { recursive: true });
-		writeFileSync(outputPath, shimContent(program, entry));
+		writeFileSync(outputPath, shimContent(program, entry, compileCacheSpecifier));
 		chmodSync(outputPath, 493);
 	}
 	return plans;
@@ -188,4 +210,105 @@ function formatShimPath(outputPath, cwd) {
 }
 
 //#endregion
-export { generateCompileCacheShim as n, formatShimPath as t };
+//#region ../core/src/cli-main.ts
+const generateWorkerArgsSchema = internalArgs({
+	bin: internalField.string({
+		description: "CLI binary or built JS entry file to invoke",
+		placeholder: "PATH"
+	}),
+	program: internalField.string({
+		description: "Program name embedded in worker metadata",
+		placeholder: "NAME"
+	}),
+	shell: internalField.enum([
+		"bash",
+		"zsh",
+		"fish"
+	], {
+		description: "Shell worker to generate",
+		placeholder: "SHELL"
+	}),
+	out: internalField.optionalString({
+		description: "Output worker path (defaults to dist/completion/<shell>-worker.<ext>)",
+		placeholder: "PATH"
+	}),
+	verify: internalField.boolean({ description: "Verify __completion-worker-path resolves to the generated worker" })
+});
+const generateWorkerCommand = defineCommand({
+	name: "generate-worker",
+	description: "Generate and verify a bundled shell completion worker",
+	args: generateWorkerArgsSchema,
+	async run(args) {
+		const { generateBundledCompletionWorker } = await import("./src-CLogLsbS.js");
+		await generateBundledCompletionWorker({
+			bin: args.bin,
+			programName: args.program,
+			shell: args.shell,
+			...args.out !== void 0 && { outputPath: args.out },
+			verify: args.verify
+		});
+	}
+});
+const generateShimArgsSchema = internalArgs({
+	entry: internalField.optionalStringArray({
+		description: "Module specifier the shim imports, relative to the shim file; repeatable, one per bin/--out (defaults to ./cli.js, ./cli.mjs, ./index.js, or ./index.mjs next to each shim)",
+		placeholder: "SPECIFIER"
+	}),
+	out: internalField.optionalStringArray({
+		description: "Output path for the generated shim; repeatable, one per --entry (defaults to the bin paths in package.json)",
+		placeholder: "PATH"
+	}),
+	program: internalField.optionalString({
+		description: "Program name for the cache directory, applied to all shims (defaults per shim to its bin name)",
+		placeholder: "NAME"
+	}),
+	compileCacheSpecifier: internalField.optionalString({
+		description: "Module specifier the shim imports enableCompileCache from (defaults to the compile-cache subpath of the politty package running this command)",
+		placeholder: "SPECIFIER"
+	})
+});
+/**
+* Run politty's own development CLI (`generate-shim`, `generate-worker`).
+*
+* `ownerPackage` is the npm name of the politty package providing the `politty`
+* bin that invoked this — `@politty/zod`, `@politty/valibot`, or `politty`. It
+* is threaded through to {@link createCompileCacheShimGenerator} so a generated
+* shim imports the cache helper from the package the user actually installed,
+* which is the one guaranteed to resolve from their own package.
+*
+* Never returns: it exits the process, like `runMain`.
+*/
+function runPolittyCli(ownerPackage) {
+	const generateCompileCacheShim = createCompileCacheShimGenerator(ownerPackage);
+	const generateShimCommand = defineCommand({
+		name: "generate-shim",
+		description: "Generate a compile-cache bin shim that loads the real CLI via dynamic import",
+		args: generateShimArgsSchema,
+		run(args) {
+			const cwd = process.cwd();
+			const results = generateCompileCacheShim({
+				...args.entry !== void 0 && { entry: args.entry },
+				...args.out !== void 0 && { out: args.out },
+				...args.program !== void 0 && { program: args.program },
+				...args.compileCacheSpecifier !== void 0 && { compileCacheSpecifier: args.compileCacheSpecifier },
+				cwd
+			});
+			for (const result of results) console.log(`Generated compile-cache shim: ${formatShimPath(result.outputPath, cwd)} (program: ${result.program}, entry: ${result.entry}, compile-cache: ${result.compileCacheSpecifier})`);
+		}
+	});
+	const cli = defineCommand({
+		name: "politty",
+		description: "politty development utilities",
+		subCommands: {
+			"generate-shim": generateShimCommand,
+			"generate-worker": generateWorkerCommand
+		}
+	});
+	return runMain(cli).catch((error) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}
+
+//#endregion
+export { createCompileCacheShimGenerator as n, runPolittyCli as t };

package/dist/cli-run-wxd6kPPf.js

@@ -0,0 +1,8 @@
+import "./register-DlGnMLIY.js";
+
+//#region src/cli-run.ts
+const { runPolittyCli } = await import("./cli-main-BQfutJEX.js");
+await runPolittyCli("@politty/zod");
+
+//#endregion
+export {  };

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as enableCompileCache } from "./compile-cache-Ct41pWGL.js";
+import { n as enableCompileCache } from "./compile-cache-BC65o7MH.js";
 
 //#region src/cli.ts
 /**
@@ -10,7 +10,7 @@ import { n as enableCompileCache } from "./compile-cache-Ct41pWGL.js";
 * before any code runs, so they could never hit a cache enabled here.
 */
 enableCompileCache("politty");
-await import("./cli-run-eibUcgys.js");
+await import("./cli-run-wxd6kPPf.js");
 
 //#endregion
 export {  };

package/dist/{compile-cache-Ct41pWGL.js → compile-cache-BC65o7MH.js}

@@ -15,7 +15,10 @@ import { homedir } from "node:os";
 *
 * ```ts
 * #!/usr/bin/env node
-* import { enableCompileCache } from "politty/compile-cache";
+* // Import from the `compile-cache` subpath of the politty package your CLI
+* // depends on — `politty generate-shim` writes that specifier for you,
+* // naming whichever package's bin generated the shim.
+* import { enableCompileCache } from "<your-politty-package>/compile-cache";
 *
 * enableCompileCache("my-cli");
 * await import("./cli.js");

package/dist/compile-cache.d.ts

@@ -11,7 +11,10 @@
  *
  * ```ts
  * #!/usr/bin/env node
- * import { enableCompileCache } from "politty/compile-cache";
+ * // Import from the `compile-cache` subpath of the politty package your CLI
+ * // depends on — `politty generate-shim` writes that specifier for you,
+ * // naming whichever package's bin generated the shim.
+ * import { enableCompileCache } from "<your-politty-package>/compile-cache";
  *
  * enableCompileCache("my-cli");
  * await import("./cli.js");

package/dist/compile-cache.js

@@ -1,3 +1,3 @@
-import { n as enableCompileCache, t as compileCacheDir } from "./compile-cache-Ct41pWGL.js";
+import { n as enableCompileCache, t as compileCacheDir } from "./compile-cache-BC65o7MH.js";
 
 export { compileCacheDir, enableCompileCache };

package/dist/{completion-gtWX3mwP.js → completion-DW5qVc3l.js}

@@ -4,8 +4,8 @@ import { n as defineCommand } from "./command-k-4yAz4J.js";
 import { c as resolveSubCommandMeta, i as resolveSubCommandAlias } from "./subcommand-router-Cskpofdk.js";
 import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
-import { execFile, execSync, spawn } from "node:child_process";
 import { promisify } from "node:util";
+import { execFile, execSync, spawn } from "node:child_process";
 
 //#region ../core/src/completion/shell-shared.ts
 /**
@@ -2757,7 +2757,7 @@ async function runTargetBin(bin, args, opts) {
 				...opts.env
 			},
 			encoding: "utf8",
-			maxBuffer: 10 * 1024 * 1024
+			maxBuffer: 10485760
 		});
 		return {
 			stdout,
@@ -3882,7 +3882,8 @@ function createDynamicCompleteCommand(rootCommand, _programName, globalArgsSchem
 			const context = parseCompletionContext(args.args, rootCommand, globalArgsSchema);
 			const inlinePrefix = context.completionType === "option-value" && context.targetOption ? detectInlineOptionPrefix(context.currentWord) : void 0;
 			const effectiveWord = inlinePrefix ? context.currentWord.slice(inlinePrefix.length) : context.currentWord;
-			const output = formatForShell(await generateCandidates(context, { shell: args.shell }), {
+			const result = await generateCandidates(context, { shell: args.shell });
+			const output = formatForShell(result, {
 				shell: args.shell,
 				currentWord: effectiveWord,
 				inlinePrefix
@@ -4587,8 +4588,12 @@ function defaultCacheDir(programName) {
 *            `$XDG_CONFIG_HOME` / `$HOME`.
 */
 function installPath(programName, shell, cacheDir) {
-	if (shell === "fish") return join(process.env.XDG_CONFIG_HOME ?? `${process.env.HOME ?? ""}/.config`, "fish", "completions", `${programName}.fish`);
-	return join(cacheDir ?? defaultCacheDir(programName), `completion.${shell}`);
+	if (shell === "fish") {
+		const cfg = process.env.XDG_CONFIG_HOME ?? `${process.env.HOME ?? ""}/.config`;
+		return join(cfg, "fish", "completions", `${programName}.fish`);
+	}
+	const dir = cacheDir ?? defaultCacheDir(programName);
+	return join(dir, `completion.${shell}`);
 }
 /** Atomic write: tmp file in the same dir, then rename. */
 function writeAtomic(path, content) {

package/dist/completion.d.ts

@@ -1,5 +1,5 @@
-import { C as Command, X as ResolvedFieldMeta, _ as DynamicCompletionResult, b as ArgsSchema, d as ExpandCompletion, g as DynamicCompletionResolver, h as DynamicCompletionContext, m as DynamicCompletionCandidate, p as CompletionDirectiveMask, v as AnyCommand } from "./arg-registry-YaWTVu_x.js";
-import { C as CompletionResult, D as InternalArgsSchema, E as InferInternalArgs, S as CompletionOptions, T as ValueCompletion, _ as CompletablePositional, a as detectShell, b as CompletionGenerator, c as withCompletionCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as CompletableOption, h as BundledWorkerOptions, i as createRefreshCompletionCommand, l as GenerateBundledCompletionWorkerOptions, m as validateBundledWorkerFile, n as createCompletionCommand, o as generateCompletion, p as generateBundledCompletionWorker, r as createCompletionWorkerPathCommand, s as getSupportedShells, t as WithCompletionOptions, u as GenerateBundledCompletionWorkerResult, v as CompletableSubcommand, w as ShellType, x as CompletionMode, y as CompletionData } from "./index-CvhsecfS.js";
+import { C as Command, X as ResolvedFieldMeta, _ as DynamicCompletionResult, b as ArgsSchema, d as ExpandCompletion, g as DynamicCompletionResolver, h as DynamicCompletionContext, m as DynamicCompletionCandidate, p as CompletionDirectiveMask, v as AnyCommand } from "./arg-registry-B8QvBM_Q.js";
+import { C as CompletionResult, D as InternalArgsSchema, E as InferInternalArgs, S as CompletionOptions, T as ValueCompletion, _ as CompletablePositional, a as detectShell, b as CompletionGenerator, c as withCompletionCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as CompletableOption, h as BundledWorkerOptions, i as createRefreshCompletionCommand, l as GenerateBundledCompletionWorkerOptions, m as validateBundledWorkerFile, n as createCompletionCommand, o as generateCompletion, p as generateBundledCompletionWorker, r as createCompletionWorkerPathCommand, s as getSupportedShells, t as WithCompletionOptions, u as GenerateBundledCompletionWorkerResult, v as CompletableSubcommand, w as ShellType, x as CompletionMode, y as CompletionData } from "./index-CMb2xLiJ.js";
 //#region ../core/src/completion/dynamic/context-parser.d.ts
 /**
  * Completion type indicates what kind of completion is expected

package/dist/completion.js

@@ -1,4 +1,4 @@
-import "./register-Bk0K83W2.js";
-import { _ as CompletionDirective, a as generateCompletion, b as resolveValueCompletion, c as createDynamicCompleteCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as extractPositionals, h as extractCompletionData, i as detectShell, l as hasCompleteCommand, m as validateBundledWorkerFile, n as createCompletionWorkerPathCommand, o as getSupportedShells, p as generateBundledCompletionWorker, r as createRefreshCompletionCommand, s as withCompletionCommand, t as createCompletionCommand, u as formatForShell, v as generateCandidates, y as parseCompletionContext } from "./completion-gtWX3mwP.js";
+import "./register-DlGnMLIY.js";
+import { _ as CompletionDirective, a as generateCompletion, b as resolveValueCompletion, c as createDynamicCompleteCommand, d as bundledWorkerShellExtension, f as defaultBundledWorkerOutputPath, g as extractPositionals, h as extractCompletionData, i as detectShell, l as hasCompleteCommand, m as validateBundledWorkerFile, n as createCompletionWorkerPathCommand, o as getSupportedShells, p as generateBundledCompletionWorker, r as createRefreshCompletionCommand, s as withCompletionCommand, t as createCompletionCommand, u as formatForShell, v as generateCandidates, y as parseCompletionContext } from "./completion-DW5qVc3l.js";
 
 export { CompletionDirective, bundledWorkerShellExtension, createCompletionCommand, createCompletionWorkerPathCommand, createDynamicCompleteCommand, createRefreshCompletionCommand, defaultBundledWorkerOutputPath, detectShell, extractCompletionData, extractPositionals, formatForShell, generateBundledCompletionWorker, generateCandidates, generateCompletion, getSupportedShells, hasCompleteCommand, parseCompletionContext, resolveValueCompletion, validateBundledWorkerFile, withCompletionCommand };

package/dist/docs.d.ts

@@ -1,4 +1,4 @@
-import { T as Example, U as SubCommandValue, X as ResolvedFieldMeta, Y as ExtractedFields, b as ArgsSchema, tt as SchemaLike, v as AnyCommand } from "./arg-registry-YaWTVu_x.js";
+import { T as Example, U as SubCommandValue, X as ResolvedFieldMeta, Y as ExtractedFields, b as ArgsSchema, tt as SchemaLike, v as AnyCommand } from "./arg-registry-B8QvBM_Q.js";
 import * as fs from "node:fs";
 //#region ../core/src/executor/subcommand-router.d.ts
 /**

package/dist/docs.js

@@ -1,8 +1,8 @@
 import { a as getValidatorAdapter } from "./field-meta-DMy5BcRr.js";
-import "./register-Bk0K83W2.js";
+import "./register-DlGnMLIY.js";
 import { n as getExtractedFields, t as extractFields } from "./schema-extractor-DMSozq40.js";
-import { r as resolveLazyCommand } from "./subcommand-router-Cskpofdk.js";
 import { t as createLogCollector } from "./log-collector-CoUkLVJB.js";
+import { r as resolveLazyCommand } from "./subcommand-router-Cskpofdk.js";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
 import path from "node:path";
@@ -67,10 +67,19 @@ function toOptionRows(options) {
 	return options.map(toOptionRow);
 }
 /**
-* Escape markdown special characters in table cells.
+* Convert hard line breaks in a description into `<br>` so they render as line
+* breaks inside a single markdown table cell or list item, instead of breaking
+* the surrounding table row / list structure.
+*/
+function inlineMarkdownBreaks(str) {
+	return str.replace(/\r?\n/g, "<br>");
+}
+/**
+* Escape markdown special characters in table cells. Embedded line breaks are
+* converted to `<br>` so multi-line descriptions stay within a single cell.
 */
 function escapeTableCell$2(str) {
-	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
+	return inlineMarkdownBreaks(str.replace(/\|/g, "\\|"));
 }
 function backtick(value) {
 	return `\`${value}\``;
@@ -195,12 +204,12 @@ function emitMarkdownList(rows) {
 			...longAliases
 		].map(backtick).join(", ");
 		if (row.inlineNegation) flags += ` / ${backtick(row.inlineNegation)}`;
-		const desc = row.description ? ` - ${row.description}` : "";
+		const desc = row.description ? ` - ${inlineMarkdownBreaks(row.description)}` : "";
 		const required = row.required ? " (required)" : "";
 		const defaultVal = row.hasDefault ? ` (default: ${JSON.stringify(row.defaultValue)})` : "";
 		const envInfo = formatEnvInfo(row.env);
 		lines.push(`- ${flags}${desc}${required}${defaultVal}${envInfo}`);
-		if (row.negationRow) lines.push(`- ${backtick(row.negationRow.flag)} - ${row.negationRow.description} ${row.negationRow.relationMarker}`);
+		if (row.negationRow) lines.push(`- ${backtick(row.negationRow.flag)} - ${inlineMarkdownBreaks(row.negationRow.description)} ${row.negationRow.relationMarker}`);
 	}
 	return lines.join("\n");
 }
@@ -306,10 +315,11 @@ function indexEndMarker(scope) {
 //#endregion
 //#region ../core/src/docs/default-renderers.ts
 /**
-* Escape markdown special characters in table cells
+* Escape markdown special characters in table cells. Embedded line breaks are
+* converted to `<br>` so multi-line descriptions stay within a single cell.
 */
 function escapeTableCell$1(str) {
-	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
+	return inlineMarkdownBreaks(str.replace(/\|/g, "\\|"));
 }
 /**
 * Render usage line
@@ -346,7 +356,7 @@ function renderArgumentsList(info) {
 	const lines = [];
 	for (const arg of info.positionalArgs) {
 		const required = arg.required ? "(required)" : "(optional)";
-		const desc = arg.description ? ` - ${arg.description}` : "";
+		const desc = arg.description ? ` - ${inlineMarkdownBreaks(arg.description)}` : "";
 		lines.push(`- \`${arg.name}\`${desc} ${required}`);
 	}
 	return lines.join("\n");
@@ -503,7 +513,7 @@ function renderArgumentsListFromArray(args) {
 	const lines = [];
 	for (const arg of args) {
 		const required = arg.required ? "(required)" : "(optional)";
-		const desc = arg.description ? ` - ${arg.description}` : "";
+		const desc = arg.description ? ` - ${inlineMarkdownBreaks(arg.description)}` : "";
 		lines.push(`- \`${arg.name}\`${desc} ${required}`);
 	}
 	return lines.join("\n");
@@ -921,7 +931,7 @@ async function executeSingleExample(example, rootCommand, commandPath) {
 	collector.start();
 	let success = true;
 	try {
-		const { runCommand } = await import("./runner-FvUwOHyE.js");
+		const { runCommand } = await import("./runner-MMjpKeEa.js");
 		const result = await runCommand(rootCommand, argv);
 		success = result.success;
 		if (!result.success && result.error) console.error(result.error.message);
@@ -2882,7 +2892,8 @@ async function generateDoc(config) {
 			} else if (parsed.kind === "global-options") if (normalizedTemplateGlobalOptions) replacements.set(placeholder, buildGlobalOptionsContent(normalizedTemplateGlobalOptions));
 			else replacements.set(placeholder, "");
 			else if (parsed.kind === "index") {
-				const indexContent = await renderCommandIndex(command, [...deriveIndexFromFiles(files, outputPath, allCommands, ignores), ...deriveIndexFromTemplateOutputs(templateMeta, outputPath, outputPath, allCommands)], rootDoc?.index);
+				const categories = [...deriveIndexFromFiles(files, outputPath, allCommands, ignores), ...deriveIndexFromTemplateOutputs(templateMeta, outputPath, outputPath, allCommands)];
+				const indexContent = await renderCommandIndex(command, categories, rootDoc?.index);
 				replacements.set(placeholder, indexContent);
 			}
 		}

package/dist/{index-CvhsecfS.d.ts → index-CMb2xLiJ.d.ts}

@@ -1,4 +1,4 @@
-import { C as Command, Z as UnknownKeysMode, b as ArgsSchema, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, n as ArgMeta, v as AnyCommand } from "./arg-registry-YaWTVu_x.js";
+import { C as Command, Z as UnknownKeysMode, b as ArgsSchema, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, n as ArgMeta, v as AnyCommand } from "./arg-registry-B8QvBM_Q.js";
 //#region ../core/src/adapter/internal-args.d.ts
 /** Runtime brand distinguishing internal descriptors from library schemas. */
 declare const INTERNAL_ARGS_BRAND = "__polittyInternalArgs";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { $ as toKebabCase, A as LogEntry, B as RunResultSuccess, C as Command, D as GlobalCleanupContext, E as GlobalArgs, F as NonRunnableCommand, G as UnknownSubcommandHandler, H as SetupContext, I as PromptResolver, J as lazy, K as LazyCommand, L as RunCommandOptions, M as LogStream, N as Logger, O as GlobalSetupContext, P as MainOptions, Q as toCamelCase, R as RunResult, S as CollectedLogs, T as Example, U as SubCommandValue, V as RunnableCommand, W as SubCommandsRecord, X as ResolvedFieldMeta, Y as ExtractedFields, Z as UnknownKeysMode, _ as DynamicCompletionResult, a as CustomCompletion, b as ArgsSchema$1, c as PromptType, d as ExpandCompletion, et as InferSchemaOutput, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, h as DynamicCompletionContext, i as CompletionType, j as LogLevel, k as IsEmpty, l as ValidateArgMeta, m as DynamicCompletionCandidate, n as ArgMeta, o as EffectContext, p as CompletionDirectiveMask, q as isLazyCommand, r as CompletionMeta, s as PromptMeta, t as ArgFn, tt as SchemaLike, u as ExpandCandidate, v as AnyCommand, w as CommandBase, x as CleanupContext, y as ArgSource, z as RunResultFailure } from "./arg-registry-YaWTVu_x.js";
-import { C as CompletionResult, D as InternalArgsSchema, S as CompletionOptions, c as withCompletionCommand, l as GenerateBundledCompletionWorkerOptions, o as generateCompletion, p as generateBundledCompletionWorker, t as WithCompletionOptions, u as GenerateBundledCompletionWorkerResult } from "./index-CvhsecfS.js";
+import { $ as toKebabCase, A as LogEntry, B as RunResultSuccess, C as Command, D as GlobalCleanupContext, E as GlobalArgs, F as NonRunnableCommand, G as UnknownSubcommandHandler, H as SetupContext, I as PromptResolver, J as lazy, K as LazyCommand, L as RunCommandOptions, M as LogStream, N as Logger, O as GlobalSetupContext, P as MainOptions, Q as toCamelCase, R as RunResult, S as CollectedLogs, T as Example, U as SubCommandValue, V as RunnableCommand, W as SubCommandsRecord, X as ResolvedFieldMeta, Y as ExtractedFields, Z as UnknownKeysMode, _ as DynamicCompletionResult, a as CustomCompletion, b as ArgsSchema$1, c as PromptType, d as ExpandCompletion, et as InferSchemaOutput, f as ResolvedExpandCandidate, g as DynamicCompletionResolver, h as DynamicCompletionContext, i as CompletionType, j as LogLevel, k as IsEmpty, l as ValidateArgMeta, m as DynamicCompletionCandidate, n as ArgMeta, o as EffectContext, p as CompletionDirectiveMask, q as isLazyCommand, r as CompletionMeta, s as PromptMeta, t as ArgFn, tt as SchemaLike, u as ExpandCandidate, v as AnyCommand, w as CommandBase, x as CleanupContext, y as ArgSource, z as RunResultFailure } from "./arg-registry-B8QvBM_Q.js";
+import { C as CompletionResult, D as InternalArgsSchema, S as CompletionOptions, c as withCompletionCommand, l as GenerateBundledCompletionWorkerOptions, o as generateCompletion, p as generateBundledCompletionWorker, t as WithCompletionOptions, u as GenerateBundledCompletionWorkerResult } from "./index-CMb2xLiJ.js";
 import { z } from "zod";
 //#region ../core/src/core/schema-extractor.d.ts
 /**
@@ -43,18 +43,38 @@ type ValidationResult<T> = {
   errors: ValidationError[];
 };
 //#endregion
+//#region ../core/src/cli-main.d.ts
+/**
+ * Run politty's own development CLI (`generate-shim`, `generate-worker`).
+ *
+ * `ownerPackage` is the npm name of the politty package providing the `politty`
+ * bin that invoked this — `@politty/zod`, `@politty/valibot`, or `politty`. It
+ * is threaded through to {@link createCompileCacheShimGenerator} so a generated
+ * shim imports the cache helper from the package the user actually installed,
+ * which is the one guaranteed to resolve from their own package.
+ *
+ * Never returns: it exits the process, like `runMain`.
+ */
+declare function runPolittyCli(ownerPackage: string): Promise<never>;
+//#endregion
 //#region ../core/src/compile-cache-shim.d.ts
 /**
  * Generator for compile-cache bin shims.
  *
  * Emits the minimal entry file described in docs/recipes.md ("Faster
- * Startup"): a shim that enables the Node.js on-disk compile cache via
- * `politty/compile-cache` and then loads the real CLI with a dynamic
- * import. Meant to be wired into a `postbuild` or `prepack` script via
- * `politty generate-shim` so the shim never has to live in source.
+ * Startup"): a shim that enables the Node.js on-disk compile cache and then
+ * loads the real CLI with a dynamic import. Meant to be wired into a
+ * `postbuild` or `prepack` script via `politty generate-shim` so the shim
+ * never has to live in source.
+ *
+ * Each politty package binds its own generator with
+ * {@link createCompileCacheShimGenerator}, so the shim imports the cache
+ * helper from the package that generated it.
  */
 /**
- * Options for {@link generateCompileCacheShim}.
+ * Options for the generator returned by
+ * {@link createCompileCacheShimGenerator} — exported as
+ * `generateCompileCacheShim` from each politty package.
  */
 interface GenerateCompileCacheShimOptions {
   /**
@@ -86,9 +106,18 @@ interface GenerateCompileCacheShimOptions {
    * `package.json` (default: `process.cwd()`).
    */
   cwd?: string;
+  /**
+   * Module specifier the shim imports `enableCompileCache` from. Defaults to
+   * the `compile-cache` subpath of the politty package this generator belongs
+   * to (see {@link createCompileCacheShimGenerator}). Set this when politty is
+   * reached some other way — a re-export from your own package, an import
+   * map, and so on.
+   */
+  compileCacheSpecifier?: string;
 }
 /**
- * One generated shim from {@link generateCompileCacheShim}.
+ * One generated shim from the generator returned by
+ * {@link createCompileCacheShimGenerator}.
  */
 interface GenerateCompileCacheShimResult {
   /** Absolute path of the generated shim. */
@@ -97,15 +126,28 @@ interface GenerateCompileCacheShimResult {
   program: string;
   /** Entry specifier baked into the shim. */
   entry: string;
+  /** Specifier the shim imports `enableCompileCache` from. */
+  compileCacheSpecifier: string;
 }
 /**
- * Generate executable compile-cache bin shims.
- *
- * With no explicit paths, one shim is generated per `bin` entry of the
- * nearest `package.json`, each importing a conventional built module next
- * to it — so a bare `politty generate-shim` in a `postbuild` script is
- * usually enough. Explicit `entry` values are paired in order with the
- * `bin` entries (or with explicit `out` values of the same count).
+ * Build the shim generator for one politty package.
+ *
+ * `ownerPackage` is the npm name of the package the generator is exported
+ * from (`@politty/zod`, `@politty/valibot`, `politty`), and the shim imports
+ * `enableCompileCache` from its `compile-cache` subpath. Taking the name from
+ * the owner rather than guessing it is what makes the specifier reliable:
+ * reaching this generator at all — through that package's bin or through an
+ * import of it — means the package is installed in the host, so the specifier
+ * resolves from the shim that lands there. The alternative, reading the host's
+ * `package.json`, could only guess which of the three politty packages was
+ * meant.
+ *
+ * The returned function generates executable shims. With no explicit paths,
+ * one is generated per `bin` entry of the nearest `package.json`, each
+ * importing a conventional built module next to it — so a bare
+ * `politty generate-shim` in a `postbuild` script is usually enough. Explicit
+ * `entry` values are paired in order with the `bin` entries (or with explicit
+ * `out` values of the same count).
  *
  * The generated files are ESM (they use top-level `await import`), so `.js`
  * output requires `"type": "module"` in the package; use a `.mjs` extension
@@ -113,7 +155,7 @@ interface GenerateCompileCacheShimResult {
  * a `bin` path still pointing at the real CLI entry fails loudly instead of
  * clobbering the build output.
  */
-declare function generateCompileCacheShim(options?: GenerateCompileCacheShimOptions): GenerateCompileCacheShimResult[];
+declare function createCompileCacheShimGenerator(ownerPackage: string): (options?: GenerateCompileCacheShimOptions) => GenerateCompileCacheShimResult[];
 //#endregion
 //#region ../core/src/core/case-types.d.ts
 /**
@@ -786,6 +828,15 @@ declare function validateCommand(command: AnyCommand, options?: ValidateCommandO
 declare function formatCommandValidationErrors(errors: CommandValidationError[]): string;
 //#endregion
 //#region src/index.d.ts
+/**
+ * Generate compile-cache bin shims that import the cache helper from
+ * `@politty/zod/compile-cache`.
+ *
+ * The specifier is this package's own name rather than something derived from
+ * the caller's `package.json`: reaching this function means `@politty/zod` is
+ * installed, so the shim it writes into your package can resolve it.
+ */
+declare const generateCompileCacheShim: (options?: GenerateCompileCacheShimOptions) => GenerateCompileCacheShimResult[];
 /**
  * Supported schema types for args in this package: zod schemas whose
  * output is an object. Narrows `@politty/core`'s Standard-Schema-based
@@ -796,4 +847,4 @@ declare const defineCommand: DefineCommandFn<ArgsSchema>;
 declare const createDefineCommand: CreateDefineCommandFn<ArgsSchema>;
 declare const arg: ArgFn<z.ZodType>;
 //#endregion
-export { type AnyCommand, type ArgFn, type ArgMeta, type ArgSource, ArgsSchema, type BoundDefineCommandFn, type BuiltinOptionDescriptions, type CamelCase, CaseVariantCollisionError, type CleanupContext, type CollectedLogs, type Command, type CommandBase, type CommandContext, type CommandValidationError, type CommandValidationResult, type CompletionDirectiveMask, type CompletionMeta, type CompletionOptions, type CompletionResult, type CompletionType, type CreateDefineCommandFn, type CustomCompletion, type DefineCommandFn, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type EffectContext, type Example, type ExpandCandidate, type ExpandCompletion, type ExtractedFields, FieldTypeConflictError, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type GenerateCompileCacheShimOptions, type GenerateCompileCacheShimResult, type GlobalArgs, type GlobalCleanupContext, type GlobalSetupContext, type HelpOptions, type InferSchemaOutput, type KebabCase, type LazyCommand, type LogEntry, type LogLevel, type LogStream, type Logger, type MainOptions, type MergedArgs, type NonRunnableCommand, type ParsedArgv, type ParserOptions, PositionalConfigError, type PromptMeta, type PromptResolver, type PromptType, ReservedAliasError, ReservedFieldNameError, type ResolvedExpandCandidate, type ResolvedFieldMeta, type RunCommandOptions, type RunResult, type RunResultFailure, type RunResultSuccess, type RunnableCommand, type SchemaLike, type SetupContext, type SubCommandValue, type SubCommandsRecord, type UnknownKeysMode, type UnknownSubcommandHandler, type ValidateArgMeta, type ValidationError, type ValidationResult, type WithCaseVariants, type WithCompletionOptions, arg, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompileCacheShim, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, validateReservedFieldNames, withCompletionCommand };
+export { type AnyCommand, type ArgFn, type ArgMeta, type ArgSource, ArgsSchema, type BoundDefineCommandFn, type BuiltinOptionDescriptions, type CamelCase, CaseVariantCollisionError, type CleanupContext, type CollectedLogs, type Command, type CommandBase, type CommandContext, type CommandValidationError, type CommandValidationResult, type CompletionDirectiveMask, type CompletionMeta, type CompletionOptions, type CompletionResult, type CompletionType, type CreateDefineCommandFn, type CustomCompletion, type DefineCommandFn, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type EffectContext, type Example, type ExpandCandidate, type ExpandCompletion, type ExtractedFields, FieldTypeConflictError, type GenerateBundledCompletionWorkerOptions, type GenerateBundledCompletionWorkerResult, type GenerateCompileCacheShimOptions, type GenerateCompileCacheShimResult, type GlobalArgs, type GlobalCleanupContext, type GlobalSetupContext, type HelpOptions, type InferSchemaOutput, type KebabCase, type LazyCommand, type LogEntry, type LogLevel, type LogStream, type Logger, type MainOptions, type MergedArgs, type NonRunnableCommand, type ParsedArgv, type ParserOptions, PositionalConfigError, type PromptMeta, type PromptResolver, type PromptType, ReservedAliasError, ReservedFieldNameError, type ResolvedExpandCandidate, type ResolvedFieldMeta, type RunCommandOptions, type RunResult, type RunResultFailure, type RunResultSuccess, type RunnableCommand, type SchemaLike, type SetupContext, type SubCommandValue, type SubCommandsRecord, type UnknownKeysMode, type UnknownSubcommandHandler, type ValidateArgMeta, type ValidationError, type ValidationResult, type WithCaseVariants, type WithCompletionOptions, arg, createCompileCacheShimGenerator, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompileCacheShim, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, runPolittyCli, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, validateReservedFieldNames, withCompletionCommand };

package/dist/index.js

@@ -1,17 +1,27 @@
 import { i as toKebabCase, r as toCamelCase } from "./field-meta-DMy5BcRr.js";
-import { t as arg$1 } from "./register-Bk0K83W2.js";
-import { n as generateCompileCacheShim } from "./src-KzC0g5CS.js";
+import { t as arg$1 } from "./register-DlGnMLIY.js";
 import { r as getUnknownKeysMode, t as extractFields } from "./schema-extractor-DMSozq40.js";
+import { n as createCompileCacheShimGenerator, t as runPolittyCli } from "./cli-main-D4kkrRfX.js";
 import { n as defineCommand$1, t as createDefineCommand$1 } from "./command-k-4yAz4J.js";
+import { C as ReservedFieldNameError, E as renderMarkdown, S as ReservedAliasError, T as renderInline, _ as DuplicateAliasError, a as parseArgv, b as FieldTypeConflictError, c as validateCommand, d as validateDuplicateFields, f as validateDuplicateNegations, g as CaseVariantCollisionError, h as validateReservedFieldNames, i as formatValidationErrors, l as validateCrossSchemaCollisions, m as validateReservedAliases, n as runMain, o as formatCommandValidationErrors, p as validatePositionalConfig, r as createDualCaseProxy, s as validateCaseVariantCollisions, t as runCommand, u as validateDuplicateAliases, v as DuplicateFieldError, w as generateHelp, x as PositionalConfigError, y as DuplicateNegationError } from "./runner-DAGvxV2P.js";
 import { o as isLazyCommand, s as lazy } from "./subcommand-router-Cskpofdk.js";
-import { a as generateCompletion, p as generateBundledCompletionWorker, s as withCompletionCommand } from "./completion-gtWX3mwP.js";
-import { C as generateHelp, E as createDualCaseProxy, S as ReservedFieldNameError, T as renderMarkdown, _ as DuplicateFieldError, a as formatCommandValidationErrors, b as PositionalConfigError, c as validateCrossSchemaCollisions, d as validateDuplicateNegations, f as validatePositionalConfig, g as DuplicateAliasError, h as CaseVariantCollisionError, i as parseArgv, l as validateDuplicateAliases, m as validateReservedFieldNames, n as runMain, o as validateCaseVariantCollisions, p as validateReservedAliases, r as formatValidationErrors, s as validateCommand, t as runCommand, u as validateDuplicateFields, v as DuplicateNegationError, w as renderInline, x as ReservedAliasError, y as FieldTypeConflictError } from "./runner-D72I7wvK.js";
 import { a as symbols, i as styles, n as logger, r as setColorEnabled, t as isColorEnabled } from "./logger-i_bb-Jhc.js";
+import { a as generateCompletion, p as generateBundledCompletionWorker, s as withCompletionCommand } from "./completion-DW5qVc3l.js";
+import "./src-bYH2XCQ4.js";
 
 //#region src/index.ts
+/**
+* Generate compile-cache bin shims that import the cache helper from
+* `@politty/zod/compile-cache`.
+*
+* The specifier is this package's own name rather than something derived from
+* the caller's `package.json`: reaching this function means `@politty/zod` is
+* installed, so the shim it writes into your package can resolve it.
+*/
+const generateCompileCacheShim = createCompileCacheShimGenerator("@politty/zod");
 const defineCommand = defineCommand$1;
 const createDefineCommand = createDefineCommand$1;
 const arg = arg$1;
 
 //#endregion
-export { CaseVariantCollisionError, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, FieldTypeConflictError, PositionalConfigError, ReservedAliasError, ReservedFieldNameError, arg, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompileCacheShim, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, validateReservedFieldNames, withCompletionCommand };
+export { CaseVariantCollisionError, DuplicateAliasError, DuplicateFieldError, DuplicateNegationError, FieldTypeConflictError, PositionalConfigError, ReservedAliasError, ReservedFieldNameError, arg, createCompileCacheShimGenerator, createDefineCommand, createDualCaseProxy, defineCommand, extractFields, formatCommandValidationErrors, formatValidationErrors, generateBundledCompletionWorker, generateCompileCacheShim, generateCompletion, generateHelp, getUnknownKeysMode, isColorEnabled, isLazyCommand, lazy, logger, parseArgv, renderInline, renderMarkdown, runCommand, runMain, runPolittyCli, setColorEnabled, styles, symbols, toCamelCase, toKebabCase, validateCaseVariantCollisions, validateCommand, validateCrossSchemaCollisions, validateDuplicateAliases, validateDuplicateFields, validateDuplicateNegations, validatePositionalConfig, validateReservedAliases, validateReservedFieldNames, withCompletionCommand };

package/dist/{prompt-CEIZ-7H1.js → prompt-BjIZThsH.js}

@@ -156,12 +156,10 @@ async function promptAndCollect(adapter, result, config) {
 		case "confirm":
 			value = await adapter.confirm({ message });
 			break;
-		case "select":
-			value = await adapter.select({
-				message,
-				options: config.choices ?? []
-			});
-			break;
+		case "select": value = await adapter.select({
+			message,
+			options: config.choices ?? []
+		});
 	}
 	if (adapter.isCancelled(value)) throw new Error("Prompt cancelled by user");
 	result[config.field.name] = value;

package/dist/prompt-clack.d.ts

@@ -1,4 +1,4 @@
-import { I as PromptResolver } from "./arg-registry-YaWTVu_x.js";
+import { I as PromptResolver } from "./arg-registry-B8QvBM_Q.js";
 //#region ../core/src/prompt/clack/index.d.ts
 /**
  * Prompt resolver backed by @clack/prompts.

package/dist/prompt-clack.js

@@ -1,5 +1,5 @@
-import "./register-Bk0K83W2.js";
-import { t as promptMissingArgs } from "./prompt-CEIZ-7H1.js";
+import "./register-DlGnMLIY.js";
+import { t as promptMissingArgs } from "./prompt-BjIZThsH.js";
 import { confirm, isCancel, password, select, text } from "@clack/prompts";
 
 //#region ../core/src/prompt/clack/index.ts

package/dist/prompt-inquirer.d.ts

@@ -1,4 +1,4 @@
-import { I as PromptResolver } from "./arg-registry-YaWTVu_x.js";
+import { I as PromptResolver } from "./arg-registry-B8QvBM_Q.js";
 //#region ../core/src/prompt/inquirer/index.d.ts
 /**
  * Prompt resolver backed by @inquirer/prompts.

package/dist/prompt-inquirer.js

@@ -1,5 +1,5 @@
-import "./register-Bk0K83W2.js";
-import { t as promptMissingArgs } from "./prompt-CEIZ-7H1.js";
+import "./register-DlGnMLIY.js";
+import { t as promptMissingArgs } from "./prompt-BjIZThsH.js";
 import { confirm, input, password, select } from "@inquirer/prompts";
 
 //#region ../core/src/prompt/inquirer/index.ts

package/dist/prompt.d.ts

@@ -1,4 +1,4 @@
-import { X as ResolvedFieldMeta, Y as ExtractedFields } from "./arg-registry-YaWTVu_x.js";
+import { X as ResolvedFieldMeta, Y as ExtractedFields } from "./arg-registry-B8QvBM_Q.js";
 //#region ../core/src/prompt/types.d.ts
 /**
  * Resolved prompt configuration for a single field

package/dist/prompt.js

@@ -1,4 +1,4 @@
-import "./register-Bk0K83W2.js";
-import { i as resolvePromptConfig, n as isInteractive, r as getFieldsToPrompt, t as promptMissingArgs } from "./prompt-CEIZ-7H1.js";
+import "./register-DlGnMLIY.js";
+import { i as resolvePromptConfig, n as isInteractive, r as getFieldsToPrompt, t as promptMissingArgs } from "./prompt-BjIZThsH.js";
 
 export { getFieldsToPrompt, isInteractive, promptMissingArgs, resolvePromptConfig };

package/dist/{register-Bk0K83W2.js → register-DlGnMLIY.js}

@@ -187,8 +187,9 @@ function extractDescription(schema) {
 * `resolveFieldMeta` (adapter/field-meta.ts).
 */
 function resolveZodFieldMeta(name, schema) {
+	const argMeta = getArgMeta(schema) ?? getArgMeta(unwrapSchema(schema));
 	return resolveFieldMeta(name, {
-		argMeta: getArgMeta(schema) ?? getArgMeta(unwrapSchema(schema)),
+		argMeta,
 		description: extractDescription(schema),
 		required: isRequired(schema),
 		defaultValue: extractDefaultValue(schema),

package/dist/{runner-D72I7wvK.js → runner-DAGvxV2P.js}

@@ -1,47 +1,11 @@
 import { a as getValidatorAdapter, i as toKebabCase, r as toCamelCase, t as getAllAliases } from "./field-meta-DMy5BcRr.js";
 import { n as getExtractedFields, o as isInternalArgsSchema, s as validateInternalArgs, t as extractFields } from "./schema-extractor-DMSozq40.js";
-import { a as resolveSubcommandWithAlias, c as resolveSubCommandMeta, n as listSubCommands, o as isLazyCommand, r as resolveLazyCommand, t as listSubCommandNamesWithAliases } from "./subcommand-router-Cskpofdk.js";
-import { n as enableCompileCache } from "./compile-cache-Ct41pWGL.js";
+import { n as enableCompileCache } from "./compile-cache-BC65o7MH.js";
 import { n as emptyLogs, r as mergeLogs, t as createLogCollector } from "./log-collector-CoUkLVJB.js";
+import { a as resolveSubcommandWithAlias, c as resolveSubCommandMeta, n as listSubCommands, o as isLazyCommand, r as resolveLazyCommand, t as listSubCommandNamesWithAliases } from "./subcommand-router-Cskpofdk.js";
 import { a as symbols, i as styles } from "./logger-i_bb-Jhc.js";
 import { stripVTControlCharacters } from "node:util";
 
-//#region ../core/src/core/case-proxy.ts
-/**
-* Wrap an args object with a Proxy that allows dual-case access.
-*
-* Given `{ "my-option": "value" }`, both `obj["my-option"]` and `obj.myOption`
-* will return `"value"`.
-*
-* - `Object.keys()`, `JSON.stringify()`, and spread return only the original keys.
-* - The `in` operator detects both case variants.
-*/
-function createDualCaseProxy(obj) {
-	return new Proxy(obj, {
-		get(target, prop, receiver) {
-			if (typeof prop === "string") {
-				if (prop in target) return Reflect.get(target, prop, receiver);
-				const camel = toCamelCase(prop);
-				if (camel !== prop && camel in target) return Reflect.get(target, camel, receiver);
-				const kebab = toKebabCase(prop);
-				if (kebab !== prop && kebab in target) return Reflect.get(target, kebab, receiver);
-			}
-			return Reflect.get(target, prop, receiver);
-		},
-		has(target, prop) {
-			if (typeof prop === "string") {
-				if (prop in target) return true;
-				const camel = toCamelCase(prop);
-				if (camel !== prop && camel in target) return true;
-				const kebab = toKebabCase(prop);
-				if (kebab !== prop && kebab in target) return true;
-			}
-			return Reflect.has(target, prop);
-		}
-	});
-}
-
-//#endregion
 //#region ../core/src/executor/command-runner.ts
 /**
 * Execute a command lifecycle: setup → run → cleanup
@@ -121,7 +85,9 @@ async function executeLifecycle(command, args, _options = {}) {
 		}
 	}
 	collector?.stop();
-	const logs = mergeLogs(_options.existingLogs ?? emptyLogs(), collector?.getLogs() ?? emptyLogs());
+	const existingLogs = _options.existingLogs ?? emptyLogs();
+	const collectedLogs = collector?.getLogs() ?? emptyLogs();
+	const logs = mergeLogs(existingLogs, collectedLogs);
 	if (error) return {
 		success: false,
 		error,
@@ -771,16 +737,31 @@ function padEndVisual(str, width) {
 	return str + " ".repeat(padding);
 }
 /**
+* Re-indent the continuation lines of a multi-line description so they align
+* under the description column. A `\n` in a description is treated as a hard
+* line break; every line after the first is padded to `column` spaces.
+*/
+function indentDescription(description, column) {
+	if (!description.includes("\n")) return description;
+	const pad = " ".repeat(column);
+	return description.split("\n").join(`\n${pad}`);
+}
+/**
 * Format a single option line
 * If flags exceed the column width, description is moved to the next line
+*
+* Descriptions may contain `\n` line breaks; continuation lines are indented to
+* stay aligned under the description column.
 */
 function formatOption(flags, description, indent = 0, extraDescPadding = 0) {
 	const flagWidth = 32;
 	const indentStr = "  ".repeat(indent);
 	const visualFlagLength = stripAnsi(flags).length;
 	const effectiveFlagWidth = flagWidth - indent * 2 + extraDescPadding;
-	if (visualFlagLength >= effectiveFlagWidth) return `${indentStr}  ${flags}\n${" ".repeat(effectiveFlagWidth + 2 + indent * 2)}${description}`;
-	return `${indentStr}  ${padEndVisual(flags, effectiveFlagWidth)}${description}`;
+	const descColumn = effectiveFlagWidth + 2 + indent * 2;
+	const desc = indentDescription(description, descColumn);
+	if (visualFlagLength >= effectiveFlagWidth) return `${indentStr}  ${flags}\n${" ".repeat(descColumn)}${desc}`;
+	return `${indentStr}  ${padEndVisual(flags, effectiveFlagWidth)}${desc}`;
 }
 /**
 * Format a single option field as a help line
@@ -915,7 +896,7 @@ function renderExamplesForHelp(examples, context) {
 	const cmdPath = context?.commandPath?.join(" ") ?? "";
 	const fullPrefix = cmdPath ? `${cmdPrefix}${cmdPath} ` : cmdPrefix;
 	for (const example of examples) {
-		lines.push(`  ${styles.dim(example.desc)}`);
+		lines.push(`  ${styles.dim(example.desc).split("\n").join("\n  ")}`);
 		lines.push(`    ${styles.dim("$")} ${fullPrefix}${example.cmd}`);
 		if (example.output) for (const line of example.output.split("\n")) lines.push(`    ${line}`);
 		lines.push("");
@@ -1237,7 +1218,10 @@ function checkReservedFieldNames(extracted, commandPath) {
 */
 function validateDuplicateFields(extracted) {
 	const errors = checkDuplicateFields(extracted, []);
-	if (errors.length > 0) throw new DuplicateFieldError(`Duplicate field name "${errors[0]?.field ?? "unknown"}" detected. Each field must have a unique name.`);
+	if (errors.length > 0) {
+		const field = errors[0]?.field ?? "unknown";
+		throw new DuplicateFieldError(`Duplicate field name "${field}" detected. Each field must have a unique name.`);
+	}
 }
 /**
 * Validate that no duplicate aliases exist
@@ -2196,7 +2180,9 @@ function parseArgs(argv, command, options = {}) {
 */
 function parseGlobalArgs(tokens, globalExtracted) {
 	if (tokens.length === 0) return {};
-	return mergeWithPositionals(parseArgv(tokens, buildParserOptions(globalExtracted)), globalExtracted);
+	const parserOptions = buildParserOptions(globalExtracted);
+	const parsed = parseArgv(tokens, parserOptions);
+	return mergeWithPositionals(parsed, globalExtracted);
 }
 /**
 * Separate global flags from command-local args in argv.
@@ -2347,6 +2333,42 @@ function formatRuntimeError(error, debug) {
 	return `${styles.error("Error:")} ${error.message}`;
 }
 
+//#endregion
+//#region ../core/src/core/case-proxy.ts
+/**
+* Wrap an args object with a Proxy that allows dual-case access.
+*
+* Given `{ "my-option": "value" }`, both `obj["my-option"]` and `obj.myOption`
+* will return `"value"`.
+*
+* - `Object.keys()`, `JSON.stringify()`, and spread return only the original keys.
+* - The `in` operator detects both case variants.
+*/
+function createDualCaseProxy(obj) {
+	return new Proxy(obj, {
+		get(target, prop, receiver) {
+			if (typeof prop === "string") {
+				if (prop in target) return Reflect.get(target, prop, receiver);
+				const camel = toCamelCase(prop);
+				if (camel !== prop && camel in target) return Reflect.get(target, camel, receiver);
+				const kebab = toKebabCase(prop);
+				if (kebab !== prop && kebab in target) return Reflect.get(target, kebab, receiver);
+			}
+			return Reflect.get(target, prop, receiver);
+		},
+		has(target, prop) {
+			if (typeof prop === "string") {
+				if (prop in target) return true;
+				const camel = toCamelCase(prop);
+				if (camel !== prop && camel in target) return true;
+				const kebab = toKebabCase(prop);
+				if (kebab !== prop && kebab in target) return true;
+			}
+			return Reflect.has(target, prop);
+		}
+	});
+}
+
 //#endregion
 //#region ../core/src/core/effect-runner.ts
 /**
@@ -2620,7 +2642,9 @@ async function runCommandInternal(command, argv, options = {}) {
 	const collector = options.captureLogs ?? false ? createLogCollector() : null;
 	collector?.start();
 	const getCurrentLogs = () => {
-		return mergeLogs(options._existingLogs ?? emptyLogs(), collector?.getLogs() ?? emptyLogs());
+		const existingLogs = options._existingLogs ?? emptyLogs();
+		const collectedLogs = collector?.getLogs() ?? emptyLogs();
+		return mergeLogs(existingLogs, collectedLogs);
 	};
 	try {
 		const parseResult = parseArgs(argv, command, {
@@ -2953,4 +2977,4 @@ function extractAndValidateGlobal(options) {
 }
 
 //#endregion
-export { generateHelp as C, createDualCaseProxy as E, ReservedFieldNameError as S, renderMarkdown as T, DuplicateFieldError as _, formatCommandValidationErrors as a, PositionalConfigError as b, validateCrossSchemaCollisions as c, validateDuplicateNegations as d, validatePositionalConfig as f, DuplicateAliasError as g, CaseVariantCollisionError as h, parseArgv as i, validateDuplicateAliases as l, validateReservedFieldNames as m, runMain as n, validateCaseVariantCollisions as o, validateReservedAliases as p, formatValidationErrors as r, validateCommand as s, runCommand as t, validateDuplicateFields as u, DuplicateNegationError as v, renderInline as w, ReservedAliasError as x, FieldTypeConflictError as y };
+export { ReservedFieldNameError as C, renderMarkdown as E, ReservedAliasError as S, renderInline as T, DuplicateAliasError as _, parseArgv as a, FieldTypeConflictError as b, validateCommand as c, validateDuplicateFields as d, validateDuplicateNegations as f, CaseVariantCollisionError as g, validateReservedFieldNames as h, formatValidationErrors as i, validateCrossSchemaCollisions as l, validateReservedAliases as m, runMain as n, formatCommandValidationErrors as o, validatePositionalConfig as p, createDualCaseProxy as r, validateCaseVariantCollisions as s, runCommand as t, validateDuplicateAliases as u, DuplicateFieldError as v, generateHelp as w, PositionalConfigError as x, DuplicateNegationError as y };

package/dist/runner-MMjpKeEa.js

@@ -0,0 +1,3 @@
+import { n as runMain, t as runCommand } from "./runner-DAGvxV2P.js";
+
+export { runCommand };

package/dist/skill.d.ts

@@ -1,4 +1,4 @@
-import { Z as UnknownKeysMode, b as ArgsSchema, v as AnyCommand } from "./arg-registry-YaWTVu_x.js";
+import { Z as UnknownKeysMode, b as ArgsSchema, v as AnyCommand } from "./arg-registry-B8QvBM_Q.js";
 import { z } from "zod";
 //#region ../core/src/skill/types.d.ts
 /**

package/dist/skill.js

@@ -1,4 +1,4 @@
-import "./register-Bk0K83W2.js";
+import "./register-DlGnMLIY.js";
 import { a as internalField, i as internalArgs, t as extractFields } from "./schema-extractor-DMSozq40.js";
 import { n as defineCommand } from "./command-k-4yAz4J.js";
 import { a as symbols, n as logger } from "./logger-i_bb-Jhc.js";
@@ -712,8 +712,9 @@ function populateAgentDirs(cwd, name, canonicalDir, expectedStamp, mode) {
 		const resolvedTargetParent = realpathSync(targetParent);
 		const targetDir = join(resolvedTargetParent, name);
 		clearInstallSlot(targetDir, expectedStamp, { restrictSymlinkTo: canonicalDir });
+		const resolvedCanonicalParent = realpathSync(resolve(canonicalDir, ".."));
 		symlinkOrCopy({
-			linkTarget: join(relative(resolvedTargetParent, realpathSync(resolve(canonicalDir, ".."))), name),
+			linkTarget: join(relative(resolvedTargetParent, resolvedCanonicalParent), name),
 			linkPath: targetDir,
 			copyFrom: canonicalDir,
 			mode
@@ -1394,7 +1395,9 @@ function danglingRoutesToSource(canonical, sourceDir) {
 		return false;
 	}
 	const absoluteTarget = isAbsolute(raw) ? raw : resolve(dirname(canonical), raw);
-	const rel = relative(resolveDeepestExisting(resolve(sourceDir)), resolveDeepestExisting(absoluteTarget));
+	const resolvedSource = resolveDeepestExisting(resolve(sourceDir));
+	const resolvedTarget = resolveDeepestExisting(absoluteTarget);
+	const rel = relative(resolvedSource, resolvedTarget);
 	if (isAbsolute(rel)) return false;
 	if (rel === ".." || rel.startsWith(`..${sep}`)) return false;
 	return true;

package/dist/src-CLogLsbS.js

@@ -0,0 +1,12 @@
+import { i as toKebabCase, r as toCamelCase } from "./field-meta-DMy5BcRr.js";
+import { t as arg } from "./register-DlGnMLIY.js";
+import { r as getUnknownKeysMode, t as extractFields } from "./schema-extractor-DMSozq40.js";
+import { n as createCompileCacheShimGenerator, t as runPolittyCli } from "./cli-main-D4kkrRfX.js";
+import { n as defineCommand, t as createDefineCommand } from "./command-k-4yAz4J.js";
+import { C as ReservedFieldNameError, E as renderMarkdown, S as ReservedAliasError, T as renderInline, _ as DuplicateAliasError, a as parseArgv, b as FieldTypeConflictError, c as validateCommand, d as validateDuplicateFields, f as validateDuplicateNegations, g as CaseVariantCollisionError, h as validateReservedFieldNames, i as formatValidationErrors, l as validateCrossSchemaCollisions, m as validateReservedAliases, n as runMain, o as formatCommandValidationErrors, p as validatePositionalConfig, r as createDualCaseProxy, s as validateCaseVariantCollisions, t as runCommand, u as validateDuplicateAliases, v as DuplicateFieldError, w as generateHelp, x as PositionalConfigError, y as DuplicateNegationError } from "./runner-DAGvxV2P.js";
+import { o as isLazyCommand, s as lazy } from "./subcommand-router-Cskpofdk.js";
+import { a as symbols, i as styles, n as logger, r as setColorEnabled, t as isColorEnabled } from "./logger-i_bb-Jhc.js";
+import { a as generateCompletion, p as generateBundledCompletionWorker, s as withCompletionCommand } from "./completion-DW5qVc3l.js";
+import "./src-bYH2XCQ4.js";
+
+export { generateBundledCompletionWorker };

package/dist/src-bYH2XCQ4.js

@@ -0,0 +1,6 @@
+import "./cli-main-D4kkrRfX.js";
+import "./runner-DAGvxV2P.js";
+import "./logger-i_bb-Jhc.js";
+import "./completion-DW5qVc3l.js";
+
+export {  };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@politty/zod",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "description": "A lightweight CLI framework inspired by citty with zod v4 registry integration for type-safe metadata management",
   "keywords": [
     "argument-parser",
@@ -71,7 +71,7 @@
     }
   },
   "dependencies": {
-    "yaml": "^2.8.3"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "25.9.5",

package/dist/cli-main-Dn88vIyn.js

@@ -1,84 +0,0 @@
-import { n as generateCompileCacheShim, t as formatShimPath } from "./src-KzC0g5CS.js";
-import { a as internalField, i as internalArgs } from "./schema-extractor-DMSozq40.js";
-import { n as defineCommand } from "./command-k-4yAz4J.js";
-import { p as generateBundledCompletionWorker } from "./completion-gtWX3mwP.js";
-import { n as runMain } from "./runner-D72I7wvK.js";
-
-//#region ../core/src/cli-main.ts
-const generateWorkerCommand = defineCommand({
-	name: "generate-worker",
-	description: "Generate and verify a bundled shell completion worker",
-	args: internalArgs({
-		bin: internalField.string({
-			description: "CLI binary or built JS entry file to invoke",
-			placeholder: "PATH"
-		}),
-		program: internalField.string({
-			description: "Program name embedded in worker metadata",
-			placeholder: "NAME"
-		}),
-		shell: internalField.enum([
-			"bash",
-			"zsh",
-			"fish"
-		], {
-			description: "Shell worker to generate",
-			placeholder: "SHELL"
-		}),
-		out: internalField.optionalString({
-			description: "Output worker path (defaults to dist/completion/<shell>-worker.<ext>)",
-			placeholder: "PATH"
-		}),
-		verify: internalField.boolean({ description: "Verify __completion-worker-path resolves to the generated worker" })
-	}),
-	async run(args) {
-		await generateBundledCompletionWorker({
-			bin: args.bin,
-			programName: args.program,
-			shell: args.shell,
-			...args.out !== void 0 && { outputPath: args.out },
-			verify: args.verify
-		});
-	}
-});
-runMain(defineCommand({
-	name: "politty",
-	description: "politty development utilities",
-	subCommands: {
-		"generate-shim": defineCommand({
-			name: "generate-shim",
-			description: "Generate a compile-cache bin shim that loads the real CLI via dynamic import",
-			args: internalArgs({
-				entry: internalField.optionalStringArray({
-					description: "Module specifier the shim imports, relative to the shim file; repeatable, one per bin/--out (defaults to ./cli.js, ./cli.mjs, ./index.js, or ./index.mjs next to each shim)",
-					placeholder: "SPECIFIER"
-				}),
-				out: internalField.optionalStringArray({
-					description: "Output path for the generated shim; repeatable, one per --entry (defaults to the bin paths in package.json)",
-					placeholder: "PATH"
-				}),
-				program: internalField.optionalString({
-					description: "Program name for the cache directory, applied to all shims (defaults per shim to its bin name)",
-					placeholder: "NAME"
-				})
-			}),
-			run(args) {
-				const cwd = process.cwd();
-				const results = generateCompileCacheShim({
-					...args.entry !== void 0 && { entry: args.entry },
-					...args.out !== void 0 && { out: args.out },
-					...args.program !== void 0 && { program: args.program },
-					cwd
-				});
-				for (const result of results) console.log(`Generated compile-cache shim: ${formatShimPath(result.outputPath, cwd)} (program: ${result.program}, entry: ${result.entry})`);
-			}
-		}),
-		"generate-worker": generateWorkerCommand
-	}
-})).catch((error) => {
-	console.error(error instanceof Error ? error.message : String(error));
-	process.exit(1);
-});
-
-//#endregion
-export {  };

package/dist/cli-run-eibUcgys.js

@@ -1,7 +0,0 @@
-import "./register-Bk0K83W2.js";
-
-//#region src/cli-run.ts
-await import("./cli-main-Dn88vIyn.js");
-
-//#endregion
-export {  };

package/dist/runner-FvUwOHyE.js

@@ -1,3 +0,0 @@
-import { n as runMain, t as runCommand } from "./runner-D72I7wvK.js";
-
-export { runCommand };