@foxian/esl 0.1.0

package/dist/vendor/core/skill/skill-md.js

@@ -0,0 +1,32 @@
+import YAML from 'yaml';
+import { z } from 'zod';
+const SkillMdMetadataSchema = z.object({
+    name: z.string().regex(/^[a-z0-9-]{1,64}$/, {
+        message: 'SKILL.md name must use lowercase letters, digits, and hyphens'
+    }),
+    description: z.string().min(1).max(1024)
+});
+export function validateSkillMd(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match) {
+        return { success: false, errors: ['SKILL.md: missing YAML frontmatter'] };
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(match[1]);
+    }
+    catch (error) {
+        return { success: false, errors: [`SKILL.md: invalid YAML frontmatter: ${error.message}`] };
+    }
+    const result = SkillMdMetadataSchema.safeParse(parsed);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return {
+        success: false,
+        errors: result.error.issues.map((issue) => {
+            const path = issue.path.join('.') || 'frontmatter';
+            return `SKILL.md ${path}: ${issue.message}`;
+        })
+    };
+}

package/dist/vendor/core/store/file-copy.d.ts

@@ -0,0 +1,3 @@
+export declare function fileExists(filePath: string): Promise<boolean>;
+export declare function copySkillDirectory(source: string, target: string): Promise<void>;
+export declare function removeDirectory(target: string): Promise<void>;

package/dist/vendor/core/store/file-copy.js

