skills-package-manager 0.3.0 → 0.4.0

package/README.md

@@ -31,7 +31,9 @@ spm add owner/repo --skill find-skills
 
 # Direct specifier — skip discovery
 spm add https://github.com/owner/repo.git#path:/skills/my-skill
-spm add file:./local-source#path:/skills/my-skill
+spm add link:./local-source/skills/my-skill
+spm add file:./skills-package.tgz#path:/skills/my-skill
+spm add npm:@scope/skills-package#path:/skills/my-skill
 ```
 
 After `spm add`, the newly added skills are resolved, materialized into `installDir`, and linked to each configured `linkTarget` immediately.
@@ -86,7 +88,7 @@ This resolves each skill from its specifier, materializes it into `installDir` (
 
 ### `spm update`
 
-Refresh git-based skills declared in `skills.json` without changing the manifest:
+Refresh resolvable skills declared in `skills.json` without changing the manifest:
 
 ```bash
 spm update
@@ -96,8 +98,8 @@ spm update find-skills rspress-custom-theme
 Behavior:
 
 - Uses `skills.json` as the source of truth
-- Re-resolves git refs to the latest commit
-- Skips `file:` skills
+- Re-resolves git refs and npm package targets
+- Skips `link:` skills
 - Fails immediately for unknown skill names
 - Writes `skills-lock.yaml` only after fetch and link succeed
 
@@ -123,13 +125,14 @@ const skills = await listRepoSkills('vercel-labs', 'skills')
 
 ## Specifier Format
 
-```
-<source>#[ref&]path:<skill-path>
+```text
+git/file/npm: <source>#[ref&]path:<skill-path>
+link: link:<path-to-skill-dir>
 ```
 
 | Part | Description | Example |
 |------|-------------|---------|
-| `source` | Git URL or `file:` path | `https://github.com/o/r.git`, `file:./local` |
+| `source` | Git URL, direct `link:` skill path, `file:` tarball, or `npm:` package name | `https://github.com/o/r.git`, `link:./local/skills/my-skill`, `file:./skills.tgz`, `npm:@scope/pkg` |
 | `ref` | Optional git ref | `main`, `v1.0.0`, `HEAD`, `6cb0992`, `6cb0992a176f2ca142e19f64dca8ac12025b035e` |
 | `path` | Path to skill directory within source | `/skills/my-skill` |
 
@@ -138,7 +141,11 @@ const skills = await listRepoSkills('vercel-labs', 'skills')
 ### Resolution Types
 
 - **`git`** — Clones the repo, resolves commit hash, copies skill files
-- **`file`** — Reads from local filesystem, computes content digest
+- **`link`** — Reads from a local directory and copies the selected skill
+- **`file`** — Extracts a local `tgz` package and copies the selected skill
+- **`npm`** — Resolves a package from the configured npm registry, locks the tarball URL/version/integrity, and installs from the downloaded tarball
+
+`npm:` reads `registry` and scoped `@scope:registry` values from `.npmrc`. Matching `:_authToken`, `:_auth`, or `username` + `:_password` entries are also used for private registry requests.
 
 ## Architecture
 

package/dist/index.js

@@ -1,15 +1,18 @@
 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 { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, stat as promises_stat, symlink, writeFile } from "node:fs/promises";
+import node_path, { basename, join } from "node:path";
 import yaml from "yaml";
 import { execFile } from "node:child_process";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { promisify } from "node:util";
 import { createHash } from "node:crypto";
+import semver from "semver";
+import { createReadStream } from "node:fs";
+import { x } from "tar";
 import * as __rspack_external__clack_prompts_3cae1695 from "@clack/prompts";
 var package_namespaceObject = {
-    rE: "0.3.0"
+    rE: "0.4.0"
 };
 const UNIVERSAL_AGENT_NAMES = [
     'Amp',
@@ -368,7 +371,9 @@ function formatErrorForDisplay(error) {
                 output += `\nExpected formats:`;
                 output += `\n  - owner/repo (GitHub shorthand)`;
                 output += `\n  - https://github.com/owner/repo.git`;
-                output += `\n  - file:./path/to/skill`;
+                output += `\n  - link:./path/to/skill-dir`;
+                output += `\n  - file:./path/to/skill-package.tgz#path:/skills/my-skill`;
+                output += `\n  - npm:@scope/skill-package#path:/skills/my-skill`;
             }
         } else if (error instanceof ManifestError) {
             if (error.code === codes_ErrorCode.LOCKFILE_OUTDATED) {
@@ -449,6 +454,213 @@ async function readSkillsManifest(rootDir) {
         });
     }
 }
