skillex 0.2.0

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+import type { StatePaths } from "./types.js";
+export declare const DEFAULT_AGENT_SKILLS_DIR = ".agent-skills";
+export declare const DEFAULT_LOCKFILE = "skills.json";
+export declare const DEFAULT_LOCAL_SKILLS_DIR = "skills";
+export declare const DEFAULT_GENERATED_DIR = "generated";
+export declare const DEFAULT_CATALOG_PATH = "catalog.json";
+export declare const DEFAULT_SKILLS_DIR = "skills";
+export declare const DEFAULT_REPO = "lgili/skillex";
+export declare const DEFAULT_REF = "main";
+/**
+ * Resolves the managed workspace state paths used by Skillex.
+ *
+ * @param cwd - Workspace root.
+ * @param baseDir - Managed local state directory.
+ * @returns Absolute paths for the state directory and lockfile.
+ */
+export declare function getStatePaths(cwd: string, baseDir?: string): StatePaths;

package/dist/config.js

@@ -0,0 +1,25 @@
+import * as path from "node:path";
+export const DEFAULT_AGENT_SKILLS_DIR = ".agent-skills";
+export const DEFAULT_LOCKFILE = "skills.json";
+export const DEFAULT_LOCAL_SKILLS_DIR = "skills";
+export const DEFAULT_GENERATED_DIR = "generated";
+export const DEFAULT_CATALOG_PATH = "catalog.json";
+export const DEFAULT_SKILLS_DIR = "skills";
+export const DEFAULT_REPO = "lgili/skillex";
+export const DEFAULT_REF = "main";
+/**
+ * Resolves the managed workspace state paths used by Skillex.
+ *
+ * @param cwd - Workspace root.
+ * @param baseDir - Managed local state directory.
+ * @returns Absolute paths for the state directory and lockfile.
+ */
+export function getStatePaths(cwd, baseDir = DEFAULT_AGENT_SKILLS_DIR) {
+    const stateDir = path.resolve(cwd, baseDir);
+    return {
+        stateDir,
+        lockfilePath: path.join(stateDir, DEFAULT_LOCKFILE),
+        skillsDirPath: path.join(stateDir, DEFAULT_LOCAL_SKILLS_DIR),
+        generatedDirPath: path.join(stateDir, DEFAULT_GENERATED_DIR),
+    };
+}

package/dist/confirm.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Prompts the user for a yes/no confirmation in interactive terminals.
+ *
+ * @param message - Prompt shown to the user.
+ * @returns `true` when the user confirms.
+ * @throws {CliError} When interactive input is unavailable.
+ */
+export declare function confirmAction(message: string): Promise<boolean>;

package/dist/confirm.js

