skillex 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,442 @@
+/**
+ * Shared types and error classes for the Skillex CLI.
+ */
+/**
+ * Supported sync file rendering modes.
+ */
+export type SyncMode = "managed-block" | "managed-file";
+/**
+ * Workspace sync write modes.
+ */
+export type SyncWriteMode = "symlink" | "copy";
+/**
+ * Marker used to detect an adapter in a workspace.
+ */
+export interface AdapterMarker {
+    path: string;
+    weight: number;
+}
+/**
+ * Static adapter definition used for detection and synchronization.
+ */
+export interface AdapterConfig {
+    id: string;
+    label: string;
+    markers: AdapterMarker[];
+    syncTarget: string;
+    legacySyncTargets?: string[];
+    syncMode: SyncMode;
+}
+/**
+ * Persisted adapter state in the workspace lockfile.
+ */
+export interface AdapterState {
+    active: string | null;
+    detected: string[];
+}
+/**
+ * Remote catalog source configuration.
+ */
+export interface CatalogSource {
+    owner: string;
+    repoName: string;
+    repo: string;
+    ref: string;
+    catalogPath: string;
+    skillsDir: string;
+    catalogUrl: string | null;
+}
+/**
+ * Optional catalog source overrides accepted by CLI and installer entrypoints.
+ */
+export interface CatalogSourceInput {
+    owner?: string | undefined;
+    repoName?: string | undefined;
+    repo?: string | undefined;
+    ref?: string | undefined;
+    catalogPath?: string | undefined;
+    skillsDir?: string | undefined;
+    catalogUrl?: string | null | undefined;
+    /** Directory to store catalog cache files. Caching is skipped when absent. */
+    cacheDir?: string | undefined;
+    /** When `true`, bypass the local catalog cache and always fetch from the network. */
+    noCache?: boolean | undefined;
+}
+/**
+ * Parsed GitHub repository reference.
+ */
+export interface ParsedGitHubRepo {
+    owner: string;
+    repo: string;
+    ref: string | null;
+}
+/**
+ * Skill manifest stored in catalog and local installs.
+ */
+export interface SkillManifest {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    author: string | null;
+    tags: string[];
+    compatibility: string[];
+    entry: string;
+    path: string;
+    files: string[];
+    scripts?: Record<string, string> | undefined;
+}
+/**
+ * Alias used by catalog payloads for individual skill entries.
+ */
+export interface CatalogEntry extends SkillManifest {
+}
+/**
+ * Remote skill catalog structure.
+ */
+export interface CatalogData {
+    formatVersion: number;
+    repo: string;
+    ref: string;
+    skills: SkillManifest[];
+}
+/**
+ * Skill entry annotated with its originating catalog source.
+ */
+export interface SourcedSkillManifest extends SkillManifest {
+    source: {
+        repo: string;
+        ref: string;
+        label?: string | undefined;
+    };
+}
+/**
+ * Clock function used to stamp lockfile updates during tests and runtime.
+ */
+export type NowFn = () => string;
+/**
+ * Search filters accepted by catalog lookups.
+ */
+export interface SearchOptions {
+    query?: string;
+    compatibility?: string[] | string;
+    tags?: string[] | string;
+}
+/**
+ * Local metadata for an installed skill entry.
+ */
+export interface InstalledSkillMetadata {
+    name: string;
+    version: string;
+    path: string;
+    installedAt: string;
+    compatibility: string[];
+    tags: string[];
+    source?: string | undefined;
+}
+/**
+ * Alias used by lockfile and installer contracts.
+ */
+export interface InstalledSkill extends InstalledSkillMetadata {
+}
+/**
+ * Catalog source persisted inside the local lockfile.
+ */
+export interface LockfileSource {
+    repo: string;
+    ref: string;
+    label?: string | undefined;
+}
+/**
+ * Workspace adapter state persisted in the lockfile.
+ */
+export interface LockfileAdapters extends AdapterState {
+}
+/**
+ * Workspace settings persisted in the lockfile.
+ */
+export interface LockfileSettings {
+    autoSync: boolean;
+}
+/**
+ * Last synchronization metadata persisted in the lockfile.
+ */
+export interface SyncMetadata {
+    adapter: string;
+    targetPath: string;
+    syncedAt: string;
+}
+/**
+ * Full workspace lockfile structure.
+ */
+export interface LockfileState {
+    formatVersion: number;
+    createdAt: string;
+    updatedAt: string;
+    sources: LockfileSource[];
+    adapters: LockfileAdapters;
+    settings: LockfileSettings;
+    sync: SyncMetadata | null;
+    syncMode: SyncWriteMode | null;
+    installed: Record<string, InstalledSkillMetadata>;
+}
+/**
+ * Result of aggregating multiple remote catalogs.
+ */
+export interface AggregatedCatalogData {
+    formatVersion: number;
+    skills: SourcedSkillManifest[];
+    sources: Array<LockfileSource & {
+        skillCount: number;
+    }>;
+}
+/**
+ * Result of resolving a skill id across configured sources.
+ */
+export interface ResolvedSkillSelection {
+    skill: SkillManifest;
+    catalog: CatalogData;
+    source: LockfileSource;
+}
+/**
+ * Common filesystem paths used by the local state manager.
+ */
+export interface StatePaths {
+    stateDir: string;
+    lockfilePath: string;
+    skillsDirPath: string;
+    generatedDirPath: string;
+}
+/**
+ * Shared workspace options accepted by most install and sync functions.
+ */
+export interface ProjectOptions extends CatalogSourceInput {
+    cwd?: string | undefined;
+    agentSkillsDir?: string | undefined;
+    adapter?: string | undefined;
+    autoSync?: boolean | undefined;
+    dryRun?: boolean | undefined;
+    mode?: SyncWriteMode | undefined;
+    trust?: boolean | undefined;
+    yes?: boolean | undefined;
+    timeout?: number | undefined;
+    now?: NowFn | undefined;
+    /** When `true`, enables verbose debug output. */
+    verbose?: boolean | undefined;
+    /** Progress callback invoked for each skill during installation. */
+    onProgress?: ((current: number, total: number, skillId: string) => void) | undefined;
+}
+/**
+ * Sync target resolved for an adapter file.
+ */
+export interface SyncTarget {
+    adapter: string;
+    filePath: string;
+    mode: SyncMode;
+}
+/**
+ * Skill document loaded from disk for sync rendering.
+ */
+export interface InstalledSkillDocument {
+    id: string;
+    name: string;
+    version: string;
+    body: string;
+    skillDir: string;
+    scripts: Record<string, string>;
+    autoInject: boolean;
+    activationPrompt: string | null;
+}
+/**
+ * Internal prepared sync state before writing to disk.
+ */
+export interface PreparedSyncResult {
+    adapter: string;
+    absoluteTargetPath: string;
+    targetPath: string;
+    cleanupPaths: string[];
+    changed: boolean;
+    currentContent: string;
+    nextContent: string;
+    diff: string;
+    syncMode: SyncWriteMode;
+    generatedSourcePath?: string | undefined;
+}
+/**
+ * Dry-run preview returned before a sync writes files.
+ */
+export interface SyncPreview {
+    adapter: string;
+    filePath: string;
+    before: string;
+    after: string;
+}
+/**
+ * Public sync result returned after writing or dry-run preparation.
+ */
+export interface SyncResult {
+    adapter: string;
+    targetPath: string;
+    changed: boolean;
+    diff: string;
+    syncMode: SyncWriteMode;
+}
+/**
+ * Shared options for sync execution.
+ */
+export interface SyncOptions {
+    cwd: string;
+    adapterId: string;
+    statePaths: StatePaths;
+    skills: InstalledSkillDocument[];
+    mode?: SyncWriteMode | undefined;
+    dryRun?: boolean | undefined;
+    linkFactory?: ((targetPath: string, linkPath: string) => Promise<CreateSymlinkResult>) | undefined;
+    warn?: ((message: string) => void) | undefined;
+}
+/**
+ * Result returned by the top-level sync command.
+ */
+export interface SyncCommandResult {
+    statePaths: StatePaths;
+    sync: {
+        adapter: string;
+        targetPath: string;
+    } | SyncMetadata;
+    skillCount: number;
+    changed: boolean;
+    diff: string;
+    dryRun: boolean;
+    syncMode: SyncWriteMode;
+}
+/**
+ * Result returned by `initProject`.
+ */
+export interface InitProjectResult {
+    created: boolean;
+    statePaths: StatePaths;
+    lockfile: LockfileState;
+}
+/**
+ * Result returned by `installSkills`.
+ */
+export interface InstallSkillsResult {
+    installedCount: number;
+    installedSkills: SkillManifest[];
+    statePaths: StatePaths;
+    autoSync: SyncCommandResult | null;
+}
+/**
+ * Result returned by `updateInstalledSkills`.
+ */
+export interface UpdateInstalledSkillsResult {
+    statePaths: StatePaths;
+    updatedSkills: SkillManifest[];
+    missingFromCatalog: string[];
+    autoSync: SyncCommandResult | null;
+}
+/**
+ * Result returned by `removeSkills`.
+ */
+export interface RemoveSkillsResult {
+    statePaths: StatePaths;
+    removedSkills: string[];
+    missingSkills: string[];
+    autoSync: SyncCommandResult | null;
+}
+/**
+ * Catalog loader signature override used in tests.
+ */
+export type CatalogLoader = (source: CatalogSource) => Promise<CatalogData>;
+/**
+ * Skill downloader implementation used by installers.
+ */
+export type SkillDownloader = (skill: SkillManifest, catalog: CatalogData, stateDir: string) => Promise<void>;
+/**
+ * Parsed CLI arguments.
+ */
+export interface ParsedArgs {
+    command?: string | undefined;
+    positionals: string[];
+    flags: Record<string, string | boolean>;
+}
+/**
+ * Parsed direct GitHub install reference.
+ */
+export interface DirectGitHubRef {
+    owner: string;
+    repo: string;
+    ref: string;
+}
+/**
+ * Result of a filesystem link attempt.
+ */
+export interface CreateSymlinkResult {
+    ok: boolean;
+    fallback: boolean;
+    relativeTarget: string;
+}
+/**
+ * Shared base class for typed Skillex errors.
+ */
+export declare class SkillexError extends Error {
+    code: string;
+    /**
+     * Creates a typed Skillex error.
+     */
+    constructor(message: string, code: string);
+}
+/**
+ * Error thrown for catalog lookup and parsing failures.
+ */
+export declare class CatalogError extends SkillexError {
+    /**
+     * Creates a catalog error.
+     */
+    constructor(message: string, code?: string);
+}
+/**
+ * Error thrown for install, update, or remove failures.
+ */
+export declare class InstallError extends SkillexError {
+    /**
+     * Creates an install error.
+     */
+    constructor(message: string, code?: string);
+}
+/**
+ * Error thrown for sync preparation or write failures.
+ */
+export declare class SyncError extends SkillexError {
+    /**
+     * Creates a sync error.
+     */
+    constructor(message: string, code?: string);
+}
+/**
+ * Error thrown for invalid user input or unsafe data.
+ */
+export declare class ValidationError extends SkillexError {
+    /**
+     * Creates a validation error.
+     */
+    constructor(message: string, code?: string);
+}
+/**
+ * Error thrown when an unknown adapter is requested.
+ */
+export declare class AdapterNotFoundError extends SkillexError {
+    /**
+     * Creates an adapter lookup error.
+     */
+    constructor(adapterId: string);
+}
+/**
+ * Error thrown for invalid CLI usage.
+ */
+export declare class CliError extends SkillexError {
+    /**
+     * Creates a CLI error.
+     */
+    constructor(message: string, code?: string);
+}

