politty 0.11.1 → 0.11.2

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,43 @@ 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
+ };
255
363
  }
364
+ /**
365
+ * Result of wrapping `T` with {@link withSkillCommand} — `T` with a
366
+ * `skills` entry added to (and required on) `subCommands`, so consumers can
367
+ * access `command.subCommands.skills` without an `as AnyCommand` cast.
368
+ */
369
+ type WithSkillCommand<T extends AnyCommand> = T & {
370
+ subCommands: NonNullable<T["subCommands"]> & {
371
+ skills: AnyCommand;
372
+ };
373
+ };
256
374
  //#endregion
257
375
  //#region src/skill/installer.d.ts
258
376
  /**
@@ -426,7 +544,7 @@ declare function scanSourceDir(sourceDir: string): ScanResult;
426
544
  * @throws if `command.subCommands.skills` already exists — silently
427
545
  * overwriting it would hide a configuration bug.
428
546
  */
429
- declare function withSkillCommand<T extends AnyCommand>(command: T, options: SkillCommandOptions): T;
547
+ declare function withSkillCommand<T extends AnyCommand>(command: T, options: SkillCommandOptions): WithSkillCommand<T>;
430
548
  //#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 };
549
+ 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
550
  //# sourceMappingURL=index.d.ts.map
@@ -1,4 +1,4 @@
1
- import { t as arg } from "../arg-registry-BeLLAW5-.js";
1
+ import { s as arg, t as extractFields } from "../schema-extractor-wzJ1cGon.js";
2
2
  import { n as defineCommand } from "../command-B4yA4LXX.js";
3
3
  import { a as symbols, n as logger } from "../logger-DbDkjdfO.js";
4
4
  import { z } from "zod";
@@ -933,6 +933,49 @@ function excludeArgMeta(options) {
933
933
  return meta;
934
934
  }
935
935
  /**
936
+ * Build the metadata for `--verbose` (shared by `add`/`sync`) honouring the
937
+ * configured alias. `undefined` alias means `arg()` is called without an
938
+ * alias key. Only called when `options.verbose.disabled` is `false`.
939
+ */
940
+ function verboseArgMeta(options) {
941
+ const meta = { description: "Print install paths and modes" };
942
+ if (options.verbose.alias !== void 0) meta.alias = options.verbose.alias;
943
+ return meta;
944
+ }
945
+ /**
946
+ * Read a same-named boolean out of a leaf command's (already-merged) args
947
+ * object. When a built-in flag is omitted because `SkillCommandOptions.
948
+ * globalArgs` already declares a same-named field (see
949
+ * `ResolvedSkillOptions.verbose`/`.json`), the local schema no longer
950
+ * declares it, but politty's runner still merges the host's
951
+ * `globalArgs`-parsed values into every leaf command's `args` regardless of
952
+ * the leaf's own schema shape. Reading it here (rather than hardcoding
953
+ * `false`) means the omission hands control to that global flag instead of
954
+ * just turning the feature off.
955
+ */
956
+ function mergedFlag(args, name) {
957
+ return Boolean(args[name]);
958
+ }
959
+ /**
960
+ * Apply the configured unknown-keys mode to a subcommand's args schema.
961
+ *
962
+ * Declared to return the general {@link ArgsSchema} type rather than the
963
+ * precise `z.object(...)` literal, so passing its result into
964
+ * `defineCommand({ args: ... })` gives every call site a single stable
965
+ * type to infer `TArgsSchema` from — the same reason the `verbose`/`json`
966
+ * disabled/enabled variants below are two full monomorphic `defineCommand`
967
+ * calls rather than one call fed a ternary: threading a schema whose type
968
+ * varies per branch directly into `args:` collapses `run`'s parameter type
969
+ * into an unusable intersection for external callers (TypeScript infers a
970
+ * type parameter used in both covariant and contravariant positions from a
971
+ * union-typed argument as an intersection).
972
+ */
973
+ function applyUnknownKeys(schema, mode) {
974
+ if (mode === "strict") return schema.strict();
975
+ if (mode === "passthrough") return schema.passthrough();
976
+ return schema;
977
+ }
978
+ /**
936
979
  * Create the `skills sync` subcommand.
937
980
  *
938
981
  * Removes and reinstalls all skills discovered in sourceDir. Skills owned
@@ -940,60 +983,68 @@ function excludeArgMeta(options) {
940
983
  * stale skills do not linger after the CLI drops them from its bundle.
941
984
  */
