politty 0.11.5 → 0.11.7

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.
Files changed (51) hide show
  1. package/README.md +30 -1
  2. package/bin/cli.mjs +3 -0
  3. package/dist/augment.d.ts +1 -16
  4. package/dist/augment.js +2 -0
  5. package/dist/cli-run-DGe88d0G.js +14 -0
  6. package/dist/cli.d.ts +1 -1
  7. package/dist/cli.js +13 -9
  8. package/dist/compile-cache.d.ts +1 -79
  9. package/dist/compile-cache.js +2 -2
  10. package/dist/completion.d.ts +1 -0
  11. package/dist/completion.js +3 -0
  12. package/dist/docs.d.ts +1 -0
  13. package/dist/docs.js +3 -0
  14. package/dist/index.d.ts +10 -814
  15. package/dist/index.js +17 -8
  16. package/dist/prompt-clack.d.ts +1 -0
  17. package/dist/prompt-clack.js +3 -0
  18. package/dist/prompt-inquirer.d.ts +1 -0
  19. package/dist/prompt-inquirer.js +3 -0
  20. package/dist/prompt.d.ts +1 -0
  21. package/dist/prompt.js +3 -0
  22. package/dist/skill.d.ts +1 -0
  23. package/dist/skill.js +3 -0
  24. package/package.json +20 -46
  25. package/dist/arg-registry-SrNIsq-d.d.ts +0 -981
  26. package/dist/cli-main.d.ts +0 -1
  27. package/dist/cli-main.js +0 -86
  28. package/dist/command-B4yA4LXX.js +0 -43
  29. package/dist/compile-cache-NnTkjJMV.js +0 -101
  30. package/dist/completion/index.d.ts +0 -3
  31. package/dist/completion/index.js +0 -3
  32. package/dist/completion-D9SKGJad.js +0 -5610
  33. package/dist/docs/index.d.ts +0 -771
  34. package/dist/docs/index.js +0 -3024
  35. package/dist/index-qqwo5WZT.d.ts +0 -673
  36. package/dist/log-collector-DK32-73m.js +0 -115
  37. package/dist/logger-DbDkjdfO.js +0 -134
  38. package/dist/prompt/clack/index.d.ts +0 -17
  39. package/dist/prompt/clack/index.js +0 -32
  40. package/dist/prompt/index.d.ts +0 -107
  41. package/dist/prompt/index.js +0 -3
  42. package/dist/prompt/inquirer/index.d.ts +0 -17
  43. package/dist/prompt/inquirer/index.js +0 -47
  44. package/dist/prompt-Cc8Tfmdv.js +0 -172
  45. package/dist/runner-BGs_QMJM.js +0 -3
  46. package/dist/runner-xN7248Ph.js +0 -2966
  47. package/dist/schema-extractor-wzJ1cGon.js +0 -488
  48. package/dist/skill/index.d.ts +0 -584
  49. package/dist/skill/index.js +0 -1756
  50. package/dist/src-BiCtSNrn.js +0 -193
  51. package/dist/subcommand-router-CTzHPGzF.js +0 -135
