skills-package-manager 0.2.0 → 0.3.0

package/bin/skills-package-manager.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
-import { runCli } from "../dist/index.js";
-runCli(process.argv).catch((error)=>{
-    console.error(error instanceof Error ? error.message : error);
-    process.exitCode = 1;
-});
+import { formatErrorForDisplay, getExitCode, isSpmError, runCli } from '../dist/index.js'
+
+runCli(process.argv).catch((error) => {
+  if (isSpmError(error)) {
+    console.error(formatErrorForDisplay(error))
+    process.exit(getExitCode(error))
+  }
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})

package/bin/spm.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
-import { runCli } from "../dist/index.js";
-runCli(process.argv).catch((error)=>{
-    console.error(error instanceof Error ? error.message : error);
-    process.exitCode = 1;
-});
+import { formatErrorForDisplay, getExitCode, isSpmError, runCli } from '../dist/index.js'
+
+runCli(process.argv).catch((error) => {
+  if (isSpmError(error)) {
+    console.error(formatErrorForDisplay(error))
+    process.exit(getExitCode(error))
+  }
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})

package/dist/index.js

@@ -1,46 +1,470 @@
+import { cac } from "cac";
 import picocolors from "picocolors";
 import { access, cp as promises_cp, lstat, mkdir, mkdtemp, readFile, readdir, rm as promises_rm, stat as promises_stat, symlink, writeFile } from "node:fs/promises";
 import node_path, { join } from "node:path";
 import yaml from "yaml";
-import { createHash } from "node:crypto";
-import { tmpdir } from "node:os";
 import { execFile } from "node:child_process";
+import { tmpdir } from "node:os";
 import { promisify } from "node:util";
-import { cac } from "cac";
+import { createHash } from "node:crypto";
 import * as __rspack_external__clack_prompts_3cae1695 from "@clack/prompts";