@@ -0,0 +1,24 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { CliError } from "./types.js";
+/**
+ * Prompts the user for a yes/no confirmation in interactive terminals.
+ *
+ * @param message - Prompt shown to the user.
+ * @returns `true` when the user confirms.
+ * @throws {CliError} When interactive input is unavailable.
+ */
+export async function confirmAction(message) {
+    if (!input.isTTY || !output.isTTY) {
+        throw new CliError("Confirmacao interativa indisponivel neste terminal. Use a flag correspondente.", "TTY_REQUIRED");
+    }
+    const rl = createInterface({ input, output });
+    try {
+        const answer = await rl.question(`${message} [y/N] `);
+        const normalized = answer.trim().toLowerCase();
+        return normalized === "y" || normalized === "yes" || normalized === "s" || normalized === "sim";
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/fs.d.ts

@@ -0,0 +1,79 @@
+import type { CreateSymlinkResult } from "./types.js";
+/**
+ * Checks whether a file or directory exists.
+ *
+ * @param targetPath - Absolute or relative path to probe.
+ * @returns `true` when the target exists.
+ */
+export declare function pathExists(targetPath: string): Promise<boolean>;
+/**
+ * Ensures that a directory exists.
+ *
+ * @param dirPath - Directory path to create.
+ */
+export declare function ensureDir(dirPath: string): Promise<void>;
+/**
+ * Reads and parses a JSON file, returning a fallback when the file is missing.
+ *
+ * @param filePath - JSON file path.
+ * @param fallback - Value returned for missing files.
+ * @returns Parsed JSON content or the fallback value.
+ */
+export declare function readJson<T>(filePath: string, fallback?: T | null): Promise<T | null>;
+/**
+ * Reads a UTF-8 text file, returning a fallback when the file is missing.
+ *
+ * @param filePath - Text file path.
+ * @param fallback - Value returned for missing files.
+ * @returns File content or the fallback value.
+ */
+export declare function readText(filePath: string, fallback?: string | null): Promise<string | null>;
+/**
+ * Writes a JSON value to disk with stable pretty-print formatting.
+ *
+ * @param filePath - Output file path.
+ * @param value - Serializable JSON value.
+ */
+export declare function writeJson(filePath: string, value: unknown): Promise<void>;
+/**
+ * Writes UTF-8 text content to disk.
+ *
+ * @param filePath - Output file path.
+ * @param value - Text content to write.
+ */
+export declare function writeText(filePath: string, value: string): Promise<void>;
+/**
+ * Removes a file or directory recursively when present.
+ *
+ * @param targetPath - File system path to remove.
+ */
+export declare function removePath(targetPath: string): Promise<void>;
+/**
+ * Creates a relative symlink and reports whether the caller should fall back to copy mode.
+ *
+ * @param targetPath - Absolute path the link should point to.
+ * @param linkPath - Absolute path of the symlink to create.
+ * @returns Symlink creation result.
+ */
+export declare function createSymlink(targetPath: string, linkPath: string): Promise<CreateSymlinkResult>;
+/**
+ * Removes a symlink without following it.
+ *
+ * @param linkPath - Link path to remove when present.
+ */
+export declare function removeSymlink(linkPath: string): Promise<void>;
+/**
+ * Reads a symlink target when the path is a symbolic link.
+ *
+ * @param linkPath - Candidate link path.
+ * @returns Link target or `null` when the path is missing or not a symlink.
+ */
+export declare function readSymlink(linkPath: string): Promise<string | null>;
+/**
+ * Validates and normalizes a safe relative path.
+ *
+ * @param relativePath - Candidate relative path.
+ * @returns Normalized POSIX relative path.
+ * @throws {ValidationError} When the path is empty, absolute, or escapes the root.
+ */
+export declare function assertSafeRelativePath(relativePath: string): string;

package/dist/fs.js

@@ -0,0 +1,184 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { ValidationError } from "./types.js";
+/**
+ * Checks whether a file or directory exists.
+ *
+ * @param targetPath - Absolute or relative path to probe.
+ * @returns `true` when the target exists.
+ */
+export async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensures that a directory exists.
+ *
+ * @param dirPath - Directory path to create.
+ */
+export async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+/**
+ * Reads and parses a JSON file, returning a fallback when the file is missing.
+ *
+ * @param filePath - JSON file path.
+ * @param fallback - Value returned for missing files.
+ * @returns Parsed JSON content or the fallback value.
+ */
+export async function readJson(filePath, fallback = null) {
+    try {
+        const content = await fs.readFile(filePath, "utf8");
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            return fallback;
+        }
+        throw error;
+    }
+}
+/**
+ * Reads a UTF-8 text file, returning a fallback when the file is missing.
+ *
+ * @param filePath - Text file path.
+ * @param fallback - Value returned for missing files.
+ * @returns File content or the fallback value.
+ */
+export async function readText(filePath, fallback = null) {
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            return fallback;
+        }
+        throw error;
+    }
+}
+/**
+ * Writes a JSON value to disk with stable pretty-print formatting.
+ *
+ * @param filePath - Output file path.
+ * @param value - Serializable JSON value.
+ */
+export async function writeJson(filePath, value) {
+    await ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+/**
+ * Writes UTF-8 text content to disk.
+ *
+ * @param filePath - Output file path.
+ * @param value - Text content to write.
+ */
+export async function writeText(filePath, value) {
+    await ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, value, "utf8");
+}
+/**
+ * Removes a file or directory recursively when present.
+ *
+ * @param targetPath - File system path to remove.
+ */
+export async function removePath(targetPath) {
+    await fs.rm(targetPath, { recursive: true, force: true });
+}
+/**
+ * Creates a relative symlink and reports whether the caller should fall back to copy mode.
+ *
+ * @param targetPath - Absolute path the link should point to.
+ * @param linkPath - Absolute path of the symlink to create.
+ * @returns Symlink creation result.
+ */
+export async function createSymlink(targetPath, linkPath) {
+    const relativeTarget = path.relative(path.dirname(linkPath), targetPath) || ".";
+    await ensureDir(path.dirname(linkPath));
+    await removePath(linkPath);
+    try {
+        await fs.symlink(relativeTarget, linkPath);
+        return {
+            ok: true,
+            fallback: false,
+            relativeTarget,
+        };
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            (error.code === "EPERM" || error.code === "ENOTSUP")) {
+            return {
+                ok: false,
+                fallback: true,
+                relativeTarget,
+            };
+        }
+        throw error;
+    }
+}
+/**
+ * Removes a symlink without following it.
+ *
+ * @param linkPath - Link path to remove when present.
+ */
+export async function removeSymlink(linkPath) {
+    try {
+        const stats = await fs.lstat(linkPath);
+        if (stats.isSymbolicLink()) {
+            await fs.unlink(linkPath);
+        }
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+}
+/**
+ * Reads a symlink target when the path is a symbolic link.
+ *
+ * @param linkPath - Candidate link path.
+ * @returns Link target or `null` when the path is missing or not a symlink.
+ */
+export async function readSymlink(linkPath) {
+    try {
+        const stats = await fs.lstat(linkPath);
+        if (!stats.isSymbolicLink()) {
+            return null;
+        }
+        return await fs.readlink(linkPath);
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Validates and normalizes a safe relative path.
+ *
+ * @param relativePath - Candidate relative path.
+ * @returns Normalized POSIX relative path.
+ * @throws {ValidationError} When the path is empty, absolute, or escapes the root.
+ */
+export function assertSafeRelativePath(relativePath) {
+    if (!relativePath || relativePath.includes("\0")) {
+        throw new ValidationError(`Caminho invalido: "${relativePath}"`);
+    }
+    const normalized = path.posix.normalize(relativePath);
+    if (normalized.startsWith("../") ||
+        normalized === ".." ||
+        path.isAbsolute(relativePath) ||
+        normalized.startsWith("/")) {
+        throw new ValidationError(`Caminho inseguro detectado: "${relativePath}"`);
+    }
+    return normalized;
+}

package/dist/http.d.ts

@@ -0,0 +1,43 @@
+/**
+ * HTTP fetch utilities with GitHub API support.
+ *
+ * Automatically attaches GitHub headers and, when `GITHUB_TOKEN` is set in
+ * the environment, an `Authorization: Bearer` header to raise the API rate
+ * limit from 60 to 5,000 requests per hour.
+ */
+/**
+ * Fetches a JSON document and parses it with default Skillex headers.
+ *
+ * @param url - Target URL.
+ * @param init - Fetch init overrides.
+ * @returns Parsed JSON payload.
+ * @throws {Error} With an actionable message on HTTP errors.
+ */
+export declare function fetchJson<T>(url: string, init?: RequestInit): Promise<T>;
+/**
+ * Fetches a UTF-8 text resource with default Skillex headers.
+ *
+ * @param url - Target URL.
+ * @param init - Fetch init overrides.
+ * @returns Response text body.
+ * @throws {Error} With an actionable message on HTTP errors.
+ */
+export declare function fetchText(url: string, init?: RequestInit): Promise<string>;
+/**
+ * Fetches a UTF-8 text resource and returns `null` when the resource does not exist.
+ *
+ * @param url - Target URL.
+ * @param init - Fetch init overrides.
+ * @returns Response text body or `null` for HTTP 404.
+ * @throws {Error} With an actionable message on non-404 HTTP errors.
+ */
+export declare function fetchOptionalText(url: string, init?: RequestInit): Promise<string | null>;
+/**
+ * Fetches a JSON document and returns `null` when the resource does not exist.
+ *
+ * @param url - Target URL.
+ * @param init - Fetch init overrides.
+ * @returns Parsed JSON payload or `null` for HTTP 404.
+ * @throws {Error} With an actionable message on non-404 HTTP errors.
+ */
+export declare function fetchOptionalJson<T>(url: string, init?: RequestInit): Promise<T | null>;

package/dist/http.js

@@ -0,0 +1,123 @@
+/**
+ * HTTP fetch utilities with GitHub API support.
+ *
+ * Automatically attaches GitHub headers and, when `GITHUB_TOKEN` is set in
+ * the environment, an `Authorization: Bearer` header to raise the API rate
+ * limit from 60 to 5,000 requests per hour.
+ */
+import { debug } from "./output.js";
+/**
+ * Fetches a JSON document and parses it with default Skillex headers.
+ *
+ * @param url - Target URL.
+ * @param init - Fetch init overrides.
+ * @returns Parsed JSON payload.
+ * @throws {Error} With an actionable message on HTTP errors.
+ */
+export async function fetchJson(url, init = {}) {
+    debug(`GET ${url}`);
+    const response = await fetch(url, withDefaultHeaders(init));
+    debug(`${response.status} ${url}`);
+    if (!response.ok) {
+        throw new Error(buildHttpErrorMessage(url, response.status));
+    }
+    return (await response.json());
+}
+/**
+ * Fetches a UTF-8 text resource with default Skillex headers.
+ *
+ * @param url - Target URL.
+ * @param init - Fetch init overrides.
+ * @returns Response text body.
+ * @throws {Error} With an actionable message on HTTP errors.
+ */
+export async function fetchText(url, init = {}) {
+    debug(`GET ${url}`);
+    const response = await fetch(url, withDefaultHeaders(init));
+    debug(`${response.status} ${url}`);
+    if (!response.ok) {
+        throw new Error(buildHttpErrorMessage(url, response.status));
+    }
+    return response.text();
+}
+/**
+ * Fetches a UTF-8 text resource and returns `null` when the resource does not exist.
+ *
+ * @param url - Target URL.
+ * @param init - Fetch init overrides.
+ * @returns Response text body or `null` for HTTP 404.
+ * @throws {Error} With an actionable message on non-404 HTTP errors.
+ */
+export async function fetchOptionalText(url, init = {}) {
+    debug(`GET ${url}`);
+    const response = await fetch(url, withDefaultHeaders(init));
+    debug(`${response.status} ${url}`);
+    if (response.status === 404) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(buildHttpErrorMessage(url, response.status));
+    }
+    return response.text();
+}
+/**
+ * Fetches a JSON document and returns `null` when the resource does not exist.
+ *
+ * @param url - Target URL.
+ * @param init - Fetch init overrides.
+ * @returns Parsed JSON payload or `null` for HTTP 404.
+ * @throws {Error} With an actionable message on non-404 HTTP errors.
+ */
+export async function fetchOptionalJson(url, init = {}) {
+    debug(`GET ${url}`);
+    const response = await fetch(url, withDefaultHeaders(init));
+    debug(`${response.status} ${url}`);
+    if (response.status === 404) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(buildHttpErrorMessage(url, response.status));
+    }
+    return (await response.json());
+}
+/**
+ * Applies default HTTP headers expected by GitHub-hosted catalog requests.
+ * Attaches `Authorization: Bearer` when `GITHUB_TOKEN` is set in the environment.
+ *
+ * @param init - User-supplied fetch options.
+ * @returns Fetch options with default headers merged in.
+ */
+function withDefaultHeaders(init) {
+    const headers = new Headers(init.headers || {});
+    if (!headers.has("User-Agent")) {
+        headers.set("User-Agent", "skillex");
+    }
+    if (!headers.has("Accept")) {
+        headers.set("Accept", "application/vnd.github+json");
+    }
+    const token = process.env.GITHUB_TOKEN;
+    if (token && !headers.has("Authorization")) {
+        headers.set("Authorization", `Bearer ${token}`);
+        debug("Using GITHUB_TOKEN for authentication");
+    }
+    return { ...init, headers };
+}
+/**
+ * Builds a human-readable, actionable error message for HTTP failures.
+ *
+ * @param url - The URL that failed.
+ * @param status - HTTP response status code.
+ * @returns Descriptive error message.
+ */
+function buildHttpErrorMessage(url, status) {
+    if (status === 403) {
+        return "GitHub API rate limit exceeded or access denied. Set the GITHUB_TOKEN environment variable to authenticate.";
+    }
+    if (status === 404) {
+        return `Repository or file not found. Check that --repo is correct and the repository is public. (${url})`;
+    }
+    if (status >= 500) {
+        return `GitHub API returned a server error (${status}). Try again in a moment.`;
+    }
+    return `Failed to fetch ${url} (HTTP ${status})`;
+}

package/dist/install.d.ts

@@ -0,0 +1,115 @@
+import type { AggregatedCatalogData, CatalogLoader, CatalogSource, DirectGitHubRef, InitProjectResult, InstallSkillsResult, LockfileSource, LockfileState, ProjectOptions, RemoveSkillsResult, SkillDownloader, SyncCommandResult, UpdateInstalledSkillsResult } from "./types.js";
+interface InstallOptions extends ProjectOptions {
+    catalogLoader?: CatalogLoader;
+    downloader?: SkillDownloader;
+    installAll?: boolean;
+    confirm?: (() => Promise<boolean>) | undefined;
+    warn?: ((message: string) => void) | undefined;
+}
+/**
+ * Initializes the local Skillex workspace state.
+ *
+ * @param options - Project initialization options.
+ * @returns Lockfile initialization result.
+ * @throws {InstallError} When initialization fails.
+ */
+export declare function initProject(options?: ProjectOptions): Promise<InitProjectResult>;
+/**
+ * Installs one or more catalog skills or direct GitHub skills into the local workspace state.
+ *
+ * @param requestedSkillIds - Requested skill ids or `owner/repo[@ref]` direct references.
+ * @param options - Installation options.
+ * @returns Install summary.
+ * @throws {InstallError} When installation fails.
+ */
+export declare function installSkills(requestedSkillIds: string[], options?: InstallOptions): Promise<InstallSkillsResult>;
+/**
+ * Updates installed skills from the configured remote catalog or their direct GitHub sources.
+ *
+ * @param requestedSkillIds - Optional subset of installed skills to update.
+ * @param options - Update options.
+ * @returns Update summary.
+ * @throws {InstallError} When update fails.
+ */
+export declare function updateInstalledSkills(requestedSkillIds: string[], options?: InstallOptions): Promise<UpdateInstalledSkillsResult>;
+/**
+ * Removes installed skills from the local workspace state.
+ *
+ * @param requestedSkillIds - Skill ids to remove.
+ * @param options - Remove options.
+ * @returns Remove summary.
+ * @throws {InstallError} When removal fails.
+ */
+export declare function removeSkills(requestedSkillIds: string[], options?: ProjectOptions): Promise<RemoveSkillsResult>;
+/**
+ * Synchronizes installed skills to the active or requested adapter target.
+ *
+ * @param options - Sync options.
+ * @returns Sync command result.
+ * @throws {InstallError} When workspace state is missing or invalid.
+ */
+export declare function syncInstalledSkills(options?: ProjectOptions): Promise<SyncCommandResult>;
+/**
+ * Reads the local workspace lockfile when it exists.
+ *
+ * @param options - Project lookup options.
+ * @returns Normalized lockfile state or `null` when no install exists.
+ */
+export declare function getInstalledSkills(options?: ProjectOptions): Promise<LockfileState | null>;
+/**
+ * Resolves the effective project catalog source using CLI overrides or local state.
+ *
+ * @param options - Project lookup options.
+ * @returns Resolved catalog source.
+ */
+export declare function resolveProjectSource(options?: ProjectOptions): Promise<CatalogSource>;
+/**
+ * Resolves all effective project sources using CLI overrides or local state.
+ *
+ * @param options - Project lookup options.
+ * @returns Resolved source list.
+ */
+export declare function resolveProjectSources(options?: ProjectOptions): Promise<LockfileSource[]>;
+/**
+ * Aggregates skills from all effective project sources.
+ *
+ * @param options - Project lookup options.
+ * @param catalogLoader - Optional catalog loader override.
+ * @returns Aggregated skills grouped by source metadata.
+ */
+export declare function loadProjectCatalogs(options?: ProjectOptions, catalogLoader?: CatalogLoader): Promise<AggregatedCatalogData>;
+/**
+ * Adds a source to the workspace lockfile.
+ *
+ * @param sourceInput - Repository to add.
+ * @param options - Project options.
+ * @returns Updated normalized lockfile.
+ */
+export declare function addProjectSource(sourceInput: {
+    repo: string;
+    ref?: string | undefined;
+    label?: string | undefined;
+}, options?: ProjectOptions): Promise<LockfileState>;
+/**
+ * Removes a source from the workspace lockfile.
+ *
+ * @param repo - Repository to remove.
+ * @param options - Project options.
+ * @returns Updated normalized lockfile.
+ */
+export declare function removeProjectSource(repo: string, options?: ProjectOptions): Promise<LockfileState>;
+/**
+ * Lists configured workspace sources.
+ *
+ * @param options - Project options.
+ * @returns Normalized source list.
+ */
+export declare function listProjectSources(options?: ProjectOptions): Promise<LockfileSource[]>;
+/**
+ * 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 declare function parseDirectGitHubRef(input: string): DirectGitHubRef | null;
+export {};