skillex 0.3.1 → 0.4.0

package/dist/install.js

@@ -1,13 +1,34 @@
+/**
+ * Install / update / remove orchestration for catalog and direct-GitHub skills.
+ *
+ * Historically this module owned every install-related concern. Lockfile
+ * shape, direct-GitHub install, auto-sync, and the shared file downloader
+ * have been extracted into focused modules. This file now contains only
+ * orchestration and re-exports the moved symbols so existing imports keep
+ * working until callers migrate to the canonical paths.
+ *
+ * Re-export shim → canonical module mapping:
+ * - lockfile shape and source-list helpers      → ./lockfile.js
+ * - direct GitHub parsing / fetch / download    → ./direct-github.js
+ * - auto-sync orchestration                     → ./auto-sync.js
+ * - shared per-file download helper             → ./downloader.js
+ */
 import * as path from "node:path";
-import { DEFAULT_INSTALL_SCOPE, DEFAULT_REF, DEFAULT_REPO, getScopedStatePaths, } from "./config.js";
-import { confirmAction } from "./confirm.js";
-import { ensureDir, pathExists, readJson, removePath, writeJson, writeText } from "./fs.js";
-import { fetchOptionalJson, fetchOptionalText, fetchText } from "./http.js";
-import { buildRawGitHubUrl, loadCatalog, resolveSource } from "./catalog.js";
+import { DEFAULT_AGENT_SKILLS_DIR, DEFAULT_INSTALL_SCOPE, DEFAULT_REF, DEFAULT_REPO, getScopedStatePaths, } from "./config.js";
+import { ensureDir, isPathInside, pathExists, readJson, removePath, writeJson, writeText } from "./fs.js";
+import { loadCatalog, resolveSource } from "./catalog.js";
 import { resolveAdapterState } from "./adapters.js";
 import { loadInstalledSkillDocuments, syncAdapterFiles } from "./sync.js";
-import { parseSkillFrontmatter } from "./skill.js";
+import { downloadSkillFiles, writeDownloadedManifest, } from "./downloader.js";
+import { createBaseLockfile, dedupeSources, getLockfileSources, normalizeLockfile, normalizeSyncHistory, parseCatalogSource, PLACEHOLDER_REPOS, toLockfileSource, } from "./lockfile.js";
+import { confirmDirectInstall, downloadDirectGitHubSkill, fetchDirectGitHubSkill, normalizeDirectManifest, parseDirectGitHubRef, parseGitHubSource, } from "./direct-github.js";
+import { maybeAutoSync, maybeSyncAfterRemove, resolveSyncAdapterIds, } from "./auto-sync.js";
 import { CliError, InstallError } from "./types.js";