+var package_namespaceObject = {
+    rE: "0.3.0"
+};
+const UNIVERSAL_AGENT_NAMES = [
+    'Amp',
+    'Antigravity',
+    'Cline',
+    'Codex',
+    'Cursor',
+    'Deep Agents',
+    'Firebender',
+    'Gemini CLI',
+    'GitHub Copilot',
+    'Kimi Code CLI',
+    'OpenCode',
+    'Warp'
+];
+const ADDITIONAL_AGENT_TARGETS = [
+    {
+        label: 'Augment',
+        path: '.augment/skills'
+    },
+    {
+        label: 'IBM Bob',
+        path: '.bob/skills'
+    },
+    {
+        label: 'Claude Code',
+        path: '.claude/skills'
+    },
+    {
+        label: 'OpenClaw',
+        path: 'skills'
+    },
+    {
+        label: 'CodeBuddy',
+        path: '.codebuddy/skills'
+    },
+    {
+        label: 'Command Code',
+        path: '.commandcode/skills'
+    },
+    {
+        label: 'Continue',
+        path: '.continue/skills'
+    },
+    {
+        label: 'Cortex Code',
+        path: '.cortex/skills'
+    },
+    {
+        label: 'Trae',
+        path: '.trae/skills'
+    }
+];
+async function promptSkillSelection(skills) {
+    if (0 === skills.length) throw new Error('No skills found in repository');
+    if (1 === skills.length) return skills;
+    const options = skills.map((skill)=>({
+            value: skill,
+            label: skill.name,
+            hint: skill.description ? skill.description.length > 60 ? `${skill.description.slice(0, 57)}...` : skill.description : void 0
+        }));
+    const selected = await __rspack_external__clack_prompts_3cae1695.multiselect({
+        message: 'Select skills to install',
+        options,
+        required: true
+    });
+    if (__rspack_external__clack_prompts_3cae1695.isCancel(selected)) {
+        __rspack_external__clack_prompts_3cae1695.cancel('Installation cancelled');
+        process.exit(0);
+    }
+    return selected;
+}
+async function promptInitManifestOptions(promptApi = __rspack_external__clack_prompts_3cae1695, exit = process.exit) {
+    const installDirInput = await promptApi.text({
+        message: 'Where should skills be installed?',
+        initialValue: '.agents/skills'
+    });
+    if (promptApi.isCancel(installDirInput)) {
+        promptApi.cancel('Initialization cancelled');
+        exit(0);
+    }
+    promptApi.note(UNIVERSAL_AGENT_NAMES.join('\n'), 'Universal (.agents/skills) — always included');
+    const selected = await promptApi.groupMultiselect({
+        message: 'Which agents do you want to install to?',
+        options: {
+            'Additional agents': ADDITIONAL_AGENT_TARGETS.map((agent)=>({
+                    value: agent.path,
+                    label: `${agent.label} (${agent.path})`
+                }))
+        },
+        required: false
+    });
+    if (promptApi.isCancel(selected)) {
+        promptApi.cancel('Initialization cancelled');
+        exit(0);
+    }
+    const installDir = String(installDirInput).trim() || '.agents/skills';
+    return {
+        installDir,
+        linkTargets: selected
+    };
+}
+var codes_ErrorCode = /*#__PURE__*/ function(ErrorCode) {
+    ErrorCode["FILE_NOT_FOUND"] = "ENOENT";
+    ErrorCode["PERMISSION_DENIED"] = "EACCES";
+    ErrorCode["FILE_EXISTS"] = "EEXIST";
+    ErrorCode["FS_ERROR"] = "EFS";
+    ErrorCode["GIT_CLONE_FAILED"] = "EGITCLONE";
+    ErrorCode["GIT_FETCH_FAILED"] = "EGITFETCH";
+    ErrorCode["GIT_CHECKOUT_FAILED"] = "EGITCHECKOUT";
+    ErrorCode["GIT_REF_NOT_FOUND"] = "EGITREF";
+    ErrorCode["GIT_NOT_INSTALLED"] = "EGITNOTFOUND";
+    ErrorCode["PARSE_ERROR"] = "EPARSE";
+    ErrorCode["JSON_PARSE_ERROR"] = "EJSONPARSE";
+    ErrorCode["YAML_PARSE_ERROR"] = "EYAMLPARSE";
+    ErrorCode["INVALID_SPECIFIER"] = "EINVALIDSPEC";
+    ErrorCode["MANIFEST_NOT_FOUND"] = "EMANIFEST";
+    ErrorCode["LOCKFILE_NOT_FOUND"] = "ELOCKFILE";
+    ErrorCode["LOCKFILE_OUTDATED"] = "ELOCKOUTDATED";
+    ErrorCode["MANIFEST_EXISTS"] = "EMANIFESTEXISTS";
+    ErrorCode["NETWORK_ERROR"] = "ENETWORK";
+    ErrorCode["REPO_NOT_FOUND"] = "EREPONOTFOUND";
+    ErrorCode["UNKNOWN_ERROR"] = "EUNKNOWN";
+    ErrorCode["NOT_IMPLEMENTED"] = "ENOTIMPL";
+    ErrorCode["VALIDATION_ERROR"] = "EVALIDATION";
+    ErrorCode["SKILL_NOT_FOUND"] = "ESKILLNOTFOUND";
+    ErrorCode["SKILL_EXISTS"] = "ESKILLEXISTS";
+    return ErrorCode;
+}({});
+class SpmError extends Error {
+    code;
+    cause;
+    context;
+    constructor(options){
+        super(options.message);
+        this.code = options.code;
+        this.cause = options.cause;
+        this.context = options.context ?? {};
+        this.name = 'SpmError';
+        if (Error.captureStackTrace) Error.captureStackTrace(this, SpmError);
+    }
+    toString() {
+        let result = `${this.code}: ${this.message}`;
+        if (this.cause) result += `\n  Caused by: ${this.cause.message}`;
+        return result;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            cause: this.cause ? {
+                name: this.cause.name,
+                message: this.cause.message
+            } : void 0,
+            stack: this.stack
+        };
+    }
+}
+class FileSystemError extends SpmError {
+    operation;
+    path;
+    constructor(options){
+        const message = options.message ?? `${options.operation} failed for ${options.path}`;
+        super({
+            code: options.code,
+            message,
+            cause: options.cause,
+            context: {
+                operation: options.operation,
+                path: options.path
+            }
+        });
+        this.operation = options.operation;
+        this.path = options.path;
+        this.name = 'FileSystemError';
+    }
+}
+class GitError extends SpmError {
+    operation;
+    repoUrl;
+    ref;
+    constructor(options){
+        const message = options.message ?? `git ${options.operation} failed${options.repoUrl ? ` for ${options.repoUrl}` : ''}`;
+        super({
+            code: options.code,
+            message,
+            cause: options.cause,
+            context: {
+                operation: options.operation,
+                repoUrl: options.repoUrl,
+                ref: options.ref
+            }
+        });
+        this.operation = options.operation;
+        this.repoUrl = options.repoUrl;
+        this.ref = options.ref;
+        this.name = 'GitError';
+    }
+}
+class ParseError extends SpmError {
+    filePath;
+    content;
+    constructor(options){
+        super({
+            code: options.code,
+            message: options.message,
+            cause: options.cause,
+            context: {
+                filePath: options.filePath,
+                contentSnippet: options.content?.slice(0, 200)
+            }
+        });
+        this.filePath = options.filePath;
+        this.content = options.content;
+        this.name = 'ParseError';
+    }
+}
+class ManifestError extends SpmError {
+    filePath;
+    constructor(options){
+        const defaultMessages = {
+            [codes_ErrorCode.MANIFEST_NOT_FOUND]: `Manifest not found: ${options.filePath}`,
+            [codes_ErrorCode.LOCKFILE_NOT_FOUND]: `Lockfile not found: ${options.filePath}`,
+            [codes_ErrorCode.LOCKFILE_OUTDATED]: `Lockfile is out of date: ${options.filePath}`,
+            [codes_ErrorCode.MANIFEST_EXISTS]: `Manifest already exists: ${options.filePath}`
+        };
+        const message = options.message ?? defaultMessages[options.code] ?? `Manifest error: ${options.filePath}`;
+        super({
+            code: options.code,
+            message,
+            cause: options.cause,
+            context: {
+                filePath: options.filePath
+            }
+        });
+        this.filePath = options.filePath;
+        this.name = 'ManifestError';
+    }
+}
+class SkillError extends SpmError {
+    skillName;
+    constructor(options){
+        const defaultMessages = {
+            [codes_ErrorCode.SKILL_NOT_FOUND]: `Skill not found: ${options.skillName}`,
+            [codes_ErrorCode.SKILL_EXISTS]: `Skill already exists: ${options.skillName}`,
+            [codes_ErrorCode.VALIDATION_ERROR]: `Skill validation failed: ${options.skillName}`
+        };
+        const message = options.message ?? defaultMessages[options.code] ?? `Skill error: ${options.skillName}`;
+        super({
+            code: options.code,
+            message,
+            cause: options.cause,
+            context: {
+                skillName: options.skillName
+            }
+        });
+        this.skillName = options.skillName;
+        this.name = 'SkillError';
+    }
+}
+class NetworkError extends SpmError {
+    url;
+    constructor(options){
+        super({
+            code: options.code,
+            message: options.message,
+            cause: options.cause,
+            context: {
+                url: options.url
+            }
+        });
+        this.url = options.url;
+        this.name = 'NetworkError';
+    }
+}
+function convertNodeError(error, context) {
+    switch(error.code){
+        case 'ENOENT':
+            return new FileSystemError({
+                code: codes_ErrorCode.FILE_NOT_FOUND,
+                operation: context.operation,
+                path: context.path,
+                cause: error
+            });
+        case 'EACCES':
+        case 'EPERM':
+            return new FileSystemError({
+                code: codes_ErrorCode.PERMISSION_DENIED,
+                operation: context.operation,
+                path: context.path,
+                cause: error
+            });
+        case 'EEXIST':
+            return new FileSystemError({
+                code: codes_ErrorCode.FILE_EXISTS,
+                operation: context.operation,
+                path: context.path,
+                cause: error
+            });
+        case 'ENOTDIR':
+            return new FileSystemError({
+                code: codes_ErrorCode.FS_ERROR,
+                operation: context.operation,
+                path: context.path,
+                message: `Not a directory: ${context.path}`,
+                cause: error
+            });
+        case 'EISDIR':
+            return new FileSystemError({
+                code: codes_ErrorCode.FS_ERROR,
+                operation: context.operation,
+                path: context.path,
+                message: `Is a directory: ${context.path}`,
+                cause: error
+            });
+        default:
+            return new FileSystemError({
+                code: codes_ErrorCode.FS_ERROR,
+                operation: context.operation,
+                path: context.path,
+                message: error.message,
+                cause: error
+            });
+    }
+}
+function formatErrorForDisplay(error) {
+    if (error instanceof SpmError) {
+        let output = `Error [${error.code}]: ${error.message}`;
+        if (error instanceof FileSystemError) {
+            if (error.code === codes_ErrorCode.FILE_NOT_FOUND) {
+                output += `\n\nThe file "${error.path}" was not found.`;
+                if (error.path.endsWith('skills.json')) output += `\nRun "spm init" to create a new skills.json file.`;
+            } else if (error.code === codes_ErrorCode.PERMISSION_DENIED) {
+                output += `\n\nPermission denied for "${error.path}".`;
+                output += `\nCheck that you have read/write access to this location.`;
+            }
+        } else if (error instanceof GitError) {
+            if (error.code === codes_ErrorCode.GIT_REF_NOT_FOUND) {
+                output += `\n\nThe reference "${error.ref}" could not be found in the repository.`;
+                output += `\nPlease check that the branch, tag, or commit hash is correct.`;
+            } else if (error.code === codes_ErrorCode.GIT_CLONE_FAILED) {
+                output += `\n\nFailed to clone the repository.`;
+                output += `\nPossible causes:`;
+                output += `\n  - The repository URL is incorrect`;
+                output += `\n  - The repository is private and requires authentication`;
+                output += `\n  - There is no internet connection`;
+            }
+        } else if (error instanceof ParseError) {
+            if (error.code === codes_ErrorCode.JSON_PARSE_ERROR || error.code === codes_ErrorCode.YAML_PARSE_ERROR) {
+                output += `\n\nFile: ${error.filePath}`;
+                output += `\nPlease check the file syntax and fix any formatting issues.`;
+            } else if (error.code === codes_ErrorCode.INVALID_SPECIFIER) {
+                output += `\n\nInvalid skill specifier format.`;
+                output += `\nExpected formats:`;
+                output += `\n  - owner/repo (GitHub shorthand)`;
+                output += `\n  - https://github.com/owner/repo.git`;
+                output += `\n  - file:./path/to/skill`;
+            }
+        } else if (error instanceof ManifestError) {
+            if (error.code === codes_ErrorCode.LOCKFILE_OUTDATED) {
+                output += `\n\nThe lockfile is out of sync with skills.json.`;
+                output += `\nRun "spm install" to update the lockfile.`;
+            }
+        }
+        if (error.cause && !(error instanceof GitError || error instanceof FileSystemError)) output += `\n\nCaused by: ${error.cause.message}`;
+        return output;
+    }
+    if (error instanceof Error) return `Error: ${error.message}`;
+    return `Error: ${String(error)}`;
+}
+function isSpmError(error) {
+    return error instanceof SpmError;
+}
+function getExitCode(error) {
+    if (error instanceof SpmError) {
+        if (error.code.startsWith('E1')) return 101;
+        if (error.code.startsWith('E2')) return 102;
+        if (error.code.startsWith('E3')) return 103;
+        if (error.code.startsWith('E4')) return 104;
+        if (error.code.startsWith('E5')) return 105;
+        if (error.code.startsWith('E9')) return 109;
+    }
+    return 1;
+}
 async function readSkillsLock(rootDir) {
     const filePath = node_path.join(rootDir, 'skills-lock.yaml');
     try {
         const raw = await readFile(filePath, 'utf8');
-        return yaml.parse(raw);
+        try {
+            return yaml.parse(raw);
+        } catch (parseError) {
+            throw new ParseError({
+                code: codes_ErrorCode.YAML_PARSE_ERROR,
+                filePath,
+                content: raw,
+                message: `Failed to parse skills-lock.yaml: ${parseError.message}`,
+                cause: parseError
+            });
+        }
     } catch (error) {
         if ('ENOENT' === error.code) return null;
-        throw error;
+        if (error instanceof ParseError) throw error;
+        throw convertNodeError(error, {
+            operation: 'read',
+            path: filePath
+        });
     }
 }
 async function readSkillsManifest(rootDir) {
     const filePath = node_path.join(rootDir, 'skills.json');
     try {
         const raw = await readFile(filePath, 'utf8');
-        const json = JSON.parse(raw);
-        return {
-            installDir: json.installDir ?? '.agents/skills',
-            linkTargets: json.linkTargets ?? [],
-            skills: json.skills ?? {}
-        };
+        try {
+            const json = JSON.parse(raw);
+            return {
+                installDir: json.installDir ?? '.agents/skills',
+                linkTargets: json.linkTargets ?? [],
+                skills: json.skills ?? {}
+            };
+        } catch (parseError) {
+            throw new ParseError({
+                code: codes_ErrorCode.JSON_PARSE_ERROR,
+                filePath,
+                content: raw,
+                message: `Failed to parse skills.json: ${parseError.message}`,
+                cause: parseError
+            });
+        }
     } catch (error) {
         if ('ENOENT' === error.code) return null;
-        throw error;
+        if (error instanceof ParseError) throw error;
+        throw convertNodeError(error, {
+            operation: 'read',
+            path: filePath
+        });
     }
 }
 function parseSpecifier(specifier) {
     const firstHashIndex = specifier.indexOf('#');
     const secondHashIndex = firstHashIndex >= 0 ? specifier.indexOf('#', firstHashIndex + 1) : -1;
-    if (secondHashIndex >= 0) throw new Error('Invalid specifier: multiple # fragments are not supported');
+    if (secondHashIndex >= 0) throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: 'Invalid specifier: multiple # fragments are not supported',
+        content: specifier
+    });
     const hashIndex = firstHashIndex;
     const sourcePart = hashIndex >= 0 ? specifier.slice(0, hashIndex) : specifier;
     const fragment = hashIndex >= 0 ? specifier.slice(hashIndex + 1) : '';
