@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.
- package/LICENSE +21 -0
- package/README.md +65 -2
- package/bin/cli.mjs +3 -0
- package/dist/agent.d.ts +2 -0
- package/dist/agent.js +1 -0
- package/dist/argv-parser-BRSUT6IV.js +1 -0
- package/dist/cli-main-CoQp6CjD.js +1 -0
- package/dist/cli-main-D4rJTFFd.js +2 -0
- package/dist/cli-run-DABESHM4.js +1 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +2 -0
- package/dist/command-BXsTrIgI.js +1 -0
- package/dist/compile-cache-6u9hgeWu.js +1 -0
- package/dist/compile-cache.d.ts +80 -0
- package/dist/compile-cache.js +1 -0
- package/dist/completion-BGidlN43.js +1 -0
- package/dist/completion-Cyw4RN-l.js +116 -0
- package/dist/completion.d.ts +333 -0
- package/dist/completion.js +1 -0
- package/dist/detect-agent-D7KSeWMh.js +3 -0
- package/dist/detect-agent-EHaSY1KW.d.ts +49 -0
- package/dist/docs.d.ts +770 -0
- package/dist/docs.js +94 -0
- package/dist/dynamic-BbeRdUqR.js +1 -0
- package/dist/dynamic-Hg5BDHzz.js +6 -0
- package/dist/import-meta-resolve-DgKm4LYW.js +3 -0
- package/dist/index.d.ts +1088 -0
- package/dist/index.js +1 -0
- package/dist/log-collector-uhRWYT-z.js +1 -0
- package/dist/logger-CoeDrmRr.js +1 -0
- package/dist/prompt-clack.d.ts +15 -0
- package/dist/prompt-clack.js +1 -0
- package/dist/prompt-fl79dWPz.js +1 -0
- package/dist/prompt-inquirer.d.ts +15 -0
- package/dist/prompt-inquirer.js +1 -0
- package/dist/prompt.d.ts +106 -0
- package/dist/prompt.js +1 -0
- package/dist/register-Ceh-HlVN.js +1 -0
- package/dist/registry-BEz5iex_.js +1 -0
- package/dist/runner-D-n1xa2K.js +33 -0
- package/dist/runner-nPWQnqQ3.js +1 -0
- package/dist/schema--6eHVfwR.js +1 -0
- package/dist/schema-extractor-DFawzmtj.js +1 -0
- package/dist/skill.d.ts +581 -0
- package/dist/skill.js +2 -0
- package/dist/subcommand-router-iqmWGZyU.js +2 -0
- package/dist/types-Dhar1ua6.d.ts +1125 -0
- package/dist/with-completion-command-CARvhYvv.d.ts +384 -0
- package/dist/with-completion-command-yg7HB6Zu.js +3 -0
- package/package.json +101 -3
package/dist/skill.d.ts
ADDED
|
@@ -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};
|