@@ -1,584 +0,0 @@
1
- import { X as UnknownKeysMode, _ as AnyCommand, y as ArgsSchema } from "../arg-registry-SrNIsq-d.js";
2
- import { z } from "zod";
3
- //#region src/skill/frontmatter.d.ts
4
- /**
5
- * Zod schema for SKILL.md frontmatter.
6
- *
7
- * Strictly validates the fields defined in the Agent Skills specification
8
- * (https://agentskills.io/specification). Unknown fields are preserved via
9
- * `.passthrough()` so spec extensions and vendor keys round-trip intact.
10
- *
11
- * Provenance / ownership for politty-managed installs is recorded under
12
- * `metadata["politty-cli"]` as `"{packageName}:{cliName}"`.
13
- */
14
- declare const skillFrontmatterSchema: z.ZodObject<{
15
- name: z.ZodString;
16
- description: z.ZodString;
17
- license: z.ZodOptional<z.ZodString>;
18
- compatibility: z.ZodOptional<z.ZodString>;
19
- metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
20
- "allowed-tools": z.ZodOptional<z.ZodString>;
21
- }, z.core.$loose>;
22
- /**
23
- * Result of parsing a SKILL.md file.
24
- */
25
- interface ParsedSkillMd {
26
- /** Parsed and validated frontmatter */
27
- frontmatter: z.infer<typeof skillFrontmatterSchema>;
28
- /** Markdown body (content after frontmatter) */
29
- body: string;
30
- /** Full raw content */
31
- rawContent: string;
32
- }
33
- /**
34
- * Parse YAML frontmatter from a SKILL.md string.
35
- *
36
- * `parseError` is set when the frontmatter fence was present but the YAML
37
- * inside failed to parse, so the scanner can distinguish "invalid YAML"
38
- * from "missing required field" in its diagnostics. A non-object root
39
- * (e.g. a top-level YAML list) also returns empty `data` without
40
- * `parseError` — Zod's schema validation surfaces that case clearly
41
- * enough on its own.
42
- *
43
- * @example
44
- * ```typescript
45
- * const result = parseFrontmatter(`---
46
- * name: commit
47
- * description: Git commit message generation
48
- * ---
49
- * # Instructions...`);
50
- *
51
- * result.data.name; // "commit"
52
- * ```
53
- */
54
- declare function parseFrontmatter(content: string): {
55
- data: Record<string, unknown>;
56
- body: string;
57
- parseError?: string;
58
- };
59
- /**
60
- * Parse and validate a SKILL.md content string.
61
- *
62
- * @returns Parsed skill metadata and body, or `null` if the frontmatter is
63
- * missing or fails schema validation.
64
- */
65
- declare function parseSkillMd(content: string): ParsedSkillMd | null;
66
- //#endregion
67
- //#region src/skill/types.d.ts
68
- /**
69
- * SKILL.md frontmatter metadata, validated against the Agent Skills
70
- * specification (https://agentskills.io/specification).
71
- *
72
- * Provenance for politty-managed installs is recorded under
73
- * `metadata["politty-cli"]` as `"{packageName}:{cliName}"`.
74
- */
75
- type SkillFrontmatter = z.infer<typeof skillFrontmatterSchema>;
76
- /**
77
- * A skill discovered from a source directory (npm package).
78
- */
79
- interface DiscoveredSkill {
80
- /** Parsed frontmatter metadata */
81
- frontmatter: SkillFrontmatter;
82
- /** Path to the directory containing SKILL.md */
83
- sourcePath: string;
84
- /** Raw SKILL.md content (frontmatter + body) */
85
- rawContent: string;
86
- }
87
- /**
88
- * All kinds of scan failure, as a runtime tuple so callers can exhaustively
89
- * iterate (e.g. for message tables). Derived {@link ScanErrorReason} stays
90
- * the single source of truth for the type-level enum.
91
- */
92
- declare const SCAN_ERROR_REASONS: readonly ["parse-failed", "name-mismatch", "read-failed", "missing-source"];
93
- /** Kind of problem encountered by {@link scanSourceDir}. */
94
- type ScanErrorReason = (typeof SCAN_ERROR_REASONS)[number];
95
- /**
96
- * A non-fatal problem encountered while scanning a source directory.
97
- *
98
- * Scan errors (invalid frontmatter, name/parent-dir mismatch, unreadable
99
- * files) are collected rather than thrown so that a single malformed skill
100
- * does not hide the rest from CLI commands.
101
- */
102
- interface ScanError {
103
- /** Directory that produced the error. */
104
- path: string;
105
- /** Kind of problem encountered. */
106
- reason: ScanErrorReason;
107
- /** Human-readable detail, suitable for logging. */
108
- message: string;
109
- /**
110
- * Parsed frontmatter `name`, when the scan got far enough to read it.
111
- * Currently populated only for `name-mismatch` — both the directory
112
- * basename and this frontmatter name correspond to plausible existing
113
- * install slot names (depending on which side the user just renamed),
114
- * so `sync`'s orphan-retention guard needs both to avoid reaping an
115
- * installed slot belonging to a source skill that failed this scan.
116
- */
117
- skillName?: string;
118
- }
119
- /**
120
- * Result of scanning a source directory for SKILL.md files.
121
- */
122
- interface ScanResult {
123
- /** Valid, spec-compliant skills. */
124
- skills: DiscoveredSkill[];
125
- /** Directories that looked like skills but failed validation. */
126
- errors: ScanError[];
127
- }
128
- /**
129
- * How an install materializes skill files under `.agents/skills/<name>`
130
- * and each `SYMLINK_TARGETS` entry.
131
- *
132
- * - `"symlink"` (default): symlink the source into place. Source updates
133
- * propagate live. Throws with guidance to retry with `"copy"` when
134
- * `symlinkSync` fails (e.g. Windows without Developer Mode, filesystems
135
- * that do not support symlinks).
136
- * - `"copy"`: recursive copy. Source updates require re-running `skills
137
- * sync`. Works on any filesystem, trades liveness for portability.
138
- */
139
- type InstallMode = "symlink" | "copy";
140
- /** Options for {@link installSkill}. */
141
- interface InstallSkillOptions {
142
- /** Install materialization strategy. Default: `"symlink"`. */
143
- mode?: InstallMode;
144
- }
145
- /** Options for {@link uninstallSkill}. */
146
- interface UninstallSkillOptions {
147
- /**
148
- * If set, `uninstallSkill` also removes a real directory at the install
149
- * path when its SKILL.md's `metadata["politty-cli"]` matches this stamp
150
- * (a copy-mode install this CLI owns). Without this option, only
151
- * symlinks are removed — real directories are assumed to be legacy or
152
- * manual installs and left untouched.
153
- */
154
- expectedOwnership?: string;
155
- }
156
- /**
157
- * Per-flag overrides for the built-in skill subcommand options.
158
- *
159
- * Pass through {@link SkillCommandOptions.flags} to resolve collisions with
160
- * CLI-level global flags. Setting `alias` to `false` disables the short
161
- * alias entirely; passing a string renames it.
162
- */
163
- interface SkillFlagOverrides {
164
- /**
165
- * `--exclude` flag on `skills sync`. The default short alias is `-x`.
166
- */
167
- exclude?: {
168
- alias?: string | false;
169
- };
170
- /**
171
- * `--verbose` flag shared by `skills add` and `skills sync`. The default
172
- * short alias is `-v`.
173
- *
174
- * This is independent of {@link SkillCommandOptions.globalArgs}'s
175
- * field-name auto-detection (which drops the flag entirely when the
176
- * host's `globalArgs` already defines a `verbose` field). `alias` instead
177
- * resolves a *short-alias-only* collision — e.g. the host's `globalArgs`
178
- * uses `-v` for an unrelated flag (not named `verbose`), so auto-detection
179
- * doesn't apply, but the single-character alias still collides.
180
- */
181
- verbose?: {
182
- alias?: string | false;
183
- };
184
- }
185
- /**
186
- * Options for `withSkillCommand`.
187
- */
188
- interface SkillCommandOptions {
189
- /**
190
- * Source directory containing SKILL.md files.
191
- *
192
- * Each subdirectory whose name matches its `SKILL.md` frontmatter `name`
193
- * is treated as a skill. Symlinks within the source tree are followed.
194
- *
195
- * @example
196
- * ```typescript
197
- * // Resolves to ../skills relative to the current file.
198
- * // Works from both src/ and dist/ if at the same depth.
199
- * const sourceDir = resolve(dirname(fileURLToPath(import.meta.url)), "../skills");
200
- * ```
201
- */
202
- sourceDir: string;
203
- /**
204
- * npm package name that owns this CLI's bundled skills.
205
- *
206
- * Each source `SKILL.md` must pre-declare
207
- * `metadata["politty-cli"]: "{package}:{cliName}"`. The `skills add` and
208
- * `skills sync` subcommands verify this stamp before installing — two
209
- * tools managing skills in the same project cannot accidentally clobber
210
- * each other. `installSkill` itself does not compare ownership;
211
- * programmatic callers that bypass `withSkillCommand` are responsible
212
- * for matching the stamp against their own `{package}:{cliName}` up
213
- * front. (In `mode: "copy"`, `installSkill` additionally requires
214
- * *some* `politty-cli` stamp on the source and throws otherwise — the
215
- * caller-side ownership check naturally satisfies that precondition.)
216
- */
217
- package: string;
218
- /**
219
- * Default install mode for the `skills add` and `skills sync` commands.
220
- * Defaults to `"symlink"` — install fails with a clear error on
221
- * filesystems without symlink support (e.g. Windows without Developer
222
- * Mode). Set to `"copy"` to always copy. See {@link InstallMode}.
223
- */
224
- mode?: InstallMode;
225
- /**
226
- * Project root directory used by every `skills` subcommand for resolving
227
- * `.agents/skills/...` install paths.
228
- *
229
- * Default: walk up from `process.cwd()` and use the first ancestor that
230
- * contains `.git/` or `package.json`; fall back to `process.cwd()` when
231
- * neither is found. This avoids creating `<sub>/.agents/skills/...` when
232
- * the CLI is invoked from a subdirectory of the project.
233
- *
234
- * Pass an explicit absolute (or cwd-relative) path to override — for
235
- * example, the directory of a CLI-specific config file.
236
- */
237
- cwd?: string;
238
- /**
239
- * The host CLI's global args schema — the same value passed to
240
- * `runMain`/`runCommand`'s `globalArgs` option.
241
- *
242
- * When provided, `skills add`/`skills sync`'s `--verbose` and `skills
243
- * list`'s `--json` are automatically omitted from their own schema if
244
- * this schema already defines a same-named *non-positional boolean*
245
- * field — no manual configuration needed, and the host's global flag of
246
- * the same name takes over instead.
247
- *
248
- * A same-named field of another type (e.g. a string verbosity level)
249
- * doesn't trigger this — the local boolean flag stays declared. However,
250
- * politty itself independently rejects that combination: when
251
- * `globalArgs` and a command's own schema declare a same-named field
252
- * with different definitions, `runMain`/`runCommand` throws
253
- * `FieldTypeConflictError` at parse time. {@link SkillFlagOverrides} can't
254
- * help here — it only renames the short alias (`-v`/`-x`), not the long
255
- * `--verbose`/`--json` field name itself, so the conflicting name stays
256
- * either way. A host whose `globalArgs` uses a non-boolean `verbose`/
257
- * `json` field must rename or remove that global field (or make it a
258
- * plain boolean) instead.
259
- *
260
- * (Historical note: this omission used to also be required to work around
261
- * a politty core bug where a global flag typed *before* the subcommand
262
- * resolved correctly as a global value, but a same-named local field's
263
- * own default would then overwrite it during the merge. That bug is
264
- * fixed in politty core independently of this option — a same-named
265
- * local and global field with *identical* definitions now resolves
266
- * correctly regardless of position. This option still omits the local
267
- * flag by default for simplicity: hosts don't need to duplicate the
268
- * flag's definition on both schemas to get the expected behavior.)
269
- *
270
- * @example
271
- * ```ts
272
- * const globalArgs = z.object({
273
- * verbose: arg(z.boolean().default(false), { alias: "v" }),
274
- * });
275
- *
276
- * const cli = withSkillCommand(baseCommand, {
277
- * sourceDir, package: "@my-agent/skills",
278
- * globalArgs, // skills add/sync automatically drop their own --verbose
279
- * });
280
- *
281
- * runMain(cli, { globalArgs }); // same schema, passed to the real entry point
282
- * ```
283
- */
284
- globalArgs?: ArgsSchema;
285
- /**
286
- * Unknown-keys handling for the `add`/`sync`/`remove`/`list` arg schemas
287
- * (applied uniformly to all four).
288
- *
289
- * - `"strip"` (default) — matches politty's own `z.object()` default:
290
- * an unrecognized flag prints a warning and its value is dropped from
291
- * the parsed args.
292
- * - `"strict"` — an unrecognized flag is a hard error, matching a host
293
- * CLI that uses `z.strictObject()`/`.strict()` throughout.
294
- * - `"passthrough"` — matches `z.object().passthrough()`: no warning,
295
- * and unlike `"strip"`, the unrecognized flag's value is *kept* on the
296
- * parsed args object under its raw CLI name (e.g. `args["some-flag"]`)
297
- * rather than dropped.
298
- *
299
- * This only governs flags the parser cannot attribute to *either* this
300
- * subcommand's own schema or the host's `globalArgs` schema — a value
301
- * that legitimately arrives via `globalArgs` (see
302
- * {@link SkillCommandOptions.globalArgs}) is validated separately against
303
- * that schema and merged in afterward, so it is never rejected here.
304
- */
305
- unknownKeys?: UnknownKeysMode;
306
- /**
307
- * Customize built-in subcommand flags. Use to resolve collisions with
308
- * the CLI's global flags or to opt out of short aliases.
309
- *
310
- * @example
311
- * ```ts
312
- * // CLI already uses -x globally; rename the exclude alias.
313
- * withSkillCommand(cmd, {
314
- * sourceDir, package: "@my-agent/skills",
315
- * flags: { exclude: { alias: "X" } },
316
- * });
317
- *
318
- * // Disable the short alias entirely.
319
- * withSkillCommand(cmd, {
320
- * sourceDir, package: "@my-agent/skills",
321
- * flags: { exclude: { alias: false } },
322
- * });
323
- * ```
324
- */
325
- flags?: SkillFlagOverrides;
326
- /**
327
- * Append a one-line skills usage hint to the wrapped command's
328
- * `description` so `--help` advertises the skills subcommand.
329
- *
330
- * - `undefined` (default) — append a default hint mentioning the
331
- * available subcommands.
332
- * - `string` — append this exact string instead.
333
- * - `false` — leave the description untouched.
334
- */
335
- descriptionAppend?: string | false;
336
- /**
337
- * Override the primary (dispatched) name and aliases of `skills add` and
338
- * `skills remove`. In each array, the *first* element becomes the
339
- * subcommand's primary name; every element after it becomes an alias.
340
- *
341
- * Default: `add: ["add", "install"]`, `remove: ["remove", "uninstall"]`.
342
- *
343
- * Useful when a host CLI wants to rename these subcommands outright, drop
344
- * the `install`/`uninstall` backward-compatibility aliases, add further
345
- * aliases, or some combination of all three.
346
- *
347
- * @example
348
- * ```ts
349
- * withSkillCommand(cmd, {
350
- * sourceDir, package: "@my-agent/skills",
351
- * commandMap: {
352
- * add: ["setup", "add", "install"], // renamed to "setup"; "add"/"install" still work
353
- * remove: ["remove"], // no aliases at all
354
- * },
355
- * });
356
- * ```
357
- */
358
- commandMap?: {
359
- /** Primary name + aliases for `skills add`. Default: `["add", "install"]`. */
360
- add?: string[];
361
- /** Primary name + aliases for `skills remove`. Default: `["remove", "uninstall"]`. */
362
- remove?: string[];
363
- };
364
- /**
365
- * Override the description text for the `skills` command and/or its
366
- * built-in subcommands. Any key left unset keeps politty's default
367
- * description for that command.
368
- *
369
- * Keys refer to the subcommand's *canonical role*, not its dispatched
370
- * name — e.g. `descriptions.add` still applies after `commandMap.add`
371
- * renames the subcommand to something else.
372
- *
373
- * @example
374
- * ```ts
375
- * withSkillCommand(cmd, {
376
- * sourceDir, package: "@my-agent/skills",
377
- * commandMap: { add: ["setup", "add", "install"] },
378
- * descriptions: {
379
- * skills: "Manage My Agent skills",
380
- * add: "Install My Agent skills", // still keyed by "add", not "setup"
381
- * },
382
- * });
383
- * ```
384
- */
385
- descriptions?: {
386
- /** Description for the top-level `skills` command. Default: `"Manage agent skills"`. */
387
- skills?: string;
388
- /** Description for `skills sync`. Default: `"Remove and reinstall all skills from source"`. */
389
- sync?: string;
390
- /** Description for `skills add`. Default: `"Install skills from source"`. */
391
- add?: string;
392
- /** Description for `skills remove`. Default: `"Remove installed skills"`. */
393
- remove?: string;
394
- /** Description for `skills list`. Default: `"List available skills from source"`. */
395
- list?: string;
396
- };
397
- }
398
- /**
399
- * Result of wrapping `T` with {@link withSkillCommand} — `T` with a
400
- * `skills` entry added to (and required on) `subCommands`, so consumers can
401
- * access `command.subCommands.skills` without an `as AnyCommand` cast.
402
- */
403
- type WithSkillCommand<T extends AnyCommand> = T & {
404
- subCommands: NonNullable<T["subCommands"]> & {
405
- skills: AnyCommand;
406
- };
407
- };
408
- //#endregion
409
- //#region src/skill/installer.d.ts
410
- /**
411
- * Key used to read provenance off an installed skill. The SKILL.md's
412
- * `metadata["politty-cli"]` must equal `"{packageName}:{cliName}"` for the
413
- * owning CLI to manage it. This stamp is authored by the skill package,
414
- * not rewritten at install time.
415
- */
416
- declare const OWNERSHIP_METADATA_KEY = "politty-cli";
417
- /**
418
- * Install a skill to the project's agent skill directories.
419
- *
420
- * Canonical `.agents/skills/<name>` and each `SYMLINK_TARGETS` entry are
421
- * populated according to `options.mode`:
422
- *
423
- * - `"symlink"` (default): symlink to the source (or to the canonical dir
424
- * for the agent-specific slots). Source updates propagate live. Throws
425
- * with guidance to retry with `"copy"` on filesystems without symlink
426
- * support (e.g. Windows without Developer Mode).
427
- * - `"copy"`: recursive copy. Works anywhere, but source updates require
428
- * re-running install.
429
- *
430
- * **Symlink target convention.** Symlinks are written with relative
431
- * targets so an install survives when the project tree is copied or
432
- * mounted at a different absolute path. The two endpoints are resolved
433
- * asymmetrically:
434
- *
435
- * - The install root (`.agents/skills/`, each `SYMLINK_TARGETS` parent)
436
- * is passed through `realpathSync` so a symlinked checkout doesn't
437
- * bake a stale parent path into the relative target.
438
- * - The source path is resolved by {@link resolveSourcePreservingPackageHop},
439
- * which walks root→leaf dereferencing every ancestor symlink (a symlinked
440
- * checkout, macOS `/tmp` → `/private/tmp`, etc.) like `realpathSync` would
441
- * — EXCEPT a `node_modules/<pkg>` (or `node_modules/@scope/<pkg>`)
442
- * symlink, which is preserved. Following the package-manager hop would
443
- * bake pnpm's volatile `node_modules/.pnpm/<pkg>@<version>_<hash>/...`
444
- * into the link target and a subsequent `pnpm update` would leave every
445
- * install dangling. Keeping the hop preserves the stable
446
- * `node_modules/<pkg>` symlink that pnpm keeps repointing, while the
447
- * project-root portion still matches the install root's realpath style
448
- * so the install survives copying or remounting the project tree.
449
- *
450
- * The overlap guard and copy-mode payload still use the *fully*
451
- * `realpathSync`-resolved source: the guard must catch a source-side
452
- * symlink whose target is nested inside the install root, and the
453
- * copy-mode payload reads through every symlink so a copy install doesn't
454
- * leave dangling references back into `node_modules`.
455
- *
456
- * No absolute-path symlinks are produced by this function.
457
- *
458
- * **Atomicity.** This call is *not* transactional across multi-step
459
- * installs. The canonical slot is cleared then written, and each
460
- * `SYMLINK_TARGETS` slot is then cleared and written one at a time. A
461
- * crash mid-install can leave the canonical slot updated and one or
462
- * more agent-specific slots stale; re-running `installSkill` (or the
463
- * `skills sync` subcommand, which iterates over multiple skills) is
464
- * idempotent and converges back to the intended state. Within a single
465
- * slot's copy-mode write, the staging-and-rename in {@link atomicCopyDir}
466
- * guarantees the destination is either absent or fully populated — a
467
- * mid-copy failure never leaves a stamp-less partial directory that the
468
- * next install's `clearInstallSlot` would refuse to replace. Multi-skill
469
- * orchestration in {@link createSkillSyncCommand} is fail-fast — the
470
- * first failed skill aborts the loop without rolling back already-
471
- * installed siblings, again because re-running converges.
472
- *
473
- * The ownership stamp (`metadata["politty-cli"]`) is authored by the skill
474
- * package; the installer does not modify SKILL.md.
475
- */
476
- declare function installSkill(skill: DiscoveredSkill, cwd?: string, options?: InstallSkillOptions): void;
477
- /**
478
- * Uninstall a skill from the project's agent skill directories.
479
- *
480
- * Each slot is unlinked only when its ownership can be proven:
481
- * - Agent-specific symlink slots (`.claude/skills/<name>` etc.) — a live
482
- * symlink is unlinked only when it routes to our canonical slot, so a
483
- * foreign tool's symlink at the same shared path is left untouched.
484
- * - The canonical slot (`.agents/skills/<name>`) — a live symlink is
485
- * unlinked only when its routed-to SKILL.md carries
486
- * `options.expectedOwnership`, so another politty-based CLI's live
487
- * install in the same shared namespace is left untouched.
488
- * - Real directories at any slot are removed only when the directory's
489
- * SKILL.md carries `options.expectedOwnership`. Unstamped or foreign
490
- * real directories are left alone so legacy/manual installs are not
491
- * silently recursively deleted.
492
- *
493
- * `skills remove` / `skills sync` always pass `expectedOwnership`. Direct
494
- * programmatic callers that omit it get the legacy permissive behaviour
495
- * on symlinks (unconditional unlink) but the conservative behaviour on
496
- * real directories (no-op). Broken (dangling) canonical symlinks are
497
- * outside this function's purview — they have no SKILL.md to read, so
498
- * `cleanupBrokenSlot` handles them with a routing check instead.
499
- */
500
- declare function uninstallSkill(name: string, cwd?: string, options?: UninstallSkillOptions): void;
501
- /**
502
- * Report whether a skill is currently installed, independent of its
503
- * ownership stamp. Returns `true` when `.agents/skills/<name>/SKILL.md`
504
- * resolves to a readable file (through a valid symlink or directly, or
505
- * via a copy-mode install); returns `false` when the path is absent or
506
- * the canonical symlink is broken (source package uninstalled).
507
- *
508
- * Callers use this to distinguish the two cases where
509
- * {@link readInstalledOwnership} returns `null` — "not installed" (safe
510
- * to install fresh) vs. "installed but unstamped" (legacy or manual
511
- * install that should not be silently clobbered).
512
- */
513
- declare function hasInstalledSkill(name: string, cwd?: string): boolean;
514
- /**
515
- * Read the ownership stamp off an installed skill's SKILL.md, if any.
516
- *
517
- * For symlink-mode installs `.agents/skills/<name>` points at the source,
518
- * so this reads the package-authored stamp. For copy-mode installs the
519
- * stamp was captured at install time into the local copy.
520
- *
521
- * @returns `metadata["politty-cli"]` as `"{packageName}:{cliName}"`, or
522
- * `null` if the skill is not installed *or* the stamp is absent/malformed.
523
- * Use {@link hasInstalledSkill} to distinguish the two cases.
524
- */
525
- declare function readInstalledOwnership(name: string, cwd?: string): string | null;
526
- //#endregion
527
- //#region src/skill/scanner.d.ts
528
- /**
529
- * Scan a source directory for SKILL.md files.
530
- *
531
- * Each immediate subdirectory is a candidate skill; its `SKILL.md` is
532
- * parsed and validated against the Agent Skills specification, and the
533
- * frontmatter `name` must match the subdirectory name (spec requirement).
534
- *
535
- * If `sourceDir` itself contains a `SKILL.md`, it is treated as a
536
- * single-skill source. The parent-directory-name match is not enforced in
537
- * that case because the caller chose an arbitrary path.
538
- *
539
- * Symlinks within the source tree are followed (symlinked skill dirs and
540
- * symlinked SKILL.md files are both accepted). npm packages already
541
- * execute arbitrary JS on install, so additional symlink-based isolation
542
- * here would not raise the trust boundary in any realistic threat model.
543
- *
544
- * @example
545
- * ```
546
- * sourceDir: "node_modules/@my-agent/skills/skills"
547
- *
548
- * node_modules/@my-agent/skills/skills/
549
- * ├── commit/
550
- * │ └── SKILL.md
551
- * └── review-pr/
552
- * └── SKILL.md
553
- * ```
554
- */
555
- declare function scanSourceDir(sourceDir: string): ScanResult;
556
- //#endregion
557
- //#region src/skill/index.d.ts
558
- /**
559
- * Wrap a command with a `skills` subcommand for managing SKILL.md-based skills.
560
- *
561
- * Adds `skills sync`, `skills add`, `skills remove`, and `skills list`.
562
- * The install materialization is controlled by `options.mode`
563
- * (see {@link SkillCommandOptions}):
564
- *
565
- * - `"symlink"` (default) — symlink the source into place. Source updates
566
- * propagate live. Install errors out with guidance to retry with `"copy"`
567
- * when `symlinkSync` fails (e.g. Windows without Developer Mode).
568
- * - `"copy"` — recursive copy. Source updates require re-running sync.
569
- *
570
- * Under both modes the canonical slot is `.agents/skills/<name>` and each
571
- * agent-specific directory (e.g. `.claude/skills/<name>`) is populated
572
- * from that canonical slot. politty never writes to `SKILL.md`. The
573
- * ownership stamp `metadata["politty-cli"] = "{package}:{cliName}"` must
574
- * be authored by the skill package itself; `add` and `sync` verify it
575
- * before installing and `remove` / `sync` consult it before deleting, so
576
- * this CLI never clobbers skills another tool installed.
577
- *
578
- * @throws if `command.subCommands.skills` already exists — silently
579
- * overwriting it would hide a configuration bug.
580
- */
581
- declare function withSkillCommand<T extends AnyCommand>(command: T, options: SkillCommandOptions): WithSkillCommand<T>;
582
- //#endregion
583
- 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 };
584
- //# sourceMappingURL=index.d.ts.map