942
985
  function createSkillSyncCommand(resolved) {
986
+ function runSync(args, verbose) {
987
+ const { skills: allSkills, errors } = loadSkills(resolved);
988
+ const stamp = resolved.stamp;
989
+ const sourceNamesAll = new Set(allSkills.map((s) => s.frontmatter.name));
990
+ const ownedInstalled = new Set(findOwnedInstalledSkills(stamp, resolved.cwd, resolved.sourceDir));
991
+ const unknownExclude = Array.from(new Set(args.exclude)).filter((n) => !sourceNamesAll.has(n) && !ownedInstalled.has(n));
992
+ if (unknownExclude.length > 0) {
993
+ const subject = unknownExclude.length === 1 ? "Skill" : "Skills";
994
+ const quoted = unknownExclude.map((n) => JSON.stringify(n)).join(", ");
995
+ throw new Error(`--exclude: ${subject} ${quoted} not found in source directory or among installed skills.\n` + formatSkillUniverse({
996
+ source: allSkills,
997
+ installed: ownedInstalled
998
+ }));
999
+ }
1000
+ const excluded = new Set(args.exclude);
1001
+ const skills = allSkills.filter((s) => !excluded.has(s.frontmatter.name));
1002
+ const rootScanFailed = scanFailedAtRoot({
1003
+ skills: allSkills,
1004
+ errors
1005
+ }, resolved.sourceDir);
1006
+ let removed = 0;
1007
+ if (!rootScanFailed) {
1008
+ const sourceNames = new Set(skills.map((s) => s.frontmatter.name));
1009
+ const erroredSlotNames = /* @__PURE__ */ new Set();
1010
+ for (const err of errors) {
1011
+ if (err.path === resolved.sourceDir) continue;
1012
+ erroredSlotNames.add(basename(err.path));
1013
+ if (err.skillName !== void 0) erroredSlotNames.add(err.skillName);
1014
+ }
1015
+ for (const orphan of ownedInstalled) {
1016
+ if (sourceNames.has(orphan) || excluded.has(orphan) || erroredSlotNames.has(orphan)) continue;
1017
+ removeOwnedSkill(orphan, stamp, resolved.cwd, resolved.sourceDir);
1018
+ removed += 1;
1019
+ }
1020
+ }
1021
+ let installed = 0;
1022
+ for (const skill of skills) {
1023
+ addSkill(skill, stamp, resolved, verbose);
1024
+ installed += 1;
1025
+ }
1026
+ if (installed === 0 && removed === 0) {
1027
+ const reason = rootScanFailed ? "source directory scan failed; see warnings" : allSkills.length > 0 && skills.length === 0 ? "all skills excluded" : "no skills bundled";
1028
+ logger.info(`No skills installed (${reason}).`);
1029
+ } else logger.info(`Sync complete: ${installed} installed, ${removed} removed.`);
1030
+ }
1031
+ if (resolved.verbose.disabled) return defineCommand({
1032
+ name: "sync",
1033
+ description: "Remove and reinstall all skills from source",
1034
+ args: applyUnknownKeys(z.object({ exclude: arg(z.array(z.string()).default([]), excludeArgMeta(resolved)) }), resolved.unknownKeys),
1035
+ run(args) {
1036
+ runSync(args, mergedFlag(args, "verbose"));
1037
+ }
1038
+ });
943
1039
  return defineCommand({
944
1040
  name: "sync",
945
1041
  description: "Remove and reinstall all skills from source",
946
- args: z.object({
1042
+ args: applyUnknownKeys(z.object({
947
1043
  exclude: arg(z.array(z.string()).default([]), excludeArgMeta(resolved)),
948
- verbose: arg(z.boolean().default(false), {
949
- alias: "v",
950
- description: "Print install paths and modes"
951
- })
952
- }),
1044
+ verbose: arg(z.boolean().default(false), verboseArgMeta(resolved))
1045
+ }), resolved.unknownKeys),
953
1046
  run(args) {
954
- const { skills: allSkills, errors } = loadSkills(resolved);
955
- const stamp = resolved.stamp;
956
- const sourceNamesAll = new Set(allSkills.map((s) => s.frontmatter.name));
957
- const ownedInstalled = new Set(findOwnedInstalledSkills(stamp, resolved.cwd, resolved.sourceDir));
958
- const unknownExclude = Array.from(new Set(args.exclude)).filter((n) => !sourceNamesAll.has(n) && !ownedInstalled.has(n));
959
- if (unknownExclude.length > 0) {
960
- const subject = unknownExclude.length === 1 ? "Skill" : "Skills";
961
- const quoted = unknownExclude.map((n) => JSON.stringify(n)).join(", ");
962
- throw new Error(`--exclude: ${subject} ${quoted} not found in source directory or among installed skills.\n` + formatSkillUniverse({
963
- source: allSkills,
964
- installed: ownedInstalled
965
- }));
966
- }
967
- const excluded = new Set(args.exclude);
968
- const skills = allSkills.filter((s) => !excluded.has(s.frontmatter.name));
969
- const rootScanFailed = scanFailedAtRoot({
970
- skills: allSkills,
971
- errors
972
- }, resolved.sourceDir);
973
- let removed = 0;
974
- if (!rootScanFailed) {
975
- const sourceNames = new Set(skills.map((s) => s.frontmatter.name));
976
- const erroredSlotNames = /* @__PURE__ */ new Set();
977
- for (const err of errors) {
978
- if (err.path === resolved.sourceDir) continue;
979
- erroredSlotNames.add(basename(err.path));
980
- if (err.skillName !== void 0) erroredSlotNames.add(err.skillName);
981
- }
982
- for (const orphan of ownedInstalled) {
983
- if (sourceNames.has(orphan) || excluded.has(orphan) || erroredSlotNames.has(orphan)) continue;
984
- removeOwnedSkill(orphan, stamp, resolved.cwd, resolved.sourceDir);
985
- removed += 1;
986
- }
987
- }
988
- let installed = 0;
989
- for (const skill of skills) {
990
- addSkill(skill, stamp, resolved, args.verbose);
991
- installed += 1;
992
- }
993
- if (installed === 0 && removed === 0) {
994
- const reason = rootScanFailed ? "source directory scan failed; see warnings" : allSkills.length > 0 && skills.length === 0 ? "all skills excluded" : "no skills bundled";
995
- logger.info(`No skills installed (${reason}).`);
996
- } else logger.info(`Sync complete: ${installed} installed, ${removed} removed.`);
1047
+ runSync(args, args.verbose);
997
1048
  }
998
1049
  });
999
1050
  }