package/dist/types.js

@@ -0,0 +1,83 @@
+/**
+ * Shared types and error classes for the Skillex CLI.
+ */
+/**
+ * Shared base class for typed Skillex errors.
+ */
+export class SkillexError extends Error {
+    code;
+    /**
+     * Creates a typed Skillex error.
+     */
+    constructor(message, code) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+/**
+ * Error thrown for catalog lookup and parsing failures.
+ */
+export class CatalogError extends SkillexError {
+    /**
+     * Creates a catalog error.
+     */
+    constructor(message, code = "CATALOG_ERROR") {
+        super(message, code);
+    }
+}
+/**
+ * Error thrown for install, update, or remove failures.
+ */
+export class InstallError extends SkillexError {
+    /**
+     * Creates an install error.
+     */
+    constructor(message, code = "INSTALL_ERROR") {
+        super(message, code);
+    }
+}
+/**
+ * Error thrown for sync preparation or write failures.
+ */
+export class SyncError extends SkillexError {
+    /**
+     * Creates a sync error.
+     */
+    constructor(message, code = "SYNC_ERROR") {
+        super(message, code);
+    }
+}
+/**
+ * Error thrown for invalid user input or unsafe data.
+ */
+export class ValidationError extends SkillexError {
+    /**
+     * Creates a validation error.
+     */
+    constructor(message, code = "VALIDATION_ERROR") {
+        super(message, code);
+    }
+}
+/**
+ * Error thrown when an unknown adapter is requested.
+ */
+export class AdapterNotFoundError extends SkillexError {
+    /**
+     * Creates an adapter lookup error.
+     */
+    constructor(adapterId) {
+        super(`Unknown adapter: ${adapterId}`, "ADAPTER_NOT_FOUND");
+    }
+}
+/**
+ * Error thrown for invalid CLI usage.
+ */
+export class CliError extends SkillexError {
+    /**
+     * Creates a CLI error.
+     */
+    constructor(message, code = "CLI_ERROR") {
+        super(message, code);
+    }
+}

package/dist/ui.d.ts

@@ -0,0 +1,43 @@
+import type { SkillManifest } from "./types.js";
+interface UiChoice {
+    name: string;
+    value: string;
+    checked?: boolean | undefined;
+}
+interface UiPrompts {
+    input?: ((options: {
+        message: string;
+        default?: string | undefined;
+    }) => Promise<string>) | undefined;
+    checkbox?: ((options: {
+        message: string;
+        instructions?: string | undefined;
+        choices: UiChoice[];
+    }) => Promise<string[]>) | undefined;
+}
+/**
+ * Filters catalog skills for the interactive UI using a case-insensitive text query.
+ *
+ * @param skills - Catalog skills.
+ * @param query - Search text.
+ * @returns Filtered skills in their original order.
+ */
+export declare function filterCatalogForUi(skills: SkillManifest[], query: string): SkillManifest[];
+/**
+ * Runs the interactive terminal flow used by `skillex ui`.
+ *
+ * @param options - UI state and optional prompt overrides.
+ * @returns Selected, installable, and removable skill ids.
+ */
+export declare function runInteractiveUi(options: {
+    skills: SkillManifest[];
+    installedIds: string[];
+    prompts?: UiPrompts | undefined;
+}): Promise<{
+    query: string;
+    visibleIds: string[];
+    selectedIds: string[];
+    toInstall: string[];
+    toRemove: string[];
+}>;
+export {};

package/dist/ui.js

@@ -0,0 +1,78 @@
+/**
+ * Filters catalog skills for the interactive UI using a case-insensitive text query.
+ *
+ * @param skills - Catalog skills.
+ * @param query - Search text.
+ * @returns Filtered skills in their original order.
+ */
+export function filterCatalogForUi(skills, query) {
+    const normalized = query.trim().toLowerCase();
+    if (!normalized) {
+        return skills;
+    }
+    return skills.filter((skill) => [skill.id, skill.name, skill.description, skill.compatibility.join(","), skill.tags.join(",")]
+        .join("\n")
+        .toLowerCase()
+        .includes(normalized));
+}
+/**
+ * Runs the interactive terminal flow used by `skillex ui`.
+ *
+ * @param options - UI state and optional prompt overrides.
+ * @returns Selected, installable, and removable skill ids.
+ */
+export async function runInteractiveUi(options) {
+    const prompts = options.prompts || (await loadPromptAdapters());
+    const query = await (prompts.input || fallbackInput)({
+        message: "Filtro das skills (Enter para mostrar tudo)",
+        default: "",
+    });
+    const filteredSkills = filterCatalogForUi(options.skills, query);
+    const installedSet = new Set(options.installedIds);
+    const visibleIds = filteredSkills.map((skill) => skill.id);
+    const selectedIds = filteredSkills.length === 0
+        ? []
+        : await (prompts.checkbox || fallbackCheckbox)({
+            message: "Selecione as skills",
+            instructions: "Type to filter first • Space to select • Enter to install",
+            choices: filteredSkills.map((skill) => ({
+                name: `${skill.name} (${skill.id}) - ${skill.description || "Sem descricao"} [${skill.compatibility.join(",") || "sem-compat"}]`,
+                value: skill.id,
+                checked: installedSet.has(skill.id),
+            })),
+        });
+    const selectedSet = new Set(selectedIds);
+    const toInstall = selectedIds.filter((skillId) => !installedSet.has(skillId));
+    const toRemove = visibleIds.filter((skillId) => installedSet.has(skillId) && !selectedSet.has(skillId));
+    return {
+        query,
+        visibleIds,
+        selectedIds,
+        toInstall,
+        toRemove,
+    };
+}
+async function loadPromptAdapters() {
+    const prompts = await import("@inquirer/prompts");
+    return {
+        input: async (options) => prompts.input({
+            message: options.message,
+            ...(options.default !== undefined ? { default: options.default } : {}),
+        }),
+        checkbox: async (options) => prompts.checkbox({
+            message: options.message,
+            ...(options.instructions ? { instructions: options.instructions } : {}),
+            choices: options.choices.map((choice) => ({
+                name: choice.name,
+                value: choice.value,
+                ...(choice.checked !== undefined ? { checked: choice.checked } : {}),
+            })),
+        }),
+    };
+}
+async function fallbackInput() {
+    return "";
+}
+async function fallbackCheckbox() {
+    return [];
+}

package/dist/user-config.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Global user configuration for the Skillex CLI.
+ *
+ * Reads and writes `~/.askillrc.json`. CLI flags and environment variables
+ * always take precedence over values stored here.
+ */
+/**
+ * Shape of the global user configuration file (`~/.askillrc.json`).
+ */
+export interface UserConfig {
+    /** Default catalog repository in `owner/repo` format. */
+    defaultRepo?: string | undefined;
+    /** Default adapter ID to use when none is detected. */
+    defaultAdapter?: string | undefined;
+    /** GitHub personal access token (fallback when GITHUB_TOKEN env is unset). */
+    githubToken?: string | undefined;
+    /** When `true`, auto-sync is disabled globally. */
+    disableAutoSync?: boolean | undefined;
+}
+/** Valid keys that may be set via `skillex config set`. */
+export declare const VALID_CONFIG_KEYS: ReadonlyArray<keyof UserConfig>;
+/**
+ * Resolves the path to the global config file.
+ *
+ * Respects `XDG_CONFIG_HOME` when set; otherwise uses `~/.askillrc.json`.
+ */
+export declare function getUserConfigPath(): string;
+/**
+ * Reads the global user configuration file.
+ *
+ * Returns an empty object when the file does not exist or is invalid JSON.
+ */
+export declare function readUserConfig(): Promise<UserConfig>;
+/**
+ * Writes the global user configuration file, merging with any existing values.
+ *
+ * @param updates - Key/value pairs to write.
+ */
+export declare function writeUserConfig(updates: Partial<UserConfig>): Promise<void>;