+const resolvedNpmPackageCache = new Map();
+function normalizeRegistryUrl(url) {
+    return url.endsWith('/') ? url : `${url}/`;
+}
+function interpolateEnv(value) {
+    return value.replace(/\$\{([^}]+)\}/g, (_match, key)=>process.env[key] ?? '');
+}
+async function readNpmRc(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        const entries = new Map();
+        for (const rawLine of content.split(/\r?\n/)){
+            const line = rawLine.trim();
+            if (!line || line.startsWith('#') || line.startsWith(';')) continue;
+            const separator = line.indexOf('=');
+            if (!(separator < 0)) entries.set(line.slice(0, separator).trim(), interpolateEnv(line.slice(separator + 1).trim()));
+        }
+        return entries;
+    } catch  {
+        return new Map();
+    }
+}
+function getCandidateDirs(cwd) {
+    const resolvedCwd = node_path.resolve(cwd);
+    if ('win32' === process.platform) {
+        const parsed = node_path.parse(resolvedCwd);
+        const relative = resolvedCwd.slice(parsed.root.length);
+        const parts = relative.split(node_path.sep).filter(Boolean);
+        return [
+            parsed.root,
+            ...parts.map((_part, index)=>node_path.join(parsed.root, ...parts.slice(0, index + 1)))
+        ];
+    }
+    const parts = resolvedCwd.split(node_path.sep).filter(Boolean);
+    return [
+        '/',
+        ...parts.map((_part, index)=>node_path.join('/', ...parts.slice(0, index + 1)))
+    ];
+}
+function buildRegistryAuthEntries(settings) {
+    const registryAuthConfigs = new Map();
+    for (const [key, value] of settings){
+        const match = key.match(/^(\/\/.+\/):(_authToken|_auth|username|_password)$/);
+        if (!match) continue;
+        const [, prefix, field] = match;
+        const config = registryAuthConfigs.get(prefix) ?? {};
+        registryAuthConfigs.set(prefix, {
+            ...config,
+            ['_authToken' === field ? 'authToken' : '_auth' === field ? 'auth' : 'username' === field ? 'username' : 'password']: value
+        });
+    }
+    return [
+        ...registryAuthConfigs.entries()
+    ].map(([prefix, config])=>{
+        if (config.authToken) return {
+            prefix,
+            authorization: `Bearer ${config.authToken}`
+        };
+        if (config.auth) return {
+            prefix,
+            authorization: `Basic ${config.auth}`
+        };
+        if (config.username && config.password) {
+            const decodedPassword = Buffer.from(config.password, 'base64').toString('utf8');
+            return {
+                prefix,
+                authorization: `Basic ${Buffer.from(`${config.username}:${decodedPassword}`).toString('base64')}`
+            };
+        }
+        return null;
+    }).filter((entry)=>null !== entry).sort((a, b)=>b.prefix.length - a.prefix.length);
+}
+async function loadNpmConfig(cwd) {
+    const configs = new Map();
+    for (const [key, value] of (await readNpmRc(node_path.join(homedir(), '.npmrc'))))configs.set(key, value);
+    for (const candidateDir of getCandidateDirs(cwd))for (const [key, value] of (await readNpmRc(node_path.join(candidateDir, '.npmrc'))))configs.set(key, value);
+    return {
+        settings: configs,
+        authEntries: buildRegistryAuthEntries(configs)
+    };
+}
+function resolveRegistryConfig(config, packageName) {
+    const scopeMatch = packageName.match(/^(@[^/]+)\//);
+    if (scopeMatch) {
+        const scopeRegistry = config.settings.get(`${scopeMatch[1]}:registry`);
+        if (scopeRegistry) return normalizeRegistryUrl(scopeRegistry);
+    }
+    return normalizeRegistryUrl(config.settings.get('registry') ?? 'https://registry.npmjs.org/');
+}
+function resolveAuthorizationHeader(config, requestUrl) {
+    const url = new URL(requestUrl);
+    const requestKey = `//${url.host}${url.pathname}`;
+    const matched = config.authEntries.find((entry)=>requestKey.startsWith(entry.prefix));
+    return matched?.authorization;
+}
+function createRequestHeaders(config, requestUrl) {
+    const authorization = resolveAuthorizationHeader(config, requestUrl);
+    if (!authorization) return;
+    return {
+        authorization
+    };
+}
+function parseRegistryPackageSpecifier(specifier) {
+    const scopedMatch = specifier.match(/^(@[^/]+\/[^@]+)(?:@(.+))?$/);
+    if (scopedMatch) return {
+        packageName: scopedMatch[1],
+        requestedVersion: scopedMatch[2] ?? null
+    };
+    const unscopedMatch = specifier.match(/^([^@/:][^@]*?)(?:@(.+))?$/);
+    if (unscopedMatch) return {
+        packageName: unscopedMatch[1],
+        requestedVersion: unscopedMatch[2] ?? null
+    };
+    throw new Error(`Unsupported npm specifier: ${specifier}`);
+}
+function resolveVersionFromMetadata(metadata, requestedVersion) {
+    const versions = metadata.versions ?? {};
+    const versionKeys = Object.keys(versions);
+    const requested = requestedVersion ?? 'latest';
+    const taggedVersion = metadata['dist-tags']?.[requested];
+    if (taggedVersion && versions[taggedVersion]) return taggedVersion;
+    if (semver.valid(requested) && versions[requested]) return requested;
+    const matched = semver.maxSatisfying(versionKeys, requested);
+    if (matched) return matched;
+    throw new Error(`Unable to resolve npm version "${requested}"`);
+}
+async function resolveNpmPackageUncached(cwd, specifier) {
+    const config = await loadNpmConfig(cwd);
+    const { packageName, requestedVersion } = parseRegistryPackageSpecifier(specifier);
+    const registry = resolveRegistryConfig(config, packageName);
+    const metadataUrl = new URL(encodeURIComponent(packageName), registry);
+    const response = await fetch(metadataUrl, {
+        headers: createRequestHeaders(config, metadataUrl.toString())
+    });
+    if (!response.ok) throw new Error(`Failed to fetch npm metadata for ${packageName}: ${response.status}`);
+    const metadata = await response.json();
+    const version = resolveVersionFromMetadata(metadata, requestedVersion);
+    const manifest = metadata.versions?.[version];
+    const tarballUrl = manifest?.dist?.tarball;
+    if (!manifest?.name || !manifest.version || !tarballUrl) throw new Error(`Invalid npm metadata for ${packageName}@${version}`);
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        tarballUrl,
+        integrity: manifest.dist?.integrity,
+        registry
+    };
+}
+async function resolveNpmPackage(cwd, specifier) {
+    const cacheKey = `${node_path.resolve(cwd)}\0${specifier}`;
+    const cached = resolvedNpmPackageCache.get(cacheKey);
+    if (cached) return cached;
+    const pending = resolveNpmPackageUncached(cwd, specifier);
+    resolvedNpmPackageCache.set(cacheKey, pending);
+    try {
+        return await pending;
+    } catch (error) {
+        resolvedNpmPackageCache.delete(cacheKey);
+        throw error;
+    }
+}
+function verifyIntegrity(buffer, integrity) {
+    for (const entry of integrity.split(/\s+/).filter(Boolean)){
+        const separatorIndex = entry.indexOf('-');
+        if (separatorIndex <= 0) continue;
+        const algorithm = entry.slice(0, separatorIndex);
+        const expectedDigest = entry.slice(separatorIndex + 1);
+        try {
+            const actualDigest = createHash(algorithm).update(buffer).digest('base64');
+            if (actualDigest === expectedDigest) return true;
+        } catch  {}
+    }
+    return false;
+}
+async function downloadNpmPackageTarball(cwd, tarballUrl, expectedIntegrity) {
+    const downloadRoot = await mkdtemp(node_path.join(tmpdir(), 'skills-pm-npm-download-'));
+    try {
+        const config = await loadNpmConfig(cwd);
+        const response = await fetch(tarballUrl, {
+            headers: createRequestHeaders(config, tarballUrl)
+        });
+        if (!response.ok) throw new Error(`Failed to download npm tarball: ${response.status}`);
+        const tarballBuffer = Buffer.from(await response.arrayBuffer());
+        if (expectedIntegrity && !verifyIntegrity(tarballBuffer, expectedIntegrity)) throw new Error(`Integrity check failed for npm tarball ${tarballUrl}`);
+        const tarballPath = node_path.join(downloadRoot, node_path.basename(new URL(tarballUrl).pathname) || 'package.tgz');
+        await writeFile(tarballPath, tarballBuffer);
+        return tarballPath;
+    } catch (error) {
+        await rm(downloadRoot, {
+            recursive: true,
+            force: true
+        }).catch(()=>{});
+        throw new Error(`Failed to download npm tarball ${tarballUrl}: ${error.message}`, {
+            cause: error
+        });
+    }
+}
+async function cleanupPackedNpmPackage(tarballPath) {
+    await rm(node_path.dirname(tarballPath), {
+        recursive: true,
+        force: true
+    }).catch(()=>{});
+}
+function normalizeLinkSource(sourcePart) {
+    const linkPath = sourcePart.slice(5).replace(/\\/g, '/').replace(/\/+$/, '');
+    return `link:${linkPath}`;
+}
 function parseSpecifier(specifier) {
     const firstHashIndex = specifier.indexOf('#');
     const secondHashIndex = firstHashIndex >= 0 ? specifier.indexOf('#', firstHashIndex + 1) : -1;
@@ -487,6 +699,11 @@ function parseSpecifier(specifier) {
     };
 }
 function normalizeSpecifier(specifier) {
+    if (specifier.startsWith('link:') && specifier.includes('#')) throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: 'Invalid link specifier: link: must point directly to a skill directory',
+        content: specifier
+    });
     let parsed;
     try {
         parsed = parseSpecifier(specifier);
@@ -499,7 +716,20 @@ function normalizeSpecifier(specifier) {
             cause: error
         });
     }