-    if (!sourcePart) throw new Error('Specifier source is required');
+    if (!sourcePart) throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: 'Specifier source is required',
+        content: specifier
+    });
     if (!fragment) return {
         sourcePart,
         ref: null,
@@ -63,7 +487,18 @@ function parseSpecifier(specifier) {
     };
 }
 function normalizeSpecifier(specifier) {
-    const parsed = parseSpecifier(specifier);
+    let parsed;
+    try {
+        parsed = parseSpecifier(specifier);
+    } catch (error) {
+        if (error instanceof ParseError) throw error;
+        throw new ParseError({
+            code: codes_ErrorCode.INVALID_SPECIFIER,
+            message: `Invalid specifier: ${error.message}`,
+            content: specifier,
+            cause: error
+        });
+    }
     const type = parsed.sourcePart.startsWith('file:') ? 'file' : parsed.sourcePart.startsWith('npm:') ? 'npm' : 'git';
     const skillPath = parsed.path || '/';
     const skillName = node_path.posix.basename(skillPath);
@@ -130,14 +565,32 @@ async function resolveGitCommit(url, ref) {
     if (commit) return commit;
     const clonedCommit = await resolveGitCommitByClone(url, target);
     if (clonedCommit) return clonedCommit;
-    throw new Error(`Unable to resolve git ref ${target} for ${url}`);
+    throw new GitError({
+        code: codes_ErrorCode.GIT_REF_NOT_FOUND,
+        operation: 'resolve-ref',
+        repoUrl: url,
+        ref: target,
+        message: `Unable to resolve git ref "${target}" for ${url}`
+    });
 }
-async function resolveLockEntry(cwd, specifier) {
-    const normalized = normalizeSpecifier(specifier);
+async function resolveLockEntry(cwd, specifier, skillName) {
+    let normalized;
+    try {
+        normalized = normalizeSpecifier(specifier);
+    } catch (error) {
+        if (error instanceof ParseError) throw error;
+        throw new ParseError({
+            code: codes_ErrorCode.INVALID_SPECIFIER,
+            message: `Failed to parse specifier "${specifier}": ${error.message}`,
+            content: specifier,
+            cause: error
+        });
+    }
+    const finalSkillName = skillName || normalized.skillName;
     if ('file' === normalized.type) {
         const sourceRoot = node_path.resolve(cwd, normalized.source.slice(5));
         return {
-            skillName: normalized.skillName,
+            skillName: finalSkillName,
             entry: {
                 specifier: normalized.normalized,
                 resolution: {
@@ -151,7 +604,7 @@ async function resolveLockEntry(cwd, specifier) {
     if ('git' === normalized.type) {
         const commit = await resolveGitCommit(normalized.source, normalized.ref);
         return {
-            skillName: normalized.skillName,
+            skillName: finalSkillName,
             entry: {
                 specifier: normalized.normalized,
                 resolution: {
@@ -164,14 +617,21 @@ async function resolveLockEntry(cwd, specifier) {
             }
         };
     }
-    throw new Error(`Unsupported specifier type in 0.1.0 core flow: ${normalized.type}`);
+    throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: `Unsupported specifier type in 0.1.0 core flow: ${normalized.type}`,
+        content: specifier
+    });
 }
-async function syncSkillsLock(cwd, manifest, existingLock) {
-    const nextSkills = {};
-    for (const specifier of Object.values(manifest.skills)){
-        const { skillName, entry } = await resolveLockEntry(cwd, specifier);
-        nextSkills[skillName] = entry;
-    }
+async function syncSkillsLock(cwd, manifest, _existingLock) {
+    const entries = await Promise.all(Object.entries(manifest.skills).map(async ([skillName, specifier])=>{
+        const { skillName: resolvedName, entry } = await resolveLockEntry(cwd, specifier, skillName);
+        return [
+            resolvedName,
+            entry
+        ];
+    }));
+    const nextSkills = Object.fromEntries(entries);
     return {
         lockfileVersion: '0.1',
         installDir: manifest.installDir ?? '.agents/skills',
@@ -181,7 +641,14 @@ async function syncSkillsLock(cwd, manifest, existingLock) {
 }
 async function writeSkillsLock(rootDir, lockfile) {
     const filePath = node_path.join(rootDir, 'skills-lock.yaml');
-    await writeFile(filePath, yaml.stringify(lockfile), 'utf8');
+    try {
+        await writeFile(filePath, yaml.stringify(lockfile), 'utf8');
+    } catch (error) {
+        throw convertNodeError(error, {
+            operation: 'write',
+            path: filePath
+        });
+    }
 }
 async function writeSkillsManifest(rootDir, manifest) {
     const filePath = node_path.join(rootDir, 'skills.json');
@@ -190,7 +657,14 @@ async function writeSkillsManifest(rootDir, manifest) {
         linkTargets: manifest.linkTargets ?? [],
         skills: manifest.skills
     };
-    await writeFile(filePath, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try {
+        await writeFile(filePath, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    } catch (error) {
+        throw convertNodeError(error, {
+            operation: 'write',
+            path: filePath
+        });
+    }
 }
 const listSkills_execFileAsync = promisify(execFile);
 const SKIP_DIRS = new Set([
@@ -343,107 +817,46 @@ function parseGitHubUrl(input) {
         repo: match[2]
     };
 }
-const UNIVERSAL_AGENT_NAMES = [
-    'Amp',
-    'Antigravity',
-    'Cline',
-    'Codex',
-    'Cursor',
-    'Deep Agents',
-    'Firebender',
-    'Gemini CLI',
-    'GitHub Copilot',
-    'Kimi Code CLI',
-    'OpenCode',
-    'Warp'
-];
-const ADDITIONAL_AGENT_TARGETS = [
-    {
-        label: 'Augment',
-        path: '.augment/skills'
-    },
-    {
-        label: 'IBM Bob',
-        path: '.bob/skills'
-    },
-    {
-        label: 'Claude Code',
-        path: '.claude/skills'
-    },
-    {
-        label: 'OpenClaw',
-        path: 'skills'
-    },
-    {
-        label: 'CodeBuddy',
-        path: '.codebuddy/skills'
-    },
-    {
-        label: 'Command Code',
-        path: '.commandcode/skills'
-    },
-    {
-        label: 'Continue',
-        path: '.continue/skills'
-    },
-    {
-        label: 'Cortex Code',
-        path: '.cortex/skills'
-    },
-    {
-        label: 'Trae',
-        path: '.trae/skills'
-    }
-];
-async function promptSkillSelection(skills) {
-    if (0 === skills.length) throw new Error('No skills found in repository');
-    if (1 === skills.length) return skills;
-    const options = skills.map((skill)=>({
-            value: skill,
-            label: skill.name,
-            hint: skill.description ? skill.description.length > 60 ? `${skill.description.slice(0, 57)}...` : skill.description : void 0
-        }));
-    const selected = await __rspack_external__clack_prompts_3cae1695.multiselect({
-        message: 'Select skills to install',
-        options,
-        required: true
-    });
-    if (__rspack_external__clack_prompts_3cae1695.isCancel(selected)) {
-        __rspack_external__clack_prompts_3cae1695.cancel('Installation cancelled');
-        process.exit(0);
-    }
-    return selected;
-}
-async function promptInitManifestOptions(promptApi = __rspack_external__clack_prompts_3cae1695, exit = process.exit) {
-    const installDirInput = await promptApi.text({
-        message: 'Where should skills be installed?',
-        initialValue: '.agents/skills'
-    });
-    if (promptApi.isCancel(installDirInput)) {
-        promptApi.cancel('Initialization cancelled');
-        exit(0);
-    }
-    promptApi.note(UNIVERSAL_AGENT_NAMES.join('\n'), 'Universal (.agents/skills) — always included');
-    const selected = await promptApi.groupMultiselect({
-        message: 'Which agents do you want to install to?',
-        options: {
-            'Additional agents': ADDITIONAL_AGENT_TARGETS.map((agent)=>({
-                    value: agent.path,
-                    label: `${agent.label} (${agent.path})`
-                }))
-        },
-        required: false
-    });
-    if (promptApi.isCancel(selected)) {
-        promptApi.cancel('Initialization cancelled');
-        exit(0);
-    }
-    const installDir = String(installDirInput).trim() || '.agents/skills';
+function parseForComparison(specifier) {
+    const parsed = parseSpecifier(specifier);
     return {
-        installDir,
-        linkTargets: selected
+        sourcePart: parsed.sourcePart,
+        ref: parsed.ref,
+        path: parsed.path || '/'
     };
 }
+function isSpecifierCompatible(manifestSpecifier, lockSpecifier) {
+    const manifest = parseForComparison(manifestSpecifier);
+    const lock = parseForComparison(lockSpecifier);
+    if (manifest.sourcePart !== lock.sourcePart) return false;
+    if (manifest.path !== lock.path) return false;
+    if (null === manifest.ref) return true;
+    return manifest.ref === lock.ref;
+}
+function normalizeInstallDir(dir) {
+    return dir ?? '.agents/skills';
+}
+function normalizeLinkTargets(targets) {
+    return targets ?? [];
+}
+function arraysEqual(a, b) {
+    if (a.length !== b.length) return false;
+    return a.every((val, i)=>val === b[i]);
+}
+function isLockInSync(manifest, lock) {
+    if (!lock) return false;
+    if (normalizeInstallDir(manifest.installDir) !== normalizeInstallDir(lock.installDir)) return false;
+    if (!arraysEqual(normalizeLinkTargets(manifest.linkTargets), normalizeLinkTargets(lock.linkTargets))) return false;
+    const manifestSkills = Object.entries(manifest.skills);
+    const lockSkillNames = Object.keys(lock.skills);
+    if (manifestSkills.length !== lockSkillNames.length) return false;
+    for (const [name, specifier] of manifestSkills){
+        const lockEntry = lock.skills[name];
+        if (!lockEntry) return false;
+        if (!isSpecifierCompatible(specifier, lockEntry.specifier)) return false;
+    }
+    return true;
+}
 async function ensureDir(dirPath) {
     await mkdir(dirPath, {
         recursive: true
@@ -459,12 +872,6 @@ async function replaceSymlink(target, linkPath) {
 async function writeJson(filePath, value) {
     await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
-async function linkSkill(rootDir, installDir, linkTarget, skillName) {
-    const absoluteTarget = node_path.join(rootDir, installDir, skillName);
-    const absoluteLink = node_path.join(rootDir, linkTarget, skillName);
-    await ensureDir(node_path.dirname(absoluteLink));
-    await replaceSymlink(absoluteTarget, absoluteLink);
-}
 async function readInstallState(rootDir) {
     const filePath = node_path.join(rootDir, '.agents/skills/.skills-pm-install-state.json');
     try {
@@ -479,6 +886,12 @@ async function writeInstallState(rootDir, value) {
     const filePath = node_path.join(dirPath, '.skills-pm-install-state.json');
     await writeJson(filePath, value);
 }
+async function linkSkill(rootDir, installDir, linkTarget, skillName) {
+    const absoluteTarget = node_path.join(rootDir, installDir, skillName);
+    const absoluteLink = node_path.join(rootDir, linkTarget, skillName);
+    await ensureDir(node_path.dirname(absoluteLink));
+    await replaceSymlink(absoluteTarget, absoluteLink);
+}
 async function materializeLocalSkill(rootDir, skillName, sourceRoot, sourcePath, installDir) {
     const relativeSkillPath = sourcePath.replace(/^\//, '');
     const absoluteSkillPath = node_path.join(sourceRoot, relativeSkillPath);
@@ -504,14 +917,24 @@ async function materializeLocalSkill(rootDir, skillName, sourceRoot, sourcePath,
 }
 const materializeGitSkill_execFileAsync = promisify(execFile);
 async function checkoutCommit(checkoutRoot, commit) {
-    await materializeGitSkill_execFileAsync('git', [
-        'checkout',
-        commit
-    ], {
-        cwd: checkoutRoot
-    });
+    try {
+        await materializeGitSkill_execFileAsync('git', [
+            'checkout',
+            commit
+        ], {
+            cwd: checkoutRoot
+        });
+    } catch (error) {
+        throw new GitError({
+            code: codes_ErrorCode.GIT_CHECKOUT_FAILED,
+            operation: 'checkout',
+            ref: commit,
+            message: `Failed to checkout commit ${commit}`,
+            cause: error
+        });
+    }
 }
-async function fetchCommitFallback(checkoutRoot, commit) {
+async function fetchCommitFallback(checkoutRoot, commit, _repoUrl) {
     try {
         await materializeGitSkill_execFileAsync('git', [
             'fetch',
@@ -554,18 +977,33 @@ async function fetchCommitFallback(checkoutRoot, commit) {
 async function materializeGitSkill(rootDir, skillName, repoUrl, commit, sourcePath, installDir) {
     const checkoutRoot = await mkdtemp(node_path.join(tmpdir(), 'skills-pm-git-checkout-'));
     try {
-        await materializeGitSkill_execFileAsync('git', [
-            'clone',
-            '--depth',
-            '1',
-            repoUrl,
-            checkoutRoot
-        ]);
+        try {
+            await materializeGitSkill_execFileAsync('git', [
+                'clone',
+                '--depth',
+                '1',
+                repoUrl,
+                checkoutRoot
+            ]);
+        } catch (error) {
+            throw new GitError({
+                code: codes_ErrorCode.GIT_CLONE_FAILED,
+                operation: 'clone',
+                repoUrl,
+                message: `Failed to clone repository ${repoUrl}`,
+                cause: error
+            });
+        }
         if (commit && 'HEAD' !== commit) try {
             await checkoutCommit(checkoutRoot, commit);
-        } catch  {
-            await fetchCommitFallback(checkoutRoot, commit);
-            await checkoutCommit(checkoutRoot, commit);
+        } catch (checkoutError) {
+            if (checkoutError instanceof GitError) try {
+                await fetchCommitFallback(checkoutRoot, commit, repoUrl);
+                await checkoutCommit(checkoutRoot, commit);
+            } catch  {
+                throw checkoutError;
+            }
+            else throw checkoutError;
         }
         const skillDocPath = node_path.join(checkoutRoot, sourcePath.replace(/^\//, ''), 'SKILL.md');
         await readFile(skillDocPath, 'utf8');
@@ -666,17 +1104,22 @@ async function linkSkillsFromLock(rootDir, manifest, lockfile) {
         linked: Object.keys(lockfile.skills)
     };
 }
-async function installSkills(rootDir) {
+async function installSkills(rootDir, options) {
     const manifest = await readSkillsManifest(rootDir);
     if (!manifest) return {
         status: 'skipped',
         reason: 'manifest-missing'
     };
     const currentLock = await readSkillsLock(rootDir);
-    const lockfile = await syncSkillsLock(rootDir, manifest, currentLock);
+    let lockfile;
+    if (options?.frozenLockfile) {
+        if (!currentLock) throw new Error('Lockfile is required in frozen mode but none was found');
+        if (!isLockInSync(manifest, currentLock)) throw new Error('Lockfile is out of sync with manifest. Run install without --frozen-lockfile to update.');
+        lockfile = currentLock;
+    } else lockfile = await syncSkillsLock(rootDir, manifest, currentLock);
     await fetchSkillsFromLock(rootDir, manifest, lockfile);
     await linkSkillsFromLock(rootDir, manifest, lockfile);
-    await writeSkillsLock(rootDir, lockfile);
+    if (!options?.frozenLockfile) await writeSkillsLock(rootDir, lockfile);
     return {
         status: 'installed',
         installed: Object.keys(lockfile.skills)
@@ -686,14 +1129,29 @@ function buildGitHubSpecifier(owner, repo, skillPath) {
     return `https://github.com/${owner}/${repo}.git#path:${skillPath}`;
 }
 async function addSingleSkill(cwd, specifier) {
-    const normalized = normalizeSpecifier(specifier);
+    let normalized;
+    try {
+        normalized = normalizeSpecifier(specifier);
+    } catch (error) {
+        if (error instanceof ParseError) throw error;
+        throw new ParseError({
+            code: codes_ErrorCode.INVALID_SPECIFIER,
+            message: `Invalid specifier: ${error.message}`,
+            content: specifier,
+            cause: error
+        });
+    }
     const existingManifest = await readSkillsManifest(cwd) ?? {
         installDir: '.agents/skills',
         linkTargets: [],
         skills: {}
     };
     const existing = existingManifest.skills[normalized.skillName];
-    if (existing && existing !== normalized.normalized) throw new Error(`Skill ${normalized.skillName} already exists with a different specifier`);
+    if (existing && existing !== normalized.normalized) throw new SkillError({
+        code: codes_ErrorCode.SKILL_EXISTS,
+        skillName: normalized.skillName,
+        message: `Skill ${normalized.skillName} already exists with a different specifier`
+    });
     existingManifest.skills[normalized.skillName] = normalized.normalized;
     await writeSkillsManifest(cwd, existingManifest);
     const existingLock = await readSkillsLock(cwd);
@@ -731,7 +1189,11 @@ async function addCommand(options) {
         if (0 === skills.length) {
             spinner.stop(picocolors.red('No skills found'));
             __rspack_external__clack_prompts_3cae1695.outro(picocolors.red(`No valid skills found in ${source}`));
-            throw new Error(`No skills found in ${source}`);
+            throw new SkillError({
+                code: codes_ErrorCode.SKILL_NOT_FOUND,
+                skillName: source,
+                message: `No skills found in ${source}`
+            });
         }
         spinner.stop(`Found ${picocolors.green(String(skills.length))} skill${1 !== skills.length ? 's' : ''}`);
         const selected = await promptSkillSelection(skills);
@@ -754,10 +1216,21 @@ async function assertManifestMissing(cwd) {
     const filePath = node_path.join(cwd, 'skills.json');
     try {
         await access(filePath);
-        throw new Error('skills.json already exists');
+        throw new ManifestError({
+            code: codes_ErrorCode.MANIFEST_EXISTS,
+            filePath,
+            message: 'skills.json already exists'
+        });
     } catch (error) {
+        if (error instanceof ManifestError) throw error;
         if ('ENOENT' === error.code) return;
-        throw error;
+        throw new FileSystemError({
+            code: codes_ErrorCode.FS_ERROR,
+            operation: 'access',
+            path: filePath,
+            message: `Failed to check if manifest exists: ${error.message}`,
+            cause: error
+        });
     }
 }
 function createDefaultManifest() {
@@ -777,7 +1250,39 @@ async function initCommand(options, promptInit = promptInitManifestOptions) {
     return manifest;
 }
 async function installCommand(options) {
-    return installSkills(options.cwd);
+    const manifest = await readSkillsManifest(options.cwd);
+    if (!manifest) throw new ManifestError({
+        code: codes_ErrorCode.MANIFEST_NOT_FOUND,
+        filePath: `${options.cwd}/skills.json`,
+        message: 'No skills.json found in the current directory. Run "spm init" to create one.'
+    });
+    const currentLock = await readSkillsLock(options.cwd);
+    if (options.frozenLockfile) {
+        if (!currentLock) throw new ManifestError({
+            code: codes_ErrorCode.LOCKFILE_NOT_FOUND,
+            filePath: `${options.cwd}/skills-lock.yaml`,
+            message: 'Lockfile is required in frozen mode but none was found. Run "spm install" first.'
+        });
+        if (!isLockInSync(manifest, currentLock)) throw new ManifestError({
+            code: codes_ErrorCode.LOCKFILE_OUTDATED,
+            filePath: `${options.cwd}/skills-lock.yaml`,
+            message: 'Lockfile is out of sync with manifest. Run install without --frozen-lockfile to update.'
+        });
+        await fetchSkillsFromLock(options.cwd, manifest, currentLock);
+        await linkSkillsFromLock(options.cwd, manifest, currentLock);
+        return {
+            status: 'installed',
+            installed: Object.keys(currentLock.skills)
+        };
+    }
+    const lockfile = await syncSkillsLock(options.cwd, manifest, currentLock);
+    await fetchSkillsFromLock(options.cwd, manifest, lockfile);
+    await linkSkillsFromLock(options.cwd, manifest, lockfile);
+    await writeSkillsLock(options.cwd, lockfile);
+    return {
+        status: 'installed',
+        installed: Object.keys(lockfile.skills)
+    };
 }
 function createEmptyResult() {
     return {
@@ -788,7 +1293,7 @@ function createEmptyResult() {
         failed: []
     };
 }
-function createBaseLock(cwd, currentLock) {
+function createBaseLock(_cwd, currentLock) {
     if (currentLock) return {
         ...currentLock,
         skills: {
@@ -804,10 +1309,18 @@ function createBaseLock(cwd, currentLock) {
 }
 async function updateCommand(options) {
     const manifest = await readSkillsManifest(options.cwd);
-    if (!manifest) return createEmptyResult();
+    if (!manifest) throw new ManifestError({
+        code: codes_ErrorCode.MANIFEST_NOT_FOUND,
+        filePath: `${options.cwd}/skills.json`,
+        message: 'No skills.json found in the current directory. Run "spm init" to create one.'
+    });
     const currentLock = await readSkillsLock(options.cwd);
     const targetSkills = options.skills ?? Object.keys(manifest.skills);
-    for (const skillName of targetSkills)if (!(skillName in manifest.skills)) throw new Error(`Unknown skill: ${skillName}`);
+    for (const skillName of targetSkills)if (!(skillName in manifest.skills)) throw new SkillError({
+        code: codes_ErrorCode.SKILL_NOT_FOUND,
+        skillName,
+        message: `Unknown skill: ${skillName}`
+    });
     const result = createEmptyResult();
     const candidateLock = createBaseLock(options.cwd, currentLock);
     candidateLock.installDir = manifest.installDir ?? '.agents/skills';
@@ -847,9 +1360,6 @@ async function updateCommand(options) {
     result.status = result.updated.length > 0 ? 'updated' : 'skipped';
     return result;
 }
-var package_namespaceObject = {
-    rE: "0.2.0"
-};
 function createHandlers(overrides) {
     return {
         addCommand: addCommand,
@@ -870,7 +1380,7 @@ async function runCli(argv, context = {}) {
     cli.help();
     cli.version(packageVersion);
     cli.showVersionOnExit = false;
-    cli.command('add [...positionals]').option('--skill <name>', 'Select a skill').action((positionals = [], options)=>{
+    cli.command('add [...positionals]').option('--skill <name>', 'Select a skill').action(async (positionals = [], options)=>{
         const specifier = positionals[0];
         if (!specifier) throw new Error('Missing required specifier');
         return handlers.addCommand({
@@ -879,16 +1389,17 @@ async function runCli(argv, context = {}) {
             skill: options.skill
         });
     });
-    cli.command('install [...args]').action(()=>handlers.installCommand({
-            cwd
+    cli.command('install [...args]').option('--frozen-lockfile', 'Fail if lockfile is out of sync').action(async (_args, options)=>handlers.installCommand({
+            cwd,
+            frozenLockfile: options.frozenLockfile
         }));
-    cli.command('update [...skills]').action((skills = [])=>handlers.updateCommand({
+    cli.command('update [...skills]').action(async (skills = [])=>handlers.updateCommand({
             cwd,
             skills: skills.length > 0 ? skills : void 0
         }));
     cli.command('init [...args]', '', {
         allowUnknownOptions: true
-    }).option('--yes [value]', 'Skip prompts and write defaults').action((args = [], options)=>{
+    }).option('--yes [value]', 'Skip prompts and write defaults').action(async (args = [], options)=>{
         if (args.length > 0) throw new Error('init does not accept positional arguments');
         for (const key of Object.keys(options))if ('--' !== key) {
             if ('yes' !== key) throw new Error(`Unknown flag for init: --${formatFlagName(key)}`);
@@ -907,6 +1418,14 @@ async function runCli(argv, context = {}) {
     if (argv.length <= 2) return void cli.outputHelp();
     if (globalOptions.help || globalOptions.h) return;
     if (!cli.matchedCommand) throw new Error(`Unknown command: ${argv[2]}`);
-    return cli.runMatchedCommand();
+    try {
+        return await cli.runMatchedCommand();
+    } catch (error) {
+        if (error instanceof SpmError) {
+            const enhancedError = new Error(formatErrorForDisplay(error));
+            throw enhancedError;
+        }
+        throw error;
+    }
 }
-export { addCommand, cloneAndDiscover, discoverSkillsInDir, fetchSkillsFromLock, initCommand, installCommand, installSkills, installStageHooks, linkSkillsFromLock, listRepoSkills, parseGitHubUrl, parseOwnerRepo, resolveLockEntry, runCli, updateCommand };
+export { FileSystemError, GitError, ManifestError, NetworkError, ParseError, SkillError, SpmError, addCommand, cloneAndDiscover, codes_ErrorCode as ErrorCode, convertNodeError, discoverSkillsInDir, fetchSkillsFromLock, formatErrorForDisplay, getExitCode, initCommand, installCommand, installSkills, installStageHooks, isLockInSync, isSpmError, linkSkillsFromLock, listRepoSkills, normalizeSpecifier, parseGitHubUrl, parseOwnerRepo, parseSpecifier, readSkillsLock, readSkillsManifest, resolveLockEntry, runCli, updateCommand, writeSkillsLock, writeSkillsManifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-package-manager",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "repository": {
     "type": "git",