politty 0.11.1 → 0.11.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,4 @@
1
- import { _ as AnyCommand } from "../arg-registry-aHbip9Hs.js";
1
+ import { X as UnknownKeysMode, _ as AnyCommand, y as ArgsSchema } from "../arg-registry-D558cYkD.js";
2
2
  import { z } from "zod";
3
3
 
4
4
  //#region src/skill/frontmatter.d.ts
@@ -168,6 +168,20 @@ interface SkillFlagOverrides {
168
168
  exclude?: {
169
169
  alias?: string | false;
170
170
  };
171
+ /**
172
+ * `--verbose` flag shared by `skills add` and `skills sync`. The default
173
+ * short alias is `-v`.
174
+ *
175
+ * This is independent of {@link SkillCommandOptions.globalArgs}'s
176
+ * field-name auto-detection (which drops the flag entirely when the
177
+ * host's `globalArgs` already defines a `verbose` field). `alias` instead
178
+ * resolves a *short-alias-only* collision — e.g. the host's `globalArgs`
179
+ * uses `-v` for an unrelated flag (not named `verbose`), so auto-detection
180
+ * doesn't apply, but the single-character alias still collides.
181
+ */
182
+ verbose?: {
183
+ alias?: string | false;
184
+ };
171
185
  }
172
186
  /**
173
187
  * Options for `withSkillCommand`.
@@ -222,6 +236,74 @@ interface SkillCommandOptions {
222
236
  * example, the directory of a CLI-specific config file.
223
237
  */
224
238
  cwd?: string;
239
+ /**
240
+ * The host CLI's global args schema — the same value passed to
241
+ * `runMain`/`runCommand`'s `globalArgs` option.
242
+ *
243
+ * When provided, `skills add`/`skills sync`'s `--verbose` and `skills
244
+ * list`'s `--json` are automatically omitted from their own schema if
245
+ * this schema already defines a same-named *non-positional boolean*
246
+ * field — no manual configuration needed, and the host's global flag of
247
+ * the same name takes over instead.
248
+ *
249
+ * A same-named field of another type (e.g. a string verbosity level)
250
+ * doesn't trigger this — the local boolean flag stays declared. However,
251
+ * politty itself independently rejects that combination: when
252
+ * `globalArgs` and a command's own schema declare a same-named field
253
+ * with different definitions, `runMain`/`runCommand` throws
254
+ * `FieldTypeConflictError` at parse time. {@link SkillFlagOverrides} can't
255
+ * help here — it only renames the short alias (`-v`/`-x`), not the long
256
+ * `--verbose`/`--json` field name itself, so the conflicting name stays
257
+ * either way. A host whose `globalArgs` uses a non-boolean `verbose`/
258
+ * `json` field must rename or remove that global field (or make it a
259
+ * plain boolean) instead.
260
+ *
261
+ * (Historical note: this omission used to also be required to work around
262
+ * a politty core bug where a global flag typed *before* the subcommand
263
+ * resolved correctly as a global value, but a same-named local field's
264
+ * own default would then overwrite it during the merge. That bug is
265
+ * fixed in politty core independently of this option — a same-named
266
+ * local and global field with *identical* definitions now resolves
267
+ * correctly regardless of position. This option still omits the local
268
+ * flag by default for simplicity: hosts don't need to duplicate the
269
+ * flag's definition on both schemas to get the expected behavior.)
270
+ *
271
+ * @example
272
+ * ```ts
273
+ * const globalArgs = z.object({
274
+ * verbose: arg(z.boolean().default(false), { alias: "v" }),
275
+ * });
276
+ *
277
+ * const cli = withSkillCommand(baseCommand, {
278
+ * sourceDir, package: "@my-agent/skills",
279
+ * globalArgs, // skills add/sync automatically drop their own --verbose
280
+ * });
281
+ *
282
+ * runMain(cli, { globalArgs }); // same schema, passed to the real entry point
283
+ * ```
284
+ */
285
+ globalArgs?: ArgsSchema;
286
+ /**
287
+ * Unknown-keys handling for the `add`/`sync`/`remove`/`list` arg schemas
288
+ * (applied uniformly to all four).
289
+ *
290
+ * - `"strip"` (default) — matches politty's own `z.object()` default:
291
+ * an unrecognized flag prints a warning and its value is dropped from
292
+ * the parsed args.
293
+ * - `"strict"` — an unrecognized flag is a hard error, matching a host
294
+ * CLI that uses `z.strictObject()`/`.strict()` throughout.
295
+ * - `"passthrough"` — matches `z.object().passthrough()`: no warning,
296
+ * and unlike `"strip"`, the unrecognized flag's value is *kept* on the
297
+ * parsed args object under its raw CLI name (e.g. `args["some-flag"]`)
298
+ * rather than dropped.
299
+ *
300
+ * This only governs flags the parser cannot attribute to *either* this
301
+ * subcommand's own schema or the host's `globalArgs` schema — a value
302
+ * that legitimately arrives via `globalArgs` (see
303
+ * {@link SkillCommandOptions.globalArgs}) is validated separately against
304
+ * that schema and merged in afterward, so it is never rejected here.
305
+ */
306
+ unknownKeys?: UnknownKeysMode;
225
307
  /**
226
308
  * Customize built-in subcommand flags. Use to resolve collisions with
227
309
  * the CLI's global flags or to opt out of short aliases.
@@ -252,7 +334,71 @@ interface SkillCommandOptions {
252
334
  * - `false` — leave the description untouched.
253
335
  */
