skillex 0.2.0

package/dist/output.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Structured output helpers for the Skillex CLI.
+ *
+ * Applies ANSI colors when stdout/stderr are TTYs and NO_COLOR is unset.
+ * Provides a verbose flag that gates debug-level output.
+ */
+/**
+ * Enables or disables verbose (debug) output for the current process.
+ *
+ * @param value - `true` to enable verbose output.
+ */
+export declare function setVerbose(value: boolean): void;
+/**
+ * Returns whether verbose mode is currently active.
+ */
+export declare function isVerbose(): boolean;
+/**
+ * Prints a green success message to stdout.
+ *
+ * @param message - Message to display.
+ */
+export declare function success(message: string): void;
+/**
+ * Prints a plain informational message to stdout.
+ *
+ * @param message - Message to display.
+ */
+export declare function info(message: string): void;
+/**
+ * Prints a yellow warning to stderr.
+ *
+ * @param message - Warning message.
+ */
+export declare function warn(message: string): void;
+/**
+ * Prints a red error message to stderr.
+ *
+ * @param message - Error message.
+ */
+export declare function error(message: string): void;
+/**
+ * Prints a dim debug message to stderr when verbose mode is active.
+ *
+ * @param message - Debug message.
+ */
+export declare function debug(message: string): void;

package/dist/output.js

@@ -0,0 +1,78 @@
+/**
+ * Structured output helpers for the Skillex CLI.
+ *
+ * Applies ANSI colors when stdout/stderr are TTYs and NO_COLOR is unset.
+ * Provides a verbose flag that gates debug-level output.
+ */
+let verboseEnabled = false;
+// ---------------------------------------------------------------------------
+// Color support detection
+// ---------------------------------------------------------------------------
+function colorEnabled(stream) {
+    return Boolean(stream.isTTY) && process.env.NO_COLOR === undefined;
+}
+function applyColor(ansiCode, text, stream) {
+    return colorEnabled(stream) ? `\x1b[${ansiCode}m${text}\x1b[0m` : text;
+}
+// ---------------------------------------------------------------------------
+// Verbose flag
+// ---------------------------------------------------------------------------
+/**
+ * Enables or disables verbose (debug) output for the current process.
+ *
+ * @param value - `true` to enable verbose output.
+ */
+export function setVerbose(value) {
+    verboseEnabled = value;
+}
+/**
+ * Returns whether verbose mode is currently active.
+ */
+export function isVerbose() {
+    return verboseEnabled;
+}
+// ---------------------------------------------------------------------------
+// Output helpers
+// ---------------------------------------------------------------------------
+/**
+ * Prints a green success message to stdout.
+ *
+ * @param message - Message to display.
+ */
+export function success(message) {
+    console.log(applyColor("32", message, process.stdout));
+}
+/**
+ * Prints a plain informational message to stdout.
+ *
+ * @param message - Message to display.
+ */
+export function info(message) {
+    console.log(message);
+}
+/**
+ * Prints a yellow warning to stderr.
+ *
+ * @param message - Warning message.
+ */
+export function warn(message) {
+    console.warn(applyColor("33", `Warning: ${message}`, process.stderr));
+}
+/**
+ * Prints a red error message to stderr.
+ *
+ * @param message - Error message.
+ */
+export function error(message) {
+    console.error(applyColor("31", message, process.stderr));
+}
+/**
+ * Prints a dim debug message to stderr when verbose mode is active.
+ *
+ * @param message - Debug message.
+ */
+export function debug(message) {
+    if (verboseEnabled) {
+        process.stderr.write(applyColor("2", `[debug] ${message}`, process.stderr) + "\n");
+    }
+}

package/dist/runner.d.ts

@@ -0,0 +1,31 @@
+import type { Writable } from "node:stream";
+import type { ProjectOptions } from "./types.js";
+interface RunSkillOptions extends ProjectOptions {
+    yes?: boolean | undefined;
+    timeout?: number | undefined;
+    confirm?: (() => Promise<boolean>) | undefined;
+    stdout?: Writable | undefined;
+    stderr?: Writable | undefined;
+}
+/**
+ * Parses a `skill-id:command` reference used by the `run` command.
+ *
+ * @param value - User-supplied run target.
+ * @returns Parsed skill id and command name.
+ * @throws {CliError} When the reference is invalid.
+ */
+export declare function parseSkillCommandReference(value: string): {
+    skillId: string;
+    command: string;
+};
+/**
+ * Executes a named script declared in an installed skill manifest.
+ *
+ * @param skillId - Installed skill identifier.
+ * @param commandName - Script name from the local `skill.json`.
+ * @param options - Execution options.
+ * @returns Child process exit code.
+ * @throws {CliError} When the skill or command is unavailable.
+ */
+export declare function runSkillScript(skillId: string, commandName: string, options?: RunSkillOptions): Promise<number>;
+export {};

