skills-package-manager 0.7.0 → 0.9.0

package/README.md

@@ -11,6 +11,8 @@ npx skills-package-manager --help
 npx skills-package-manager --version
 npx skills-package-manager add <specifier> [--skill <name>]
 npx skills-package-manager install
+npx skills-package-manager patch <skill>
+npx skills-package-manager patch-commit <edit-dir>
 npx skills-package-manager update [skill...]
 npx skills-package-manager init [--yes]
 ```
@@ -104,6 +106,40 @@ npx skills-package-manager install
 
 This resolves each skill from its specifier, materializes it into `installDir` (default `.agents/skills/`), and creates symlinks for each `linkTarget`.
 When `selfSkill` is `true`, `npx skills-package-manager install` also installs the bundled `skills-package-manager-cli` skill so users get guidance for `skills.json`, `skills-lock.yaml`, and `npx skills-package-manager` commands. This helper skill is not written to `skills-lock.yaml`.
+If `patchedSkills` contains an entry for a skill, the corresponding patch file is applied after the skill is materialized.
+
+### `npx skills-package-manager patch`
+
+Prepare a skill for patching without changing the manifest yet:
+
+```bash
+npx skills-package-manager patch hello-skill
+npx skills-package-manager patch hello-skill --edit-dir ./tmp/hello-skill
+```
+
+Behavior:
+
+- Resolves the currently locked content for the target skill
+- Extracts an editable copy into a temporary directory by default
+- Reapplies any committed patch for that skill unless `--ignore-existing` is passed
+- Writes patch edit metadata so `patch-commit` can generate a new patch file later
+
+### `npx skills-package-manager patch-commit`
+
+Commit an edited patch directory back into the project:
+
+```bash
+npx skills-package-manager patch-commit /tmp/skills-pm-patch-hello-skill-12345
+npx skills-package-manager patch-commit ./tmp/hello-skill --patches-dir ./custom-patches
+```
+
+Behavior:
+
+- Compares the edited directory with the original resolved skill content
+- Writes a unified diff patch file to `patches/<skill>.patch` by default
+- Updates `skills.json` through the `patchedSkills` field
+- Updates `skills-lock.yaml` with patch path and digest metadata
+- Reinstalls and relinks the patched skill so the working tree reflects the committed patch
 
 ### `npx skills-package-manager update`
 
@@ -172,10 +208,11 @@ link: link:<path-to-skill-dir>
 src/
 ├── bin/           # CLI entry points
 ├── cli/           # CLI runner and interactive prompts
-├── commands/      # add, install command implementations
+├── commands/      # add, install, patch command implementations
 ├── config/        # skills.json / skills-lock.yaml read/write
 ├── github/        # Git clone + skill discovery (listSkills)
 ├── install/       # Skill materialization, linking, pruning
+├── patches/       # Patch edit state, diff generation, patch application
 ├── specifiers/    # Specifier parsing and normalization
 └── utils/         # Hashing, filesystem helpers
 ```

package/dist/index.d.ts

