skillex 0.2.0

package/bin/skillex.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { main } from "../dist/cli.js";
+import { CliError } from "../dist/types.js";
+
+main(process.argv.slice(2)).catch((error) => {
+  const message =
+    error instanceof CliError || error instanceof Error ? error.message : String(error);
+  console.error(`Error: ${message}`);
+  process.exitCode = 1;
+});

package/dist/adapters.d.ts

@@ -0,0 +1,60 @@
+import type { AdapterConfig, AdapterState } from "./types.js";
+/**
+ * Lists supported adapters for CLI help and UI display.
+ *
+ * @returns Lightweight adapter descriptors.
+ */
+export declare function listAdapters(): Array<Pick<AdapterConfig, "id" | "label">>;
+/**
+ * Lists canonical adapter identifiers.
+ *
+ * @returns Supported adapter ids.
+ */
+export declare function listAdapterIds(): string[];
+/**
+ * Normalizes adapter aliases to canonical adapter identifiers.
+ *
+ * @param adapterId - User-supplied adapter identifier.
+ * @returns Canonical adapter id or `null` when empty.
+ */
+export declare function normalizeAdapterId(adapterId: string | null | undefined): string | null;
+/**
+ * Normalizes a list of adapter identifiers or aliases.
+ *
+ * @param values - Adapter values as a list or comma-separated string.
+ * @returns Canonical adapter ids without duplicates.
+ */
+export declare function normalizeAdapterList(values: string[] | string | null | undefined): string[];
+/**
+ * Checks whether an adapter id or alias maps to a supported adapter.
+ *
+ * @param adapterId - Adapter identifier to check.
+ * @returns `true` when the adapter is known.
+ */
+export declare function isKnownAdapter(adapterId: string | null | undefined): boolean;
+/**
+ * Resolves a canonical adapter configuration by id or alias.
+ *
+ * @param adapterId - Adapter identifier to resolve.
+ * @returns Adapter configuration.
+ * @throws {AdapterNotFoundError} When the adapter is unknown.
+ */
+export declare function getAdapter(adapterId: string): AdapterConfig;
+/**
+ * Detects supported adapters present in a workspace and orders them by specificity.
+ *
+ * @param cwd - Workspace root.
+ * @returns Ordered list of detected adapter ids.
+ */
+export declare function detectAdapters(cwd: string): Promise<string[]>;
+/**
+ * Resolves the active adapter state for a workspace.
+ *
+ * @param options - Resolution options including cwd and optional adapter override.
+ * @returns Active and detected adapter ids.
+ * @throws {AdapterNotFoundError} When the explicit override is unknown.
+ */
+export declare function resolveAdapterState(options?: {
+    cwd?: string | undefined;
+    adapter?: string | undefined;
+}): Promise<AdapterState>;

package/dist/adapters.js