+// Re-export everything moved to focused modules so existing imports keep working.
+export { createBaseLockfile, dedupeSources, getLockfileSources, normalizeLockfile, normalizeSyncHistory, parseCatalogSource, PLACEHOLDER_REPOS, toLockfileSource, } from "./lockfile.js";
+export { confirmDirectInstall, downloadDirectGitHubSkill, fetchDirectGitHubSkill, normalizeDirectManifest, parseDirectGitHubRef, parseGitHubSource, } from "./direct-github.js";
+export { maybeAutoSync, maybeSyncAfterRemove, resolveSyncAdapterIds, } from "./auto-sync.js";
+export { downloadSkillFiles, writeDownloadedManifest, } from "./downloader.js";
 /**
  * Initializes the local Skillex workspace state.
  *
@@ -105,7 +126,12 @@ export async function installSkills(requestedSkillIds, options = {}) {
             }
         }
         else if (!directRefs.length) {
-            throw new InstallError("Provide at least one skill-id, use --all, or pass owner/repo[@ref].", "INSTALL_REQUIRES_SKILL");
+            throw new InstallError([
+                "No install target provided. Pick one of:",
+                "  • skillex install <skill-id> [<skill-id> ...]   from a configured catalog source",
+                "  • skillex install --all                          install every skill in the catalog",
+                "  • skillex install owner/repo[@ref] --trust       install directly from a GitHub repo",
+            ].join("\n"), "INSTALL_REQUIRES_SKILL");
         }
         for (const directRef of directRefs) {
             if (!options.trust) {
@@ -132,7 +158,7 @@ export async function installSkills(requestedSkillIds, options = {}) {
             now,
             changed: installedSkills.length > 0,
             mode: options.mode,
-        }, options.agentSkillsDir));
+        }, options.agentSkillsDir), syncInstalledSkills);
         return {
             installedCount: installedSkills.length,
             installedSkills,
@@ -221,7 +247,7 @@ export async function updateInstalledSkills(requestedSkillIds, options = {}) {
             now,
             changed: updatedSkills.length > 0,
             mode: options.mode,
-        }, options.agentSkillsDir));
+        }, options.agentSkillsDir), syncInstalledSkills);
         return {
             statePaths,
             updatedSkills,
@@ -265,13 +291,17 @@ export async function removeSkills(requestedSkillIds, options = {}) {
                 missingSkills.push(skillId);
                 continue;
             }
-            await removePath(resolveInstalledSkillPath(cwd, metadata.path));
+            const resolvedSkillPath = resolveInstalledSkillPath(cwd, metadata.path);
+            if (!isPathInside(resolvedSkillPath, statePaths.skillsDirPath)) {
+                throw new InstallError(`Refusing to remove "${skillId}": lockfile path "${metadata.path}" resolves outside the managed skills store (${statePaths.skillsDirPath}).`, "INSTALL_PATH_UNSAFE");
+            }
+            await removePath(resolvedSkillPath);
             delete lockfile.installed[skillId];
             removedSkills.push(skillId);
         }
         lockfile.updatedAt = now();
         await writeJson(statePaths.lockfilePath, lockfile);
-        const autoSync = await maybeSyncAfterRemove(withAgentSkillsDir({
+        const autoSyncs = await maybeSyncAfterRemove(withAgentSkillsDir({
             cwd,
             scope: options.scope,
             adapters: lockfile.adapters,
@@ -282,12 +312,13 @@ export async function removeSkills(requestedSkillIds, options = {}) {
             now,
             changed: removedSkills.length > 0,
             mode: options.mode,
-        }, options.agentSkillsDir));
+        }, options.agentSkillsDir), syncInstalledSkills);
         return {
             statePaths,
             removedSkills,
             missingSkills,
-            autoSync,
+            autoSync: autoSyncs?.[0] ?? null,
+            autoSyncs: autoSyncs ?? [],
         };
     }
     catch (error) {
@@ -550,244 +581,24 @@ export async function listProjectSources(options = {}) {
     const fallbackSource = resolveSource(toCatalogSourceInput(options, resolvePrimarySourceOverride(options, existing)));
     return getLockfileSources(existing, fallbackSource);
 }
-/**
- * Parses a direct GitHub install reference in `owner/repo[@ref]` format.
- *
- * @param input - User-supplied install argument.
- * @returns Parsed direct GitHub reference or `null` when the value is not a direct ref.
- */
-export function parseDirectGitHubRef(input) {
-    if (!input || input.startsWith("http://") || input.startsWith("https://")) {
-        return null;
-    }
-    const match = input.trim().match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:@(.+))?$/);
-    if (!match) {
-        return null;
-    }
-    return {
-        owner: match[1],
-        repo: match[2],
-        ref: match[3] || "main",
-    };
-}
-function createBaseLockfile(source, now) {
-    return {
-        formatVersion: 1,
-        createdAt: now(),
-        updatedAt: now(),
-        sources: [toLockfileSource(source)],
-        adapters: {
-            active: null,
-            detected: [],
-        },
-        settings: {
-            autoSync: true,
-        },
-        sync: null,
-        syncHistory: {},
-        syncMode: null,
-        installed: {},
-    };
-}
 async function downloadSkill(skill, catalog, skillsDirPath) {
     const skillTargetDir = path.join(skillsDirPath, skill.id);
-    await removePath(skillTargetDir);
-    await ensureDir(skillTargetDir);
-    for (const relativePath of skill.files) {
-        const remotePath = skill.path ? path.posix.join(skill.path, relativePath) : relativePath;
-        const rawUrl = buildRawGitHubUrl(catalog.repo, catalog.ref, remotePath);
-        const content = await fetchText(rawUrl, { headers: { Accept: "text/plain" } });
-        const localPath = path.join(skillTargetDir, relativePath);
-        await writeText(localPath, content);
-    }
-    await writeDownloadedManifest(skillTargetDir, {
+    await downloadSkillFiles({
+        repo: catalog.repo,
+        ref: catalog.ref,
+        skillRelPath: skill.path,
+        files: skill.files,
+        targetDir: skillTargetDir,
+    });
+    const downloaded = {
         ...skill,
         source: {
             repo: catalog.repo,
             ref: catalog.ref,
             path: skill.path,
         },
-    });
-}
-async function downloadDirectGitHubSkill(skill, skillsDirPath) {
-    const skillTargetDir = path.join(skillsDirPath, skill.manifest.id);
-    await removePath(skillTargetDir);
-    await ensureDir(skillTargetDir);
-    for (const relativePath of skill.manifest.files) {
-        const remotePath = skill.manifest.path ? path.posix.join(skill.manifest.path, relativePath) : relativePath;
-        const rawUrl = buildRawGitHubUrl(skill.repo, skill.ref, remotePath);
-        const content = await fetchText(rawUrl, { headers: { Accept: "text/plain" } });
-        await writeText(path.join(skillTargetDir, relativePath), content);
-    }
-    await writeDownloadedManifest(skillTargetDir, {
-        ...skill.manifest,
-        source: {
-            repo: skill.repo,
-            ref: skill.ref,
-            path: skill.manifest.path,
-        },
-    });
-}
-async function writeDownloadedManifest(skillTargetDir, manifest) {
-    await writeJson(path.join(skillTargetDir, "skill.json"), manifest);
-}
-async function fetchDirectGitHubSkill(reference) {
-    const repoId = `${reference.owner}/${reference.repo}`;
-    const manifestUrl = buildRawGitHubUrl(repoId, reference.ref, "skill.json");
-    const manifest = await fetchOptionalJson(manifestUrl, {
-        headers: { Accept: "application/json" },
-    });
-    if (manifest) {
-        return {
-            repo: repoId,
-            ref: reference.ref,
-            source: `github:${repoId}@${reference.ref}`,
-            manifest: normalizeDirectManifest(manifest, reference),
-        };
-    }
-    const skillMarkdown = await fetchOptionalText(buildRawGitHubUrl(repoId, reference.ref, "SKILL.md"), {
-        headers: { Accept: "text/plain" },
-    });
-    if (!skillMarkdown) {
-        throw new InstallError(`No skill.json or SKILL.md found at ${repoId}@${reference.ref}.`, "DIRECT_SKILL_NOT_FOUND");
-    }
-    const frontmatter = parseSkillFrontmatter(skillMarkdown);
-    return {
-        repo: repoId,
-        ref: reference.ref,
-        source: `github:${repoId}@${reference.ref}`,
-        manifest: {
-            id: normalizeRepoSkillId(reference.repo),
-            name: frontmatter.name || toTitleCase(reference.repo),
-            version: "0.1.0",
-            description: frontmatter.description || `Skill instalada diretamente de ${repoId}.`,
-            author: reference.owner,
-            tags: [],
-            compatibility: [],
-            entry: "SKILL.md",
-            path: "",
-            files: ["SKILL.md"],
-        },
-    };
-}
-function normalizeDirectManifest(manifest, reference) {
-    return {
-        id: manifest.id || normalizeRepoSkillId(reference.repo),
-        name: manifest.name || toTitleCase(reference.repo),
-        version: manifest.version || "0.1.0",
-        description: manifest.description || `Skill instalada diretamente de ${reference.owner}/${reference.repo}.`,
-        author: manifest.author || reference.owner,
-        tags: Array.isArray(manifest.tags) ? manifest.tags : [],
-        compatibility: Array.isArray(manifest.compatibility) ? manifest.compatibility : [],
-        entry: manifest.entry || "SKILL.md",
-        path: manifest.path || "",
-        files: Array.isArray(manifest.files) && manifest.files.length > 0 ? manifest.files : [manifest.entry || "SKILL.md"],
-        ...(manifest.scripts ? { scripts: manifest.scripts } : {}),
-    };
-}
-function normalizeLockfile(existing, source, now) {
-    if (!existing) {
-        return createBaseLockfile(source, now);
-    }
-    const detectedAdapters = Array.isArray(existing.adapters)
-        ? existing.adapters
-        : Array.isArray(existing.adapters?.detected)
-            ? existing.adapters.detected
-            : [];
-    const activeAdapter = Array.isArray(existing.adapters)
-        ? existing.adapters[0] || null
-        : existing.adapters?.active || detectedAdapters[0] || null;
-    return {
-        formatVersion: Number(existing.formatVersion || 1),
-        createdAt: existing.createdAt || now(),
-        updatedAt: existing.updatedAt || now(),
-        sources: getLockfileSources(existing, source),
-        adapters: {
-            active: activeAdapter,
-            detected: [...new Set(detectedAdapters.filter(Boolean))],
-        },
-        settings: {
-            autoSync: existing.settings?.autoSync ?? true,
-        },
-        sync: existing.sync || null,
-        syncHistory: normalizeSyncHistory(existing),
-        syncMode: existing.syncMode || null,
-        installed: existing.installed || {},
-    };
-}
-function normalizeSyncHistory(existing) {
-    const history = {};
-    const candidate = existing && "syncHistory" in existing && existing.syncHistory && typeof existing.syncHistory === "object"
-        ? existing.syncHistory
-        : null;
-    if (candidate) {
-        for (const [adapterId, metadata] of Object.entries(candidate)) {
-            if (!metadata || typeof metadata !== "object") {
-                continue;
-            }
-            if (!("adapter" in metadata) || !("targetPath" in metadata) || !("syncedAt" in metadata)) {
-                continue;
-            }
-            history[adapterId] = metadata;
-        }
-    }
-    if (existing?.sync?.adapter && !history[existing.sync.adapter]) {
-        history[existing.sync.adapter] = existing.sync;
-    }
-    return history;
-}
-/** Repos that are known placeholder values written by older versions and must be ignored. */
-const PLACEHOLDER_REPOS = new Set(["owner/repo"]);
-function getLockfileSources(existing, fallbackSource) {
-    const legacyCatalog = getLegacyCatalog(existing);
-    const configuredSources = Array.isArray(existing?.sources)
-        ? existing.sources
-            .filter((entry) => Boolean(entry?.repo))
-            .filter((entry) => !PLACEHOLDER_REPOS.has(entry.repo))
-            .map((entry) => ({
-            repo: entry.repo,
-            ref: entry.ref || DEFAULT_REF,
-            ...(entry.label ? { label: entry.label } : {}),
-        }))
-        : [];
-    if (configuredSources.length > 0) {
-        return dedupeSources(configuredSources);
-    }
-    if (legacyCatalog?.repo && !PLACEHOLDER_REPOS.has(legacyCatalog.repo)) {
-        return dedupeSources([
-            {
-                repo: legacyCatalog.repo,
-                ref: legacyCatalog.ref || DEFAULT_REF,
-            },
-        ]);
-    }
-    return [toLockfileSource(fallbackSource)];
-}
-function getLegacyCatalog(existing) {
-    if (!existing || !("catalog" in existing)) {
-        return null;
-    }
-    const legacyState = existing;
-    return legacyState.catalog || null;
-}
-function dedupeSources(sources) {
-    const unique = new Map();
-    for (const source of sources) {
-        const key = `${source.repo}@${source.ref}`;
-        if (!unique.has(key)) {
-            unique.set(key, source);
-        }
-    }
-    return [...unique.values()];
-}
-function toLockfileSource(source, label) {
-    return {
-        repo: source.repo,
-        ref: source.ref,
-        ...((label || source.repo === DEFAULT_REPO) && (label || source.repo === DEFAULT_REPO)
-            ? { label: label || "official" }
-            : {}),
     };
+    await writeDownloadedManifest(skillTargetDir, downloaded);
 }
 function resolvePrimarySourceOverride(options, existing) {
     const sources = getLockfileSources(existing, resolveSource(toCatalogSourceInput(options)));
@@ -849,16 +660,6 @@ async function resolveInstalledCatalogSelection(skillId, sourceRef, options, loc
     }
     return null;
 }
-function parseCatalogSource(source) {
-    const match = source.match(/^catalog:([^@]+\/[^@]+)@(.+)$/);
-    if (!match) {
-        return null;
-    }
-    return {
-        repo: match[1],
-        ref: match[2],
-    };
-}
 function buildInstalledMetadata(skill, context) {
     return {
         name: skill.name,
@@ -894,69 +695,6 @@ function getNow(options) {
 function toPosix(value) {
     return value.split(path.sep).join("/");
 }
-async function maybeAutoSync(options) {
-    if (!options.enabled || !options.changed) {
-        return null;
-    }
-    if (resolveSyncAdapterIds(options.adapters, options.adapterOverride).length === 0) {
-        return null;
-    }
-    return syncInstalledSkills({
-        cwd: options.cwd,
-        scope: options.scope || DEFAULT_INSTALL_SCOPE,
-        ...(options.agentSkillsDir ? { agentSkillsDir: options.agentSkillsDir } : {}),
-        ...(options.adapterOverride ? { adapter: options.adapterOverride } : {}),
-        ...(options.mode ? { mode: options.mode } : {}),
-        now: options.now,
-    });
-}
-async function maybeSyncAfterRemove(options) {
-    if (!options.changed) {
-        return null;
-    }
-    const adapters = new Set();
-    for (const adapterId of Object.keys(options.syncHistory || {})) {
-        adapters.add(adapterId);
-    }
-    if (options.legacySync?.adapter) {
-        adapters.add(options.legacySync.adapter);
-    }
-    if (options.adapterOverride) {
-        adapters.add(options.adapterOverride);
-    }
-    else if (options.enabled) {
-        for (const adapterId of resolveSyncAdapterIds(options.adapters)) {
-            adapters.add(adapterId);
-        }
-    }
-    let result = null;
-    for (const adapterId of adapters) {
-        result = await syncInstalledSkills({
-            cwd: options.cwd,
-            scope: options.scope || DEFAULT_INSTALL_SCOPE,
-            ...(options.agentSkillsDir ? { agentSkillsDir: options.agentSkillsDir } : {}),
-            adapter: adapterId,
-            ...(options.mode ? { mode: options.mode } : {}),
-            now: options.now,
-        });
-    }
-    return result;
-}
-function resolveSyncAdapterIds(adapters, adapterOverride) {
-    if (adapterOverride) {
-        return [adapterOverride];
-    }
-    const adapterIds = [];
-    if (adapters.active) {
-        adapterIds.push(adapters.active);
-    }
-    for (const adapterId of adapters.detected || []) {
-        if (!adapterIds.includes(adapterId)) {
-            adapterIds.push(adapterId);
-        }
-    }
-    return adapterIds;
-}
 function toCatalogSourceInput(options, overrides = {}) {
     const input = {};
     if (options.owner) {
@@ -997,36 +735,6 @@ function resolveStatePathsForOptions(cwd, options) {
 function resolveInstalledSkillPath(cwd, skillPath) {
     return path.isAbsolute(skillPath) ? skillPath : path.resolve(cwd, skillPath);
 }
-async function confirmDirectInstall(skillRef, options) {
-    const warning = `Warning: ${skillRef} will be installed directly from GitHub and has not been verified by the active catalog.`;
-    (options.warn || console.error)(warning);
-    const confirm = options.confirm || (() => confirmAction("Continuar com a instalacao direta?"));
-    const accepted = await confirm();
-    if (!accepted) {
-        throw new InstallError("Instalacao direta cancelada pelo usuario.", "INSTALL_CANCELLED");
-    }
-}
-function parseGitHubSource(source) {
-    if (!source.startsWith("github:")) {
-        return null;
-    }
-    const withoutPrefix = source.slice("github:".length);
-    const separatorIndex = withoutPrefix.lastIndexOf("@");
-    if (separatorIndex <= 0) {
-        return null;
-    }
-    return parseDirectGitHubRef(`${withoutPrefix.slice(0, separatorIndex)}@${withoutPrefix.slice(separatorIndex + 1)}`);
-}
-function normalizeRepoSkillId(repo) {
-    return repo.trim().toLowerCase();
-}
-function toTitleCase(skillId) {
-    return skillId
-        .split("-")
-        .filter(Boolean)
-        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-        .join(" ");
-}
 function toInstallError(error, fallbackMessage) {
     if (error instanceof InstallError) {
         return error;
@@ -1034,6 +742,25 @@ function toInstallError(error, fallbackMessage) {
     if (error instanceof CliError) {
         return new InstallError(error.message, error.code);
     }
-    const message = error instanceof Error ? error.message : String(error);
-    return new InstallError(`${fallbackMessage}: ${message}`);
-}
+    // Preserve the underlying error code when present (HttpError, NodeJS.ErrnoException, etc.)
+    // so callers can react programmatically to specific failure modes such as
+    // HTTP_RATE_LIMIT, HTTP_TIMEOUT, EACCES, ENOENT, etc.
+    const underlyingCode = error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : null;
+    const baseMessage = error instanceof Error ? error.message : String(error);
+    const annotatedMessage = underlyingCode
+        ? `${fallbackMessage}: ${baseMessage} (${underlyingCode})`
+        : `${fallbackMessage}: ${baseMessage}`;
+    return new InstallError(annotatedMessage, underlyingCode || "INSTALL_ERROR");
+}
+// Silence unused-import warnings while keeping the symbols available as named re-exports.
+void DEFAULT_AGENT_SKILLS_DIR;
+void DEFAULT_REF;
+void DEFAULT_REPO;
+void dedupeSources;
+void normalizeSyncHistory;
+void normalizeDirectManifest;
+void createBaseLockfile;
+void PLACEHOLDER_REPOS;
+void resolveSyncAdapterIds;

package/dist/lockfile.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Lockfile shape, normalization, source-list management, and migration helpers.
+ *
+ * Keeps `install.ts` focused on install/update/remove orchestration. All
+ * callers should import from here directly; `install.ts` re-exports these
+ * symbols for backward compatibility with existing test imports.
+ */
+import type { CatalogSource, LockfileSource, LockfileState, NowFn, SyncHistory } from "./types.js";
+/** Repos that are known placeholder values written by older versions and must be ignored. */
+export declare const PLACEHOLDER_REPOS: Set<string>;
+/**
+ * Builds an empty lockfile seeded with a single source and `autoSync` on by default.
+ */
+export declare function createBaseLockfile(source: CatalogSource, now: NowFn): LockfileState;
+/**
+ * Normalizes a possibly-legacy lockfile shape into the current `LockfileState`.
+ * Handles arrays-of-strings adapters from very old versions, missing
+ * `syncHistory`, and the deprecated single `sync` field.
+ */
+export declare function normalizeLockfile(existing: LockfileState | null, source: CatalogSource, now: NowFn): LockfileState;
+/**
+ * Coerces the historic and current shapes of `syncHistory` into the
+ * normalized form, including a fallback that rebuilds the history from a
+ * legacy single-`sync` field.
+ */
+export declare function normalizeSyncHistory(existing: LockfileState | null): SyncHistory;
+/**
+ * Resolves the configured source list, dropping placeholders and falling back
+ * to legacy single-catalog metadata when no `sources` array exists.
+ */
+export declare function getLockfileSources(existing: LockfileState | null, fallbackSource: CatalogSource): LockfileSource[];
+/**
+ * Deduplicates a source list keyed by `${repo}@${ref}`, preserving the
+ * first occurrence (which carries any label).
+ */
+export declare function dedupeSources(sources: LockfileSource[]): LockfileSource[];
+/**
+ * Converts a `CatalogSource` to a `LockfileSource`, attaching a label only
+ * when one is explicitly provided or when the source is the default
+ * first-party repo (which gets the `official` label automatically).
+ */
+export declare function toLockfileSource(source: CatalogSource, label?: string): LockfileSource;
+/**
+ * Parses a `catalog:owner/repo@ref` source string into a `LockfileSource`.
+ */
+export declare function parseCatalogSource(source: string): LockfileSource | null;