@@ -1007,44 +1058,54 @@ function createSkillSyncCommand(resolved) {
1007
1058
  * and lists every unknown name at once. Duplicates are deduplicated.
1008
1059
  */
1009
1060
  function createSkillAddCommand(resolved) {
1061
+ const nameArgMeta = {
1062
+ positional: true,
1063
+ description: "Skill name(s) to install (default: all)",
1064
+ placeholder: "NAME"
1065
+ };
1066
+ function runAdd(args, verbose) {
1067
+ const scanResult = loadSkills(resolved);
1068
+ const sourceSkills = scanResult.skills;
1069
+ const stamp = resolved.stamp;
1070
+ if (args.name.length > 0) {
1071
+ const known = new Set(sourceSkills.map((s) => s.frontmatter.name));
1072
+ const requested = Array.from(new Set(args.name));
1073
+ const unknown = requested.filter((n) => !known.has(n));
1074
+ if (unknown.length > 0) {
1075
+ const subject = unknown.length === 1 ? "Skill" : "Skills";
1076
+ const quoted = unknown.map((n) => JSON.stringify(n)).join(", ");
1077
+ throw new Error(`${subject} ${quoted} not found in source directory.\n` + formatSkillUniverse({ source: sourceSkills }));
1078
+ }
1079
+ const wanted = new Set(requested);
1080
+ for (const skill of sourceSkills) if (wanted.has(skill.frontmatter.name)) addSkill(skill, stamp, resolved, verbose);
1081
+ return;
1082
+ }
1083
+ if (sourceSkills.length === 0) {
1084
+ if (scanFailedAtRoot(scanResult, resolved.sourceDir)) logger.info("No skills installed (source directory scan failed; see warnings).");
1085
+ else logger.info("No skills found in source directory.");
1086
+ return;
1087
+ }
1088
+ for (const skill of sourceSkills) addSkill(skill, stamp, resolved, verbose);
1089
+ }
1090
+ if (resolved.verbose.disabled) return defineCommand({
1091
+ name: resolved.commandNames.add.name,
1092
+ ...resolved.commandNames.add.aliases.length > 0 ? { aliases: resolved.commandNames.add.aliases } : {},
1093
+ description: "Install skills from source",
1094
+ args: applyUnknownKeys(z.object({ name: arg(z.array(z.string()).default([]), nameArgMeta) }), resolved.unknownKeys),
1095
+ run(args) {
1096
+ runAdd(args, mergedFlag(args, "verbose"));
1097
+ }
1098
+ });
1010
1099
  return defineCommand({
1011
- name: "add",
1012
- aliases: ["install"],
1100
+ name: resolved.commandNames.add.name,
1101
+ ...resolved.commandNames.add.aliases.length > 0 ? { aliases: resolved.commandNames.add.aliases } : {},
1013
1102
  description: "Install skills from source",
1014
- args: z.object({
1015
- name: arg(z.array(z.string()).default([]), {
1016
- positional: true,
1017
- description: "Skill name(s) to install (default: all)",
1018
- placeholder: "NAME"
1019
- }),
1020
- verbose: arg(z.boolean().default(false), {
1021
- alias: "v",
1022
- description: "Print install paths and modes"
1023
- })
1024
- }),
1103
+ args: applyUnknownKeys(z.object({
1104
+ name: arg(z.array(z.string()).default([]), nameArgMeta),
1105
+ verbose: arg(z.boolean().default(false), verboseArgMeta(resolved))
1106
+ }), resolved.unknownKeys),
1025
1107
  run(args) {
1026
- const scanResult = loadSkills(resolved);
1027
- const sourceSkills = scanResult.skills;
1028
- const stamp = resolved.stamp;
1029
- if (args.name.length > 0) {
1030
- const known = new Set(sourceSkills.map((s) => s.frontmatter.name));
1031
- const requested = Array.from(new Set(args.name));
1032
- const unknown = requested.filter((n) => !known.has(n));
1033
- if (unknown.length > 0) {
1034
- const subject = unknown.length === 1 ? "Skill" : "Skills";
1035
- const quoted = unknown.map((n) => JSON.stringify(n)).join(", ");
1036
- throw new Error(`${subject} ${quoted} not found in source directory.\n` + formatSkillUniverse({ source: sourceSkills }));
1037
- }
1038
- const wanted = new Set(requested);
1039
- for (const skill of sourceSkills) if (wanted.has(skill.frontmatter.name)) addSkill(skill, stamp, resolved, args.verbose);
1040
- return;
1041
- }
1042
- if (sourceSkills.length === 0) {
1043
- if (scanFailedAtRoot(scanResult, resolved.sourceDir)) logger.info("No skills installed (source directory scan failed; see warnings).");
1044
- else logger.info("No skills found in source directory.");
1045
- return;
1046
- }
1047
- for (const skill of sourceSkills) addSkill(skill, stamp, resolved, args.verbose);
1108
+ runAdd(args, args.verbose);
1048
1109
  }
1049
1110
  });
1050
1111
  }
@@ -1058,14 +1119,14 @@ function createSkillAddCommand(resolved) {
1058
1119
  */
1059
1120
  function createSkillRemoveCommand(resolved) {
1060
1121
  return defineCommand({
1061
- name: "remove",
1062
- aliases: ["uninstall"],
1122
+ name: resolved.commandNames.remove.name,
1123
+ ...resolved.commandNames.remove.aliases.length > 0 ? { aliases: resolved.commandNames.remove.aliases } : {},
1063
1124
  description: "Remove installed skills",
1064
- args: z.object({ name: arg(z.string().optional(), {
1125
+ args: applyUnknownKeys(z.object({ name: arg(z.string().optional(), {
1065
1126
  positional: true,
1066
1127
  description: "Skill name to remove (default: all)",
1067
1128
  placeholder: "NAME"
1068
- }) }),
1129
+ }) }), resolved.unknownKeys),
1069
1130
  run(args) {
1070
1131
  const scanResult = loadSkills(resolved);
1071
1132
  const sourceSkills = scanResult.skills;
@@ -1124,35 +1185,46 @@ function slotPresent(name, cwd) {
1124
1185
  * Lists available skills from the source directory.
1125
1186
  */
1126
1187
  function createSkillListCommand(resolved) {
1188
+ function runList(json) {
1189
+ const scanResult = loadSkills(resolved, { silentStdout: json });
1190
+ const sourceSkills = scanResult.skills;
1191
+ const stamp = resolved.stamp;
1192
+ if (json) {
1193
+ console.log(JSON.stringify(sourceSkills.map((s) => ({
1194
+ name: s.frontmatter.name,
1195
+ description: s.frontmatter.description,
1196
+ owner: s.frontmatter.metadata?.["politty-cli"] ?? null,
1197
+ expectedOwner: stamp,
1198
+ status: listStatus(s.frontmatter.name, stamp, resolved.cwd, resolved.sourceDir),
1199
+ sourcePath: s.sourcePath
1200
+ }))));
1201
+ return;
1202
+ }
1203
+ if (sourceSkills.length === 0) {
1204
+ if (scanFailedAtRoot(scanResult, resolved.sourceDir)) logger.info("Source directory scan failed; see warnings.");
1205
+ else logger.info("No skills found in source directory.");
1206
+ return;
1207
+ }
1208
+ logger.info("Available skills:");
1209
+ for (const skill of sourceSkills) {
1210
+ const status = listStatus(skill.frontmatter.name, stamp, resolved.cwd, resolved.sourceDir);
1211
+ logger.info(` ${skill.frontmatter.name.padEnd(20)} ${status.padEnd(14)} ${skill.frontmatter.description}`);
1212
+ }
1213
+ }
1214
+ if (resolved.json.disabled) return defineCommand({
1215
+ name: "list",
1216
+ description: "List available skills from source",
1217
+ args: applyUnknownKeys(z.object({}), resolved.unknownKeys),
1218
+ run(args) {
1219
+ runList(mergedFlag(args, "json"));
1220
+ }
1221
+ });
1127
1222
  return defineCommand({
1128
1223
  name: "list",
1129
1224
  description: "List available skills from source",
1130
- args: z.object({ json: arg(z.boolean().default(false), { description: "Output as JSON" }) }),
1225
+ args: applyUnknownKeys(z.object({ json: arg(z.boolean().default(false), { description: "Output as JSON" }) }), resolved.unknownKeys),
1131
1226
  run(args) {
1132
- const scanResult = loadSkills(resolved, { silentStdout: args.json });
1133
- const sourceSkills = scanResult.skills;
1134
- const stamp = resolved.stamp;
1135
- if (args.json) {
1136
- console.log(JSON.stringify(sourceSkills.map((s) => ({
1137
- name: s.frontmatter.name,
1138
- description: s.frontmatter.description,
1139
- owner: s.frontmatter.metadata?.["politty-cli"] ?? null,
1140
- expectedOwner: stamp,
1141
- status: listStatus(s.frontmatter.name, stamp, resolved.cwd, resolved.sourceDir),
1142
- sourcePath: s.sourcePath
1143
- }))));
1144
- return;
1145
- }
1146
- if (sourceSkills.length === 0) {
1147
- if (scanFailedAtRoot(scanResult, resolved.sourceDir)) logger.info("Source directory scan failed; see warnings.");
1148
- else logger.info("No skills found in source directory.");
1149
- return;
1150
- }
1151
- logger.info("Available skills:");
1152
- for (const skill of sourceSkills) {
1153
- const status = listStatus(skill.frontmatter.name, stamp, resolved.cwd, resolved.sourceDir);
1154
- logger.info(` ${skill.frontmatter.name.padEnd(20)} ${status.padEnd(14)} ${skill.frontmatter.description}`);
1155
- }
1227
+ runList(args.json);
1156
1228
  }
1157
1229
  });
1158
1230
  }
@@ -1371,8 +1443,24 @@ function findOwnedInstalledSkills(expectedOwnership, cwd, sourceDir) {
1371
1443
 
1372
1444
  //#endregion
1373
1445
  //#region src/skill/options.ts
1446
+ /** Default unknown-keys mode for the `add`/`sync`/`remove`/`list` arg schemas. */
1447
+ const DEFAULT_UNKNOWN_KEYS = "strip";
1374
1448
  /** Default short alias for `skills sync --exclude`. */
1375
1449
  const DEFAULT_EXCLUDE_ALIAS = "x";
1450
+ /** Default short alias for `skills add`/`skills sync --verbose`. */
1451
+ const DEFAULT_VERBOSE_ALIAS = "v";
1452
+ /** Default primary name + aliases for `skills add`. */
1453
+ const DEFAULT_ADD_NAMES = ["add", "install"];
1454
+ /** Default primary name + aliases for `skills remove`. */
1455
+ const DEFAULT_REMOVE_NAMES = ["remove", "uninstall"];
1456
+ /**
1457
+ * Same safe-token pattern politty's own command validator enforces for
1458
+ * subcommand aliases (`checkSubCommandAliasConflicts` in
1459
+ * src/validator/command-validator.ts). That check only runs when a host
1460
+ * explicitly calls `validateCommand()`, not automatically from
1461
+ * `runMain`/`runCommand`, so `commandMap` entries need their own check.
1462
+ */
1463
+ const SAFE_TOKEN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
1376
1464
  /** Marker files identifying a project root for find-up. */
1377
1465
  const PROJECT_ROOT_MARKERS = [".git", "package.json"];
1378
1466
  /**
@@ -1382,6 +1470,16 @@ const PROJECT_ROOT_MARKERS = [".git", "package.json"];
1382
1470
  * - `cwd` — `findProjectRoot(process.cwd()) ?? process.cwd()`.
1383
1471
  * - `excludeAlias` — `"x"` unless overridden via
1384
1472
  * `flags.exclude.alias` (string) or disabled (`false`).
1473
+ * - `verbose` — alias `"v"` unless overridden via `flags.verbose.alias`;
1474
+ * the flag itself is omitted from `add`/`sync` whenever `globalArgs`
1475
+ * already defines a `verbose` field.
1476
+ * - `json` — the flag is omitted from `list` whenever `globalArgs` already
1477
+ * defines a `json` field.
1478
+ * - `commandNames.add`/`.remove` — primary name `"add"`/`"remove"` plus
1479
+ * alias `"install"`/`"uninstall"` unless overridden via
1480
+ * `options.commandMap.add`/`.remove` (first array element becomes the
1481
+ * primary name, the rest become aliases).
1482
+ * - `unknownKeys` — `"strip"` unless overridden via `options.unknownKeys`.
1385
1483
  * - `descriptionAppend` — a one-line hint mentioning the skills
1386
1484
  * subcommands. Pass an explicit string to override or `false` to opt out.
1387
1485
  */
@@ -1392,6 +1490,13 @@ function resolveSkillOptions(options, cliName) {
1392
1490
  mode: options.mode,
1393
1491
  cwd: resolveCwd(options.cwd),
1394
1492
  excludeAlias: resolveExcludeAlias(options.flags?.exclude?.alias),
1493
+ verbose: resolveVerbose(options.flags?.verbose, options.globalArgs),
1494
+ json: { disabled: hasGlobalField(options.globalArgs, "json") },
1495
+ commandNames: {
1496
+ add: resolveCommandNaming(options.commandMap?.add, DEFAULT_ADD_NAMES, "add"),
1497
+ remove: resolveCommandNaming(options.commandMap?.remove, DEFAULT_REMOVE_NAMES, "remove")
1498
+ },
1499
+ unknownKeys: options.unknownKeys ?? DEFAULT_UNKNOWN_KEYS,
1395
1500
  descriptionAppend: resolveDescriptionAppend(options.descriptionAppend, cliName),
1396
1501
  stamp: `${options.package}:${cliName}`
1397
1502
  };
@@ -1424,6 +1529,57 @@ function resolveExcludeAlias(value) {
1424
1529
  if (typeof value === "string") return value;
1425
1530
  return DEFAULT_EXCLUDE_ALIAS;
1426
1531
  }
1532
+ /**
1533
+ * The first element of `value` (or `defaults`, when `value` is `undefined`)
1534
+ * becomes the primary name; the rest become aliases.
1535
+ */
1536
+ function resolveCommandNaming(value, defaults, label) {
1537
+ const names = value ?? defaults;
1538
+ if (names.length === 0) throw new Error(`SkillCommandOptions.commandMap.${label} must include at least one name.`);
1539
+ const invalid = names.find((name) => !SAFE_TOKEN.test(name));
1540
+ if (invalid !== void 0) throw new Error(`SkillCommandOptions.commandMap.${label} contains an invalid entry ${JSON.stringify(invalid)}. Names/aliases must start with an alphanumeric character and contain only alphanumeric characters, hyphens, or underscores.`);
1541
+ return {
1542
+ name: names[0],
1543
+ aliases: names.slice(1)
1544
+ };
1545
+ }
1546
+ function resolveVerbose(value, globalArgs) {
1547
+ return {
1548
+ alias: value?.alias === false ? void 0 : value?.alias ?? DEFAULT_VERBOSE_ALIAS,
1549
+ disabled: hasGlobalField(globalArgs, "verbose")
1550
+ };
1551
+ }
1552
+ /**
1553
+ * Does `globalArgs` (the host's `runMain`/`runCommand` global args schema,
1554
+ * if passed through `SkillCommandOptions.globalArgs`) already declare a
1555
+ * *non-positional boolean* field with this name? Determines whether the
1556
+ * matching built-in local flag (`verbose`/`json`) is omitted — see
1557
+ * {@link SkillCommandOptions.globalArgs}. Positional fields are excluded: a
1558
+ * positional named `verbose`/`json` has no `--verbose`/`--json` flag syntax
1559
+ * at all, so it can't actually collide with one. Non-boolean fields are
1560
+ * excluded too: `mergedFlag` boolean-coerces whatever value flows through,
1561
+ * and a same-named string/number field (e.g. a verbosity level or enum)
1562
+ * isn't really the same flag — coercing it (e.g. `Boolean("off")` is `true`)
1563
+ * would silently misread it, so it's not treated as a collision here and
1564
+ * the local boolean flag stays declared.
1565
+ *
1566
+ * Note: politty itself independently rejects this same situation. When
1567
+ * `globalArgs` and a command's own schema both declare a same-named field
1568
+ * with different definitions (as happens here — global non-boolean vs.
1569
+ * local boolean), `runMain`/`runCommand` throws `FieldTypeConflictError` at
1570
+ * parse time, regardless of what this function decides. This function
1571
+ * keeping the local flag "declared" doesn't make the combination usable —
1572
+ * it just means the failure surfaces as politty's own clear error instead
1573
+ * of a silent boolean-coercion misread. {@link SkillFlagOverrides.verbose}'s
1574
+ * `alias` option can't help either, since it only renames the short alias,
1575
+ * not the conflicting long field name. A host whose `globalArgs` defines a
1576
+ * non-boolean `verbose`/`json` field must rename or remove that global
1577
+ * field (or make it a plain boolean) instead.
1578
+ */
1579
+ function hasGlobalField(globalArgs, name) {
1580
+ if (!globalArgs) return false;
1581
+ return extractFields(globalArgs).fields.some((field) => field.name === name && !field.positional && field.type === "boolean");
1582
+ }
1427
1583
  function resolveDescriptionAppend(value, cliName) {
1428
1584
  if (value === false) return false;
1429
1585
  if (typeof value === "string") return value;
@@ -1521,13 +1677,25 @@ const SCAN_ERROR_REASONS = [
1521
1677
  function withSkillCommand(command, options) {
1522
1678
  if (command.subCommands && Object.hasOwn(command.subCommands, "skills")) throw new Error(`withSkillCommand: command "${command.name}" already defines a "skills" subcommand.`);
1523
1679
  const resolved = resolveSkillOptions(options, command.name);
1680
+ const addName = resolved.commandNames.add.name;
1681
+ const removeName = resolved.commandNames.remove.name;
1682
+ const allNames = [
1683
+ "sync",
1684
+ "list",
1685
+ addName,
1686
+ ...resolved.commandNames.add.aliases,
1687
+ removeName,
1688
+ ...resolved.commandNames.remove.aliases
1689
+ ];
1690
+ const duplicate = allNames.find((name, i) => allNames.indexOf(name) !== i);
1691
+ if (duplicate) throw new Error(`withSkillCommand: commandMap produced duplicate subcommand name/alias "${duplicate}".`);
1524
1692
  const skillsSubCommand = defineCommand({
1525
1693
  name: "skills",
1526
1694
  description: "Manage agent skills",
1527
1695
  subCommands: {
1528
1696
  sync: createSkillSyncCommand(resolved),
1529
- add: createSkillAddCommand(resolved),
1530
- remove: createSkillRemoveCommand(resolved),
1697
+ [addName]: createSkillAddCommand(resolved),
1698
+ [removeName]: createSkillRemoveCommand(resolved),
1531
1699
  list: createSkillListCommand(resolved)
1532
1700
  }
1533
1701
  });