-    const type = parsed.sourcePart.startsWith('file:') ? 'file' : parsed.sourcePart.startsWith('npm:') ? 'npm' : 'git';
+    const type = parsed.sourcePart.startsWith('link:') ? 'link' : parsed.sourcePart.startsWith('file:') ? 'file' : parsed.sourcePart.startsWith('npm:') ? 'npm' : 'git';
+    if ('link' === type) {
+        const linkSource = normalizeLinkSource(parsed.sourcePart);
+        const linkPath = linkSource.slice(5);
+        const skillName = node_path.posix.basename(linkPath);
+        return {
+            type,
+            source: linkSource,
+            ref: null,
+            path: '/',
+            normalized: linkSource,
+            skillName
+        };
+    }
     const skillPath = parsed.path || '/';
     const skillName = node_path.posix.basename(skillPath);
     const normalized = parsed.ref ? `${parsed.sourcePart}#${parsed.ref}&path:${skillPath}` : parsed.path ? `${parsed.sourcePart}#path:${skillPath}` : parsed.sourcePart;
@@ -515,7 +745,50 @@ function normalizeSpecifier(specifier) {
 function sha256(content) {
     return `sha256-${createHash('sha256').update(content).digest('hex')}`;
 }
+function toPortablePath(filePath) {
+    return '/' === node_path.sep ? filePath : filePath.split(node_path.sep).join('/');
+}
+async function hashDirectoryEntry(hash, rootDir, currentDir) {
+    const entries = await readdir(currentDir, {
+        withFileTypes: true
+    });
+    entries.sort((a, b)=>a.name.localeCompare(b.name));
+    for (const entry of entries){
+        const absolutePath = node_path.join(currentDir, entry.name);
+        const relativePath = toPortablePath(node_path.relative(rootDir, absolutePath));
+        const stats = await lstat(absolutePath);
+        if (stats.isSymbolicLink()) {
+            hash.update(`symlink:${relativePath}\n`);
+            hash.update(await readlink(absolutePath));
+            hash.update('\n');
+            continue;
+        }
+        if (stats.isDirectory()) {
+            hash.update(`dir:${relativePath}\n`);
+            await hashDirectoryEntry(hash, rootDir, absolutePath);
+            continue;
+        }
+        hash.update(`file:${relativePath}\n`);
+        hash.update(await readFile(absolutePath));
+        hash.update('\n');
+    }
+}
+async function sha256Directory(rootDir) {
+    const hash = createHash('sha256');
+    await hashDirectoryEntry(hash, rootDir, rootDir);
+    return `sha256-${hash.digest('hex')}`;
+}
+async function sha256File(filePath, suffix = '') {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(filePath))hash.update(chunk);
+    if (suffix) hash.update(suffix);
+    return `sha256-${hash.digest('hex')}`;
+}
 const execFileAsync = promisify(execFile);
