@foxian/esl 0.1.0

package/dist/commands/release-delete.js

@@ -0,0 +1,34 @@
+import { isBuiltinIdentity, parseSkillName } from '../vendor/core/index.js';
+import { requireOkResponse } from '../api-error.js';
+import { apiUrl, fetchWithTimeout, requireFreshToken, resolveNetworkConfig } from './network-options.js';
+/**
+ * Delete a single Skill Release (CONTEXT:单版本删除). The version number stays burned,
+ * so this is a deliberate, hard-to-undo action: the caller has to echo the version.
+ *
+ * A release other skills pin through their Release Dependency Lock is refused unless
+ * `force` is passed, and the server only accepts that from a platform administrator.
+ */
+export async function executeReleaseDelete(identity, version, options = {}) {
+    if (isBuiltinIdentity(identity)) {
+        throw new Error(`Unknown built-in skill: ${identity}; built-in skills have no releases`);
+    }
+    if (options.confirm !== version) {
+        throw new Error(`Deleting ${identity}@${version} requires an explicit confirmation: pass --confirm ${version} (the version number is burned and cannot be republished).`);
+    }
+    const token = await requireFreshToken(options);
+    const server = options.server ?? (await resolveNetworkConfig(options)).server;
+    const { scope, skillName } = parseSkillName(identity);
+    const fetchImpl = options.customFetch ?? fetch;
+    const response = await fetchWithTimeout(fetchImpl, apiUrl(server, `/api/skills/${encodeURIComponent(scope)}/${encodeURIComponent(skillName)}/releases/${encodeURIComponent(version)}/delete`), {
+        method: 'POST',
+        headers: {
+            Authorization: `token ${token}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(options.force ? { confirm: version, force: true } : { confirm: version })
+    });
+    if (!response.ok) {
+        await requireOkResponse(response, 'Failed to delete the release');
+    }
+    return response.json();
+}

package/dist/commands/release-manifest.d.ts

@@ -0,0 +1,5 @@
+export interface ManifestOptions {
+    license?: string;
+}
+export declare const DEFAULT_LICENSE = "MIT";
+export declare function ensureReleaseManifest(options: ManifestOptions, directory: string): Promise<void>;

package/dist/commands/release-manifest.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createMinimalReleaseManifest, validateSkillMd } from '../vendor/core/index.js';
+import { notify } from '../output.js';
+export const DEFAULT_LICENSE = 'MIT';
+// v3 清单必须有 name（ADR-0032）。补缺场景下身份尚未与服务器确认，
+// 以 SKILL.md 的 short name 写裸名——即个人命名空间语义。
+async function deriveSkillName(directory) {
+    const skillMd = await fs
+        .readFile(path.join(directory, 'SKILL.md'), 'utf8')
+        .then((content) => validateSkillMd(content), () => undefined);
+    if (skillMd?.success)
+        return skillMd.data.name;
+    return path.basename(directory);
+}
+export async function ensureReleaseManifest(options, directory) {
+    const license = options.license ?? DEFAULT_LICENSE;
+    if (!options.license) {
+        notify(`release.json is missing; creating it with the default license ${license} (pass --license to override).`);
+    }
+    const releaseJson = createMinimalReleaseManifest(await deriveSkillName(directory), license);
+    await fs.writeFile(path.join(directory, 'release.json'), `${JSON.stringify(releaseJson, null, 2)}\n`, 'utf8');
+}

package/dist/commands/rename.d.ts

@@ -0,0 +1,5 @@
+import { type NetworkCommandOptions } from './network-options.js';
+export interface RenameOptions extends NetworkCommandOptions {
+    newName: string;
+}
+export declare function executeRename(identity: string, options: RenameOptions): Promise<unknown>;

package/dist/commands/rename.js

@@ -0,0 +1,25 @@
+import { apiUrl, fetchWithTimeout, requireFreshToken } from './network-options.js';
+import { isBuiltinIdentity } from '../vendor/core/index.js';
+import { requireOkResponse } from '../api-error.js';
+export async function executeRename(identity, options) {
+    if (isBuiltinIdentity(identity)) {
+        throw new Error(`Unknown built-in skill: ${identity}; built-in skills cannot be renamed`);
+    }
+    const token = await requireFreshToken(options);
+    const server = options.server;
+    if (!server)
+        throw new Error('Missing server; run esl login or pass --server');
+    const fetchImpl = options.customFetch ?? fetch;
+    const response = await fetchWithTimeout(fetchImpl, apiUrl(server, `/api/skills/${encodeURIComponent(identity)}/rename`), {
+        method: 'POST',
+        headers: {
+            Authorization: `token ${token}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({ name: options.newName })
+    });
+    if (!response.ok) {
+        await requireOkResponse(response, 'Failed to rename skill');
+    }
+    return response.json();
+}

package/dist/commands/repair-tag.d.ts

@@ -0,0 +1,5 @@
+import { type NetworkCommandOptions } from './network-options.js';
+export interface RepairTagOptions extends NetworkCommandOptions {
+    version: string;
+}
+export declare function executeRepairTag(identity: string, options: RepairTagOptions): Promise<unknown>;

package/dist/commands/repair-tag.js

@@ -0,0 +1,14 @@
+import { apiUrl, fetchWithTimeout, requireFreshToken } from './network-options.js';
+import { requireOkResponse } from '../api-error.js';
+export async function executeRepairTag(identity, options) {
+    const token = await requireFreshToken(options);
+    const server = options.server;
+    if (!server)
+        throw new Error('Missing server; run esl login or pass --server');
+    const fetchImpl = options.customFetch ?? fetch;
+    const response = await fetchWithTimeout(fetchImpl, apiUrl(server, `/api/skills/${encodeURIComponent(identity)}/releases/${encodeURIComponent(options.version)}/repair-tag`), { method: 'POST', headers: { Authorization: `token ${token}` } });
+    if (!response.ok) {
+        await requireOkResponse(response, 'Failed to repair release tag');
+    }
+    return response.json();
+}

package/dist/commands/reset-source.d.ts

@@ -0,0 +1,16 @@
+import { execFile } from 'node:child_process';
+import type { NetworkCommandOptions } from './network-options.js';
+declare const defaultExecFileAsync: typeof execFile.__promisify__;
+export interface ResetSourceOptions extends NetworkCommandOptions {
+    directory?: string;
+    force?: boolean;
+    noInput?: boolean;
+    execFileAsync?: typeof defaultExecFileAsync;
+}
+export interface ResetSourceResult {
+    directory: string;
+    remoteUrl: string;
+    releaseManifestRenamedTo: string | null;
+}
+export declare function executeResetSource(options?: ResetSourceOptions): Promise<ResetSourceResult>;
+export {};

package/dist/commands/reset-source.js

@@ -0,0 +1,71 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { executeInfo } from './info.js';
+import { notify } from '../output.js';
+import { confirm, isInteractive } from '../prompt.js';
+import { fileExists } from '../vendor/core/index.js';
+const defaultExecFileAsync = promisify(execFile);
+export async function executeResetSource(options = {}) {
+    const directory = options.directory ?? process.cwd();
+    const execFileAsync = options.execFileAsync ?? defaultExecFileAsync;
+    let remoteUrl;
+    try {
+        remoteUrl = (await execFileAsync('git', ['remote', 'get-url', 'esl'], { cwd: directory })).stdout.trim();
+    }
+    catch {
+        throw new Error(`Skill source at ${directory} has no esl remote; it is already an un-managed local source and needs no reset`);
+    }
+    // 守门：Registry API 只读探测。身份在当前登录下可见时，服务器上的源仍在——
+    // 脱管前的核实假设（「源已删除」）不成立。硬阻断（ADR-0028：避免误删），
+    // 提示先核实；--force 显式表态「我知道源还在，就是要另立新源」才放行。
+    if (options.force !== true && remoteUrl.startsWith('http')) {
+        const identity = identityFromRemoteUrl(remoteUrl);
+        if (identity) {
+            try {
+                await executeInfo(identity, options);
+                throw new Error(`The skill identity ${identity} still exists on the configured ESL server; refusing to reset the source link. ` +
+                    'Verify on the server first: if you only switched accounts, log in with the maintaining account and "esl upload" to sync; ' +
+                    'if the source really should be deleted, delete it in the Web skill lifecycle UI (unpublished skills: a manage-permission holder; published skills: the platform administrator or organization owner). ' +
+                    'To proceed with a reset anyway - detaching locally and registering a brand-new source with a new Skill ID later - re-run with --force.');
+            }
+            catch (error) {
+                // 守门自身抛出的拒绝执行错误必须向上传递；其余探测失败（源已删除、
+                // 无权限或网络不通）→ 按用户主张的脱管场景放行。
+                if (error instanceof Error && error.message.includes('refusing to reset'))
+                    throw error;
+            }
+        }
+    }
+    if (options.force !== true) {
+        if (options.noInput || !isInteractive()) {
+            throw new Error('Resetting the source link requires confirmation; pass --force to skip the confirmation in non-interactive runs');
+        }
+        const confirmed = await confirm(`Remove the esl remote (${remoteUrl}) and reset this directory to a local skill source? `);
+        if (!confirmed) {
+            throw new Error('Reset cancelled');
+        }
+    }
+    const manifestPath = path.join(directory, 'release.json');
+    const backupPath = `${path.join(directory, 'release.json')}.before-reset`;
+    const hasManifest = await fileExists(manifestPath);
+    if (hasManifest && (await fileExists(backupPath))) {
+        // 破坏性前置检查：任何冲突都在动 remote 之前发现，绝不留下脱管一半的目录。
+        throw new Error(`A previous reset backup already exists at ${backupPath}; remove or rename it, then re-run "esl reset-source"`);
+    }
+    await execFileAsync('git', ['remote', 'remove', 'esl'], { cwd: directory });
+    let releaseManifestRenamedTo = null;
+    if (hasManifest) {
+        await fs.rename(manifestPath, backupPath);
+        releaseManifestRenamedTo = backupPath;
+        notify(`Release Manifest renamed to ${path.basename(backupPath)}`);
+    }
+    return { directory, remoteUrl, releaseManifestRenamedTo };
+}
+// 与 upload 的 skillNameFromRemote 相同的解析约定：取 /git/ 与 .git 之间的
+// 组织/仓库路径并拼成 `@scope/name`。
+function identityFromRemoteUrl(remoteUrl) {
+    const match = remoteUrl.match(/\/git\/(.+?)(?:\.git)?\/?$/);
+    return match ? `@${match[1]}` : null;
+}

package/dist/commands/resolve-unlink-identity.d.ts

@@ -0,0 +1,14 @@
+export interface ResolveUnlinkIdentityOptions {
+    /** 默认 process.cwd()；测试可注入，避免依赖 chdir */
+    cwd?: string;
+}
+export interface ResolvedUnlinkTarget {
+    identity: string;
+    /** 是否从技能目录的 release.json 推导（含省略 / . / 路径） */
+    fromDirectory: boolean;
+    /** 推导时使用的绝对技能目录；显式 @identity 时为 null */
+    skillDir: string | null;
+    /** 调用方传入 undefined 或 '.'（脚枪提示用） */
+    usedOmitOrDot: boolean;
+}
+export declare function resolveUnlinkIdentity(target: string | undefined, options?: ResolveUnlinkIdentityOptions): Promise<ResolvedUnlinkTarget>;

package/dist/commands/resolve-unlink-identity.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileExists, validateReleaseManifest } from '../vendor/core/index.js';
+function completeBareIdentity(name) {
+    if (name.startsWith('@')) {
+        return name;
+    }
+    return `@local/${name}`;
+}
+async function identityFromSkillDir(skillDir) {
+    const releasePath = path.join(skillDir, 'release.json');
+    if (!(await fileExists(releasePath))) {
+        throw new Error(`Cannot infer skill identity from ${skillDir}: release.json is missing; pass @scope/skill-name explicitly`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(releasePath, 'utf8'));
+    }
+    catch {
+        throw new Error(`Cannot infer skill identity from ${skillDir}: release.json is not valid JSON; pass @scope/skill-name explicitly`);
+    }
+    const validation = validateReleaseManifest(parsed);
+    if (!validation.success) {
+        throw new Error(`Cannot infer skill identity from ${skillDir}: ${validation.errors.join(', ')}; pass @scope/skill-name explicitly`);
+    }
+    return completeBareIdentity(validation.data.name);
+}
+export async function resolveUnlinkIdentity(target, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (typeof target === 'string' && target.startsWith('@')) {
+        return {
+            identity: target,
+            fromDirectory: false,
+            skillDir: null,
+            usedOmitOrDot: false
+        };
+    }
+    const usedOmitOrDot = target === undefined || target === '.';
+    const skillDir = usedOmitOrDot ? path.resolve(cwd) : path.resolve(cwd, target);
+    const identity = await identityFromSkillDir(skillDir);
+    return {
+        identity,
+        fromDirectory: true,
+        skillDir,
+        usedOmitOrDot
+    };
+}