@@ -0,0 +1,102 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const EXCLUDED_DIRS = new Set(['.git']);
+export async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function copyRecursive(src, dest) {
+    await fs.mkdir(dest, { recursive: true });
+    const entries = await fs.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            if (EXCLUDED_DIRS.has(entry.name)) {
+                continue;
+            }
+            await copyRecursive(srcPath, destPath);
+        }
+        else {
+            await fs.copyFile(srcPath, destPath);
+            await fs.chmod(destPath, 0o444);
+        }
+    }
+}
+export async function copySkillDirectory(source, target) {
+    const resolvedSource = await resolveExistingPath(source);
+    const resolvedTarget = path.resolve(target);
+    if (pathsOverlap(resolvedSource, resolvedTarget)) {
+        throw new Error(`Source and target directories must not overlap: ${resolvedSource} and ${resolvedTarget}`);
+    }
+    await removeDirectory(target);
+    await copyRecursive(source, target);
+}
+export async function removeDirectory(target) {
+    if (await isSymbolicLink(target)) {
+        await fs.rm(target, { force: true });
+        return;
+    }
+    try {
+        await makeWritableRecursive(target);
+    }
+    catch {
+        // Directory may not exist.
+    }
+    await fs.rm(target, { recursive: true, force: true });
+}
+async function makeWritableRecursive(dir) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const stat = await fs.lstat(fullPath);
+        if (stat.isSymbolicLink()) {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            await makeWritableRecursive(fullPath);
+        }
+        else {
+            try {
+                await fs.chmod(fullPath, 0o666);
+            }
+            catch {
+                // Ignore failures while restoring file permissions.
+            }
+        }
+    }
+}
+async function resolveExistingPath(input) {
+    try {
+        return await fs.realpath(input);
+    }
+    catch {
+        return path.resolve(input);
+    }
+}
+async function isSymbolicLink(input) {
+    try {
+        return (await fs.lstat(input)).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function pathsOverlap(source, target) {
+    return isSameOrDescendant(source, target) || isSameOrDescendant(target, source);
+}
+function isSameOrDescendant(parent, candidate) {
+    const relative = path.relative(parent, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}

package/dist/vendor/core/store/local-store.d.ts

@@ -0,0 +1,43 @@
+export interface LocalStorePaths {
+    root: string;
+    configJson: string;
+    credentialsJson: string;
+    cacheDir: string;
+    skillsDir: string;
+}
+export interface ProjectStorePaths {
+    root: string;
+    skillsDir: string;
+}
+export interface LocalStoreOptions {
+    homeDir?: string;
+}
+export declare function resolveLocalStorePaths(options?: LocalStoreOptions): LocalStorePaths;
+export declare function resolveProjectStorePaths(projectRoot: string): ProjectStorePaths;
+export declare function initializeLocalStore(options?: LocalStoreOptions): Promise<LocalStorePaths>;
+export interface OrganizationMembership {
+    org: string;
+    identity: 'ordinary' | 'managing' | 'owner';
+    /** 便捷判据：是否所有者成员。 */
+    isOwnerMember: boolean;
+}
+export interface EslCredentials {
+    token: string | null;
+    loginAt: string | null;
+}
+export interface ConfigIdentity {
+    legacyIdentity?: boolean;
+}
+export interface EslConfig extends ConfigIdentity {
+    server: string | null;
+    username: string | null;
+    /** 账户语言偏好（ADR-0044）；null 表示未主动选择。 */
+    locale?: string | null;
+    organizations: OrganizationMembership[] | null;
+    tools: string[];
+}
+export declare function loadConfig(options?: LocalStoreOptions): Promise<EslConfig>;
+export declare function saveConfig(config: Partial<EslConfig>, options?: LocalStoreOptions): Promise<EslConfig>;
+export declare function loadCredentials(options?: LocalStoreOptions): Promise<EslCredentials>;
+export declare function saveCredentials(credentials: Partial<EslCredentials>, options?: LocalStoreOptions): Promise<EslCredentials>;
+export declare function clearCredentials(options?: LocalStoreOptions): Promise<EslCredentials>;

package/dist/vendor/core/store/local-store.js

@@ -0,0 +1,104 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+export function resolveLocalStorePaths(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const root = path.join(homeDir, '.eslib');
+    return {
+        root,
+        configJson: path.join(root, 'config.json'),
+        credentialsJson: path.join(root, 'credentials.json'),
+        cacheDir: path.join(root, 'cache'),
+        skillsDir: path.join(root, 'skills')
+    };
+}
+export function resolveProjectStorePaths(projectRoot) {
+    const root = path.join(projectRoot, '.eslib');
+    return {
+        root,
+        skillsDir: path.join(root, 'skills')
+    };
+}
+async function writeJsonIfMissing(filePath, value) {
+    try {
+        await fs.access(filePath);
+    }
+    catch {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    }
+}
+export async function initializeLocalStore(options = {}) {
+    const paths = resolveLocalStorePaths(options);
+    await fs.mkdir(paths.cacheDir, { recursive: true });
+    await fs.mkdir(paths.skillsDir, { recursive: true });
+    await writeJsonIfMissing(paths.configJson, {
+        server: null,
+        username: null,
+        organizations: null,
+        tools: []
+    });
+    await writeJsonIfMissing(paths.credentialsJson, {
+        token: null,
+        loginAt: null
+    });
+    return paths;
+}
+export async function loadConfig(options = {}) {
+    const paths = resolveLocalStorePaths(options);
+    const raw = await fs.readFile(paths.configJson, 'utf8');
+    const parsed = JSON.parse(raw);
+    // 旧版配置带 org/role（ADR-0032 已废除）：读取侧剥离并打标记。
+    const staleMemberships = parsed.organizations;
+    const staleMembershipShape = Array.isArray(staleMemberships) &&
+        staleMemberships.some((membership) => typeof membership === 'object' &&
+            membership !== null &&
+            ('role' in membership || 'isOrgManager' in membership));
+    const legacyIdentity = 'org' in parsed || 'role' in parsed || staleMembershipShape;
+    const { org: _legacyOrg, role: _legacyRole, ...rest } = parsed;
+    if (rest.organizations === undefined) {
+        rest.organizations = null;
+    }
+    return legacyIdentity ? { ...rest, legacyIdentity: true } : rest;
+}
+export async function saveConfig(config, options = {}) {
+    const paths = resolveLocalStorePaths(options);
+    const current = await loadConfig(options);
+    const updated = {
+        ...current,
+        ...config,
+        organizations: config.organizations ?? current.organizations,
+        tools: config.tools ?? current.tools
+    };
+    await fs.mkdir(paths.root, { recursive: true });
+    await fs.writeFile(paths.configJson, `${JSON.stringify(updated, null, 2)}\n`, 'utf8');
+    return updated;
+}
+export async function loadCredentials(options = {}) {
+    const paths = resolveLocalStorePaths(options);
+    return JSON.parse(await fs.readFile(paths.credentialsJson, 'utf8'));
+}
+export async function saveCredentials(credentials, options = {}) {
+    const paths = resolveLocalStorePaths(options);
+    const current = await loadCredentials(options);
+    const updated = {
+        token: credentials.token === undefined ? current.token : credentials.token,
+        loginAt: credentials.loginAt === undefined ? current.loginAt : credentials.loginAt
+    };
+    await fs.mkdir(paths.root, { recursive: true });
+    await fs.writeFile(paths.credentialsJson, `${JSON.stringify(updated, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600
+    });
+    return updated;
+}
+export async function clearCredentials(options = {}) {
+    const paths = resolveLocalStorePaths(options);
+    await fs.mkdir(paths.root, { recursive: true });
+    const cleared = { token: null, loginAt: null };
+    await fs.writeFile(paths.credentialsJson, `${JSON.stringify(cleared, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600
+    });
+    return cleared;
+}

package/dist/vendor/core/store/skill-store.d.ts

@@ -0,0 +1,24 @@
+export interface InstallManifestSkill {
+    identity: string;
+    version: string;
+    source: 'registry' | 'local' | 'builtin' | 'link';
+    specifier: string;
+    resolved?: string;
+    integrity?: string;
+    skillId?: string;
+    sourceDir: string;
+    installedAt: string;
+}
+export interface InstallManifest {
+    version: 1;
+    tools?: string[];
+    skills: Record<string, InstallManifestSkill>;
+}
+export declare const INSTALL_MANIFEST_FILE = ".esl-install-manifest.json";
+export declare function skillDirectoryName(identity: string): string;
+export declare function skillSourceDirectoryName(identity: string): string;
+export declare function skillSourceRelativeDir(identity: string): string;
+export declare function installManifestPath(storeRoot: string): string;
+export declare function defaultInstallManifest(): InstallManifest;
+export declare function loadInstallManifest(storeRoot: string): Promise<InstallManifest>;
+export declare function saveInstallManifest(storeRoot: string, manifest: InstallManifest): Promise<void>;

package/dist/vendor/core/store/skill-store.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parseSkillName } from '../schema/skill-json.js';
+export const INSTALL_MANIFEST_FILE = '.esl-install-manifest.json';
+export function skillDirectoryName(identity) {
+    const { scope, skillName } = parseSkillName(identity);
+    return `${scope}_${skillName}`;
+}
+export function skillSourceDirectoryName(identity) {
+    const { scope, skillName } = parseSkillName(identity);
+    return path.join(`@${scope}`, skillName);
+}
+export function skillSourceRelativeDir(identity) {
+    return path.join('skills', skillSourceDirectoryName(identity));
+}
+export function installManifestPath(storeRoot) {
+    return path.join(storeRoot, INSTALL_MANIFEST_FILE);
+}
+export function defaultInstallManifest() {
+    return { version: 1, skills: {} };
+}
+export async function loadInstallManifest(storeRoot) {
+    try {
+        const raw = await fs.readFile(installManifestPath(storeRoot), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || typeof parsed.skills !== 'object' || parsed.skills === null) {
+            throw new Error('Invalid ESL install manifest');
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return defaultInstallManifest();
+        }
+        throw error;
+    }
+}
+export async function saveInstallManifest(storeRoot, manifest) {
+    await fs.mkdir(storeRoot, { recursive: true });
+    await fs.writeFile(installManifestPath(storeRoot), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}

package/dist/vendor/core/store/skills-json.d.ts

@@ -0,0 +1,34 @@
+export interface SkillsJson {
+    skills: Record<string, string>;
+    tools?: string[];
+}
+export interface SkillsLockEntry {
+    skillId?: string;
+    identity?: string;
+    version: string;
+    resolved: string;
+    integrity: string;
+    source?: 'registry' | 'local' | 'builtin' | 'link';
+}
+export interface SkillsLockJson {
+    lockfileVersion: number;
+    skills: Record<string, SkillsLockEntry>;
+}
+export declare function loadSkillsJson(root: string): Promise<SkillsJson>;
+export declare function saveSkillsJson(root: string, data: SkillsJson): Promise<void>;
+export declare function loadSkillsLock(root: string): Promise<SkillsLockJson>;
+export declare function saveSkillsLock(root: string, data: SkillsLockJson): Promise<void>;
+export declare function addSkillDependency(root: string, name: string, specifier: string): Promise<void>;
+export declare function removeSkillDependency(root: string, name: string): Promise<void>;
+export declare function addLockEntry(root: string, name: string, entry: SkillsLockEntry): Promise<void>;
+export declare function removeLockEntry(root: string, name: string): Promise<void>;
+export declare function recordInstalledSkill(storeRoot: string, name: string, entry: SkillsLockEntry, specifier?: string): Promise<void>;
+export declare function removeInstalledSkill(storeRoot: string, name: string): Promise<void>;
+export declare function renameSkillState(dependencyRoot: string, storeRoot: string, oldName: string, newName: string): Promise<void>;
+export interface SkillListEntry {
+    name: string;
+    version: string;
+    source: 'registry' | 'local' | 'builtin' | 'link';
+}
+export declare function listSkills(root: string): Promise<SkillListEntry[]>;
+export { defaultInstallManifest, loadInstallManifest, saveInstallManifest } from './skill-store.js';

package/dist/vendor/core/store/skills-json.js

@@ -0,0 +1,146 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { BUILTIN_SPECIFIER_PREFIX } from '../skill/builtin-package.js';
+import { loadInstallManifest, saveInstallManifest, skillSourceRelativeDir } from './skill-store.js';
+const SKILLS_JSON_FILE = '.skills.json';
+const SKILLS_LOCK_FILE = '.skills-lock.json';
+function defaultSkillsJson() {
+    return { skills: {} };
+}
+function defaultSkillsLock() {
+    return { lockfileVersion: 1, skills: {} };
+}
+async function readJsonFile(filePath, fallback) {
+    try {
+        return JSON.parse(await fs.readFile(filePath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return fallback;
+        }
+        throw error;
+    }
+}
+async function writeJsonFile(filePath, value) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+function sourceFromSpecifier(specifier) {
+    if (specifier.startsWith('file:')) {
+        return 'local';
+    }
+    if (specifier.startsWith('link:')) {
+        return 'link';
+    }
+    if (specifier.startsWith(BUILTIN_SPECIFIER_PREFIX)) {
+        return 'builtin';
+    }
+    return 'registry';
+}
+function manifestEntryFromLock(identity, entry, specifier, current) {
+    return {
+        identity: entry.identity ?? identity,
+        version: entry.version,
+        source: entry.source ?? current?.source ?? sourceFromSpecifier(specifier),
+        specifier: current?.specifier ?? specifier,
+        resolved: entry.resolved,
+        integrity: entry.integrity,
+        skillId: entry.skillId,
+        sourceDir: current?.sourceDir ?? skillSourceRelativeDir(identity),
+        installedAt: current?.installedAt ?? new Date().toISOString()
+    };
+}
+export async function loadSkillsJson(root) {
+    return readJsonFile(path.join(root, SKILLS_JSON_FILE), defaultSkillsJson());
+}
+export async function saveSkillsJson(root, data) {
+    await writeJsonFile(path.join(root, SKILLS_JSON_FILE), {
+        ...(data.tools === undefined ? {} : { tools: data.tools }),
+        skills: { ...data.skills }
+    });
+}
+export async function loadSkillsLock(root) {
+    return readJsonFile(path.join(root, SKILLS_LOCK_FILE), defaultSkillsLock());
+}
+export async function saveSkillsLock(root, data) {
+    await writeJsonFile(path.join(root, SKILLS_LOCK_FILE), {
+        lockfileVersion: data.lockfileVersion ?? 1,
+        skills: { ...data.skills }
+    });
+}
+export async function addSkillDependency(root, name, specifier) {
+    const current = await loadSkillsJson(root);
+    await saveSkillsJson(root, {
+        ...current,
+        skills: { ...current.skills, [name]: specifier }
+    });
+}
+export async function removeSkillDependency(root, name) {
+    const skillsJson = await loadSkillsJson(root);
+    delete skillsJson.skills[name];
+    await saveSkillsJson(root, skillsJson);
+}
+export async function addLockEntry(root, name, entry) {
+    const lockJson = await loadSkillsLock(root);
+    lockJson.skills[name] = {
+        ...entry,
+        identity: entry.identity ?? name,
+        source: entry.source ?? sourceFromSpecifier(entry.resolved)
+    };
+    await saveSkillsLock(root, lockJson);
+}
+export async function removeLockEntry(root, name) {
+    const lockJson = await loadSkillsLock(root);
+    delete lockJson.skills[name];
+    await saveSkillsLock(root, lockJson);
+}
+export async function recordInstalledSkill(storeRoot, name, entry, specifier) {
+    const installManifest = await loadInstallManifest(storeRoot);
+    installManifest.skills[name] = manifestEntryFromLock(name, entry, specifier ?? installManifest.skills[name]?.specifier ?? entry.resolved, installManifest.skills[name]);
+    await saveInstallManifest(storeRoot, installManifest);
+}
+export async function removeInstalledSkill(storeRoot, name) {
+    const installManifest = await loadInstallManifest(storeRoot);
+    delete installManifest.skills[name];
+    await saveInstallManifest(storeRoot, installManifest);
+}
+export async function renameSkillState(dependencyRoot, storeRoot, oldName, newName) {
+    const [skillsJson, lockJson, installManifest] = await Promise.all([
+        loadSkillsJson(dependencyRoot),
+        loadSkillsLock(dependencyRoot),
+        loadInstallManifest(storeRoot)
+    ]);
+    const dependency = skillsJson.skills[oldName];
+    const lockEntry = lockJson.skills[oldName];
+    const installed = installManifest.skills[oldName];
+    if (dependency !== undefined) {
+        delete skillsJson.skills[oldName];
+        skillsJson.skills[newName] = dependency;
+    }
+    if (lockEntry !== undefined) {
+        delete lockJson.skills[oldName];
+        lockJson.skills[newName] = { ...lockEntry, identity: newName };
+    }
+    if (installed !== undefined) {
+        delete installManifest.skills[oldName];
+        installManifest.skills[newName] = {
+            ...installed,
+            identity: newName,
+            sourceDir: skillSourceRelativeDir(newName)
+        };
+    }
+    await Promise.all([
+        saveSkillsJson(dependencyRoot, skillsJson),
+        saveSkillsLock(dependencyRoot, lockJson),
+        saveInstallManifest(storeRoot, installManifest)
+    ]);
+}
+export async function listSkills(root) {
+    const manifest = await loadInstallManifest(root);
+    return Object.entries(manifest.skills).map(([name, entry]) => ({
+        name,
+        version: entry.version,
+        source: entry.source
+    }));
+}
+export { defaultInstallManifest, loadInstallManifest, saveInstallManifest } from './skill-store.js';

package/dist/vendor/core/version/select-version.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The Skill Release a Skill User gets by default: the highest published version
+ * that is not a prerelease. Prereleases are installable only when a version is
+ * requested explicitly.
+ */
+export declare function highestStableVersion(versions: readonly string[]): string | undefined;
+/**
+ * Published versions newest first, so a version listing reads the same wherever
+ * it is shown. Entries that are not valid SemVer sort to the end.
+ */
+export declare function sortVersionsDescending(versions: readonly string[]): string[];
+/**
+ * The version a dependency range resolves to: the highest published version that
+ * satisfies the range. Used when freezing a Release Dependency Lock.
+ */
+export declare function highestSatisfyingVersion(versions: readonly string[], range: string): string | undefined;

package/dist/vendor/core/version/select-version.js

@@ -0,0 +1,34 @@
+import semver from 'semver';
+/**
+ * The Skill Release a Skill User gets by default: the highest published version
+ * that is not a prerelease. Prereleases are installable only when a version is
+ * requested explicitly.
+ */
+export function highestStableVersion(versions) {
+    return versions
+        .filter((version) => semver.valid(version) !== null && semver.prerelease(version) === null)
+        .sort(semver.rcompare)[0];
+}
+/**
+ * Published versions newest first, so a version listing reads the same wherever
+ * it is shown. Entries that are not valid SemVer sort to the end.
+ */
+export function sortVersionsDescending(versions) {
+    return [...versions].sort((left, right) => {
+        const leftValid = semver.valid(left) !== null;
+        const rightValid = semver.valid(right) !== null;
+        if (!leftValid || !rightValid) {
+            return leftValid === rightValid ? 0 : leftValid ? -1 : 1;
+        }
+        return semver.rcompare(left, right);
+    });
+}
+/**
+ * The version a dependency range resolves to: the highest published version that
+ * satisfies the range. Used when freezing a Release Dependency Lock.
+ */
+export function highestSatisfyingVersion(versions, range) {
+    return versions
+        .filter((version) => semver.valid(version) !== null && semver.satisfies(version, range))
+        .sort(semver.rcompare)[0];
+}

package/dist/vendor/core/version/version.d.ts

@@ -0,0 +1,2 @@
+export type ReleaseType = 'major' | 'minor' | 'patch';
+export declare function bumpSkillVersion(directory: string, release: ReleaseType): Promise<string>;

package/dist/vendor/core/version/version.js

@@ -0,0 +1,25 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { validateSkillJson } from '../schema/skill-json.js';
+function nextVersion(current, release) {
+    const [major, minor, patch] = current.split('.').map(Number);
+    if (release === 'major') {
+        return `${major + 1}.0.0`;
+    }
+    if (release === 'minor') {
+        return `${major}.${minor + 1}.0`;
+    }
+    return `${major}.${minor}.${patch + 1}`;
+}
+export async function bumpSkillVersion(directory, release) {
+    const skillJsonPath = path.join(directory, 'skill.json');
+    const raw = await fs.readFile(skillJsonPath, 'utf8');
+    const data = JSON.parse(raw);
+    const validation = validateSkillJson(data);
+    if (!validation.success) {
+        throw new Error(`Cannot bump invalid skill.json: ${validation.errors.join(', ')}`);
+    }
+    const version = nextVersion(validation.data.version, release);
+    await fs.writeFile(skillJsonPath, `${JSON.stringify({ ...validation.data, version }, null, 2)}\n`, 'utf8');
+    return version;
+}