package/dist/runner.js

@@ -0,0 +1,94 @@
+import { spawn } from "node:child_process";
+import * as path from "node:path";
+import { DEFAULT_AGENT_SKILLS_DIR, getStatePaths } from "./config.js";
+import { confirmAction } from "./confirm.js";
+import { readJson } from "./fs.js";
+import { CliError } from "./types.js";
+/**
+ * Parses a `skill-id:command` reference used by the `run` command.
+ *
+ * @param value - User-supplied run target.
+ * @returns Parsed skill id and command name.
+ * @throws {CliError} When the reference is invalid.
+ */
+export function parseSkillCommandReference(value) {
+    const separatorIndex = value.indexOf(":");
+    if (separatorIndex <= 0 || separatorIndex === value.length - 1) {
+        throw new CliError('Use o formato "skill-id:comando" para executar scripts.', "INVALID_RUN_REFERENCE");
+    }
+    return {
+        skillId: value.slice(0, separatorIndex),
+        command: value.slice(separatorIndex + 1),
+    };
+}
+/**
+ * Executes a named script declared in an installed skill manifest.
+ *
+ * @param skillId - Installed skill identifier.
+ * @param commandName - Script name from the local `skill.json`.
+ * @param options - Execution options.
+ * @returns Child process exit code.
+ * @throws {CliError} When the skill or command is unavailable.
+ */
+export async function runSkillScript(skillId, commandName, options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const statePaths = getStatePaths(cwd, options.agentSkillsDir || DEFAULT_AGENT_SKILLS_DIR);
+    const lockfile = (await readJson(statePaths.lockfilePath, null)) || null;
+    if (!lockfile) {
+        throw new CliError("Nenhuma instalacao local encontrada. Rode: skillex init", "LOCKFILE_MISSING");
+    }
+    const metadata = lockfile.installed?.[skillId];
+    if (!metadata?.path) {
+        throw new CliError(`Skill "${skillId}" nao esta instalada.`, "SKILL_NOT_INSTALLED");
+    }
+    const skillDir = path.resolve(cwd, metadata.path);
+    const manifest = (await readJson(path.join(skillDir, "skill.json"), {})) || {};
+    const scripts = manifest.scripts || {};
+    const script = scripts[commandName];
+    if (!script) {
+        const available = Object.keys(scripts);
+        throw new CliError(available.length > 0
+            ? `Comando "${commandName}" nao existe para "${skillId}". Disponiveis: ${available.join(", ")}`
+            : `A skill "${skillId}" nao declara scripts executaveis.`, "RUN_COMMAND_NOT_FOUND");
+    }
+    const confirm = options.confirm || (() => confirmAction(`Executar em ${skillId}: ${script}?`));
+    if (!options.yes) {
+        const accepted = await confirm();
+        if (!accepted) {
+            throw new CliError("Execucao cancelada pelo usuario.", "RUN_CANCELLED");
+        }
+    }
+    const stdout = options.stdout || process.stdout;
+    const stderr = options.stderr || process.stderr;
+    const timeoutSeconds = options.timeout || 30;
+    const timeoutMs = timeoutSeconds * 1000;
+    return new Promise((resolve, reject) => {
+        let timedOut = false;
+        const child = spawn(script, {
+            cwd: skillDir,
+            env: process.env,
+            shell: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.stdout?.on("data", (chunk) => {
+            stdout.write(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr.write(chunk);
+        });
+        child.on("error", reject);
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+        }, timeoutMs);
+        child.on("close", (code) => {
+            clearTimeout(timeout);
+            if (timedOut) {
+                stderr.write(`Tempo limite excedido (${timeoutSeconds}s).\n`);
+                resolve(1);
+                return;
+            }
+            resolve(code ?? 0);
+        });
+    });
+}

package/dist/skill.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Parsed frontmatter values supported by Skillex skills.
+ */
+export interface SkillFrontmatter {
+    name?: string | undefined;
+    description?: string | undefined;
+    autoInject?: boolean | undefined;
+    activationPrompt?: string | undefined;
+}
+/**
+ * Parses the YAML-like frontmatter at the top of a `SKILL.md` file.
+ *
+ * @param content - Raw markdown content.
+ * @returns Parsed frontmatter fields relevant to Skillex.
+ */
+export declare function parseSkillFrontmatter(content: string): SkillFrontmatter;
+/**
+ * Removes supported frontmatter and the top-level heading from a skill document.
+ *
+ * @param content - Raw markdown content.
+ * @returns Normalized markdown body.
+ */
+export declare function normalizeSkillContent(content: string): string;

package/dist/skill.js

@@ -0,0 +1,61 @@
+/**
+ * Parses the YAML-like frontmatter at the top of a `SKILL.md` file.
+ *
+ * @param content - Raw markdown content.
+ * @returns Parsed frontmatter fields relevant to Skillex.
+ */
+export function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!match || match[1] === undefined) {
+        return {};
+    }
+    const values = {};
+    for (const rawLine of match[1].split("\n")) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex <= 0) {
+            continue;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        const rawValue = line.slice(separatorIndex + 1).trim();
+        const value = normalizeFrontmatterValue(rawValue);
+        if (key === "name" && typeof value === "string") {
+            values.name = value;
+        }
+        if (key === "description" && typeof value === "string") {
+            values.description = value;
+        }
+        if (key === "autoInject" && typeof value === "boolean") {
+            values.autoInject = value;
+        }
+        if (key === "activationPrompt" && typeof value === "string") {
+            values.activationPrompt = value;
+        }
+    }
+    return values;
+}
+/**
+ * Removes supported frontmatter and the top-level heading from a skill document.
+ *
+ * @param content - Raw markdown content.
+ * @returns Normalized markdown body.
+ */
+export function normalizeSkillContent(content) {
+    const withoutFrontmatter = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "");
+    const withoutTopHeading = withoutFrontmatter.replace(/^#\s+.+\n+/, "");
+    return withoutTopHeading.trim();
+}
+function normalizeFrontmatterValue(value) {
+    const trimmed = value.trim().replace(/^["']|["']$/g, "");
+    const normalized = trimmed.toLowerCase();
+    if (normalized === "true") {
+        return true;
+    }
+    if (normalized === "false") {
+        return false;
+    }
+    return trimmed;
+}

package/dist/sync.d.ts

@@ -0,0 +1,41 @@
+import type { InstalledSkillDocument, LockfileState, PreparedSyncResult, SyncOptions, SyncResult } from "./types.js";
+/**
+ * Loads installed skill documents from the local workspace state directory.
+ *
+ * @param context - Workspace root and lockfile context.
+ * @returns Installed skill documents used for sync rendering.
+ */
+export declare function loadInstalledSkillDocuments(context: {
+    cwd: string;
+    lockfile: LockfileState;
+}): Promise<InstalledSkillDocument[]>;
+/**
+ * Synchronizes installed skills into the target file consumed by an adapter.
+ *
+ * @param options - Sync execution options.
+ * @returns Final sync result.
+ * @throws {SyncError} When sync preparation or file writing fails.
+ */
+export declare function syncAdapterFiles(options: SyncOptions): Promise<SyncResult>;
+/**
+ * Prepares the next sync state without writing files.
+ *
+ * @param options - Sync preparation options.
+ * @returns Prepared sync state with before/after content and diff.
+ * @throws {SyncError} When the adapter cannot be prepared.
+ */
+export declare function prepareSyncAdapterFiles(options: Omit<SyncOptions, "dryRun">): Promise<PreparedSyncResult>;
+/**
+ * Renders installed skills into a single markdown document.
+ *
+ * @param skills - Installed skill documents.
+ * @returns Consolidated markdown body.
+ */
+export declare function renderInstalledSkills(skills: InstalledSkillDocument[]): string;
+/**
+ * Builds the managed auto-inject block for all installed skills that request it.
+ *
+ * @param skills - Installed skill documents.
+ * @returns Managed auto-inject block or `null` when nothing should be injected.
+ */
+export declare function buildAutoInjectBlock(skills: InstalledSkillDocument[]): string | null;