+function toPortableRelativePath(from, to) {
+    const relativePath = node_path.relative(from, to) || '.';
+    return '/' === node_path.sep ? relativePath : relativePath.split(node_path.sep).join('/');
+}
 async function resolveGitCommitByLsRemote(url, target) {
     try {
         const { stdout } = await execFileAsync('git', [
@@ -553,7 +826,7 @@ async function resolveGitCommitByClone(url, target) {
     } catch  {
         return null;
     } finally{
-        await promises_rm(checkoutRoot, {
+        await rm(checkoutRoot, {
             recursive: true,
             force: true
         }).catch(()=>{});
@@ -587,17 +860,32 @@ async function resolveLockEntry(cwd, specifier, skillName) {
         });
     }
     const finalSkillName = skillName || normalized.skillName;
-    if ('file' === normalized.type) {
+    if ('link' === normalized.type) {
         const sourceRoot = node_path.resolve(cwd, normalized.source.slice(5));
+        return {
+            skillName: finalSkillName,
+            entry: {
+                specifier: normalized.normalized,
+                resolution: {
+                    type: 'link',
+                    path: toPortableRelativePath(cwd, sourceRoot)
+                },
+                digest: await sha256Directory(sourceRoot)
+            }
+        };
+    }
+    if ('file' === normalized.type) {
+        const tarballPath = node_path.resolve(cwd, normalized.source.slice(5));
         return {
             skillName: finalSkillName,
             entry: {
                 specifier: normalized.normalized,
                 resolution: {
                     type: 'file',
-                    path: node_path.relative(cwd, sourceRoot) || '.'
+                    tarball: toPortableRelativePath(cwd, tarballPath),
+                    path: normalized.path
                 },
-                digest: sha256(`${sourceRoot}:${normalized.path}`)
+                digest: await sha256File(tarballPath, `:${normalized.path}`)
             }
         };
     }
@@ -617,15 +905,46 @@ async function resolveLockEntry(cwd, specifier, skillName) {
             }
         };
     }
+    if ('npm' === normalized.type) {
+        const packageSpecifier = normalized.source.slice(4);
+        const resolved = await resolveNpmPackage(cwd, packageSpecifier);
+        return {
+            skillName: finalSkillName,
+            entry: {
+                specifier: normalized.normalized,
+                resolution: {
+                    type: 'npm',
+                    packageName: resolved.name,
+                    version: resolved.version,
+                    path: normalized.path,
+                    tarball: resolved.tarballUrl,
+                    integrity: resolved.integrity,
+                    registry: resolved.registry
+                },
+                digest: sha256([
+                    resolved.name,
+                    resolved.version,
+                    resolved.tarballUrl,
+                    resolved.integrity ?? '',
+                    resolved.registry ?? '',
+                    normalized.path
+                ].join(':'))
+            }
+        };
+    }
     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) {
+async function syncSkillsLock(cwd, manifest, _existingLock, options) {
     const entries = await Promise.all(Object.entries(manifest.skills).map(async ([skillName, specifier])=>{
         const { skillName: resolvedName, entry } = await resolveLockEntry(cwd, specifier, skillName);
+        options?.onProgress?.({
+            type: 'resolved',
+            skillName: resolvedName
+        });
         return [
             resolvedName,
             entry
@@ -700,7 +1019,7 @@ async function parseSkillDir(dir, relativePath) {
     try {
         const content = await readFile(join(dir, 'SKILL.md'), 'utf8');
         const meta = parseSkillFrontmatter(content);
-        const dirName = dir.split('/').pop() ?? '';
+        const dirName = basename(dir);
         return {
             name: meta.name || dirName,
             description: meta.description,
@@ -760,14 +1079,14 @@ async function cloneAndDiscover(gitUrl, ref) {
         return {
             skills,
             cleanup: async ()=>{
-                await promises_rm(tempDir, {
+                await rm(tempDir, {
                     recursive: true,
                     force: true
                 }).catch(()=>{});
             }
         };
     } catch (error) {
-        await promises_rm(tempDir, {
+        await rm(tempDir, {
             recursive: true,
             force: true
         }).catch(()=>{});
@@ -819,10 +1138,11 @@ function parseGitHubUrl(input) {
 }
 function parseForComparison(specifier) {
     const parsed = parseSpecifier(specifier);
+    const isLink = parsed.sourcePart.startsWith('link:');
     return {
-        sourcePart: parsed.sourcePart,
-        ref: parsed.ref,
-        path: parsed.path || '/'
+        sourcePart: isLink ? normalizeLinkSource(parsed.sourcePart) : parsed.sourcePart,
+        ref: isLink ? null : parsed.ref,
+        path: isLink ? '/' : parsed.path || '/'
     };
 }
 function isSpecifierCompatible(manifestSpecifier, lockSpecifier) {
@@ -862,8 +1182,17 @@ async function ensureDir(dirPath) {
         recursive: true
     });
 }
+async function replaceDir(from, to) {
+    await rm(to, {
+        recursive: true,
+        force: true
+    });
+    await cp(from, to, {
+        recursive: true
+    });
+}
 async function replaceSymlink(target, linkPath) {
-    await promises_rm(linkPath, {
+    await rm(linkPath, {
         recursive: true,
         force: true
     });
@@ -872,18 +1201,19 @@ async function replaceSymlink(target, linkPath) {
 async function writeJson(filePath, value) {
     await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
-async function readInstallState(rootDir) {
-    const filePath = node_path.join(rootDir, '.agents/skills/.skills-pm-install-state.json');
+const INSTALL_STATE_FILE = '.skills-pm-install-state.json';
+async function readInstallState(rootDir, installDir) {
+    const filePath = node_path.join(rootDir, installDir, INSTALL_STATE_FILE);
     try {
         return JSON.parse(await readFile(filePath, 'utf8'));
     } catch  {
         return null;
     }
 }
-async function writeInstallState(rootDir, value) {
-    const dirPath = node_path.join(rootDir, '.agents/skills');
+async function writeInstallState(rootDir, installDir, value) {
+    const dirPath = node_path.join(rootDir, installDir);
     await ensureDir(dirPath);
-    const filePath = node_path.join(dirPath, '.skills-pm-install-state.json');
+    const filePath = node_path.join(dirPath, INSTALL_STATE_FILE);
     await writeJson(filePath, value);
 }
 async function linkSkill(rootDir, installDir, linkTarget, skillName) {
@@ -905,10 +1235,7 @@ async function materializeLocalSkill(rootDir, skillName, sourceRoot, sourcePath,
     if (!skillDoc) throw new Error(`Invalid skill at ${absoluteSkillPath}: missing SKILL.md`);
     const targetDir = node_path.join(rootDir, installDir, skillName);
     await ensureDir(node_path.dirname(targetDir));
-    await promises_cp(absoluteSkillPath, targetDir, {
-        recursive: true,
-        force: true
-    });
+    await replaceDir(absoluteSkillPath, targetDir);
     await writeJson(node_path.join(targetDir, '.skills-pm.json'), {
         name: skillName,
         installedBy: 'skills-package-manager',
@@ -1009,12 +1336,33 @@ async function materializeGitSkill(rootDir, skillName, repoUrl, commit, sourcePa
         await readFile(skillDocPath, 'utf8');
         await materializeLocalSkill(rootDir, skillName, checkoutRoot, sourcePath, installDir);
     } finally{
-        await promises_rm(checkoutRoot, {
+        await rm(checkoutRoot, {
             recursive: true,
             force: true
         });
     }
 }
+async function materializePackedSkill(rootDir, skillName, tarballPath, sourcePath, installDir) {
+    const extractRoot = await mkdtemp(node_path.join(tmpdir(), 'skills-pm-packed-skill-'));
+    try {
+        await mkdir(node_path.join(extractRoot, 'package'), {
+            recursive: true
+        });
+        await x({
+            file: tarballPath,
+            cwd: node_path.join(extractRoot, 'package'),
+            strip: 1,
+            preservePaths: false,
+            strict: true
+        });
+        await materializeLocalSkill(rootDir, skillName, node_path.join(extractRoot, 'package'), sourcePath, installDir);
+    } finally{
+        await rm(extractRoot, {
+            recursive: true,
+            force: true
+        }).catch(()=>{});
+    }
+}
 async function isManagedSkillDir(dirPath) {
     try {
         const marker = JSON.parse(await readFile(node_path.join(dirPath, '.skills-pm.json'), 'utf8'));
@@ -1033,7 +1381,7 @@ async function pruneManagedSkills(rootDir, installDir, linkTargets, wantedSkillN
             const skillDir = node_path.join(absoluteInstallDir, entry);
             if (await isManagedSkillDir(skillDir)) {
                 if (!wanted.has(entry)) {
-                    await promises_rm(skillDir, {
+                    await rm(skillDir, {
                         recursive: true,
                         force: true
                     });
@@ -1041,7 +1389,7 @@ async function pruneManagedSkills(rootDir, installDir, linkTargets, wantedSkillN
                         const linkPath = node_path.join(rootDir, linkTarget, entry);
                         try {
                             const stat = await lstat(linkPath);
-                            if (stat.isSymbolicLink() || stat.isDirectory() || stat.isFile()) await promises_rm(linkPath, {
+                            if (stat.isSymbolicLink() || stat.isDirectory() || stat.isFile()) await rm(linkPath, {
                                 recursive: true,
                                 force: true
                             });
@@ -1055,50 +1403,98 @@ async function pruneManagedSkills(rootDir, installDir, linkTargets, wantedSkillN
 const installStageHooks = {
     beforeFetch: async (_rootDir, _manifest, _lockfile)=>{}
 };
-function extractSkillPath(specifier, skillName) {
-    const marker = '#path:';
-    const index = specifier.indexOf(marker);
-    if (index >= 0) return specifier.slice(index + marker.length);
-    return `/${skillName}`;
+async function areManagedSkillsInstalled(rootDir, installDir, skillNames) {
+    for (const skillName of skillNames)try {
+        await access(node_path.join(rootDir, installDir, skillName, 'SKILL.md'));
+    } catch  {
+        return false;
+    }
+    return true;
 }
-async function fetchSkillsFromLock(rootDir, manifest, lockfile) {
+async function fetchSkillsFromLock(rootDir, manifest, lockfile, options) {
     await installStageHooks.beforeFetch(rootDir, manifest, lockfile);
+    const installDir = manifest.installDir ?? '.agents/skills';
+    const linkTargets = manifest.linkTargets ?? [];
+    await pruneManagedSkills(rootDir, installDir, linkTargets, Object.keys(lockfile.skills));
     const lockDigest = sha256(JSON.stringify(lockfile));
-    const state = await readInstallState(rootDir);
-    if (state?.lockDigest === lockDigest) return {
+    const state = await readInstallState(rootDir, installDir);
+    if (state?.lockDigest === lockDigest && await areManagedSkillsInstalled(rootDir, installDir, Object.keys(lockfile.skills))) return {
         status: 'skipped',
         reason: 'up-to-date'
     };
-    const installDir = manifest.installDir ?? '.agents/skills';
-    const linkTargets = manifest.linkTargets ?? [];
-    await pruneManagedSkills(rootDir, installDir, linkTargets, Object.keys(lockfile.skills));
-    for (const [skillName, entry] of Object.entries(lockfile.skills)){
-        if ('file' === entry.resolution.type) {
-            await materializeLocalSkill(rootDir, skillName, node_path.resolve(rootDir, entry.resolution.path), extractSkillPath(entry.specifier, skillName), installDir);
-            continue;
-        }
-        if ('git' === entry.resolution.type) {
-            await materializeGitSkill(rootDir, skillName, entry.resolution.url, entry.resolution.commit, entry.resolution.path, installDir);
-            continue;
+    const downloadedTarballs = new Map();
+    try {
+        for (const [skillName, entry] of Object.entries(lockfile.skills)){
+            if ('link' === entry.resolution.type) {
+                await materializeLocalSkill(rootDir, skillName, node_path.resolve(rootDir, entry.resolution.path), '/', installDir);
+                options?.onProgress?.({
+                    type: 'added',
+                    skillName
+                });
+                continue;
+            }
+            if ('file' === entry.resolution.type) {
+                await materializePackedSkill(rootDir, skillName, node_path.resolve(rootDir, entry.resolution.tarball), entry.resolution.path, installDir);
+                options?.onProgress?.({
+                    type: 'added',
+                    skillName
+                });
+                continue;
+            }
+            if ('git' === entry.resolution.type) {
+                await materializeGitSkill(rootDir, skillName, entry.resolution.url, entry.resolution.commit, entry.resolution.path, installDir);
+                options?.onProgress?.({
+                    type: 'added',
+                    skillName
+                });
+                continue;
+            }
+            if ('npm' === entry.resolution.type) {
+                const cacheKey = `${entry.resolution.tarball}\0${entry.resolution.integrity ?? ''}`;
+                let tarballPathPromise = downloadedTarballs.get(cacheKey);
+                if (!tarballPathPromise) {
+                    tarballPathPromise = downloadNpmPackageTarball(rootDir, entry.resolution.tarball, entry.resolution.integrity);
+                    downloadedTarballs.set(cacheKey, tarballPathPromise);
+                }
+                const tarballPath = await tarballPathPromise;
+                await materializePackedSkill(rootDir, skillName, tarballPath, entry.resolution.path, installDir);
+                options?.onProgress?.({
+                    type: 'added',
+                    skillName
+                });
+                continue;
+            }
+            throw new Error(`Unsupported resolution type in 0.1.0 core flow: ${entry.resolution.type}`);
         }
-        throw new Error(`Unsupported resolution type in 0.1.0 core flow: ${entry.resolution.type}`);
+        await writeInstallState(rootDir, installDir, {
+            lockDigest,
+            installDir,
+            linkTargets,
+            installerVersion: '0.1.0',
+            installedAt: new Date().toISOString()
+        });
+    } finally{
+        const settledTarballs = await Promise.allSettled(downloadedTarballs.values());
+        const downloadedPaths = new Set(settledTarballs.filter((result)=>'fulfilled' === result.status).map((result)=>result.value));
+        await Promise.all([
+            ...downloadedPaths
+        ].map((tarballPath)=>cleanupPackedNpmPackage(tarballPath)));
     }
-    await writeInstallState(rootDir, {
-        lockDigest,
-        installDir,
-        linkTargets,
-        installerVersion: '0.1.0',
-        installedAt: new Date().toISOString()
-    });
     return {
         status: 'fetched',
         fetched: Object.keys(lockfile.skills)
     };
 }
-async function linkSkillsFromLock(rootDir, manifest, lockfile) {
+async function linkSkillsFromLock(rootDir, manifest, lockfile, options) {
     const installDir = manifest.installDir ?? '.agents/skills';
     const linkTargets = manifest.linkTargets ?? [];
-    for (const skillName of Object.keys(lockfile.skills))for (const linkTarget of linkTargets)await linkSkill(rootDir, installDir, linkTarget, skillName);
+    for (const skillName of Object.keys(lockfile.skills)){
+        for (const linkTarget of linkTargets)await linkSkill(rootDir, installDir, linkTarget, skillName);
+        options?.onProgress?.({
+            type: 'installed',
+            skillName
+        });
+    }
     return {
         status: 'linked',
         linked: Object.keys(lockfile.skills)
@@ -1116,9 +1512,19 @@ async function installSkills(rootDir, options) {
         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);
+        for (const skillName of Object.keys(lockfile.skills))options?.onProgress?.({
+            type: 'resolved',
+            skillName
+        });
+    } else lockfile = await syncSkillsLock(rootDir, manifest, currentLock, {
+        onProgress: options?.onProgress
+    });
+    await fetchSkillsFromLock(rootDir, manifest, lockfile, {
+        onProgress: options?.onProgress
+    });
+    await linkSkillsFromLock(rootDir, manifest, lockfile, {
+        onProgress: options?.onProgress
+    });
     if (!options?.frozenLockfile) await writeSkillsLock(rootDir, lockfile);
     return {
         status: 'installed',
@@ -1180,7 +1586,9 @@ async function addCommand(options) {
             const skillPath = found?.path ?? `/${skill}`;
             const gitSpecifier = buildGitHubSpecifier(owner, repo, skillPath);
             const result = await addSingleSkill(cwd, gitSpecifier);
+            spinner.start('Installing skills...');
             await installSkills(cwd);
+            spinner.stop('Installed skills');
             __rspack_external__clack_prompts_3cae1695.outro(`Added ${picocolors.cyan(result.skillName)}`);
             return result;
         }
@@ -1204,12 +1612,17 @@ async function addCommand(options) {
             results.push(result);
             __rspack_external__clack_prompts_3cae1695.log.success(`Added ${picocolors.cyan(result.skillName)}`);
         }
+        spinner.start('Installing skills...');
         await installSkills(cwd);
+        spinner.stop('Installed skills');
         __rspack_external__clack_prompts_3cae1695.outro('Done');
         return 1 === results.length ? results[0] : results;
     }
     const result = await addSingleSkill(cwd, specifier);
+    const spinner = __rspack_external__clack_prompts_3cae1695.spinner();
+    spinner.start('Installing skills...');
     await installSkills(cwd);
+    spinner.stop('Installed skills');
     return result;
 }
 async function assertManifestMissing(cwd) {
@@ -1249,6 +1662,117 @@ async function initCommand(options, promptInit = promptInitManifestOptions) {
     await writeSkillsManifest(options.cwd, manifest);
     return manifest;
 }
+const phaseLabelMap = {
+    resolving: 'Resolving',
+    fetching: 'Fetching',
+    linking: 'Linking',
+    finalizing: 'Finalizing',
+    done: 'Done'
+};
+function clampCount(value, total) {
+    if (value < 0) return 0;
+    if (value > total) return total;
+    return value;
+}
+function calculatePercent(snapshot) {
+    if ('done' === snapshot.phase) return 100;
+    if (0 === snapshot.total) return 0;
+    const maxSteps = 3 * snapshot.total;
+    const completed = snapshot.resolved + snapshot.added + snapshot.installed;
+    return Math.floor(completed / maxSteps * 100);
+}
+function formatSummary(snapshot) {
+    const total = snapshot.total;
+    return `resolved ${snapshot.resolved}/${total}, added ${snapshot.added}/${total}, installed ${snapshot.installed}/${total}`;
+}
+function formatTTYLine(snapshot) {
+    const percent = calculatePercent(snapshot);
+    const progress = Math.round(percent / 100 * 20);
+    const filled = '='.repeat(progress);
+    const empty = '-'.repeat(Math.max(0, 20 - progress));
+    const phase = phaseLabelMap[snapshot.phase];
+    const summary = formatSummary(snapshot);
+    const skill = snapshot.currentSkill ? `, skill: ${snapshot.currentSkill}` : '';
+    return `[${filled}${empty}] ${percent}% ${phase} ${summary}${skill}`;
+}
+function createInstallProgressReporter(options = {}) {
+    const write = options.write ?? ((text)=>process.stderr.write(text));
+    const info = options.info ?? ((text)=>console.info(text));
+    const useTTY = options.isTTY ?? true === process.stderr.isTTY;
+    const snapshot = {
+        total: 0,
+        resolved: 0,
+        added: 0,
+        installed: 0,
+        phase: 'resolving'
+    };
+    let renderedTTY = false;
+    let lastLineLength = 0;
+    function renderTTY() {
+        const line = formatTTYLine(snapshot);
+        const clearPadding = lastLineLength > line.length ? ' '.repeat(lastLineLength - line.length) : '';
+        write(`\r${line}${clearPadding}`);
+        lastLineLength = line.length;
+        renderedTTY = true;
+    }
+    function logStage(phase) {
+        info(`spm install: ${phaseLabelMap[phase].toLowerCase()}...`);
+    }
+    function render() {
+        if (useTTY) return void renderTTY();
+    }
+    return {
+        start (total) {
+            snapshot.total = Math.max(0, total);
+            snapshot.resolved = 0;
+            snapshot.added = 0;
+            snapshot.installed = 0;
+            snapshot.phase = 'resolving';
+            snapshot.currentSkill = void 0;
+            if (useTTY) renderTTY();
+            else {
+                const noun = 1 === snapshot.total ? 'skill' : 'skills';
+                info(`spm install: starting (${snapshot.total} ${noun})`);
+                logStage('resolving');
+            }
+        },
+        setPhase (phase) {
+            snapshot.phase = phase;
+            snapshot.currentSkill = void 0;
+            render();
+            if (!useTTY && 'finalizing' !== phase) logStage(phase);
+        },
+        onProgress (event) {
+            snapshot.currentSkill = event.skillName;
+            switch(event.type){
+                case 'resolved':
+                    snapshot.resolved = clampCount(snapshot.resolved + 1, snapshot.total);
+                    break;
+                case 'added':
+                    snapshot.added = clampCount(snapshot.added + 1, snapshot.total);
+                    break;
+                case 'installed':
+                    snapshot.installed = clampCount(snapshot.installed + 1, snapshot.total);
+                    break;
+                default:
+            }
+            render();
+        },
+        complete () {
+            snapshot.phase = 'done';
+            snapshot.currentSkill = void 0;
+            const summary = formatSummary(snapshot);
+            if (useTTY) {
+                renderTTY();
+                write('\n');
+            }
+            info(`spm install: ${summary}`);
+        },
+        fail () {
+            if (useTTY && renderedTTY) write('\n');
+        }
+    };
+}
 async function installCommand(options) {
     const manifest = await readSkillsManifest(options.cwd);
     if (!manifest) throw new ManifestError({
@@ -1257,32 +1781,67 @@ async function installCommand(options) {
         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.'
+    const totalSkills = Object.keys(manifest.skills).length;
+    const reporter = createInstallProgressReporter();
+    const onProgress = (event)=>reporter.onProgress(event);
+    let started = false;
+    try {
+        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.'
+            });
+            reporter.start(totalSkills);
+            started = true;
+            for (const skillName of Object.keys(currentLock.skills))onProgress({
+                type: 'resolved',
+                skillName
+            });
+            reporter.setPhase('fetching');
+            await fetchSkillsFromLock(options.cwd, manifest, currentLock, {
+                onProgress
+            });
+            reporter.setPhase('linking');
+            await linkSkillsFromLock(options.cwd, manifest, currentLock, {
+                onProgress
+            });
+            reporter.setPhase('finalizing');
+            reporter.complete();
+            return {
+                status: 'installed',
+                installed: Object.keys(currentLock.skills)
+            };
+        }
+        reporter.start(totalSkills);
+        started = true;
+        const lockfile = await syncSkillsLock(options.cwd, manifest, currentLock, {
+            onProgress
+        });
+        reporter.setPhase('fetching');
+        await fetchSkillsFromLock(options.cwd, manifest, lockfile, {
+            onProgress
         });
-        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.'
+        reporter.setPhase('linking');
+        await linkSkillsFromLock(options.cwd, manifest, lockfile, {
+            onProgress
         });
-        await fetchSkillsFromLock(options.cwd, manifest, currentLock);
-        await linkSkillsFromLock(options.cwd, manifest, currentLock);
+        reporter.setPhase('finalizing');
+        await writeSkillsLock(options.cwd, lockfile);
+        reporter.complete();
         return {
             status: 'installed',
-            installed: Object.keys(currentLock.skills)
+            installed: Object.keys(lockfile.skills)
         };
+    } catch (error) {
+        if (started) reporter.fail();
+        throw error;
     }
-    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 {
@@ -1327,17 +1886,26 @@ async function updateCommand(options) {
     candidateLock.linkTargets = manifest.linkTargets ?? [];
     for (const skillName of targetSkills){
         const specifier = manifest.skills[skillName];
-        if (specifier.startsWith('file:')) {
-            result.skipped.push({
-                name: skillName,
-                reason: 'file-specifier'
-            });
-            continue;
-        }
         try {
+            const normalized = normalizeSpecifier(specifier);
+            if ('link' === normalized.type) {
+                result.skipped.push({
+                    name: skillName,
+                    reason: 'link-specifier'
+                });
+                continue;
+            }
             const { entry } = await resolveLockEntry(options.cwd, specifier);
             const previous = currentLock?.skills[skillName];
-            if (previous?.resolution.type === 'git' && 'git' === entry.resolution.type && previous.resolution.commit === entry.resolution.commit) {
+            if (previous?.resolution.type === 'git' && 'git' === entry.resolution.type && previous.specifier === entry.specifier && previous.resolution.url === entry.resolution.url && previous.resolution.commit === entry.resolution.commit && previous.resolution.path === entry.resolution.path) {
+                result.unchanged.push(skillName);
+                continue;
+            }
+            if (previous?.resolution.type === 'npm' && 'npm' === entry.resolution.type && previous.specifier === entry.specifier && previous.resolution.packageName === entry.resolution.packageName && previous.resolution.version === entry.resolution.version && previous.resolution.path === entry.resolution.path && previous.resolution.tarball === entry.resolution.tarball && previous.resolution.integrity === entry.resolution.integrity && previous.resolution.registry === entry.resolution.registry) {
+                result.unchanged.push(skillName);
+                continue;
+            }
+            if (previous?.resolution.type === 'file' && 'file' === entry.resolution.type && previous.specifier === entry.specifier && previous.digest === entry.digest) {
                 result.unchanged.push(skillName);
                 continue;
             }
@@ -1428,4 +1996,4 @@ async function runCli(argv, context = {}) {
         throw error;
     }
 }
-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 };
+export { FileSystemError, GitError, ManifestError, NetworkError, ParseError, SkillError, SpmError, addCommand, cloneAndDiscover, codes_ErrorCode as ErrorCode, convertNodeError, createInstallProgressReporter, 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.3.0",
+  "version": "0.4.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -21,6 +21,8 @@
     "@clack/prompts": "^1.1.0",
     "cac": "^7.0.0",
     "picocolors": "^1.1.1",
+    "semver": "^7.7.2",
+    "tar": "^7.4.3",
     "yaml": "^2.8.1"
   },
   "devDependencies": {