package/dist/commands/search.d.ts

@@ -0,0 +1,19 @@
+import { type NetworkCommandOptions } from './network-options.js';
+export interface SkillSearchResult {
+    name: string;
+    /** 对外当前显示名（ADR-0048）：标题位优先显示名，name 作技术名。 */
+    displayName?: string;
+    description: string;
+    scope?: string;
+    skillName?: string;
+    latestStableVersion?: string;
+    visibility?: string;
+}
+export interface SkillSearchFilters {
+    query?: string;
+    namespace?: string;
+    keyword?: string;
+    visibility?: 'public' | 'private';
+    limit?: number;
+}
+export declare function executeSearch(query: string | undefined, options?: NetworkCommandOptions): Promise<SkillSearchResult[]>;

package/dist/commands/search.js

@@ -0,0 +1,33 @@
+import { apiUrl, fetchWithTimeout, resolveOptionalFreshToken, resolveNetworkConfig } from './network-options.js';
+import { isBuiltinIdentity } from '../vendor/core/index.js';
+import { requireOkResponse } from '../api-error.js';
+export async function executeSearch(query, options = {}) {
+    const fetchImpl = options.customFetch ?? fetch;
+    const server = options.server ?? (await resolveNetworkConfig(options)).server;
+    // 与 info 对齐（ADR-0049）：存在有效登录态则随请求携带 Skill User Token，
+    // 匿名仍可浏览 public 已发布技能。
+    const token = await resolveOptionalFreshToken({ homeDir: options.homeDir });
+    const filters = new URLSearchParams();
+    if (query !== undefined && query !== '') {
+        filters.set('q', query);
+    }
+    const searchOptions = options;
+    if (searchOptions.visibility === 'private' && !token) {
+        throw new Error('Searching private skills requires login; run "esl login" first');
+    }
+    if (searchOptions.namespace)
+        filters.set('namespace', searchOptions.namespace);
+    if (searchOptions.keyword)
+        filters.set('keyword', searchOptions.keyword);
+    if (searchOptions.visibility)
+        filters.set('visibility', searchOptions.visibility);
+    if (searchOptions.limit !== undefined)
+        filters.set('limit', String(searchOptions.limit));
+    const queryString = filters.toString();
+    const res = await fetchWithTimeout(fetchImpl, apiUrl(server, `/api/skills/search${queryString ? `?${queryString}` : ''}`), { headers: token ? { Authorization: `token ${token}` } : {} });
+    if (!res.ok) {
+        await requireOkResponse(res, 'Failed to search skills');
+    }
+    const results = (await res.json());
+    return results.filter((result) => !isBuiltinIdentity(result.name));
+}

