@politty/zod 0.0.0

package/dist/src-KzC0g5CS.js

@@ -0,0 +1,191 @@
+import "./completion-gtWX3mwP.js";
+import "./runner-D72I7wvK.js";
+import "./logger-i_bb-Jhc.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";
+
+//#region ../core/src/compile-cache-shim.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.
+*/
+/**
+* Marker identifying files this generator wrote (overwrite guard). Must be
+* shim-specific: other politty artifacts (e.g. completion scripts) also say
+* "Generated by politty", and those must never be treated as overwritable.
+*/
+const SHIM_MARKER = "Generated by politty: compile-cache bin shim";
+/** Entry candidates tried, in order, when `entry` is omitted. */
+const DEFAULT_ENTRY_CANDIDATES = [
+	"./cli.js",
+	"./cli.mjs",
+	"./index.js",
+	"./index.mjs"
+];
+/**
+* Read the nearest `package.json`, walking up from `startDir` to the
+* filesystem root. A malformed file is a real error and propagates.
+*/
+function readNearestPackageJson(startDir) {
+	let dir = resolve(startDir);
+	for (;;) {
+		const candidate = join(dir, "package.json");
+		if (existsSync(candidate)) return {
+			pkg: JSON.parse(readFileSync(candidate, "utf8")),
+			dir
+		};
+		const parent = dirname(dir);
+		if (parent === dir) return void 0;
+		dir = parent;
+	}
+}
+/**
+* `bin` entries as `[name, path]` pairs: the object form's entries in
+* declaration order, or the string form as a single pair named after the
+* package (npm's own convention for `"bin": "path"`).
+*/
+function binEntries(pkg) {
+	if (!pkg) return [];
+	if (typeof pkg.bin === "string" && pkg.bin) {
+		const name = defaultProgramName(pkg);
+		return name ? [[name, pkg.bin]] : [];
+	}
+	if (typeof pkg.bin === "object" && pkg.bin !== null) return Object.entries(pkg.bin).filter((pair) => typeof pair[1] === "string" && pair[1] !== "");
+	return [];
+}
+/**
+* Derive the fallback program name from a package.json: the first `bin`
+* command name when present (that is the name users type in their shell),
+* else the package name without its scope.
+*/
+function defaultProgramName(pkg) {
+	if (!pkg) return void 0;
+	if (typeof pkg.bin === "object" && pkg.bin !== null) {
+		const [first] = Object.keys(pkg.bin);
+		if (first) return first;
+	}
+	if (typeof pkg.name === "string" && pkg.name) {
+		const name = pkg.name;
+		return name.startsWith("@") ? name.split("/")[1] ?? name : name;
+	}
+}
+/**
+* Pick the default entry: the first {@link DEFAULT_ENTRY_CANDIDATES} that
+* exists next to the shim (never the shim itself).
+*/
+function defaultEntry(outputPath) {
+	const dir = dirname(outputPath);
+	const self = basename(outputPath);
+	for (const candidate of DEFAULT_ENTRY_CANDIDATES) {
+		if (basename(candidate) === self) continue;
+		if (existsSync(join(dir, candidate))) return candidate;
+	}
+}
+function shimContent(program, entry) {
+	return [
+		"#!/usr/bin/env node",
+		"",
+		`// ${SHIM_MARKER}.`,
+		"// Enables the Node.js on-disk compile cache (V8 code cache) before the",
+		"// 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\");",
+		`  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.",
+		"}",
+		`await import(${JSON.stringify(entry)});`,
+		""
+	].join("\n");
+}
+function toArray(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
+/**
+* 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).
+*
+* The generated files are ESM (they use top-level `await import`), so `.js`
+* output requires `"type": "module"` in the package; use a `.mjs` extension
+* otherwise. Refuses to overwrite an existing file it did not generate, so
+* a `bin` path still pointing at the real CLI entry fails loudly instead of
+* clobbering the build output.
+*/
+function generateCompileCacheShim(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	const found = readNearestPackageJson(cwd);
+	const pkg = found?.pkg;
+	const entries = toArray(options.entry);
+	const outs = toArray(options.out);
+	const bins = binEntries(pkg);
+	let outputPaths;
+	if (outs.length > 0) {
+		if (entries.length > 0 && entries.length !== outs.length) throw new Error(`--entry count (${entries.length}) does not match --out count (${outs.length}); pass one --out per --entry or omit --out entirely.`);
+		outputPaths = outs.map((out) => isAbsolute(out) ? out : resolve(cwd, out));
+	} else {
+		if (bins.length === 0 || found === void 0) throw new Error("Cannot derive the output path: no bin entry in package.json. Pass --out explicitly.");
+		if (entries.length > 0 && entries.length !== bins.length) throw new Error(`--entry count (${entries.length}) does not match the package's bin entries (${bins.length}); pass one --entry per bin (in declaration order) or matching --out paths.`);
+		outputPaths = bins.map(([, path]) => resolve(found.dir, path));
+	}
+	if (new Set(outputPaths).size !== outputPaths.length) throw new Error("Duplicate output paths; each shim needs a distinct output file. Check the --out values (or the bin paths in package.json when --out is omitted).");
+	const binNameByPath = /* @__PURE__ */ new Map();
+	if (found) for (const [name, path] of bins) binNameByPath.set(resolve(found.dir, path), name);
+	const warnings = [];
+	const plans = outputPaths.map((outputPath, index) => {
+		const matchedBinName = binNameByPath.get(outputPath);
+		const program = options.program ?? matchedBinName ?? defaultProgramName(pkg);
+		if (!program) throw new Error("Cannot derive a program name: no bin or name in package.json. Pass --program explicitly.");
+		if (options.program === void 0 && matchedBinName === void 0 && outs.length > 0) warnings.push(`Warning: ${formatShimPath(outputPath, cwd)} does not match any bin path in package.json, so its cache directory uses the program name ${JSON.stringify(program)}. Pass --program to override.`);
+		if (outputPath.endsWith(".cjs")) throw new Error("The generated shim is an ES module and cannot be written to a .cjs file. Use a .mjs (or .js in a \"type\": \"module\" package) output path.");
+		if (extname(outputPath) === "") throw new Error("The generated shim is an ES module and cannot be written to an extensionless file (it would not load on every supported Node.js version). Use a .mjs (or .js in a \"type\": \"module\" package) output path.");
+		if (outputPath.endsWith(".js") && pkg?.type !== "module") throw new Error(pkg === void 0 ? "The generated shim is an ES module, and no package.json was found to confirm .js files are treated as ESM. Write it to a .mjs file instead (e.g. --out dist/bin.mjs)." : "The generated shim is an ES module, but the package is not \"type\": \"module\". Write it to a .mjs file instead (e.g. --out dist/bin.mjs).");
+		const entry = entries[index] ?? defaultEntry(outputPath);
+		if (entry === void 0) throw new Error(`Cannot derive an entry: none of ${DEFAULT_ENTRY_CANDIDATES.join(", ")} exist next to ${outputPath}. Pass --entry explicitly.`);
+		if (!entry.startsWith("./") && !entry.startsWith("../") && !entry.startsWith("file:")) throw new Error(`Invalid entry ${entry}: pass a specifier relative to the shim file ("./..." or "../...") or a file: URL.`);
+		let entryPath;
+		if (entry.startsWith("file:")) try {
+			entryPath = fileURLToPath(entry);
+		} catch {
+			entryPath = void 0;
+		}
+		else entryPath = resolve(dirname(outputPath), entry);
+		if (entryPath === outputPath) throw new Error(`The shim at ${outputPath} would import itself (entry ${entry}). Point bin at a separate shim path (e.g. dist/bin.js) or pass a different --entry.`);
+		if (existsSync(outputPath) && !readFileSync(outputPath, "utf8").includes(SHIM_MARKER)) throw new Error(`Refusing to overwrite ${outputPath}: it exists and was not generated by politty. If bin currently points at your real CLI entry, point it at a separate shim path (e.g. dist/bin.js) or pass --out explicitly.`);
+		return {
+			outputPath,
+			program,
+			entry
+		};
+	});
+	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));
+		chmodSync(outputPath, 493);
+	}
+	return plans;
+}
+/**
+* Format a generated path for CLI output: relative to `cwd` when inside it.
+*/
+function formatShimPath(outputPath, cwd) {
+	const rel = relative(cwd, outputPath);
+	return rel && !rel.startsWith("..") ? rel : outputPath;
+}
+
+//#endregion
+export { generateCompileCacheShim as n, formatShimPath as t };

