@foxian/esl 0.1.0

package/dist/commands/tools.js

@@ -0,0 +1,73 @@
+import { listToolLinks, parseToolSelection, removeToolLinks, resolveToolName, resolveLocalStorePaths, resolveProjectStorePaths, SUPPORTED_TOOLS } from '../vendor/core/index.js';
+function storeRootFor(options) {
+    if (options.global) {
+        return resolveLocalStorePaths(options).root;
+    }
+    return resolveProjectStorePaths(options.projectRoot ?? process.cwd()).root;
+}
+function parseCommaList(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+export async function executeToolsList(options = {}) {
+    const storeRoot = storeRootFor(options);
+    const entries = await listToolLinks({
+        storeRoot,
+        level: options.global ? 'global' : 'project',
+        projectRoot: options.projectRoot ?? process.cwd(),
+        homeDir: options.homeDir
+    });
+    const tools = parseCommaList(options.tool).map((tool) => resolveToolName(tool) ?? tool.toLowerCase());
+    const skills = parseCommaList(options.skill).map((skill) => skill.toLowerCase());
+    const statuses = parseCommaList(options.status).map((status) => status.toLowerCase());
+    return entries.filter((entry) => {
+        if (tools.length > 0 && !tools.includes(entry.tool)) {
+            return false;
+        }
+        if (skills.length > 0 && !skills.includes(entry.identity.toLowerCase())) {
+            return false;
+        }
+        if (options.managed === true && !entry.managed) {
+            return false;
+        }
+        if (options.unmanaged === true && entry.managed) {
+            return false;
+        }
+        if (statuses.length > 0 && !statuses.includes(entry.status)) {
+            return false;
+        }
+        return true;
+    });
+}
+export async function executeToolsRemove(skillName, options) {
+    if (options.tools.length === 0) {
+        throw new Error(`No tools selected. Supported tools: ${SUPPORTED_TOOLS.join(', ')}`);
+    }
+    const storeRoot = storeRootFor(options);
+    return removeToolLinks({
+        storeRoot,
+        identity: skillName,
+        tools: options.tools,
+        level: options.global ? 'global' : 'project'
+    });
+}
+export function parseToolsOption(value) {
+    if (!value) {
+        return [];
+    }
+    return parseToolSelection(value);
+}
+export function formatToolsList(entries) {
+    if (entries.length === 0) {
+        return ['No matching skill links.'];
+    }
+    return entries.map((entry) => {
+        const target = entry.targetDir ? ` -> ${entry.targetDir}` : '';
+        return `${entry.tool.padEnd(10)} ${entry.identity.padEnd(32)} ${entry.level.padEnd(7)} ${entry.status.padEnd(11)} ${entry.managed ? 'managed' : 'unmanaged'}${target}`;
+    });
+}

package/dist/commands/uninstall.d.ts

@@ -0,0 +1,19 @@
+import { type LocalStoreOptions, type ToolName } from '@esl/core';
+export interface UninstallOptions extends LocalStoreOptions {
+    projectRoot?: string;
+    global?: boolean;
+    noAdapt?: boolean;
+    force?: boolean;
+}
+export interface UninstallResult {
+    removedLinks: Array<{
+        identity: string;
+        tool: ToolName;
+        targetDir: string;
+        status: 'removed' | 'missing' | 'conflict';
+    }>;
+    sourceRemoved: boolean;
+    sourcePath?: string;
+}
+export declare function executeUninstall(name: string, options?: UninstallOptions): Promise<UninstallResult>;
+export declare function ensureGitignore(projectRoot: string): Promise<void>;

package/dist/commands/uninstall.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadInstallManifest, removeDirectory, removeInstalledSkill, removeLinkedSkillDirectory, removeLockEntry, removeSkillDependency, removeToolLinks, resolveLocalStorePaths, resolveProjectStorePaths, SUPPORTED_TOOLS } from '../vendor/core/index.js';
+import { installTargetDir, projectSkillsDir } from './network-options.js';
+function throwIfToolLinkConflicts(removedLinks) {
+    const conflicts = removedLinks.filter((result) => result.status === 'conflict');
+    if (conflicts.length > 0) {
+        throw new Error(`Tool link conflict; content was not removed: ${conflicts
+            .map((result) => `${result.tool} (${result.targetDir})`)
+            .join(', ')}`);
+    }
+}
+export async function executeUninstall(name, options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    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);
+    const installManifest = await loadInstallManifest(storeRoot);
+    const entry = installManifest.skills[name];
+    if (!entry) {
+        throw new Error(`Skill ${name} is not installed by ESL`);
+    }
+    const removedLinks = await removeToolLinks({
+        storeRoot,
+        identity: name,
+        tools: [...SUPPORTED_TOOLS],
+        level: options.global ? 'global' : 'project'
+    });
+    throwIfToolLinkConflicts(removedLinks);
+    if (entry.source === 'link') {
+        await removeLinkedSkillDirectory(name, storeRoot);
+        await removeSkillDependency(dependencyRoot, name);
+        await removeLockEntry(dependencyRoot, name);
+        await removeInstalledSkill(storeRoot, name);
+        return {
+            removedLinks,
+            sourceRemoved: false,
+            sourcePath: entry.resolved
+        };
+    }
+    await removeDirectory(targetDir);
+    await removeSkillDependency(dependencyRoot, name);
+    await removeLockEntry(dependencyRoot, name);
+    await removeInstalledSkill(storeRoot, name);
+    return {
+        removedLinks,
+        sourceRemoved: true
+    };
+}
+const ESL_GITIGNORE_MARKER = '# ESL managed (do not edit)';
+const ESL_GITIGNORE_ENTRIES = ['.eslib/'];
+export async function ensureGitignore(projectRoot) {
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    let content = '';
+    try {
+        content = await fs.readFile(gitignorePath, 'utf8');
+    }
+    catch {
+        // .gitignore does not exist yet.
+    }
+    const missingEntries = ESL_GITIGNORE_ENTRIES.filter((entry) => !content.includes(entry));
+    if (missingEntries.length === 0) {
+        return;
+    }
+    if (content.includes(ESL_GITIGNORE_MARKER)) {
+        await fs.writeFile(gitignorePath, `${content.trimEnd()}\n${missingEntries.join('\n')}\n`, 'utf8');
+        return;
+    }
+    const newBlock = `\n${ESL_GITIGNORE_MARKER}\n${missingEntries.join('\n')}\n`;
+    await fs.writeFile(gitignorePath, content.trimEnd() + newBlock, 'utf8');
+}