254
336
  descriptionAppend?: string | false;
337
+ /**
338
+ * Override the primary (dispatched) name and aliases of `skills add` and
339
+ * `skills remove`. In each array, the *first* element becomes the
340
+ * subcommand's primary name; every element after it becomes an alias.
341
+ *
342
+ * Default: `add: ["add", "install"]`, `remove: ["remove", "uninstall"]`.
343
+ *
344
+ * Useful when a host CLI wants to rename these subcommands outright, drop
345
+ * the `install`/`uninstall` backward-compatibility aliases, add further
346
+ * aliases, or some combination of all three.
347
+ *
348
+ * @example
349
+ * ```ts
350
+ * withSkillCommand(cmd, {
351
+ * sourceDir, package: "@my-agent/skills",
352
+ * commandMap: {
353
+ * add: ["setup", "add", "install"], // renamed to "setup"; "add"/"install" still work
354
+ * remove: ["remove"], // no aliases at all
355
+ * },
356
+ * });
357
+ * ```
358
+ */
359
+ commandMap?: {
360
+ /** Primary name + aliases for `skills add`. Default: `["add", "install"]`. */add?: string[]; /** Primary name + aliases for `skills remove`. Default: `["remove", "uninstall"]`. */
361
+ remove?: string[];
362
+ };
363
+ /**
364
+ * Override the description text for the `skills` command and/or its
365
+ * built-in subcommands. Any key left unset keeps politty's default
366
+ * description for that command.
367
+ *
368
+ * Keys refer to the subcommand's *canonical role*, not its dispatched
369
+ * name — e.g. `descriptions.add` still applies after `commandMap.add`
370
+ * renames the subcommand to something else.
371
+ *
372
+ * @example
373
+ * ```ts
374
+ * withSkillCommand(cmd, {
375
+ * sourceDir, package: "@my-agent/skills",
376
+ * commandMap: { add: ["setup", "add", "install"] },
377
+ * descriptions: {
378
+ * skills: "Manage My Agent skills",
379
+ * add: "Install My Agent skills", // still keyed by "add", not "setup"
380
+ * },
381
+ * });
382
+ * ```
383
+ */
384
+ descriptions?: {
385
+ /** Description for the top-level `skills` command. Default: `"Manage agent skills"`. */skills?: string; /** Description for `skills sync`. Default: `"Remove and reinstall all skills from source"`. */
386
+ sync?: string; /** Description for `skills add`. Default: `"Install skills from source"`. */
387
+ add?: string; /** Description for `skills remove`. Default: `"Remove installed skills"`. */
388
+ remove?: string; /** Description for `skills list`. Default: `"List available skills from source"`. */
389
+ list?: string;
390
+ };
255
391
  }
392
+ /**
393
+ * Result of wrapping `T` with {@link withSkillCommand} — `T` with a
394
+ * `skills` entry added to (and required on) `subCommands`, so consumers can
395
+ * access `command.subCommands.skills` without an `as AnyCommand` cast.
396
+ */
397
+ type WithSkillCommand<T extends AnyCommand> = T & {
398
+ subCommands: NonNullable<T["subCommands"]> & {
399
+ skills: AnyCommand;
400
+ };
401
+ };
256
402
  //#endregion
257
403
  //#region src/skill/installer.d.ts
258
404
  /**
@@ -426,7 +572,7 @@ declare function scanSourceDir(sourceDir: string): ScanResult;
426
572
  * @throws if `command.subCommands.skills` already exists — silently
427
573
  * overwriting it would hide a configuration bug.
428
574
  */
429
- declare function withSkillCommand<T extends AnyCommand>(command: T, options: SkillCommandOptions): T;
575
+ declare function withSkillCommand<T extends AnyCommand>(command: T, options: SkillCommandOptions): WithSkillCommand<T>;
430
576
  //#endregion
431
- export { type DiscoveredSkill, type InstallMode, type InstallSkillOptions, OWNERSHIP_METADATA_KEY, type ParsedSkillMd, SCAN_ERROR_REASONS, type ScanError, type ScanErrorReason, type ScanResult, type SkillCommandOptions, type SkillFlagOverrides, type SkillFrontmatter, type UninstallSkillOptions, hasInstalledSkill, installSkill, parseFrontmatter, parseSkillMd, readInstalledOwnership, scanSourceDir, skillFrontmatterSchema, uninstallSkill, withSkillCommand };
577
+ export { type DiscoveredSkill, type InstallMode, type InstallSkillOptions, OWNERSHIP_METADATA_KEY, type ParsedSkillMd, SCAN_ERROR_REASONS, type ScanError, type ScanErrorReason, type ScanResult, type SkillCommandOptions, type SkillFlagOverrides, type SkillFrontmatter, type UninstallSkillOptions, type WithSkillCommand, hasInstalledSkill, installSkill, parseFrontmatter, parseSkillMd, readInstalledOwnership, scanSourceDir, skillFrontmatterSchema, uninstallSkill, withSkillCommand };
432
578
  //# sourceMappingURL=index.d.ts.map