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 { 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: resolved.descriptions.sync,
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
- description: "Remove and reinstall all skills from source",
946
- args: z.object({
1041
+ description: resolved.descriptions.sync,
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: resolved.descriptions.add,
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"],
1013
- 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
- }),
1100
+ name: resolved.commandNames.add.name,
1101
+ ...resolved.commandNames.add.aliases.length > 0 ? { aliases: resolved.commandNames.add.aliases } : {},
1102
+ description: resolved.descriptions.add,
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"],
1063
- description: "Remove installed skills",
1064
- args: z.object({ name: arg(z.string().optional(), {
1122
+ name: resolved.commandNames.remove.name,
1123
+ ...resolved.commandNames.remove.aliases.length > 0 ? { aliases: resolved.commandNames.remove.aliases } : {},
1124
+ description: resolved.descriptions.remove,
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: resolved.descriptions.list,
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
- description: "List available skills from source",
1130
- args: z.object({ json: arg(z.boolean().default(false), { description: "Output as JSON" }) }),
1224
+ description: resolved.descriptions.list,
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,36 @@ 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
+ * Default description text for the `skills` command and each built-in
1458
+ * subcommand, keyed by canonical role. Overridden per-key via
1459
+ * `SkillCommandOptions.descriptions`.
1460
+ */
1461
+ const DEFAULT_DESCRIPTIONS = {
1462
+ skills: "Manage agent skills",
1463
+ sync: "Remove and reinstall all skills from source",
1464
+ add: "Install skills from source",
1465
+ remove: "Remove installed skills",
1466
+ list: "List available skills from source"
1467
+ };
1468
+ /**
1469
+ * Same safe-token pattern politty's own command validator enforces for
1470
+ * subcommand aliases (`checkSubCommandAliasConflicts` in
1471
+ * src/validator/command-validator.ts). That check only runs when a host
1472
+ * explicitly calls `validateCommand()`, not automatically from
1473
+ * `runMain`/`runCommand`, so `commandMap` entries need their own check.
1474
+ */
1475
+ const SAFE_TOKEN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
1376
1476
  /** Marker files identifying a project root for find-up. */
1377
1477
  const PROJECT_ROOT_MARKERS = [".git", "package.json"];
1378
1478
  /**
@@ -1382,8 +1482,20 @@ const PROJECT_ROOT_MARKERS = [".git", "package.json"];
1382
1482
  * - `cwd` — `findProjectRoot(process.cwd()) ?? process.cwd()`.
1383
1483
  * - `excludeAlias` — `"x"` unless overridden via
1384
1484
  * `flags.exclude.alias` (string) or disabled (`false`).
1485
+ * - `verbose` — alias `"v"` unless overridden via `flags.verbose.alias`;
1486
+ * the flag itself is omitted from `add`/`sync` whenever `globalArgs`
1487
+ * already defines a `verbose` field.
1488
+ * - `json` — the flag is omitted from `list` whenever `globalArgs` already
1489
+ * defines a `json` field.
1490
+ * - `commandNames.add`/`.remove` — primary name `"add"`/`"remove"` plus
1491
+ * alias `"install"`/`"uninstall"` unless overridden via
1492
+ * `options.commandMap.add`/`.remove` (first array element becomes the
1493
+ * primary name, the rest become aliases).
1494
+ * - `unknownKeys` — `"strip"` unless overridden via `options.unknownKeys`.
1385
1495
  * - `descriptionAppend` — a one-line hint mentioning the skills
1386
1496
  * subcommands. Pass an explicit string to override or `false` to opt out.
1497
+ * - `descriptions` — politty's default text per canonical role, unless
1498
+ * overridden via `options.descriptions`.
1387
1499
  */
1388
1500
  function resolveSkillOptions(options, cliName) {
1389
1501
  return {
@@ -1392,8 +1504,26 @@ function resolveSkillOptions(options, cliName) {
1392
1504
  mode: options.mode,
1393
1505
  cwd: resolveCwd(options.cwd),
1394
1506
  excludeAlias: resolveExcludeAlias(options.flags?.exclude?.alias),
1507
+ verbose: resolveVerbose(options.flags?.verbose, options.globalArgs),
1508
+ json: { disabled: hasGlobalField(options.globalArgs, "json") },
1509
+ commandNames: {
1510
+ add: resolveCommandNaming(options.commandMap?.add, DEFAULT_ADD_NAMES, "add"),
1511
+ remove: resolveCommandNaming(options.commandMap?.remove, DEFAULT_REMOVE_NAMES, "remove")
1512
+ },
1513
+ unknownKeys: options.unknownKeys ?? DEFAULT_UNKNOWN_KEYS,
1395
1514
  descriptionAppend: resolveDescriptionAppend(options.descriptionAppend, cliName),
1396
- stamp: `${options.package}:${cliName}`
1515
+ stamp: `${options.package}:${cliName}`,
1516
+ descriptions: resolveDescriptions(options.descriptions)
1517
+ };
1518
+ }
1519
+ /** Fill in {@link DEFAULT_DESCRIPTIONS} for any key the caller left unset. */
1520
+ function resolveDescriptions(value) {
1521
+ return {
1522
+ skills: value?.skills ?? DEFAULT_DESCRIPTIONS.skills,
1523
+ sync: value?.sync ?? DEFAULT_DESCRIPTIONS.sync,
1524
+ add: value?.add ?? DEFAULT_DESCRIPTIONS.add,
1525
+ remove: value?.remove ?? DEFAULT_DESCRIPTIONS.remove,
1526
+ list: value?.list ?? DEFAULT_DESCRIPTIONS.list
1397
1527
  };
1398
1528
  }
1399
1529
  function resolveCwd(override) {
@@ -1424,6 +1554,57 @@ function resolveExcludeAlias(value) {
1424
1554
  if (typeof value === "string") return value;
1425
1555
  return DEFAULT_EXCLUDE_ALIAS;
1426
1556
  }
1557
+ /**
1558
+ * The first element of `value` (or `defaults`, when `value` is `undefined`)
1559
+ * becomes the primary name; the rest become aliases.
1560
+ */
1561
+ function resolveCommandNaming(value, defaults, label) {
1562
+ const names = value ?? defaults;
1563
+ if (names.length === 0) throw new Error(`SkillCommandOptions.commandMap.${label} must include at least one name.`);
1564
+ const invalid = names.find((name) => !SAFE_TOKEN.test(name));
1565
+ 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.`);
1566
+ return {
1567
+ name: names[0],
1568
+ aliases: names.slice(1)
1569
+ };
1570
+ }
1571
+ function resolveVerbose(value, globalArgs) {
1572
+ return {
1573
+ alias: value?.alias === false ? void 0 : value?.alias ?? DEFAULT_VERBOSE_ALIAS,
1574
+ disabled: hasGlobalField(globalArgs, "verbose")
1575
+ };
1576
+ }
1577
+ /**
1578
+ * Does `globalArgs` (the host's `runMain`/`runCommand` global args schema,
1579
+ * if passed through `SkillCommandOptions.globalArgs`) already declare a
1580
+ * *non-positional boolean* field with this name? Determines whether the
1581
+ * matching built-in local flag (`verbose`/`json`) is omitted — see
1582
+ * {@link SkillCommandOptions.globalArgs}. Positional fields are excluded: a
1583
+ * positional named `verbose`/`json` has no `--verbose`/`--json` flag syntax
1584
+ * at all, so it can't actually collide with one. Non-boolean fields are
1585
+ * excluded too: `mergedFlag` boolean-coerces whatever value flows through,
1586
+ * and a same-named string/number field (e.g. a verbosity level or enum)
1587
+ * isn't really the same flag — coercing it (e.g. `Boolean("off")` is `true`)
1588
+ * would silently misread it, so it's not treated as a collision here and
1589
+ * the local boolean flag stays declared.
1590
+ *
1591
+ * Note: politty itself independently rejects this same situation. When
1592
+ * `globalArgs` and a command's own schema both declare a same-named field
1593
+ * with different definitions (as happens here — global non-boolean vs.
1594
+ * local boolean), `runMain`/`runCommand` throws `FieldTypeConflictError` at
1595
+ * parse time, regardless of what this function decides. This function
1596
+ * keeping the local flag "declared" doesn't make the combination usable —
1597
+ * it just means the failure surfaces as politty's own clear error instead
1598
+ * of a silent boolean-coercion misread. {@link SkillFlagOverrides.verbose}'s
1599
+ * `alias` option can't help either, since it only renames the short alias,
1600
+ * not the conflicting long field name. A host whose `globalArgs` defines a
1601
+ * non-boolean `verbose`/`json` field must rename or remove that global
1602
+ * field (or make it a plain boolean) instead.
1603
+ */
1604
+ function hasGlobalField(globalArgs, name) {
1605
+ if (!globalArgs) return false;
1606
+ return extractFields(globalArgs).fields.some((field) => field.name === name && !field.positional && field.type === "boolean");
1607
+ }
1427
1608
  function resolveDescriptionAppend(value, cliName) {
1428
1609
  if (value === false) return false;
1429
1610
  if (typeof value === "string") return value;
@@ -1521,13 +1702,25 @@ const SCAN_ERROR_REASONS = [
1521
1702
  function withSkillCommand(command, options) {
1522
1703
  if (command.subCommands && Object.hasOwn(command.subCommands, "skills")) throw new Error(`withSkillCommand: command "${command.name}" already defines a "skills" subcommand.`);
1523
1704
  const resolved = resolveSkillOptions(options, command.name);
1705
+ const addName = resolved.commandNames.add.name;
1706
+ const removeName = resolved.commandNames.remove.name;
1707
+ const allNames = [
1708
+ "sync",
1709
+ "list",
1710
+ addName,
1711
+ ...resolved.commandNames.add.aliases,
1712
+ removeName,
1713
+ ...resolved.commandNames.remove.aliases
1714
+ ];
1715
+ const duplicate = allNames.find((name, i) => allNames.indexOf(name) !== i);
1716
+ if (duplicate) throw new Error(`withSkillCommand: commandMap produced duplicate subcommand name/alias "${duplicate}".`);
1524
1717
  const skillsSubCommand = defineCommand({
1525
1718
  name: "skills",
1526
- description: "Manage agent skills",
1719
+ description: resolved.descriptions.skills,
1527
1720
  subCommands: {
1528
1721
  sync: createSkillSyncCommand(resolved),
1529
- add: createSkillAddCommand(resolved),
1530
- remove: createSkillRemoveCommand(resolved),
1722
+ [addName]: createSkillAddCommand(resolved),
1723
+ [removeName]: createSkillRemoveCommand(resolved),
1531
1724
  list: createSkillListCommand(resolved)
1532
1725
  }
1533
1726
  });
@@ -0,0 +1,135 @@
1
+ //#region src/lazy.ts
2
+ /**
3
+ * Marker property for LazyCommand identification
4
+ */
5
+ const LAZY_BRAND = "__politty_lazy__";
6
+ /**
7
+ * Type guard: check if a value is a LazyCommand
8
+ */
9
+ function isLazyCommand(value) {
10
+ return typeof value === "object" && value !== null && LAZY_BRAND in value && value[LAZY_BRAND] === true;
11
+ }
12
+ /**
13
+ * Create a lazily-loaded subcommand with synchronous metadata.
14
+ *
15
+ * The `meta` command provides names, descriptions, and args schema
16
+ * for static analysis (completion scripts, help text) without loading
17
+ * the full command module.
18
+ *
19
+ * The `load` function is called only at execution time.
20
+ *
21
+ * @example
22
+ * ```ts
23
+ * import { lazy, defineCommand } from "politty";
24
+ *
25
+ * const cli = defineCommand({
26
+ * name: "mycli",
27
+ * subCommands: {
28
+ * deploy: lazy(
29
+ * defineCommand({
30
+ * name: "deploy",
31
+ * description: "Deploy the application",
32
+ * args: z.object({ env: arg(z.string()) }),
33
+ * }),
34
+ * () => import("./deploy.js").then((m) => m.deployCommand),
35
+ * ),
36
+ * },
37
+ * });
38
+ * ```
39
+ */
40
+ function lazy(meta, load) {
41
+ return {
42
+ [LAZY_BRAND]: true,
43
+ meta,
44
+ load
45
+ };
46
+ }
47
+ /**
48
+ * Resolve synchronous metadata from a SubCommandValue.
49
+ * Returns null for legacy async subcommands whose metadata is unavailable.
50
+ */
51
+ function resolveSubCommandMeta(subCmd) {
52
+ if (isLazyCommand(subCmd)) return subCmd.meta;
53
+ if (typeof subCmd === "function") return null;
54
+ return subCmd;
55
+ }
56
+
57
+ //#endregion
58
+ //#region src/executor/subcommand-router.ts
59
+ /**
60
+ * Resolve a lazy-loaded command (sync or async)
61
+ *
62
+ * @param cmd - The command or lazy loader function
63
+ * @returns The resolved command
64
+ */
65
+ async function resolveLazyCommand(cmd) {
66
+ if (isLazyCommand(cmd)) return await cmd.load();
67
+ if (typeof cmd === "function") return await cmd();
68
+ return cmd;
69
+ }
70
+ /**
71
+ * Resolve a subcommand by name (including alias lookup) and return both the
72
+ * resolved command and the canonical name if accessed via alias.
73
+ *
74
+ * This avoids a redundant alias scan when the caller needs both pieces of info.
75
+ */
76
+ async function resolveSubcommandWithAlias(command, name) {
77
+ if (!command.subCommands) return;
78
+ const subCmd = Object.hasOwn(command.subCommands, name) ? command.subCommands[name] : void 0;
79
+ if (subCmd) return {
80
+ command: await resolveLazyCommand(subCmd),
81
+ aliasFor: void 0
82
+ };
83
+ const canonicalName = resolveSubCommandAlias(command, name);
84
+ if (canonicalName) return {
85
+ command: await resolveLazyCommand(command.subCommands[canonicalName]),
86
+ aliasFor: canonicalName
87
+ };
88
+ }
89
+ /**
90
+ * Resolve an alias to the canonical subcommand name.
91
+ * Returns the canonical name if the given name is an alias, or undefined.
92
+ *
93
+ * Note: Aliases are only recognized for eagerly-defined commands and
94
+ * `lazy()` commands (which carry synchronous metadata). Pure async
95
+ * subcommand functions do not expose metadata synchronously, so their
96
+ * aliases cannot be resolved without loading the module.
97
+ *
98
+ * @param command - The parent command
99
+ * @param alias - The alias to look up
100
+ * @returns The canonical subcommand name, or undefined
101
+ */
102
+ function resolveSubCommandAlias(command, alias) {
103
+ if (!command.subCommands) return void 0;
104
+ for (const [name, subCmd] of Object.entries(command.subCommands)) if (resolveSubCommandMeta(subCmd)?.aliases?.includes(alias)) return name;
105
+ }
106
+ /**
107
+ * Build a set of all recognized subcommand names including aliases.
108
+ *
109
+ * @param command - The parent command
110
+ * @returns Set of all names (canonical + aliases)
111
+ */
112
+ function listSubCommandNamesWithAliases(command) {
113
+ const names = /* @__PURE__ */ new Set();
114
+ if (!command.subCommands) return names;
115
+ for (const [name, subCmd] of Object.entries(command.subCommands)) {
116
+ names.add(name);
117
+ const meta = resolveSubCommandMeta(subCmd);
118
+ if (meta?.aliases) for (const alias of meta.aliases) names.add(alias);
119
+ }
120
+ return names;
121
+ }
122
+ /**
123
+ * List all subcommand names for a command
124
+ *
125
+ * @param command - The parent command
126
+ * @returns Array of subcommand names
127
+ */
128
+ function listSubCommands(command) {
129
+ if (!command.subCommands) return [];
130
+ return Object.keys(command.subCommands);
131
+ }
132
+
133
+ //#endregion
134
+ 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 };
135
+ //# sourceMappingURL=subcommand-router-CTzHPGzF.js.map