@@ -0,0 +1,213 @@
+import * as path from "node:path";
+import { pathExists } from "./fs.js";
+import { AdapterNotFoundError } from "./types.js";
+const ADAPTERS = [
+    {
+        id: "codex",
+        label: "OpenAI Codex",
+        markers: [
+            { path: "AGENTS.md", weight: 1 },
+            { path: ".codex", weight: 12 },
+            { path: ".codex/skills", weight: 16 },
+        ],
+        syncTarget: "AGENTS.md",
+        syncMode: "managed-block",
+    },
+    {
+        id: "copilot",
+        label: "GitHub Copilot",
+        markers: [{ path: ".github/copilot-instructions.md", weight: 16 }],
+        syncTarget: ".github/copilot-instructions.md",
+        syncMode: "managed-block",
+    },
+    {
+        id: "cline",
+        label: "Cline / Roo Code",
+        markers: [
+            { path: ".cline", weight: 16 },
+            { path: ".roo", weight: 16 },
+            { path: ".clinerules", weight: 12 },
+            { path: ".roo/rules", weight: 12 },
+        ],
+        syncTarget: ".clinerules/skillex-skills.md",
+        legacySyncTargets: [".clinerules/askill-skills.md"],
+        syncMode: "managed-file",
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        markers: [
+            { path: ".cursor", weight: 16 },
+            { path: ".cursor/rules", weight: 18 },
+            { path: ".cursorrules", weight: 12 },
+        ],
+        syncTarget: ".cursor/rules/skillex-skills.mdc",
+        legacySyncTargets: [".cursor/rules/askill-skills.mdc"],
+        syncMode: "managed-file",
+    },
+    {
+        id: "claude",
+        label: "Claude Code",
+        markers: [
+            { path: "CLAUDE.md", weight: 16 },
+            { path: ".claude", weight: 18 },
+        ],
+        syncTarget: "CLAUDE.md",
+        syncMode: "managed-block",
+    },
+    {
+        id: "gemini",
+        label: "Gemini CLI",
+        markers: [
+            { path: "GEMINI.md", weight: 16 },
+            { path: ".gemini", weight: 18 },
+        ],
+        syncTarget: "GEMINI.md",
+        syncMode: "managed-block",
+    },
+    {
+        id: "windsurf",
+        label: "Windsurf",
+        markers: [
+            { path: ".windsurf", weight: 16 },
+            { path: ".windsurf/rules", weight: 18 },
+        ],
+        syncTarget: ".windsurf/rules/skillex-skills.md",
+        legacySyncTargets: [".windsurf/rules/askill-skills.md"],
+        syncMode: "managed-file",
+    },
+];
+const ADAPTER_INDEX = new Map(ADAPTERS.map((adapter, index) => [adapter.id, index]));
+const ADAPTER_ALIASES = new Map([
+    ["github-copilot", "copilot"],
+    ["roo", "cline"],
+    ["roo-code", "cline"],
+    ["claude-code", "claude"],
+    ["gemini-cli", "gemini"],
+    ["codeium", "windsurf"],
+    ["codeium-windsurf", "windsurf"],
+]);
+/**
+ * Lists supported adapters for CLI help and UI display.
+ *
+ * @returns Lightweight adapter descriptors.
+ */
+export function listAdapters() {
+    return ADAPTERS.map((adapter) => ({
+        id: adapter.id,
+        label: adapter.label,
+    }));
+}
+/**
+ * Lists canonical adapter identifiers.
+ *
+ * @returns Supported adapter ids.
+ */
+export function listAdapterIds() {
+    return ADAPTERS.map((adapter) => adapter.id);
+}
+/**
+ * Normalizes adapter aliases to canonical adapter identifiers.
+ *
+ * @param adapterId - User-supplied adapter identifier.
+ * @returns Canonical adapter id or `null` when empty.
+ */
+export function normalizeAdapterId(adapterId) {
+    if (adapterId === undefined || adapterId === null) {
+        return null;
+    }
+    const normalized = String(adapterId).trim().toLowerCase();
+    if (!normalized) {
+        return null;
+    }
+    return ADAPTER_ALIASES.get(normalized) || normalized;
+}
+/**
+ * Normalizes a list of adapter identifiers or aliases.
+ *
+ * @param values - Adapter values as a list or comma-separated string.
+ * @returns Canonical adapter ids without duplicates.
+ */
+export function normalizeAdapterList(values) {
+    if (!values) {
+        return [];
+    }
+    const items = Array.isArray(values) ? values : String(values).split(",");
+    const normalized = [];
+    for (const item of items) {
+        const canonical = normalizeAdapterId(item);
+        if (!canonical || normalized.includes(canonical)) {
+            continue;
+        }
+        normalized.push(canonical);
+    }
+    return normalized;
+}
+/**
+ * Checks whether an adapter id or alias maps to a supported adapter.
+ *
+ * @param adapterId - Adapter identifier to check.
+ * @returns `true` when the adapter is known.
+ */
+export function isKnownAdapter(adapterId) {
+    return ADAPTERS.some((adapter) => adapter.id === normalizeAdapterId(adapterId));
+}
+/**
+ * Resolves a canonical adapter configuration by id or alias.
+ *
+ * @param adapterId - Adapter identifier to resolve.
+ * @returns Adapter configuration.
+ * @throws {AdapterNotFoundError} When the adapter is unknown.
+ */
+export function getAdapter(adapterId) {
+    const adapter = ADAPTERS.find((candidate) => candidate.id === normalizeAdapterId(adapterId)) || null;
+    if (!adapter) {
+        throw new AdapterNotFoundError(String(adapterId));
+    }
+    return adapter;
+}
+/**
+ * Detects supported adapters present in a workspace and orders them by specificity.
+ *
+ * @param cwd - Workspace root.
+ * @returns Ordered list of detected adapter ids.
+ */
+export async function detectAdapters(cwd) {
+    const detected = [];
+    for (const adapter of ADAPTERS) {
+        const score = await adapterScore(cwd, adapter);
+        if (score > 0) {
+            detected.push({ id: adapter.id, score, index: ADAPTER_INDEX.get(adapter.id) || 0 });
+        }
+    }
+    detected.sort((left, right) => right.score - left.score || left.index - right.index);
+    return detected.map((adapter) => adapter.id);
+}
+/**
+ * Resolves the active adapter state for a workspace.
+ *
+ * @param options - Resolution options including cwd and optional adapter override.
+ * @returns Active and detected adapter ids.
+ * @throws {AdapterNotFoundError} When the explicit override is unknown.
+ */
+export async function resolveAdapterState(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const preferred = normalizeAdapterId(options.adapter);
+    if (preferred && !isKnownAdapter(preferred)) {
+        throw new AdapterNotFoundError(preferred);
+    }
+    const detected = await detectAdapters(cwd);
+    return {
+        active: preferred || detected[0] || null,
+        detected,
+    };
+}
+async function adapterScore(cwd, adapter) {
+    let score = 0;
+    for (const marker of adapter.markers) {
+        if (await pathExists(path.join(cwd, marker.path))) {
+            score += marker.weight;
+        }
+    }
+    return score;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,73 @@
+import type { CatalogData, CatalogSource, CatalogSourceInput, ParsedGitHubRepo, SearchOptions, SkillManifest } from "./types.js";
+/**
+ * Reads a cached catalog from disk.
+ *
+ * @param cacheDir - Directory where cache files are stored.
+ * @param cacheKey - Unique key for this catalog source.
+ * @returns Cached catalog data, or `null` if missing or expired.
+ */
+export declare function readCatalogCache(cacheDir: string, cacheKey: string): Promise<CatalogData | null>;
+/**
+ * Writes catalog data to the local cache with a 5-minute TTL.
+ *
+ * @param cacheDir - Directory where cache files are stored.
+ * @param cacheKey - Unique key for this catalog source.
+ * @param data - Catalog data to cache.
+ */
+export declare function writeCatalogCache(cacheDir: string, cacheKey: string, data: CatalogData): Promise<void>;
+/**
+ * Computes a short, stable cache key for a catalog source URL.
+ *
+ * @param source - Resolved catalog source.
+ * @returns 16-character hex string.
+ */
+export declare function computeCatalogCacheKey(source: CatalogSource): string;
+/**
+ * Loads a remote skill catalog from `catalog.json` or falls back to repository tree inspection.
+ *
+ * @param options - Catalog source overrides.
+ * @returns Normalized remote catalog data.
+ * @throws {CatalogError} When the catalog cannot be fetched or normalized.
+ */
+export declare function loadCatalog(options?: CatalogSourceInput): Promise<CatalogData>;
+/**
+ * Resolves the effective GitHub catalog source from CLI options.
+ *
+ * @param options - Catalog source overrides.
+ * @returns Normalized catalog source.
+ * @throws {CatalogError} When the repository reference is invalid.
+ */
+export declare function resolveSource(options?: CatalogSourceInput): CatalogSource;
+/**
+ * Parses a GitHub repository reference in `owner/repo` or GitHub URL format.
+ *
+ * @param input - Repository reference to parse.
+ * @returns Parsed GitHub repository parts.
+ * @throws {CatalogError} When the input cannot be parsed.
+ */
+export declare function parseGitHubRepo(input: string): ParsedGitHubRepo;
+/**
+ * Builds a raw GitHub content URL for a repository file.
+ *
+ * @param repo - Repository in `owner/name` format.
+ * @param ref - Branch, tag, or commit.
+ * @param filePath - Repository-relative file path.
+ * @returns Raw GitHub content URL.
+ */
+export declare function buildRawGitHubUrl(repo: string, ref: string, filePath: string): string;
+/**
+ * Builds the GitHub tree API URL for a repository reference.
+ *
+ * @param repo - Repository in `owner/name` format.
+ * @param ref - Branch, tag, or commit.
+ * @returns GitHub API URL for recursive tree inspection.
+ */
+export declare function buildGitHubApiUrl(repo: string, ref: string): string;
+/**
+ * Filters a list of skills using text, compatibility, and tag criteria.
+ *
+ * @param skills - Skills to search.
+ * @param options - Search filters.
+ * @returns Matching skills ordered by id.
+ */
+export declare function searchCatalogSkills(skills: SkillManifest[], options?: SearchOptions): SkillManifest[];