package/dist/commands/share.d.ts

@@ -0,0 +1,17 @@
+import { type NetworkCommandOptions } from './network-options.js';
+export interface ShareOptions extends NetworkCommandOptions {
+    all?: boolean;
+    team?: string;
+    user?: string;
+    write?: boolean;
+    manage?: boolean;
+    reset?: boolean;
+}
+export interface ShareTarget {
+    action: 'share_all_read' | 'share_all_write' | 'set_team' | 'add_member' | 'reset_to_private';
+    team?: string;
+    username?: string;
+    permission?: 'read' | 'write' | 'manage';
+}
+export declare function resolveShareTarget(options: ShareOptions): ShareTarget;
+export declare function executeShare(identity: string, options: ShareOptions): Promise<unknown>;

package/dist/commands/share.js

@@ -0,0 +1,56 @@
+import { parseSkillName, isBuiltinIdentity } from '../vendor/core/index.js';
+import { apiUrl, fetchWithTimeout, requireFreshToken, resolveNetworkConfig } from './network-options.js';
+import { requireOkResponse } from '../api-error.js';
+export function resolveShareTarget(options) {
+    const selected = [options.all, options.team, options.user, options.reset].filter(Boolean);
+    if (selected.length === 0) {
+        throw new Error('Choose one sharing target: --all, --team, --user, or --reset');
+    }
+    if (selected.length > 1) {
+        throw new Error('Choose only one of --all, --team, --user, or --reset');
+    }
+    if (options.write && options.manage) {
+        throw new Error('Choose only one permission level: --write or --manage');
+    }
+    if (options.all) {
+        return { action: options.write ? 'share_all_write' : 'share_all_read' };
+    }
+    if (options.team) {
+        return {
+            action: 'set_team',
+            team: options.team,
+            permission: options.manage ? 'manage' : options.write ? 'write' : 'read'
+        };
+    }
+    if (options.user) {
+        // ADR-0025 三档:manage 档授予对方协管(配权限、发布)的能力。
+        return {
+            action: 'add_member',
+            username: options.user,
+            permission: options.manage ? 'manage' : options.write ? 'write' : 'read'
+        };
+    }
+    return { action: 'reset_to_private' };
+}
+export async function executeShare(identity, options) {
+    if (isBuiltinIdentity(identity)) {
+        throw new Error(`Unknown built-in skill: ${identity}; built-in skills have no permissions to share`);
+    }
+    const target = resolveShareTarget(options);
+    const token = await requireFreshToken(options);
+    const server = options.server ?? (await resolveNetworkConfig(options)).server;
+    const { scope, skillName } = parseSkillName(identity);
+    const fetchImpl = options.customFetch ?? fetch;
+    const response = await fetchWithTimeout(fetchImpl, apiUrl(server, `/api/skills/${encodeURIComponent(scope)}/${encodeURIComponent(skillName)}/permissions`), {
+        method: 'POST',
+        headers: {
+            Authorization: `token ${token}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(target)
+    });
+    if (!response.ok) {
+        await requireOkResponse(response, 'Failed to update skill permissions');
+    }
+    return response.json();
+}

package/dist/commands/source.d.ts

@@ -0,0 +1,10 @@
+import { execFile } from 'node:child_process';
+import { type NetworkCommandOptions } from './network-options.js';
+declare const defaultExecFileAsync: typeof execFile.__promisify__;
+export interface SourceOptions extends NetworkCommandOptions {
+    target?: string;
+    cwd?: string;
+    execFileAsync?: typeof defaultExecFileAsync;
+}
+export declare function executeSource(name: string, options?: SourceOptions): Promise<string>;
+export {};

package/dist/commands/source.js

@@ -0,0 +1,34 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { parseSkillName, isBuiltinIdentity } from '../vendor/core/index.js';
+import { gitAuthHeaderConfig, fetchWithTimeout, requireConfigured, requireFreshToken, resolveNetworkConfig } from './network-options.js';
+import { executeInfo } from './info.js';
+import { notify } from '../output.js';
+const defaultExecFileAsync = promisify(execFile);
+export async function executeSource(name, options = {}) {
+    if (isBuiltinIdentity(name)) {
+        throw new Error(`Unknown built-in skill: ${name}; built-in skills have no source repository`);
+    }
+    const execFileAsync = options.execFileAsync ?? defaultExecFileAsync;
+    const authToken = await requireFreshToken(options);
+    const info = await executeInfo(name, options);
+    const { server } = await resolveNetworkConfig(options);
+    const fetchImpl = options.customFetch ?? fetch;
+    const accessResponse = await fetchWithTimeout(fetchImpl, `${server.replace(/\/$/, '')}/api/skills/${encodeURIComponent(name)}/source-access`, {
+        method: 'POST',
+        headers: { Authorization: `token ${authToken}` }
+    });
+    if (!accessResponse.ok) {
+        throw new Error(`Failed to authorize source access: ${await accessResponse.text()}`);
+    }
+    const access = (await accessResponse.json());
+    const remoteUrl = requireConfigured(access.cloneUrl ?? info.cloneUrl, 'cloneUrl');
+    const authHeader = gitAuthHeaderConfig(authToken);
+    const { skillName } = parseSkillName(name);
+    const cwd = options.cwd ?? process.cwd();
+    const targetDir = options.target ?? path.join(cwd, skillName);
+    notify(`Cloning ${name}...`);
+    await execFileAsync('git', ['-c', authHeader, 'clone', remoteUrl, targetDir]);
+    return targetDir;
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,16 @@
+import { execFile } from 'node:child_process';
+import { type NetworkCommandOptions } from './network-options.js';
+declare const defaultExecFileAsync: typeof execFile.__promisify__;
+export interface StatusOptions extends NetworkCommandOptions {
+    directory?: string;
+    execFileAsync?: typeof defaultExecFileAsync;
+}
+export interface SourceStatus {
+    serverHosted: boolean;
+    clean: boolean;
+    ahead: number;
+    behind: number;
+    lastCommit?: string;
+}
+export declare function executeStatus(options?: StatusOptions): Promise<SourceStatus>;
+export {};

package/dist/commands/status.js

@@ -0,0 +1,77 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { gitAuthHeaderConfig, requireFreshToken, resolveNetworkConfig, sourceRemoteOriginDrifted } from './network-options.js';
+import { notify } from '../output.js';
+const defaultExecFileAsync = promisify(execFile);
+export async function executeStatus(options = {}) {
+    const directory = options.directory ?? process.cwd();
+    const execFileAsync = options.execFileAsync ?? defaultExecFileAsync;
+    if (!(await isInsideWorkTree(execFileAsync, directory))) {
+        return { serverHosted: false, clean: true, ahead: 0, behind: 0 };
+    }
+    const remoteUrl = await eslRemoteUrl(execFileAsync, directory);
+    if (remoteUrl === null) {
+        return { serverHosted: false, clean: true, ahead: 0, behind: 0 };
+    }
+    // ADR-0023：Source Remote origin 与配置 server 漂移时只读提示——不修改任何
+    // 配置，指引跑一次 upload 完成重指；提示后 ahead/behind 仍按上次本地同步显示。
+    try {
+        const { server } = await resolveNetworkConfig(options);
+        if (sourceRemoteOriginDrifted(remoteUrl, server)) {
+            notify('Notice: the esl remote origin differs from the configured ESL server (server origin migration). ' +
+                'Run "esl upload" in this directory once to re-home the remote; ' +
+                'the ahead/behind counts below may be stale until then.');
+        }
+    }
+    catch {
+        // server 未配置或读取失败；维持现状
+    }
+    // Refresh the server-side ref when logged in, so ahead/behind are accurate
+    // even when another maintainer pushed in the meantime.
+    try {
+        const token = await requireFreshToken(options);
+        await execFileAsync('git', ['-c', gitAuthHeaderConfig(token), 'fetch', 'esl'], { cwd: directory });
+    }
+    catch {
+        // Not logged in or server unreachable; fall back to the last local sync.
+    }
+    const status = await execFileAsync('git', ['status', '--porcelain'], { cwd: directory });
+    const clean = !status.stdout.trim();
+    let ahead = 0;
+    let behind = 0;
+    try {
+        ahead = parseInt((await execFileAsync('git', ['rev-list', '--count', 'esl/main..HEAD'], { cwd: directory })).stdout.trim() || '0', 10);
+        behind = parseInt((await execFileAsync('git', ['rev-list', '--count', 'HEAD..esl/main'], { cwd: directory })).stdout.trim() || '0', 10);
+    }
+    catch {
+        // esl/main may not exist yet (the source was never pushed).
+    }
+    let lastCommit;
+    try {
+        const log = await execFileAsync('git', ['log', '-1', '--format=%h %s'], { cwd: directory });
+        lastCommit = log.stdout.trim() || undefined;
+    }
+    catch {
+        // no commits yet
+    }
+    return { serverHosted: true, clean, ahead, behind, lastCommit };
+}
+async function isInsideWorkTree(execFileAsync, directory) {
+    try {
+        const res = await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: directory });
+        return res.stdout.trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+async function eslRemoteUrl(execFileAsync, directory) {
+    try {
+        const res = await execFileAsync('git', ['remote', 'get-url', 'esl'], { cwd: directory });
+        const url = res.stdout.trim();
+        return url.length > 0 ? url : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/sync-builtin.d.ts

@@ -0,0 +1,10 @@
+import { type LocalStoreOptions } from '@esl/core';
+export interface SyncBuiltinOptions extends LocalStoreOptions {
+    builtinDir?: string;
+}
+export interface SyncBuiltinResult {
+    synced: boolean;
+    failed: boolean;
+}
+export declare function syncGlobalBuiltinSkill(options?: SyncBuiltinOptions): Promise<SyncBuiltinResult>;
+export declare function retryPendingGlobalSync(options?: SyncBuiltinOptions): Promise<SyncBuiltinResult>;

package/dist/commands/sync-builtin.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { BUILTIN_IDENTITY, loadSkillsJson, loadSkillsLock, resolveLocalStorePaths } from '../vendor/core/index.js';
+import { executeInstall } from './install.js';
+import { resolveBuiltinDir } from '../builtin-dir.js';
+const SYNC_PENDING_MARKER = '.builtin-sync-pending';
+export async function syncGlobalBuiltinSkill(options = {}) {
+    const globalRoot = resolveLocalStorePaths(options).root;
+    try {
+        const skillsJson = await loadSkillsJson(globalRoot);
+        if (!skillsJson.skills[BUILTIN_IDENTITY]) {
+            return { synced: false, failed: false };
+        }
+        const builtinDir = options.builtinDir ?? resolveBuiltinDir();
+        const lock = await loadSkillsLock(globalRoot);
+        const installedVersion = lock.skills[BUILTIN_IDENTITY]?.version;
+        await executeInstall(BUILTIN_IDENTITY, {
+            homeDir: options.homeDir,
+            builtinDir,
+            global: true,
+            noAdapt: false
+        });
+        const newLock = await loadSkillsLock(globalRoot);
+        const synced = newLock.skills[BUILTIN_IDENTITY]?.version !== installedVersion;
+        return { synced, failed: false };
+    }
+    catch (error) {
+        await writeSyncPendingMarker(globalRoot, error);
+        return { synced: false, failed: true };
+    }
+}
+export async function retryPendingGlobalSync(options = {}) {
+    const globalRoot = resolveLocalStorePaths(options).root;
+    if (!await hasSyncPendingMarker(globalRoot)) {
+        return { synced: false, failed: false };
+    }
+    const result = await syncGlobalBuiltinSkill(options);
+    if (!result.failed) {
+        await clearSyncPendingMarker(globalRoot);
+    }
+    return result;
+}
+async function writeSyncPendingMarker(globalRoot, error) {
+    try {
+        await fs.mkdir(globalRoot, { recursive: true });
+        await fs.writeFile(path.join(globalRoot, SYNC_PENDING_MARKER), `${new Date().toISOString()} ${error.message ?? String(error)}\n`, 'utf8');
+    }
+    catch {
+        // Marker writes are best-effort; a failed marker must not mask the original error.
+    }
+}
+async function hasSyncPendingMarker(globalRoot) {
+    try {
+        await fs.access(path.join(globalRoot, SYNC_PENDING_MARKER));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function clearSyncPendingMarker(globalRoot) {
+    try {
+        await fs.rm(path.join(globalRoot, SYNC_PENDING_MARKER), { force: true });
+    }
+    catch {
+        // Best-effort cleanup.
+    }
+}

package/dist/commands/tools.d.ts

@@ -0,0 +1,19 @@
+import { type LocalStoreOptions, type RemovedToolLinkResult, type ToolLinkEntry, type ToolName } from '@esl/core';
+export interface ToolsListOptions extends LocalStoreOptions {
+    projectRoot?: string;
+    global?: boolean;
+    tool?: string;
+    skill?: string;
+    managed?: boolean;
+    unmanaged?: boolean;
+    status?: string;
+}
+export interface ToolsRemoveOptions extends LocalStoreOptions {
+    projectRoot?: string;
+    global?: boolean;
+    tools: ToolName[];
+}
+export declare function executeToolsList(options?: ToolsListOptions): Promise<ToolLinkEntry[]>;
+export declare function executeToolsRemove(skillName: string, options: ToolsRemoveOptions): Promise<RemovedToolLinkResult[]>;
+export declare function parseToolsOption(value: string | undefined): ToolName[];
+export declare function formatToolsList(entries: ToolLinkEntry[]): string[];