package/dist/commands/unlink.d.ts

@@ -0,0 +1,14 @@
+import { type LocalStoreOptions } from '@esl/core';
+export interface UnlinkOptions extends LocalStoreOptions {
+    projectRoot?: string;
+    global?: boolean;
+    /** 仅用于解析技能目录；默认 process.cwd()。不等于改变项目根语义之外的额外根 */
+    cwd?: string;
+}
+export interface UnlinkResult {
+    identity: string;
+    targetDir: string;
+    sourceDir: string;
+    restored: boolean;
+}
+export declare function executeUnlink(target: string | undefined, options?: UnlinkOptions): Promise<UnlinkResult>;

package/dist/commands/unlink.js

@@ -0,0 +1,108 @@
+import path from 'node:path';
+import { fileExists, loadInstallManifest, loadSkillsJson, loadSkillsLock, removeInstalledSkill, removeLockEntry, removeSkillDependency, removeToolLinks, resolveLocalStorePaths, resolveProjectStorePaths, saveInstallManifest, saveSkillsJson, saveSkillsLock, SUPPORTED_TOOLS, unlinkSkillDirectory } from '../vendor/core/index.js';
+import { installTargetDir, projectSkillsDir } from './network-options.js';
+import { resolveUnlinkIdentity } from './resolve-unlink-identity.js';
+function samePath(left, right) {
+    const a = path.resolve(left);
+    const b = path.resolve(right);
+    return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+export async function executeUnlink(target, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const resolved = await resolveUnlinkIdentity(target, { cwd });
+    const name = resolved.identity;
+    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);
+    const installManifest = await loadInstallManifest(storeRoot);
+    const entry = installManifest.skills[name];
+    if (resolved.fromDirectory && resolved.skillDir) {
+        const pathMatches = Object.entries(installManifest.skills)
+            .filter(([, skill]) => skill.source === 'link' &&
+            typeof skill.resolved === 'string' &&
+            samePath(skill.resolved, resolved.skillDir))
+            .map(([identity]) => identity);
+        const mismatched = pathMatches.filter((identity) => identity !== name);
+        if (mismatched.length > 0) {
+            throw new Error(`Skill directory ${resolved.skillDir} is linked as ${pathMatches.join(', ')}, not ${name}; pass the linked @scope/skill-name explicitly`);
+        }
+    }
+    if (!entry || entry.source !== 'link') {
+        let message = `Skill ${name} is not linked by ESL`;
+        if (!options.global && resolved.usedOmitOrDot && resolved.skillDir) {
+            const looksLikeSkillDir = (await fileExists(path.join(resolved.skillDir, 'release.json'))) ||
+                (await fileExists(path.join(resolved.skillDir, 'SKILL.md')));
+            if (looksLikeSkillDir) {
+                message +=
+                    '. For a project-level Skill Source Link, run this from the project root as `esl unlink ./relative/path` or pass @identity; if the skill was linked with --global, pass --global';
+            }
+        }
+        throw new Error(message);
+    }
+    const sourceDir = entry.resolved;
+    if (!sourceDir) {
+        throw new Error(`Skill ${name} has no linked source path in the install manifest`);
+    }
+    const { hasLinkStagingRecord } = await import('../vendor/core/index.js');
+    const hasStaging = await hasLinkStagingRecord(name, storeRoot);
+    if (!hasStaging) {
+        const removedLinks = await removeToolLinks({
+            storeRoot,
+            identity: name,
+            tools: [...SUPPORTED_TOOLS],
+            level: options.global ? 'global' : 'project'
+        });
+        const conflicts = removedLinks.filter((result) => result.status === 'conflict');
+        if (conflicts.length > 0) {
+            throw new Error(`Tool link conflict; content was not removed: ${conflicts
+                .map((result) => `${result.tool} (${result.targetDir})`)
+                .join(', ')}`);
+        }
+    }
+    const result = await unlinkSkillDirectory(name, storeRoot);
+    if (result.restored && result.record) {
+        const skillsJson = await loadSkillsJson(dependencyRoot);
+        const previousSpecifier = result.record.dependencySpecifier;
+        if (previousSpecifier === undefined) {
+            delete skillsJson.skills[name];
+        }
+        else {
+            skillsJson.skills[name] = previousSpecifier;
+        }
+        await saveSkillsJson(dependencyRoot, skillsJson);
+        const lockJson = await loadSkillsLock(dependencyRoot);
+        const previousLock = result.record.lockEntry;
+        if (previousLock === undefined) {
+            delete lockJson.skills[name];
+        }
+        else {
+            lockJson.skills[name] = previousLock;
+        }
+        await saveSkillsLock(dependencyRoot, lockJson);
+        const restoredManifest = await loadInstallManifest(storeRoot);
+        const previousManifest = result.record.manifestEntry;
+        if (previousManifest === undefined) {
+            delete restoredManifest.skills[name];
+        }
+        else {
+            restoredManifest.skills[name] = previousManifest;
+        }
+        await saveInstallManifest(storeRoot, restoredManifest);
+    }
+    else {
+        await removeSkillDependency(dependencyRoot, name);
+        await removeLockEntry(dependencyRoot, name);
+        await removeInstalledSkill(storeRoot, name);
+    }
+    return {
+        identity: name,
+        targetDir,
+        sourceDir,
+        restored: result.restored
+    };
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,18 @@
+import { type ToolName } from '@esl/core';
+import type { NetworkCommandOptions } from './network-options.js';
+export interface UpdateOptions extends NetworkCommandOptions {
+    projectRoot?: string;
+    skillName?: string;
+    global?: boolean;
+    noAdapt?: boolean;
+    tools?: ToolName[];
+    force?: boolean;
+}
+export interface UpdateResultEntry {
+    name: string;
+    from: string;
+    skipped?: 'link';
+    to: string;
+}
+export type UpdateResult = UpdateResultEntry[];
+export declare function executeUpdate(options?: UpdateOptions): Promise<UpdateResult>;

package/dist/commands/update.js

@@ -0,0 +1,176 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import semver from 'semver';
+import { resolveProjectStorePaths, syncToolLinks, BUILTIN_SPECIFIER_PREFIX, highestStableVersion, isBuiltinIdentity, listToolLinks, loadInstallManifest, loadSkillsJson, loadSkillsLock, renameSkillState, resolveLocalStorePaths, validateSkillDirectory } from '../vendor/core/index.js';
+import { executeInfo } from './info.js';
+import { executeInstall } from './install.js';
+import { publishedInstallTargetDir, publishedProjectSkillsDir, requireFreshToken } from './network-options.js';
+export async function executeUpdate(options = {}) {
+    const dependencyRoot = options.global ? resolveLocalStorePaths(options).root : options.projectRoot ?? process.cwd();
+    const storeRoot = options.global ? dependencyRoot : resolveProjectStorePaths(dependencyRoot).root;
+    const skillsJson = await loadSkillsJson(dependencyRoot);
+    const lockJson = await loadSkillsLock(dependencyRoot);
+    const results = [];
+    const targetIdentities = new Set();
+    const hasRegistrySkills = Object.entries(skillsJson.skills).some(([name, specifier]) => (!options.skillName || options.skillName === name) &&
+        !specifier.startsWith('file:') &&
+        !specifier.startsWith('link:') &&
+        !specifier.startsWith(BUILTIN_SPECIFIER_PREFIX));
+    if (hasRegistrySkills) {
+        await requireFreshToken(options);
+    }
+    for (const [name, specifier] of Object.entries(skillsJson.skills)) {
+        if (options.skillName && options.skillName !== name) {
+            continue;
+        }
+        const installManifest = await loadInstallManifest(storeRoot);
+        if (installManifest.skills[name]?.source === 'link' || specifier.startsWith('link:')) {
+            results.push({ name, from: 'link', to: 'linked (skipped)', skipped: 'link' });
+            continue;
+        }
+        if (specifier.startsWith(BUILTIN_SPECIFIER_PREFIX) || isBuiltinIdentity(name)) {
+            targetIdentities.add(name);
+            const currentVersion = lockJson.skills[name]?.version;
+            const targetDir = await executeInstall(name, {
+                ...options,
+                projectRoot: dependencyRoot,
+                noAdapt: true
+            });
+            const validation = await validateSkillDirectory(targetDir);
+            const to = validation.success ? validation.data.skillJson.version : 'builtin';
+            if (currentVersion !== to) {
+                results.push({ name, from: currentVersion ?? 'builtin', to });
+            }
+            continue;
+        }
+        if (specifier.startsWith('file:')) {
+            targetIdentities.add(name);
+            const targetDir = await executeInstall(specifier.slice('file:'.length), {
+                ...options,
+                projectRoot: dependencyRoot,
+                noAdapt: true
+            });
+            const validation = await validateSkillDirectory(targetDir);
+            results.push({
+                name,
+                from: lockJson.skills[name]?.version ?? 'local',
+                to: validation.success ? validation.data.skillJson.version : 'local'
+            });
+            continue;
+        }
+        try {
+            const info = await executeInfo(name, options);
+            const resolvedName = info.currentName ?? name;
+            targetIdentities.add(resolvedName);
+            const latestVersion = highestStableVersion(info.versions ?? []);
+            if (!latestVersion) {
+                continue;
+            }
+            const currentVersion = lockJson.skills[name]?.version;
+            // An update only ever moves forward: a lower version published later must
+            // not pull an installed skill backwards.
+            const needsUpdate = !currentVersion || semver.gt(latestVersion, currentVersion);
+            if (needsUpdate) {
+                await executeInstall(resolvedName, {
+                    ...options,
+                    projectRoot: dependencyRoot,
+                    version: latestVersion,
+                    noAdapt: true
+                });
+            }
+            if (resolvedName !== name) {
+                const oldDirectory = options.global
+                    ? publishedInstallTargetDir(name, options)
+                    : publishedProjectSkillsDir(dependencyRoot, name);
+                const newDirectory = options.global
+                    ? publishedInstallTargetDir(resolvedName, options)
+                    : publishedProjectSkillsDir(dependencyRoot, resolvedName);
+                if (!needsUpdate && await directoryExists(oldDirectory)) {
+                    await fs.mkdir(path.dirname(newDirectory), { recursive: true });
+                    await fs.rename(oldDirectory, newDirectory);
+                }
+                else {
+                    await fs.rm(oldDirectory, { recursive: true, force: true });
+                }
+                await renameSkillState(dependencyRoot, storeRoot, name, resolvedName);
+                results.push({
+                    name: resolvedName,
+                    from: currentVersion ?? 'unknown',
+                    to: needsUpdate ? latestVersion : (currentVersion ?? latestVersion)
+                });
+                continue;
+            }
+            if (!needsUpdate) {
+                continue;
+            }
+            results.push({
+                name: resolvedName,
+                from: currentVersion ?? 'unknown',
+                to: latestVersion
+            });
+        }
+        catch (error) {
+            if (isBlockingNetworkConfigurationError(error)) {
+                throw error;
+            }
+            console.error(`Failed to update ${name}: ${error.message}`);
+        }
+    }
+    if (targetIdentities.size === 0) {
+        return results;
+    }
+    if (options.tools && options.tools.length > 0) {
+        const linkResults = await syncToolLinks({
+            storeRoot,
+            level: options.global ? 'global' : 'project',
+            tools: options.tools,
+            identities: [...targetIdentities],
+            projectRoot: dependencyRoot,
+            homeDir: options.homeDir,
+            force: options.force
+        });
+        const failedLinks = linkResults
+            .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(', ')}`);
+        }
+    }
+    else {
+        const linkEntries = await listToolLinks({
+            storeRoot,
+            level: options.global ? 'global' : 'project',
+            projectRoot: dependencyRoot,
+            homeDir: options.homeDir
+        });
+        const issues = linkEntries.filter((entry) => targetIdentities.has(entry.identity) &&
+            (entry.status === 'broken' || entry.status === 'conflict'));
+        if (issues.length > 0) {
+            throw new Error(`Tool link issue: ${issues
+                .map((entry) => `${entry.tool} (${entry.identity}: ${entry.status})`)
+                .join(', ')}`);
+        }
+    }
+    return results;
+}
+async function directoryExists(directory) {
+    try {
+        return (await fs.stat(directory)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isBlockingNetworkConfigurationError(error) {
+    const message = error.message ?? '';
+    return (message.startsWith('Missing server;') ||
+        message.startsWith('Missing token;') ||
+        message.startsWith('Login expired;'));
+}

package/dist/commands/upload.d.ts

@@ -0,0 +1,27 @@
+import { execFile } from 'node:child_process';
+import { type NetworkCommandOptions } from './network-options.js';
+declare const defaultExecFileAsync: typeof execFile.__promisify__;
+export interface UploadOptions extends NetworkCommandOptions {
+    directory?: string;
+    license?: string;
+    message?: string;
+    noInput?: boolean;
+    /** Required in non-interactive first uploads; must equal release.json.name. */
+    confirmIdentity?: string;
+    /** Injected by tests in place of the interactive confirmation prompt. */
+    confirmPrompt?: (question: string) => Promise<boolean>;
+    execFileAsync?: typeof defaultExecFileAsync;
+}
+export interface UploadedSkill {
+    name: string;
+    skillId: string;
+    cloneUrl: string;
+    status?: string;
+    alreadyUpToDate?: boolean;
+}
+export declare function executeUpload(options?: UploadOptions): Promise<UploadedSkill>;
+export interface GitIdentity {
+    name: string;
+    email: string;
+}
+export {};