package/dist/subcommand-router-Cskpofdk.js

@@ -0,0 +1,134 @@
+//#region ../core/src/lazy.ts
+/**
+* Marker property for LazyCommand identification
+*/
+const LAZY_BRAND = "__politty_lazy__";
+/**
+* Type guard: check if a value is a LazyCommand
+*/
+function isLazyCommand(value) {
+	return typeof value === "object" && value !== null && LAZY_BRAND in value && value[LAZY_BRAND] === true;
+}
+/**
+* Create a lazily-loaded subcommand with synchronous metadata.
+*
+* The `meta` command provides names, descriptions, and args schema
+* for static analysis (completion scripts, help text) without loading
+* the full command module.
+*
+* The `load` function is called only at execution time.
+*
+* @example
+* ```ts
+* import { lazy, defineCommand } from "politty";
+*
+* const cli = defineCommand({
+*   name: "mycli",
+*   subCommands: {
+*     deploy: lazy(
+*       defineCommand({
+*         name: "deploy",
+*         description: "Deploy the application",
+*         args: z.object({ env: arg(z.string()) }),
+*       }),
+*       () => import("./deploy.js").then((m) => m.deployCommand),
+*     ),
+*   },
+* });
+* ```
+*/
+function lazy(meta, load) {
+	return {
+		[LAZY_BRAND]: true,
+		meta,
+		load
+	};
+}
+/**
+* Resolve synchronous metadata from a SubCommandValue.
+* Returns null for legacy async subcommands whose metadata is unavailable.
+*/
+function resolveSubCommandMeta(subCmd) {
+	if (isLazyCommand(subCmd)) return subCmd.meta;
+	if (typeof subCmd === "function") return null;
+	return subCmd;
+}
+
+//#endregion
+//#region ../core/src/executor/subcommand-router.ts
+/**
+* Resolve a lazy-loaded command (sync or async)
+*
+* @param cmd - The command or lazy loader function
+* @returns The resolved command
+*/
+async function resolveLazyCommand(cmd) {
+	if (isLazyCommand(cmd)) return await cmd.load();
+	if (typeof cmd === "function") return await cmd();
+	return cmd;
+}
+/**
+* Resolve a subcommand by name (including alias lookup) and return both the
+* resolved command and the canonical name if accessed via alias.
+*
+* This avoids a redundant alias scan when the caller needs both pieces of info.
+*/
+async function resolveSubcommandWithAlias(command, name) {
+	if (!command.subCommands) return;
+	const subCmd = Object.hasOwn(command.subCommands, name) ? command.subCommands[name] : void 0;
+	if (subCmd) return {
+		command: await resolveLazyCommand(subCmd),
+		aliasFor: void 0
+	};
+	const canonicalName = resolveSubCommandAlias(command, name);
+	if (canonicalName) return {
+		command: await resolveLazyCommand(command.subCommands[canonicalName]),
+		aliasFor: canonicalName
+	};
+}
+/**
+* Resolve an alias to the canonical subcommand name.
+* Returns the canonical name if the given name is an alias, or undefined.
+*
+* Note: Aliases are only recognized for eagerly-defined commands and
+* `lazy()` commands (which carry synchronous metadata). Pure async
+* subcommand functions do not expose metadata synchronously, so their
+* aliases cannot be resolved without loading the module.
+*
+* @param command - The parent command
+* @param alias - The alias to look up
+* @returns The canonical subcommand name, or undefined
+*/
+function resolveSubCommandAlias(command, alias) {
+	if (!command.subCommands) return void 0;
+	for (const [name, subCmd] of Object.entries(command.subCommands)) if (resolveSubCommandMeta(subCmd)?.aliases?.includes(alias)) return name;
+}
+/**
+* Build a set of all recognized subcommand names including aliases.
+*
+* @param command - The parent command
+* @returns Set of all names (canonical + aliases)
+*/
+function listSubCommandNamesWithAliases(command) {
+	const names = /* @__PURE__ */ new Set();
+	if (!command.subCommands) return names;
+	for (const [name, subCmd] of Object.entries(command.subCommands)) {
+		names.add(name);
+		const meta = resolveSubCommandMeta(subCmd);
+		if (meta?.aliases) for (const alias of meta.aliases) names.add(alias);
+	}
+	return names;
+}
+/**
+* List all subcommand names for a command
+*
+* @param command - The parent command
+* @returns Array of subcommand names
+*/
+function listSubCommands(command) {
+	if (!command.subCommands) return [];
+	return Object.keys(command.subCommands);
+}
+
+//#endregion
+export { resolveSubcommandWithAlias as a, resolveSubCommandMeta as c, resolveSubCommandAlias as i, listSubCommands as n, isLazyCommand as o, resolveLazyCommand as r, lazy as s, listSubCommandNamesWithAliases as t };

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@politty/zod",
+  "version": "0.0.0",
+  "description": "A lightweight CLI framework inspired by citty with zod v4 registry integration for type-safe metadata management",
+  "keywords": [
+    "argument-parser",
+    "cli",
+    "command-line",
+    "type-safe",
+    "typescript",
+    "zod"
+  ],
+  "license": "MIT",
+  "author": "toiroakr",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toiroakr/politty.git",
+    "directory": "packages/zod"
+  },
+  "bin": {
+    "politty": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/cli.mjs",
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./augment": {
+      "types": "./dist/augment.d.ts",
+      "default": "./dist/augment.js"
+    },
+    "./compile-cache": {
+      "types": "./dist/compile-cache.d.ts",
+      "default": "./dist/compile-cache.js"
+    },
+    "./docs": {
+      "types": "./dist/docs.d.ts",
+      "default": "./dist/docs.js"
+    },
+    "./completion": {
+      "types": "./dist/completion.d.ts",
+      "default": "./dist/completion.js"
+    },
+    "./skill": {
+      "types": "./dist/skill.d.ts",
+      "default": "./dist/skill.js"
+    },
+    "./prompt": {
+      "types": "./dist/prompt.d.ts",
+      "default": "./dist/prompt.js"
+    },
+    "./prompt/clack": {
+      "types": "./dist/prompt-clack.d.ts",
+      "default": "./dist/prompt-clack.js"
+    },
+    "./prompt/inquirer": {
+      "types": "./dist/prompt-inquirer.d.ts",
+      "default": "./dist/prompt-inquirer.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "dependencies": {
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "25.9.5",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "zod": "4.4.3",
+    "@politty/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@clack/prompts": "^0.10.0 || ^0.11.0 || ^1.0.0",
+    "@inquirer/prompts": "^8.3.2",
+    "zod": "^4.2.1"
+  },
+  "peerDependenciesMeta": {
+    "@clack/prompts": {
+      "optional": true
+    },
+    "@inquirer/prompts": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.12.0 <21.0.0 || >=21.7.0"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}