@@ -0,0 +1,488 @@
+export declare function addCommand(options: AddCommandOptions): Promise<{
+    skillName: string;
+    specifier: string;
+} | {
+    skillName: string;
+    specifier: string;
+}[]>;
+
+export declare type AddCommandOptions = {
+    cwd: string;
+    specifier: string;
+    skill?: string;
+    global?: boolean;
+    yes?: boolean;
+    agent?: string[];
+};
+
+/**
+ * Clone a git repo (shallow) into a temp dir, discover skills, then clean up.
+ */
+export declare function cloneAndDiscover(gitUrl: string, ref?: string): Promise<{
+    skills: SkillInfo[];
+    cleanup: () => Promise<void>;
+}>;
+
+/**
+ * Converts a Node.js file system error to an appropriate SPM error type
+ */
+export declare function convertNodeError(error: NodeJS.ErrnoException, context: {
+    operation: string;
+    path: string;
+}): FileSystemError;
+
+export declare function createInstallProgressReporter(options?: ProgressReporterOptions): InstallProgressReporter;
+
+/**
+ * Discover skills in a local directory by scanning for SKILL.md files.
+ * Recursively scans the repo tree for directories containing SKILL.md.
+ */
+export declare function discoverSkillsInDir(baseDir: string): Promise<SkillInfo[]>;
+
+/**
+ * Error codes for SPM (Skills Package Manager)
+ * Inspired by pnpm's error code system
+ */
+export declare enum ErrorCode {
+    FILE_NOT_FOUND = "ENOENT",
+    PERMISSION_DENIED = "EACCES",
+    FILE_EXISTS = "EEXIST",
+    FS_ERROR = "EFS",
+    GIT_CLONE_FAILED = "EGITCLONE",
+    GIT_FETCH_FAILED = "EGITFETCH",
+    GIT_CHECKOUT_FAILED = "EGITCHECKOUT",
+    GIT_REF_NOT_FOUND = "EGITREF",
+    GIT_NOT_INSTALLED = "EGITNOTFOUND",
+    PARSE_ERROR = "EPARSE",
+    JSON_PARSE_ERROR = "EJSONPARSE",
+    YAML_PARSE_ERROR = "EYAMLPARSE",
+    INVALID_SPECIFIER = "EINVALIDSPEC",
+    MANIFEST_NOT_FOUND = "EMANIFEST",
+    LOCKFILE_NOT_FOUND = "ELOCKFILE",
+    LOCKFILE_OUTDATED = "ELOCKOUTDATED",
+    MANIFEST_EXISTS = "EMANIFESTEXISTS",
+    MANIFEST_VALIDATION_ERROR = "EMANIFESTVAL",
+    NETWORK_ERROR = "ENETWORK",
+    REPO_NOT_FOUND = "EREPONOTFOUND",
+    INSTALL_ERROR = "EINSTALL",
+    UNKNOWN_ERROR = "EUNKNOWN",
+    NOT_IMPLEMENTED = "ENOTIMPL",
+    VALIDATION_ERROR = "EVALIDATION",
+    SKILL_NOT_FOUND = "ESKILLNOTFOUND",
+    SKILL_EXISTS = "ESKILLEXISTS"
+}
+
+export declare function expandSkillsManifest(_rootDir: string, manifest: SkillsManifest): Promise<NormalizedSkillsManifest>;
+
+export declare function fetchSkillsFromLock(rootDir: string, manifest: SkillsManifest, lockfile: SkillsLock, options?: {
+    onProgress?: InstallProgressListener;
+}): Promise<{
+    readonly status: "skipped";
+    readonly reason: "up-to-date";
+    readonly fetched?: undefined;
+} | {
+    readonly status: "fetched";
+    readonly fetched: string[];
+    reason?: undefined;
+}>;
+
+/**
+ * Error thrown when file system operations fail
+ */
+export declare class FileSystemError extends SpmError {
+    readonly operation: string;
+    readonly path: string;
+    constructor(options: {
+        code: ErrorCode.FILE_NOT_FOUND | ErrorCode.PERMISSION_DENIED | ErrorCode.FILE_EXISTS | ErrorCode.FS_ERROR;
+        operation: 'read' | 'write' | 'access' | 'mkdir' | 'rm' | 'copy' | 'symlink' | string;
+        path: string;
+        message?: string;
+        cause?: Error;
+    });
+}
+
+/**
+ * Formats an error for display to the user
+ * Provides helpful context for known error types
+ */
+export declare function formatErrorForDisplay(error: unknown): string;
+
+/**
+ * Gets the exit code for an error
+ * Returns 1 for general errors, specific codes for known error types
+ */
+export declare function getExitCode(error: unknown): number;
+
+/**
+ * Error thrown when git operations fail
+ */
+export declare class GitError extends SpmError {
+    readonly operation: string;
+    readonly repoUrl?: string;
+    readonly ref?: string;
+    constructor(options: {
+        code: ErrorCode.GIT_CLONE_FAILED | ErrorCode.GIT_FETCH_FAILED | ErrorCode.GIT_CHECKOUT_FAILED | ErrorCode.GIT_REF_NOT_FOUND | ErrorCode.GIT_NOT_INSTALLED;
+        operation: 'clone' | 'fetch' | 'checkout' | 'ls-remote' | 'rev-parse' | string;
+        repoUrl?: string;
+        ref?: string;
+        message?: string;
+        cause?: Error;
+    });
+}
+
+export declare function initCommand(options: InitCommandOptions, promptInit?: InitPrompter): Promise<SkillsManifest>;
+
+export declare type InitCommandOptions = {
+    cwd: string;
+    yes?: boolean;
+};
+
+declare type InitPrompter = () => Promise<InitPromptResult>;
+
+declare type InitPromptResult = {
+    installDir: string;
+    linkTargets: string[];
+};
+
+export declare function installCommand(options: InstallCommandOptions): Promise<{
+    status: "skipped";
+    reason: string;
+    installed?: undefined;
+} | {
+    status: "installed";
+    installed: string[];
+    reason?: undefined;
+}>;
+
+export declare type InstallCommandOptions = {
+    cwd: string;
+    frozenLockfile?: boolean;
+    onProgress?: InstallProgressListener;
+};
+
+declare type InstallPhase = 'resolving' | 'fetching' | 'linking' | 'finalizing' | 'done';
+
+export declare type InstallProgressEvent = {
+    type: 'resolved';
+    skillName: string;
+} | {
+    type: 'reused';
+    skillName: string;
+} | {
+    type: 'downloaded';
+    skillName: string;
+} | {
+    type: 'added';
+    skillName: string;
+} | {
+    type: 'installed';
+    skillName: string;
+};
+
+export declare type InstallProgressListener = (event: InstallProgressEvent) => void;
+
+declare type InstallProgressReporter = {
+    start(total: number): void;
+    setPhase(phase: Exclude<InstallPhase, 'done'>): void;
+    onProgress(event: InstallProgressEvent): void;
+    complete(): void;
+    fail(): void;
+};
+
+export declare function installSkills(rootDir: string, options?: {
+    frozenLockfile?: boolean;
+    onProgress?: InstallProgressListener;
+}): Promise<{
+    readonly status: "skipped";
+    readonly reason: "manifest-missing";
+    installed?: undefined;
+} | {
+    readonly status: "installed";
+    readonly installed: string[];
+    reason?: undefined;
+}>;
+
+export declare const installStageHooks: {
+    beforeFetch: (_rootDir: string, _manifest: SkillsManifest, _lockfile: SkillsLock) => Promise<void>;
+};
+
+export declare function isLockInSync(rootDir: string, manifest: NormalizedSkillsManifest, lock: SkillsLock | null, manifestStat?: ManifestStat | null, installState?: {
+    manifestStat?: ManifestStat;
+} | null): Promise<boolean>;
+
+/**
+ * Checks if an error is a known SPM error
+ */
+export declare function isSpmError(error: unknown): error is SpmError;
+
+export declare function linkSkillsFromLock(rootDir: string, manifest: SkillsManifest, lockfile: SkillsLock, options?: {
+    onProgress?: InstallProgressListener;
+}): Promise<{
+    readonly status: "linked";
+    readonly linked: string[];
+}>;
+
+/**
+ * List skills in a GitHub repo by cloning and scanning.
+ * This avoids GitHub API rate limits.
+ */
+export declare function listRepoSkills(owner: string, repo: string, ref?: string): Promise<SkillInfo[]>;
+
+/**
+ * Error thrown when manifest or lockfile operations fail
+ */
+export declare class ManifestError extends SpmError {
+    readonly filePath: string;
+    constructor(options: {
+        code: ErrorCode.MANIFEST_NOT_FOUND | ErrorCode.LOCKFILE_NOT_FOUND | ErrorCode.LOCKFILE_OUTDATED | ErrorCode.MANIFEST_EXISTS | ErrorCode.MANIFEST_VALIDATION_ERROR;
+        filePath: string;
+        message?: string;
+        cause?: Error;
+    });
+}
+
+declare interface ManifestStat {
+    mtimeMs: number;
+    size: number;
+}
+
+/**
+ * Error thrown when network operations fail
+ */
+export declare class NetworkError extends SpmError {
+    readonly url?: string;
+    constructor(options: {
+        code: ErrorCode.NETWORK_ERROR | ErrorCode.REPO_NOT_FOUND;
+        url?: string;
+        message: string;
+        cause?: Error;
+    });
+}
+
+/**
+ * Skills manifest output type after validation/default application.
+ * Use this for normalized manifests returned from reads/parsing.
+ */
+declare type NormalizedSkillsManifest = {
+    $schema?: string;
+    installDir: string;
+    linkTargets: string[];
+    selfSkill?: boolean;
+    skills: Record<string, string>;
+    patchedSkills?: Record<string, string>;
+};
+
+export declare type NormalizedSpecifier = {
+    type: 'git' | 'link' | 'file' | 'npm';
+    source: string;
+    ref: string | null;
+    path: string;
+    normalized: string;
+    skillName: string;
+};
+
+export declare function normalizeSkillsManifest(manifest: Partial<SkillsManifest>): NormalizedSkillsManifest;
+
+export declare function normalizeSpecifier(specifier: string): NormalizedSpecifier;
+
+/**
+ * Error thrown when parsing fails (JSON, YAML, specifiers)
+ */
+export declare class ParseError extends SpmError {
+    readonly filePath?: string;
+    readonly content?: string;
+    constructor(options: {
+        code: ErrorCode.PARSE_ERROR | ErrorCode.JSON_PARSE_ERROR | ErrorCode.YAML_PARSE_ERROR | ErrorCode.INVALID_SPECIFIER;
+        filePath?: string;
+        content?: string;
+        message: string;
+        cause?: Error;
+    });
+}
+
+export declare function parseGitHubUrl(input: string): {
+    owner: string;
+    repo: string;
+} | null;
+
+export declare function parseOwnerRepo(input: string): {
+    owner: string;
+    repo: string;
+} | null;
+
+export declare function parseSpecifier(specifier: string): {
+    sourcePart: string;
+    ref: string | null;
+    path: string;
+};
+
+export declare function patchCommand(options: PatchCommandOptions): Promise<PatchCommandResult>;
+
+export declare type PatchCommandOptions = {
+    cwd: string;
+    skillName: string;
+    editDir?: string;
+    ignoreExisting?: boolean;
+};
+
+export declare type PatchCommandResult = {
+    status: 'patched';
+    skillName: string;
+    editDir: string;
+    originalSpecifier: string;
+};
+
+export declare function patchCommitCommand(options: PatchCommitCommandOptions): Promise<PatchCommitCommandResult>;
+
+export declare type PatchCommitCommandOptions = {
+    cwd: string;
+    editDir: string;
+    patchesDir?: string;
+};
+
+export declare type PatchCommitCommandResult = {
+    status: 'patched';
+    skillName: string;
+    patchFile: string;
+};
+
+declare type ProgressReporterOptions = {
+    isTTY?: boolean;
+    write?: (text: string) => void;
+    info?: (text: string) => void;
+};
+
+export declare function readSkillsLock(rootDir: string): Promise<SkillsLock | null>;
+
+export declare function readSkillsManifest(rootDir: string): Promise<NormalizedSkillsManifest | null>;
+
+export declare function resolveLockEntry(cwd: string, specifier: string, skillName?: string): Promise<{
+    skillName: string;
+    entry: SkillsLockEntry;
+}>;
+
+export declare function runCli(argv: string[], context?: {
+    cwd?: string;
+}): Promise<unknown>;
+
+/**
+ * Error thrown when a skill operation fails
+ */
+export declare class SkillError extends SpmError {
+    readonly skillName: string;
+    constructor(options: {
+        code: ErrorCode.SKILL_NOT_FOUND | ErrorCode.SKILL_EXISTS | ErrorCode.VALIDATION_ERROR;
+        skillName: string;
+        message?: string;
+        cause?: Error;
+    });
+}
+
+export declare type SkillInfo = {
+    name: string;
+    description: string;
+    path: string;
+};
+
+export declare type SkillsLock = {
+    lockfileVersion: '0.1';
+    installDir: string;
+    linkTargets: string[];
+    skills: Record<string, SkillsLockEntry>;
+};
+
+export declare type SkillsLockEntry = {
+    specifier: string;
+    resolution: {
+        type: 'link';
+        path: string;
+    } | {
+        type: 'file';
+        tarball: string;
+        path: string;
+    } | {
+        type: 'git';
+        url: string;
+        commit: string;
+        path: string;
+    } | {
+        type: 'npm';
+        packageName: string;
+        version: string;
+        path: string;
+        tarball: string;
+        integrity?: string;
+        registry?: string;
+    };
+    digest: string;
+    patch?: {
+        path: string;
+        digest: string;
+    };
+};
+
+/**
+ * Skills manifest input type used for authoring/writing manifests.
+ * This preserves optionality for fields with defaults.
+ */
+export declare type SkillsManifest = {
+    $schema?: string;
+    installDir?: string;
+    linkTargets?: string[];
+    selfSkill?: boolean;
+    skills?: Record<string, string>;
+    patchedSkills?: Record<string, string>;
+};
+
+/**
+ * Base error class for SPM (Skills Package Manager)
+ * All custom errors should extend this class
+ */
+export declare class SpmError extends Error {
+    readonly code: ErrorCode;
+    readonly cause?: Error;
+    readonly context: Record<string, unknown>;
+    constructor(options: {
+        code: ErrorCode;
+        message: string;
+        cause?: Error;
+        context?: Record<string, unknown>;
+    });
+    /**
+     * Returns a formatted string representation of the error
+     */
+    toString(): string;
+    /**
+     * Returns a detailed object representation for logging/debugging
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+export declare function updateCommand(options: UpdateCommandOptions): Promise<UpdateCommandResult>;
+
+export declare type UpdateCommandOptions = {
+    cwd: string;
+    skills?: string[];
+};
+
+export declare type UpdateCommandResult = {
+    status: 'updated' | 'skipped' | 'failed';
+    updated: string[];
+    unchanged: string[];
+    skipped: Array<{
+        name: string;
+        reason: 'link-specifier';
+    }>;
+    failed: Array<{
+        name: string;
+        reason: string;
+    }>;
+};
+
+export declare function withBundledSelfSkillLock(rootDir: string, manifest: SkillsManifest, lockfile: SkillsLock): Promise<SkillsLock>;
+
+export declare function writeSkillsLock(rootDir: string, lockfile: SkillsLock): Promise<void>;
+
+export declare function writeSkillsManifest(rootDir: string, manifest: SkillsManifest): Promise<void>;
+
+export { }