politty 0.9.0 → 0.9.1

package/dist/skill/index.d.ts

@@ -0,0 +1,432 @@
+import { _ as AnyCommand } from "../arg-registry-DDJpsUea.js";
+import { z } from "zod";
+
+//#region src/skill/frontmatter.d.ts
+/**
+ * Zod schema for SKILL.md frontmatter.
+ *
+ * Strictly validates the fields defined in the Agent Skills specification
+ * (https://agentskills.io/specification). Unknown fields are preserved via
+ * `.passthrough()` so spec extensions and vendor keys round-trip intact.
+ *
+ * Provenance / ownership for politty-managed installs is recorded under
+ * `metadata["politty-cli"]` as `"{packageName}:{cliName}"`.
+ */
+declare const skillFrontmatterSchema: z.ZodObject<{
+  name: z.ZodString;
+  description: z.ZodString;
+  license: z.ZodOptional<z.ZodString>;
+  compatibility: z.ZodOptional<z.ZodString>;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  "allowed-tools": z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * Result of parsing a SKILL.md file.
+ */
+interface ParsedSkillMd {
+  /** Parsed and validated frontmatter */
+  frontmatter: z.infer<typeof skillFrontmatterSchema>;
+  /** Markdown body (content after frontmatter) */
+  body: string;
+  /** Full raw content */
+  rawContent: string;
+}
+/**
+ * Parse YAML frontmatter from a SKILL.md string.
+ *
+ * `parseError` is set when the frontmatter fence was present but the YAML
+ * inside failed to parse, so the scanner can distinguish "invalid YAML"
+ * from "missing required field" in its diagnostics. A non-object root
+ * (e.g. a top-level YAML list) also returns empty `data` without
+ * `parseError` — Zod's schema validation surfaces that case clearly
+ * enough on its own.
+ *
+ * @example
+ * ```typescript
+ * const result = parseFrontmatter(`---
+ * name: commit
+ * description: Git commit message generation
+ * ---
+ * # Instructions...`);
+ *
+ * result.data.name; // "commit"
+ * ```
+ */
+declare function parseFrontmatter(content: string): {
+  data: Record<string, unknown>;
+  body: string;
+  parseError?: string;
+};
+/**
+ * Parse and validate a SKILL.md content string.
+ *
+ * @returns Parsed skill metadata and body, or `null` if the frontmatter is
+ *   missing or fails schema validation.
+ */
+declare function parseSkillMd(content: string): ParsedSkillMd | null;
+//#endregion
+//#region src/skill/types.d.ts
+/**
+ * SKILL.md frontmatter metadata, validated against the Agent Skills
+ * specification (https://agentskills.io/specification).
+ *
+ * Provenance for politty-managed installs is recorded under
+ * `metadata["politty-cli"]` as `"{packageName}:{cliName}"`.
+ */
+type SkillFrontmatter = z.infer<typeof skillFrontmatterSchema>;
+/**
+ * A skill discovered from a source directory (npm package).
+ */
+interface DiscoveredSkill {
+  /** Parsed frontmatter metadata */
+  frontmatter: SkillFrontmatter;
+  /** Path to the directory containing SKILL.md */
+  sourcePath: string;
+  /** Raw SKILL.md content (frontmatter + body) */
+  rawContent: string;
+}
+/**
+ * All kinds of scan failure, as a runtime tuple so callers can exhaustively
+ * iterate (e.g. for message tables). Derived {@link ScanErrorReason} stays
+ * the single source of truth for the type-level enum.
+ */
+declare const SCAN_ERROR_REASONS: readonly ["parse-failed", "name-mismatch", "read-failed", "missing-source"];
+/** Kind of problem encountered by {@link scanSourceDir}. */
+type ScanErrorReason = (typeof SCAN_ERROR_REASONS)[number];
+/**
+ * A non-fatal problem encountered while scanning a source directory.
+ *
+ * Scan errors (invalid frontmatter, name/parent-dir mismatch, unreadable
+ * files) are collected rather than thrown so that a single malformed skill
+ * does not hide the rest from CLI commands.
+ */
+interface ScanError {
+  /** Directory that produced the error. */
+  path: string;
+  /** Kind of problem encountered. */
+  reason: ScanErrorReason;
+  /** Human-readable detail, suitable for logging. */
+  message: string;
+  /**
+   * Parsed frontmatter `name`, when the scan got far enough to read it.
+   * Currently populated only for `name-mismatch` — both the directory
+   * basename and this frontmatter name correspond to plausible existing
+   * install slot names (depending on which side the user just renamed),
+   * so `sync`'s orphan-retention guard needs both to avoid reaping an
+   * installed slot belonging to a source skill that failed this scan.
+   */
+  skillName?: string;
+}
+/**
+ * Result of scanning a source directory for SKILL.md files.
+ */
+interface ScanResult {
+  /** Valid, spec-compliant skills. */
+  skills: DiscoveredSkill[];
+  /** Directories that looked like skills but failed validation. */
+  errors: ScanError[];
+}
+/**
+ * How an install materializes skill files under `.agents/skills/<name>`
+ * and each `SYMLINK_TARGETS` entry.
+ *
+ * - `"symlink"` (default): symlink the source into place. Source updates
+ *   propagate live. Throws with guidance to retry with `"copy"` when
+ *   `symlinkSync` fails (e.g. Windows without Developer Mode, filesystems
+ *   that do not support symlinks).
+ * - `"copy"`: recursive copy. Source updates require re-running `skills
+ *   sync`. Works on any filesystem, trades liveness for portability.
+ */
+type InstallMode = "symlink" | "copy";
+/** Options for {@link installSkill}. */
+interface InstallSkillOptions {
+  /** Install materialization strategy. Default: `"symlink"`. */
+  mode?: InstallMode;
+}
+/** Options for {@link uninstallSkill}. */
+interface UninstallSkillOptions {
+  /**
+   * If set, `uninstallSkill` also removes a real directory at the install
+   * path when its SKILL.md's `metadata["politty-cli"]` matches this stamp
+   * (a copy-mode install this CLI owns). Without this option, only
+   * symlinks are removed — real directories are assumed to be legacy or
+   * manual installs and left untouched.
+   */
+  expectedOwnership?: string;
+}
+/**
+ * Per-flag overrides for the built-in skill subcommand options.
+ *
+ * Pass through {@link SkillCommandOptions.flags} to resolve collisions with
+ * CLI-level global flags. Setting `alias` to `false` disables the short
+ * alias entirely; passing a string renames it.
+ */
+interface SkillFlagOverrides {
+  /**
+   * `--exclude` flag on `skills sync`. The default short alias is `-x`.
+   */
+  exclude?: {
+    alias?: string | false;
+  };
+}
+/**
+ * Options for `withSkillCommand`.
+ */
+interface SkillCommandOptions {
+  /**
+   * Source directory containing SKILL.md files.
+   *
+   * Each subdirectory whose name matches its `SKILL.md` frontmatter `name`
+   * is treated as a skill. Symlinks within the source tree are followed.
+   *
+   * @example
+   * ```typescript
+   * // Resolves to ../skills relative to the current file.
+   * // Works from both src/ and dist/ if at the same depth.
+   * const sourceDir = resolve(dirname(fileURLToPath(import.meta.url)), "../skills");
+   * ```
+   */
+  sourceDir: string;
+  /**
+   * npm package name that owns this CLI's bundled skills.
+   *
+   * Each source `SKILL.md` must pre-declare
+   * `metadata["politty-cli"]: "{package}:{cliName}"`. The `skills add` and
+   * `skills sync` subcommands verify this stamp before installing — two
+   * tools managing skills in the same project cannot accidentally clobber
+   * each other. `installSkill` itself does not compare ownership;
+   * programmatic callers that bypass `withSkillCommand` are responsible
+   * for matching the stamp against their own `{package}:{cliName}` up
+   * front. (In `mode: "copy"`, `installSkill` additionally requires
+   * *some* `politty-cli` stamp on the source and throws otherwise — the
+   * caller-side ownership check naturally satisfies that precondition.)
+   */
+  package: string;
+  /**
+   * Default install mode for the `skills add` and `skills sync` commands.
+   * Defaults to `"symlink"` — install fails with a clear error on
+   * filesystems without symlink support (e.g. Windows without Developer
+   * Mode). Set to `"copy"` to always copy. See {@link InstallMode}.
+   */
+  mode?: InstallMode;
+  /**
+   * Project root directory used by every `skills` subcommand for resolving
+   * `.agents/skills/...` install paths.
+   *
+   * Default: walk up from `process.cwd()` and use the first ancestor that
+   * contains `.git/` or `package.json`; fall back to `process.cwd()` when
+   * neither is found. This avoids creating `<sub>/.agents/skills/...` when
+   * the CLI is invoked from a subdirectory of the project.
+   *
+   * Pass an explicit absolute (or cwd-relative) path to override — for
+   * example, the directory of a CLI-specific config file.
+   */
+  cwd?: string;
+  /**
+   * Customize built-in subcommand flags. Use to resolve collisions with
+   * the CLI's global flags or to opt out of short aliases.
+   *
+   * @example
+   * ```ts
+   * // CLI already uses -x globally; rename the exclude alias.
+   * withSkillCommand(cmd, {
+   *   sourceDir, package: "@my-agent/skills",
+   *   flags: { exclude: { alias: "X" } },
+   * });
+   *
+   * // Disable the short alias entirely.
+   * withSkillCommand(cmd, {
+   *   sourceDir, package: "@my-agent/skills",
+   *   flags: { exclude: { alias: false } },
+   * });
+   * ```
+   */
+  flags?: SkillFlagOverrides;
+  /**
+   * Append a one-line skills usage hint to the wrapped command's
+   * `description` so `--help` advertises the skills subcommand.
+   *
+   * - `undefined` (default) — append a default hint mentioning the
+   *   available subcommands.
+   * - `string` — append this exact string instead.
+   * - `false` — leave the description untouched.
+   */
+  descriptionAppend?: string | false;
+}
+//#endregion
+//#region src/skill/installer.d.ts
+/**
+ * Key used to read provenance off an installed skill. The SKILL.md's
+ * `metadata["politty-cli"]` must equal `"{packageName}:{cliName}"` for the
+ * owning CLI to manage it. This stamp is authored by the skill package,
+ * not rewritten at install time.
+ */
+declare const OWNERSHIP_METADATA_KEY = "politty-cli";
+/**
+ * Install a skill to the project's agent skill directories.
+ *
+ * Canonical `.agents/skills/<name>` and each `SYMLINK_TARGETS` entry are
+ * populated according to `options.mode`:
+ *
+ * - `"symlink"` (default): symlink to the source (or to the canonical dir
+ *   for the agent-specific slots). Source updates propagate live. Throws
+ *   with guidance to retry with `"copy"` on filesystems without symlink
+ *   support (e.g. Windows without Developer Mode).
+ * - `"copy"`: recursive copy. Works anywhere, but source updates require
+ *   re-running install.
+ *
+ * **Symlink target convention.** Symlinks are written with relative
+ * targets so an install survives when the project tree is copied or
+ * mounted at a different absolute path. The two endpoints are resolved
+ * asymmetrically:
+ *
+ * - The install root (`.agents/skills/`, each `SYMLINK_TARGETS` parent)
+ *   is passed through `realpathSync` so a symlinked checkout doesn't
+ *   bake a stale parent path into the relative target.
+ * - The source path is resolved by {@link resolveSourcePreservingPackageHop},
+ *   which walks root→leaf dereferencing every ancestor symlink (a symlinked
+ *   checkout, macOS `/tmp` → `/private/tmp`, etc.) like `realpathSync` would
+ *   — EXCEPT a `node_modules/<pkg>` (or `node_modules/@scope/<pkg>`)
+ *   symlink, which is preserved. Following the package-manager hop would
+ *   bake pnpm's volatile `node_modules/.pnpm/<pkg>@<version>_<hash>/...`
+ *   into the link target and a subsequent `pnpm update` would leave every
+ *   install dangling. Keeping the hop preserves the stable
+ *   `node_modules/<pkg>` symlink that pnpm keeps repointing, while the
+ *   project-root portion still matches the install root's realpath style
+ *   so the install survives copying or remounting the project tree.
+ *
+ * The overlap guard and copy-mode payload still use the *fully*
+ * `realpathSync`-resolved source: the guard must catch a source-side
+ * symlink whose target is nested inside the install root, and the
+ * copy-mode payload reads through every symlink so a copy install doesn't
+ * leave dangling references back into `node_modules`.
+ *
+ * No absolute-path symlinks are produced by this function.
+ *
+ * **Atomicity.** This call is *not* transactional across multi-step
+ * installs. The canonical slot is cleared then written, and each
+ * `SYMLINK_TARGETS` slot is then cleared and written one at a time. A
+ * crash mid-install can leave the canonical slot updated and one or
+ * more agent-specific slots stale; re-running `installSkill` (or the
+ * `skills sync` subcommand, which iterates over multiple skills) is
+ * idempotent and converges back to the intended state. Within a single
+ * slot's copy-mode write, the staging-and-rename in {@link atomicCopyDir}
+ * guarantees the destination is either absent or fully populated — a
+ * mid-copy failure never leaves a stamp-less partial directory that the
+ * next install's `clearInstallSlot` would refuse to replace. Multi-skill
+ * orchestration in {@link createSkillSyncCommand} is fail-fast — the
+ * first failed skill aborts the loop without rolling back already-
+ * installed siblings, again because re-running converges.
+ *
+ * The ownership stamp (`metadata["politty-cli"]`) is authored by the skill
+ * package; the installer does not modify SKILL.md.
+ */
+declare function installSkill(skill: DiscoveredSkill, cwd?: string, options?: InstallSkillOptions): void;
+/**
+ * Uninstall a skill from the project's agent skill directories.
+ *
+ * Each slot is unlinked only when its ownership can be proven:
+ * - Agent-specific symlink slots (`.claude/skills/<name>` etc.) — a live
+ *   symlink is unlinked only when it routes to our canonical slot, so a
+ *   foreign tool's symlink at the same shared path is left untouched.
+ * - The canonical slot (`.agents/skills/<name>`) — a live symlink is
+ *   unlinked only when its routed-to SKILL.md carries
+ *   `options.expectedOwnership`, so another politty-based CLI's live
+ *   install in the same shared namespace is left untouched.
+ * - Real directories at any slot are removed only when the directory's
+ *   SKILL.md carries `options.expectedOwnership`. Unstamped or foreign
+ *   real directories are left alone so legacy/manual installs are not
+ *   silently recursively deleted.
+ *
+ * `skills remove` / `skills sync` always pass `expectedOwnership`. Direct
+ * programmatic callers that omit it get the legacy permissive behaviour
+ * on symlinks (unconditional unlink) but the conservative behaviour on
+ * real directories (no-op). Broken (dangling) canonical symlinks are
+ * outside this function's purview — they have no SKILL.md to read, so
+ * `cleanupBrokenSlot` handles them with a routing check instead.
+ */
+declare function uninstallSkill(name: string, cwd?: string, options?: UninstallSkillOptions): void;
+/**
+ * Report whether a skill is currently installed, independent of its
+ * ownership stamp. Returns `true` when `.agents/skills/<name>/SKILL.md`
+ * resolves to a readable file (through a valid symlink or directly, or
+ * via a copy-mode install); returns `false` when the path is absent or
+ * the canonical symlink is broken (source package uninstalled).
+ *
+ * Callers use this to distinguish the two cases where
+ * {@link readInstalledOwnership} returns `null` — "not installed" (safe
+ * to install fresh) vs. "installed but unstamped" (legacy or manual
+ * install that should not be silently clobbered).
+ */
+declare function hasInstalledSkill(name: string, cwd?: string): boolean;
+/**
+ * Read the ownership stamp off an installed skill's SKILL.md, if any.
+ *
+ * For symlink-mode installs `.agents/skills/<name>` points at the source,
+ * so this reads the package-authored stamp. For copy-mode installs the
+ * stamp was captured at install time into the local copy.
+ *
+ * @returns `metadata["politty-cli"]` as `"{packageName}:{cliName}"`, or
+ *   `null` if the skill is not installed *or* the stamp is absent/malformed.
+ *   Use {@link hasInstalledSkill} to distinguish the two cases.
+ */
+declare function readInstalledOwnership(name: string, cwd?: string): string | null;
+//#endregion
+//#region src/skill/scanner.d.ts
+/**
+ * Scan a source directory for SKILL.md files.
+ *
+ * Each immediate subdirectory is a candidate skill; its `SKILL.md` is
+ * parsed and validated against the Agent Skills specification, and the
+ * frontmatter `name` must match the subdirectory name (spec requirement).
+ *
+ * If `sourceDir` itself contains a `SKILL.md`, it is treated as a
+ * single-skill source. The parent-directory-name match is not enforced in
+ * that case because the caller chose an arbitrary path.
+ *
+ * Symlinks within the source tree are followed (symlinked skill dirs and
+ * symlinked SKILL.md files are both accepted). npm packages already
+ * execute arbitrary JS on install, so additional symlink-based isolation
+ * here would not raise the trust boundary in any realistic threat model.
+ *
+ * @example
+ * ```
+ * sourceDir: "node_modules/@my-agent/skills/skills"
+ *
+ * node_modules/@my-agent/skills/skills/
+ * ├── commit/
+ * │   └── SKILL.md
+ * └── review-pr/
+ *     └── SKILL.md
+ * ```
+ */
+declare function scanSourceDir(sourceDir: string): ScanResult;
+//#endregion
+//#region src/skill/index.d.ts
+/**
+ * Wrap a command with a `skills` subcommand for managing SKILL.md-based skills.
+ *
+ * Adds `skills sync`, `skills add`, `skills remove`, and `skills list`.
+ * The install materialization is controlled by `options.mode`
+ * (see {@link SkillCommandOptions}):
+ *
+ * - `"symlink"` (default) — symlink the source into place. Source updates
+ *   propagate live. Install errors out with guidance to retry with `"copy"`
+ *   when `symlinkSync` fails (e.g. Windows without Developer Mode).
+ * - `"copy"` — recursive copy. Source updates require re-running sync.
+ *
+ * Under both modes the canonical slot is `.agents/skills/<name>` and each
+ * agent-specific directory (e.g. `.claude/skills/<name>`) is populated
+ * from that canonical slot. politty never writes to `SKILL.md`. The
+ * ownership stamp `metadata["politty-cli"] = "{package}:{cliName}"` must
+ * be authored by the skill package itself; `add` and `sync` verify it
+ * before installing and `remove` / `sync` consult it before deleting, so
+ * this CLI never clobbers skills another tool installed.
+ *
+ * @throws if `command.subCommands.skills` already exists — silently
+ *   overwriting it would hide a configuration bug.
+ */
+declare function withSkillCommand<T extends AnyCommand>(command: T, options: SkillCommandOptions): T;
+//#endregion
+export { type DiscoveredSkill, type InstallMode, type InstallSkillOptions, OWNERSHIP_METADATA_KEY, type ParsedSkillMd, SCAN_ERROR_REASONS, type ScanError, type ScanErrorReason, type ScanResult, type SkillCommandOptions, type SkillFlagOverrides, type SkillFrontmatter, type UninstallSkillOptions, hasInstalledSkill, installSkill, parseFrontmatter, parseSkillMd, readInstalledOwnership, scanSourceDir, skillFrontmatterSchema, uninstallSkill, withSkillCommand };
+//# sourceMappingURL=index.d.ts.map