@foxian/esl 0.1.0

package/dist/commands/install.js

@@ -0,0 +1,435 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { promisify } from 'node:util';
+import { addLockEntry, addSkillDependency, loadConfig, loadInstallManifest, loadSkillsJson, resolveProjectStorePaths, syncToolLinks, SUPPORTED_TOOLS, copySkillDirectory, createMinimalSkillManifest, evaluateCompatibility, fileExists, highestStableVersion, isBuiltinIdentity, loadBuiltinPackageOrThrow, BUILTIN_SPECIFIER_PREFIX, recordInstalledSkill, removeDirectory, resolveLocalStorePaths, resolveToolName, skillSourceRelativeDir, validateReleaseManifest, validateSkillDirectory, validateSkillMd, preparePublishedSkillPackage } from '../vendor/core/index.js';
+import { requireOkResponse } from '../api-error.js';
+import { installTargetDir, gitAuthHeaderConfig, fetchWithTimeout, requireConfigured, requireFreshToken, resolveNetworkConfig, projectSkillsDir, publishedInstallTargetDir, publishedProjectSkillsDir } from './network-options.js';
+import { executeInfo } from './info.js';
+import { notify } from '../output.js';
+import { resolveBuiltinDir } from '../builtin-dir.js';
+const defaultExecFileAsync = promisify(execFile);
+function isLocalPath(nameOrPath) {
+    return nameOrPath.startsWith('.') || nameOrPath.startsWith('/') || nameOrPath.startsWith('\\') || path.isAbsolute(nameOrPath);
+}
+/**
+ * A deprecated release stays installable — it just carries a warning for whoever
+ * lands on it. Silence would hide that a safer release exists.
+ */
+function warnIfDeprecated(name, version, message) {
+    if (!message) {
+        return;
+    }
+    console.warn(`Warning: ${name}@${version} is deprecated — ${message}`);
+}
+/**
+ * The version to record for a skill installed from a bare source directory: the
+ * Release Manifest's version when the source carries one, and 0.1.0 for a draft
+ * directory that has no manifest yet.
+ */
+async function readSourceVersion(directory) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(path.join(directory, 'release.json'), 'utf8'));
+        const validation = validateReleaseManifest(parsed);
+        if (validation.success) {
+            return validation.data.version;
+        }
+    }
+    catch {
+        // No manifest, or an unreadable one: fall back to the draft version.
+    }
+    return '0.1.0';
+}
+async function installFromLocalPath(sourcePath, projectRoot, options) {
+    const resolved = path.resolve(sourcePath);
+    const skillJsonPath = path.join(resolved, 'skill.json');
+    let identity;
+    let version;
+    let needsGeneratedSkillJson = false;
+    let generatedDescription = '';
+    const packageValidation = await validateSkillDirectory(resolved);
+    if (packageValidation.success) {
+        identity = packageValidation.data.skillJson.name;
+        version = packageValidation.data.skillJson.version;
+    }
+    else {
+        if (await fileExists(skillJsonPath)) {
+            throw new Error(`Invalid skill package at ${resolved}: ${packageValidation.errors.join(', ')}`);
+        }
+        if (!(await fileExists(path.join(resolved, 'SKILL.md')))) {
+            throw new Error(`Invalid skill package at ${resolved}: ${packageValidation.errors.join(', ')}`);
+        }
+        const skillMdValidation = validateSkillMd(await fs.readFile(path.join(resolved, 'SKILL.md'), 'utf8'));
+        if (!skillMdValidation.success) {
+            throw new Error(`Invalid skill package at ${resolved}: ${skillMdValidation.errors.join(', ')}`);
+        }
+        identity = `@local/${skillMdValidation.data.name}`;
+        version = await readSourceVersion(resolved);
+        needsGeneratedSkillJson = true;
+        generatedDescription = skillMdValidation.data.description;
+    }
+    const storeRoot = options.global
+        ? resolveLocalStorePaths(options).root
+        : resolveProjectStorePaths(projectRoot).root;
+    const dependencyRoot = options.global ? storeRoot : projectRoot;
+    const targetDir = options.global ? installTargetDir(identity, options) : projectSkillsDir(projectRoot, identity);
+    await copySkillDirectory(resolved, targetDir);
+    if (needsGeneratedSkillJson) {
+        const author = process.env.USER ?? process.env.USERNAME ?? 'anonymous';
+        const skillJson = {
+            ...createMinimalSkillManifest({
+                name: identity,
+                description: generatedDescription,
+                author
+            }),
+            version
+        };
+        await fs.writeFile(path.join(targetDir, 'skill.json'), `${JSON.stringify(skillJson, null, 2)}\n`, 'utf8');
+    }
+    const specifier = `file:${resolved}`;
+    const lockEntry = {
+        version,
+        resolved: specifier,
+        integrity: '',
+        source: 'local'
+    };
+    await addSkillDependency(dependencyRoot, identity, specifier);
+    await addLockEntry(dependencyRoot, identity, lockEntry);
+    await recordInstalledSkill(storeRoot, identity, lockEntry, specifier);
+    return targetDir;
+}
+async function installFromBuiltin(name, projectRoot, options) {
+    const builtinDir = options.builtinDir ?? resolveBuiltinDir();
+    const builtin = await loadBuiltinPackageOrThrow(builtinDir, name);
+    const storeRoot = options.global
+        ? resolveLocalStorePaths(options).root
+        : resolveProjectStorePaths(projectRoot).root;
+    const dependencyRoot = options.global ? storeRoot : projectRoot;
+    const targetDir = options.global
+        ? installTargetDir(name, options)
+        : projectSkillsDir(projectRoot, name);
+    await copySkillDirectory(builtin.directory, targetDir);
+    const specifier = `${BUILTIN_SPECIFIER_PREFIX}${builtin.shortName}`;
+    const lockEntry = {
+        identity: name,
+        version: builtin.version,
+        resolved: specifier,
+        integrity: builtin.checksum,
+        source: 'builtin'
+    };
+    await addSkillDependency(dependencyRoot, name, specifier);
+    await addLockEntry(dependencyRoot, name, lockEntry);
+    await recordInstalledSkill(storeRoot, name, lockEntry, specifier);
+    return targetDir;
+}
+async function installFromServer(name, projectRoot, options) {
+    const execFileAsync = options.execFileAsync ?? defaultExecFileAsync;
+    const authToken = await requireFreshToken(options);
+    const info = await executeInfo(name, options);
+    const authHeader = gitAuthHeaderConfig(authToken);
+    const version = options.version ?? highestStableVersion(info.versions ?? []);
+    if (!version) {
+        throw new Error(`Skill ${name} has no published Skill Release; use esl source for source access`);
+    }
+    const requestedRelease = info.releases?.find((release) => release.version === version);
+    warnIfDeprecated(name, version, requestedRelease?.deprecatedMessage);
+    const requestedPackageUrl = requestedRelease?.packageUrl ?? info.packageUrl;
+    if (requestedPackageUrl) {
+        return installPublishedPackage(name, version, requestedPackageUrl, projectRoot, options, authToken);
+    }
+    const remoteUrl = requireConfigured(info.cloneUrl, 'cloneUrl');
+    if (options.global || !projectRoot) {
+        const globalRoot = resolveLocalStorePaths(options).root;
+        const targetDir = path.normalize(installTargetDir(name, options));
+        await removeDirectory(targetDir);
+        notify(`Cloning ${name}...`);
+        await execFileAsync('git', ['-c', authHeader, 'clone', remoteUrl, targetDir]);
+        await execFileAsync('git', ['checkout', version], { cwd: targetDir });
+        if (info.publishedPackage) {
+            await preparePublishedSkillPackage(targetDir, name);
+        }
+        const specifier = `^${version}`;
+        const lockEntry = {
+            version,
+            resolved: remoteUrl,
+            integrity: '',
+            source: 'registry'
+        };
+        await addSkillDependency(globalRoot, name, specifier);
+        await addLockEntry(globalRoot, name, lockEntry);
+        await recordInstalledSkill(globalRoot, name, lockEntry, specifier);
+        return targetDir;
+    }
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'esl-install-'));
+    try {
+        const cloneDir = path.join(tmpDir, 'repo');
+        notify(`Cloning ${name}...`);
+        await execFileAsync('git', ['-c', authHeader, 'clone', remoteUrl, cloneDir]);
+        if (version) {
+            await execFileAsync('git', ['checkout', version], { cwd: cloneDir });
+        }
+        const targetDir = projectSkillsDir(projectRoot, name);
+        await copySkillDirectory(cloneDir, targetDir);
+        if (info.publishedPackage) {
+            await preparePublishedSkillPackage(targetDir, name);
+        }
+        const specifier = `^${version}`;
+        const lockEntry = {
+            version,
+            resolved: remoteUrl,
+            integrity: '',
+            source: 'registry'
+        };
+        const storeRoot = resolveProjectStorePaths(projectRoot).root;
+        await addSkillDependency(projectRoot, name, specifier);
+        await addLockEntry(projectRoot, name, lockEntry);
+        await recordInstalledSkill(storeRoot, name, lockEntry, specifier);
+        return targetDir;
+    }
+    finally {
+        await removeDirectory(tmpDir);
+    }
+}
+async function installPublishedPackage(name, version, packageUrl, projectRoot, options, authToken) {
+    const fetchImpl = options.customFetch ?? fetch;
+    const execFileAsync = options.execFileAsync ?? defaultExecFileAsync;
+    const serverUrl = options.server ?? (await resolveNetworkConfig(options)).server;
+    const resolvedPackageUrl = packageUrl.startsWith('http') ? packageUrl : `${await serverUrl}${packageUrl}`;
+    const response = await fetchWithTimeout(fetchImpl, resolvedPackageUrl, {
+        headers: { Authorization: `token ${authToken}` }
+    });
+    if (!response.ok) {
+        await requireOkResponse(response, 'Failed to download Published Skill Package');
+    }
+    const packageBytes = Buffer.from(await response.arrayBuffer());
+    const integrity = `sha256-${crypto.createHash('sha256').update(packageBytes).digest('hex')}`;
+    const expectedIntegrity = path.basename(new URL(resolvedPackageUrl).pathname).replace(/\.json$/, '');
+    if (expectedIntegrity.startsWith('sha256-') && integrity !== expectedIntegrity) {
+        throw new Error(`Published Skill Package checksum does not match Registry metadata: expected ${expectedIntegrity}, got ${integrity}`);
+    }
+    const packageData = JSON.parse(packageBytes.toString('utf8'));
+    if (!options.ignoreCompatibility) {
+        const compatibility = await evaluateCompatibility(packageData.releaseManifest.compatibility ?? {}, { execFileAsync });
+        if (!compatibility.compatible) {
+            const reasons = [
+                ...compatibility.missingTools.map((tool) => `missing tool ${tool}`),
+                ...compatibility.unsupportedLanguages.map((language) => `unsupported language ${language}`)
+            ];
+            throw new Error(`Published Skill Package is incompatible: ${reasons.join(', ')}`);
+        }
+    }
+    const targetDir = options.global || !projectRoot
+        ? publishedInstallTargetDir(name, options)
+        : publishedProjectSkillsDir(projectRoot, name);
+    const stagingDir = `${targetDir}.staging-${process.pid}-${Date.now()}`;
+    await removeDirectory(stagingDir);
+    for (const [relativePath, content] of Object.entries(packageData.files ?? {})) {
+        const destination = path.join(stagingDir, relativePath);
+        await fs.mkdir(path.dirname(destination), { recursive: true });
+        await fs.writeFile(destination, content, 'utf8');
+    }
+    if (packageData.version !== version || packageData.name !== name) {
+        await removeDirectory(stagingDir);
+        throw new Error('Published Skill Package metadata does not match the requested Release');
+    }
+    const previousDir = `${targetDir}.previous-${process.pid}-${Date.now()}`;
+    try {
+        await fs.rename(targetDir, previousDir);
+    }
+    catch {
+        await removeDirectory(previousDir);
+    }
+    try {
+        await fs.rename(stagingDir, targetDir);
+    }
+    catch (error) {
+        await removeDirectory(stagingDir);
+        try {
+            await fs.rename(previousDir, targetDir);
+        }
+        catch {
+        }
+        throw error;
+    }
+    await removeDirectory(previousDir);
+    const storeRoot = options.global || !projectRoot
+        ? resolveLocalStorePaths(options).root
+        : resolveProjectStorePaths(projectRoot).root;
+    const dependencyRoot = options.global || !projectRoot ? storeRoot : projectRoot;
+    const specifier = `^${version}`;
+    const lockEntry = {
+        skillId: packageData.skillId,
+        identity: name,
+        version,
+        resolved: resolvedPackageUrl,
+        integrity,
+        source: 'registry'
+    };
+    await addSkillDependency(dependencyRoot, name, specifier);
+    await addLockEntry(dependencyRoot, name, lockEntry);
+    await recordInstalledSkill(storeRoot, name, lockEntry, specifier);
+    await installPublishedDependencies(packageData.dependencyLock ?? {}, dependencyRoot, storeRoot, options, authToken, new Set([name]));
+    return targetDir;
+}
+async function installPublishedDependencies(dependencyLock, dependencyRoot, storeRoot, options, authToken, seen) {
+    for (const [dependencyName, dependency] of Object.entries(dependencyLock)) {
+        if (seen.has(dependencyName))
+            continue;
+        seen.add(dependencyName);
+        const dependencyInfo = await executeInfo(dependencyName, options);
+        const dependencyPackageUrl = dependencyInfo.releases?.find((release) => release.version === dependency.version)?.packageUrl ?? dependencyInfo.packageUrl;
+        if (!dependencyPackageUrl) {
+            throw new Error(`Dependency ${dependencyName} has no published Skill Release`);
+        }
+        const fetchImpl = options.customFetch ?? fetch;
+        const serverUrl = options.server ?? (await resolveNetworkConfig(options)).server;
+        const resolvedPackageUrl = dependencyPackageUrl.startsWith('http')
+            ? dependencyPackageUrl
+            : `${serverUrl}${dependencyPackageUrl}`;
+        const response = await fetchWithTimeout(fetchImpl, resolvedPackageUrl, {
+            headers: { Authorization: `token ${authToken}` }
+        });
+        if (!response.ok) {
+            await requireOkResponse(response, 'Failed to download dependency Published Skill Package');
+        }
+        const packageBytes = Buffer.from(await response.arrayBuffer());
+        const integrity = `sha256-${crypto.createHash('sha256').update(packageBytes).digest('hex')}`;
+        const expectedIntegrity = path.basename(new URL(resolvedPackageUrl).pathname).replace(/\.json$/, '');
+        if (expectedIntegrity.startsWith('sha256-') && integrity !== expectedIntegrity) {
+            throw new Error(`Dependency Published Skill Package checksum does not match Registry metadata: expected ${expectedIntegrity}, got ${integrity}`);
+        }
+        const packageData = JSON.parse(packageBytes.toString('utf8'));
+        if (!options.ignoreCompatibility) {
+            const compatibility = await evaluateCompatibility(packageData.releaseManifest.compatibility ?? {}, {
+                execFileAsync: options.execFileAsync
+            });
+            if (!compatibility.compatible) {
+                throw new Error(`Dependency ${dependencyName} is incompatible: ${[
+                    ...compatibility.missingTools.map((tool) => `missing tool ${tool}`),
+                    ...compatibility.unsupportedLanguages.map((language) => `unsupported language ${language}`)
+                ].join(', ')}`);
+            }
+        }
+        const dependencyTargetDir = path.join(storeRoot, skillSourceRelativeDir(dependencyName));
+        const dependencyStagingDir = `${dependencyTargetDir}.staging-${process.pid}-${Date.now()}`;
+        await removeDirectory(dependencyStagingDir);
+        for (const [relativePath, content] of Object.entries(packageData.files ?? {})) {
+            const destination = path.join(dependencyStagingDir, relativePath);
+            await fs.mkdir(path.dirname(destination), { recursive: true });
+            await fs.writeFile(destination, content, 'utf8');
+        }
+        const dependencyPreviousDir = `${dependencyTargetDir}.previous-${process.pid}-${Date.now()}`;
+        try {
+            await fs.rename(dependencyTargetDir, dependencyPreviousDir);
+        }
+        catch {
+            await removeDirectory(dependencyPreviousDir);
+        }
+        try {
+            await fs.rename(dependencyStagingDir, dependencyTargetDir);
+        }
+        catch (error) {
+            await removeDirectory(dependencyStagingDir);
+            try {
+                await fs.rename(dependencyPreviousDir, dependencyTargetDir);
+            }
+            catch {
+            }
+            throw error;
+        }
+        await removeDirectory(dependencyPreviousDir);
+        const dependencySpecifier = `^${dependency.version}`;
+        const dependencyLockEntry = {
+            skillId: dependency.skillId,
+            identity: dependencyName,
+            version: dependency.version,
+            resolved: resolvedPackageUrl,
+            integrity,
+            source: 'registry'
+        };
+        await addLockEntry(dependencyRoot, dependencyName, dependencyLockEntry);
+        await recordInstalledSkill(storeRoot, dependencyName, dependencyLockEntry, dependencySpecifier);
+        await installPublishedDependencies(dependency.dependencyLock ?? {}, dependencyRoot, storeRoot, options, authToken, seen);
+    }
+}
+export async function resolveDefaultInstallTools(projectRoot, options) {
+    const dependencyRoot = options.global
+        ? resolveLocalStorePaths(options).root
+        : projectRoot;
+    const skillsJson = await loadSkillsJson(dependencyRoot);
+    if (skillsJson.tools && skillsJson.tools.length > 0) {
+        return skillsJson.tools.map((tool) => {
+            const resolved = resolveToolName(tool);
+            if (resolved === undefined) {
+                throw new Error(`Unknown configured tool: ${tool}. Supported tools: ${SUPPORTED_TOOLS.join(', ')}`);
+            }
+            return resolved;
+        });
+    }
+    const config = await loadConfig(options);
+    return config.tools.map((tool) => {
+        const resolved = resolveToolName(tool);
+        if (resolved === undefined) {
+            throw new Error(`Unknown configured tool: ${tool}. Supported tools: ${SUPPORTED_TOOLS.join(', ')}`);
+        }
+        return resolved;
+    });
+}
+export async function executeInstall(nameOrPath, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const failedLinks = [];
+    const storeRoot = options.global
+        ? resolveLocalStorePaths(options).root
+        : resolveProjectStorePaths(projectRoot).root;
+    const beforeManifest = await loadInstallManifest(storeRoot);
+    const targetDir = isBuiltinIdentity(nameOrPath)
+        ? await installFromBuiltin(nameOrPath, projectRoot, options)
+        : isLocalPath(nameOrPath)
+            ? await installFromLocalPath(nameOrPath, projectRoot, options)
+            : await installFromServer(nameOrPath, options.global ? null : projectRoot, options);
+    if (!options.noAdapt) {
+        const tools = options.tools ?? await resolveDefaultInstallTools(projectRoot, options);
+        if (tools.length > 0) {
+            const installManifest = await loadInstallManifest(storeRoot);
+            const targetPath = path.resolve(targetDir);
+            const installedIdentities = new Set();
+            for (const [identity, entry] of Object.entries(installManifest.skills)) {
+                const previouslyInstalled = beforeManifest.skills[identity];
+                if (path.resolve(storeRoot, entry.sourceDir) === targetPath ||
+                    !previouslyInstalled ||
+                    JSON.stringify(previouslyInstalled) !== JSON.stringify(entry)) {
+                    installedIdentities.add(identity);
+                }
+            }
+            const results = await syncToolLinks({
+                storeRoot,
+                level: options.global ? 'global' : 'project',
+                tools,
+                identities: [...installedIdentities],
+                projectRoot,
+                homeDir: options.homeDir,
+                force: options.force
+            });
+            failedLinks.push(...results
+                .filter((result) => result.status === 'conflict' || result.status === 'failed')
+                .map((result) => {
+                const detail = result.status === 'conflict'
+                    ? `: ${result.error ?? 'conflict'}`
+                    : result.error
+                        ? `: ${result.error}`
+                        : '';
+                return `${result.tool} (${result.targetDir})${detail}`;
+            }));
+        }
+    }
+    if (!options.global) {
+        const { ensureGitignore } = await import('./uninstall.js');
+        await ensureGitignore(projectRoot);
+    }
+    if (failedLinks.length > 0) {
+        throw new Error(`Tool link failed; existing content was not overwritten: ${failedLinks.join(', ')}`);
+    }
+    return targetDir;
+}

