@politty/loculus 0.0.0-stage → 0.1.0

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