package/dist/commands/link.d.ts

@@ -0,0 +1,11 @@
+import { type ToolName } from '@esl/core';
+import { type NetworkCommandOptions } from './network-options.js';
+export interface LinkOptions extends NetworkCommandOptions {
+    identity?: string;
+    global?: boolean;
+    tools?: ToolName[];
+    noTools?: boolean;
+    force?: boolean;
+    projectRoot?: string;
+}
+export declare function executeLink(sourcePath: string, options?: LinkOptions): Promise<string>;

package/dist/commands/link.js

@@ -0,0 +1,170 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { addLockEntry, addSkillDependency, fileExists, linkSkillDirectory, loadInstallManifest, loadSkillsJson, loadSkillsLock, parseSkillName, resolveLocalStorePaths, resolveProjectStorePaths, saveInstallManifest, skillSourceRelativeDir, syncToolLinks, validateReleaseManifest, validateSkillMd } from '../vendor/core/index.js';
+import { installTargetDir, projectSkillsDir } from './network-options.js';
+import { resolveDefaultInstallTools } from './install.js';
+async function readSourceVersion(directory) {
+    const releasePath = path.join(directory, 'release.json');
+    if (!(await fileExists(releasePath))) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(releasePath, 'utf8'));
+    }
+    catch {
+        throw new Error(`Invalid release.json at ${releasePath}: file must contain valid JSON`);
+    }
+    const validation = validateReleaseManifest(parsed);
+    if (!validation.success) {
+        throw new Error(`Invalid release.json at ${releasePath}: ${validation.errors.join(', ')}`);
+    }
+    return validation.data.version;
+}
+function completeBareIdentity(shortName, requestedIdentity) {
+    if (!requestedIdentity) {
+        return `@local/${shortName}`;
+    }
+    if (requestedIdentity.startsWith('@') && !requestedIdentity.includes('/')) {
+        return `@${requestedIdentity.slice(1)}/${shortName}`;
+    }
+    if (requestedIdentity.startsWith('@')) {
+        const { scope, skillName } = parseSkillName(requestedIdentity);
+        if (skillName !== shortName) {
+            throw new Error(`--identity short name must match the skill source: expected ${skillName}, got ${shortName}`);
+        }
+        return `@${scope}/${skillName}`;
+    }
+    throw new Error('--identity must be a namespace (@namespace) or a full skill identity (@namespace/skill-name)');
+}
+async function resolveSourceSkill(sourceDir, requestedIdentity) {
+    const skillMdPath = path.join(sourceDir, 'SKILL.md');
+    if (!(await fileExists(skillMdPath))) {
+        throw new Error(`Skill source requires SKILL.md: ${sourceDir}`);
+    }
+    const skillMd = validateSkillMd(await fs.readFile(skillMdPath, 'utf8'));
+    if (!skillMd.success) {
+        throw new Error(`Invalid SKILL.md at ${skillMdPath}: ${skillMd.errors.join(', ')}`);
+    }
+    const version = await readSourceVersion(sourceDir);
+    const shortName = skillMd.data.name;
+    let releaseIdentity = null;
+    if (version !== null) {
+        const release = validateReleaseManifest(JSON.parse(await fs.readFile(path.join(sourceDir, 'release.json'), 'utf8')));
+        if (!release.success) {
+            throw new Error(`Invalid release.json: ${release.errors.join(', ')}`);
+        }
+        releaseIdentity = release.data.name;
+    }
+    if (releaseIdentity?.includes('/')) {
+        if (requestedIdentity && requestedIdentity !== releaseIdentity) {
+            throw new Error(`release.json declares ${releaseIdentity}; --identity cannot rename a linked skill`);
+        }
+        parseSkillName(releaseIdentity);
+        return { identity: releaseIdentity, version: version ?? '0.1.0', shortName };
+    }
+    const sourceShortName = releaseIdentity ?? shortName;
+    if (sourceShortName !== shortName) {
+        throw new Error(`release.json short name must match SKILL.md: expected ${shortName}, got ${sourceShortName}`);
+    }
+    return {
+        identity: completeBareIdentity(shortName, requestedIdentity),
+        version: version ?? '0.1.0',
+        shortName
+    };
+}
+export async function executeLink(sourcePath, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const resolved = path.resolve(sourcePath);
+    const source = await resolveSourceSkill(resolved, options.identity);
+    const identity = source.identity;
+    const storeRoot = options.global
+        ? resolveLocalStorePaths(options).root
+        : resolveProjectStorePaths(projectRoot).root;
+    const dependencyRoot = options.global ? storeRoot : projectRoot;
+    const targetDir = options.global ? installTargetDir(identity, options) : projectSkillsDir(projectRoot, identity);
+    const [installManifest, skillsJson, lockJson] = await Promise.all([
+        loadInstallManifest(storeRoot),
+        loadSkillsJson(dependencyRoot),
+        loadSkillsLock(dependencyRoot)
+    ]);
+    const previous = {
+        manifestEntry: installManifest.skills[identity],
+        dependencySpecifier: skillsJson.skills[identity],
+        lockEntry: lockJson.skills[identity]
+    };
+    await linkSkillDirectory({
+        identity,
+        sourceDir: resolved,
+        storeRoot,
+        force: options.force,
+        previous
+    });
+    const specifier = `link:${resolved}`;
+    const lockEntry = {
+        identity,
+        version: source.version,
+        resolved,
+        integrity: '',
+        source: 'link'
+    };
+    await addSkillDependency(dependencyRoot, identity, specifier);
+    await addLockEntry(dependencyRoot, identity, lockEntry);
+    await recordLinkInstallState(storeRoot, identity, lockEntry, specifier);
+    await finishLink(identity, projectRoot, storeRoot, targetDir, options);
+    return targetDir;
+}
+async function recordLinkInstallState(storeRoot, identity, lockEntry, specifier) {
+    const installManifest = await loadInstallManifest(storeRoot);
+    const current = installManifest.skills[identity];
+    installManifest.skills[identity] = {
+        identity,
+        version: lockEntry.version,
+        resolved: lockEntry.resolved,
+        integrity: lockEntry.integrity,
+        source: 'link',
+        specifier,
+        sourceDir: current?.sourceDir ?? skillSourceRelativeDir(identity),
+        installedAt: current?.installedAt ?? new Date().toISOString()
+    };
+    await saveInstallManifest(storeRoot, installManifest);
+}
+async function syncSelectedTools(identity, projectRoot, storeRoot, options) {
+    if (options.noTools) {
+        return;
+    }
+    const tools = options.tools ?? await resolveDefaultInstallTools(projectRoot, options);
+    if (tools.length === 0) {
+        return;
+    }
+    const results = await syncToolLinks({
+        storeRoot,
+        level: options.global ? 'global' : 'project',
+        tools,
+        identities: [identity],
+        projectRoot,
+        homeDir: options.homeDir,
+        force: options.force
+    });
+    const failedLinks = results
+        .filter((result) => result.status === 'conflict' || result.status === 'failed')
+        .map((result) => {
+        const detail = result.status === 'conflict'
+            ? `: ${result.error ?? 'conflict'}`
+            : result.error
+                ? `: ${result.error}`
+                : '';
+        return `${result.tool} (${result.targetDir})${detail}`;
+    });
+    if (failedLinks.length > 0) {
+        throw new Error(`Tool link failed; existing content was not overwritten: ${failedLinks.join(', ')}`);
+    }
+}
+async function finishLink(identity, projectRoot, storeRoot, targetDir, options) {
+    await syncSelectedTools(identity, projectRoot, storeRoot, options);
+    if (!options.global) {
+        const { ensureGitignore } = await import('./uninstall.js');
+        await ensureGitignore(projectRoot);
+    }
+    return targetDir;
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,6 @@
+import { type LocalStoreOptions, type SkillListEntry } from '@esl/core';
+export interface ListOptions extends LocalStoreOptions {
+    global?: boolean;
+    json?: boolean;
+}
+export declare function executeList(options?: ListOptions): Promise<SkillListEntry[]>;

package/dist/commands/list.js

@@ -0,0 +1,7 @@
+import { listSkills, resolveLocalStorePaths, resolveProjectStorePaths } from '../vendor/core/index.js';
+export async function executeList(options = {}) {
+    const storeRoot = options.global
+        ? resolveLocalStorePaths(options).root
+        : resolveProjectStorePaths(process.cwd()).root;
+    return listSkills(storeRoot);
+}

package/dist/commands/login.d.ts

@@ -0,0 +1,20 @@
+import { type LocalStoreOptions, type OrganizationMembership } from '@esl/core';
+export interface LoginOptions extends LocalStoreOptions {
+    server?: string;
+    username?: string;
+    passwordFile?: string;
+    tokenFile?: string;
+    locale?: string | null;
+    noInput?: boolean;
+    readInput?: () => Promise<string>;
+    readServer?: () => Promise<string>;
+    readUsername?: (prompt: string) => Promise<string>;
+    customFetch?: typeof fetch;
+}
+export interface LoginResult {
+    token: string;
+    username: string;
+    organizations: OrganizationMembership[];
+    locale?: string | null;
+}
+export declare function executeLogin(options: LoginOptions): Promise<LoginResult>;