@datename/fastcode-termux 0.0.0-stage → 0.1.6

package/src/config/themes.ts

@@ -0,0 +1,77 @@
+/**
+ * Built-in color themes. The `banner` triple is fed to gradient-string
+ * (start → mid → end) so each theme produces a recognizable big-text logo.
+ */
+export const THEMES = {
+    fastcode: {
+        id: "fastcode",
+        label: "FastCode (default)",
+        banner: ["#ff7a00", "#ff2d95", "#7c4dff"],
+        user: "cyan",
+        assistant: "white",
+        system: "gray",
+        border: "magenta",
+        accent: "magenta",
+        muted: "gray",
+        error: "red",
+        success: "green",
+    },
+    neon: {
+        id: "neon",
+        label: "Neon",
+        banner: ["#00ffd0", "#00b3ff", "#7c4dff"],
+        user: "cyanBright",
+        assistant: "whiteBright",
+        system: "gray",
+        border: "cyan",
+        accent: "cyan",
+        muted: "gray",
+        error: "red",
+        success: "greenBright",
+    },
+    sunset: {
+        id: "sunset",
+        label: "Sunset",
+        banner: ["#ff5f6d", "#ffc371", "#ff9966"],
+        user: "yellow",
+        assistant: "whiteBright",
+        system: "gray",
+        border: "yellow",
+        accent: "yellow",
+        muted: "gray",
+        error: "redBright",
+        success: "green",
+    },
+    matrix: {
+        id: "matrix",
+        label: "Matrix",
+        banner: ["#00ff41", "#008f11", "#003b00"],
+        user: "greenBright",
+        assistant: "green",
+        system: "gray",
+        border: "green",
+        accent: "green",
+        muted: "gray",
+        error: "redBright",
+        success: "greenBright",
+    },
+    mono: {
+        id: "mono",
+        label: "Monochrome",
+        banner: ["#ffffff", "#cccccc", "#888888"],
+        user: "white",
+        assistant: "whiteBright",
+        system: "gray",
+        border: "white",
+        accent: "white",
+        muted: "gray",
+        error: "red",
+        success: "white",
+    },
+};
+export const DEFAULT_THEME = "fastcode";
+export function getTheme(id) {
+    if (id && THEMES[id])
+        return THEMES[id];
+    return THEMES[DEFAULT_THEME];
+}

package/src/config/trust.ts

@@ -0,0 +1,67 @@
+/**
+ * Project trust store.
+ *
+ * Agent tools can read, write, delete and execute inside the workspace, so a
+ * folder is only enabled after the user confirms it once. The list lives in
+ * ~/.fastcode/trusted.json and is compared by real path.
+ *
+ * FASTCODE_TRUST_ALL=1 marks every directory trusted (scripts, CI).
+ */
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, getPaths } from "./paths.js";
+const TRUTHY = ["1", "true", "yes", "on"];
+export function normalizeProjectPath(dir) {
+    const absolute = resolve(dir);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+export function loadTrust() {
+    const { trust } = getPaths();
+    if (!existsSync(trust))
+        return { trusted: [] };
+    try {
+        const raw = JSON.parse(readFileSync(trust, "utf8"));
+        return { trusted: Array.isArray(raw.trusted) ? raw.trusted.filter((entry) => entry && typeof entry.path === "string") : [] };
+    }
+    catch {
+        return { trusted: [] };
+    }
+}
+function saveTrust(state) {
+    const paths = getPaths();
+    ensureDir(paths.root);
+    writeFileSync(paths.trust, JSON.stringify(state, null, 2), "utf8");
+}
+export function trustAllEnabled() {
+    return TRUTHY.includes((process.env["FASTCODE_TRUST_ALL"] ?? "").trim().toLowerCase());
+}
+export function isTrusted(dir) {
+    if (trustAllEnabled())
+        return true;
+    const target = normalizeProjectPath(dir);
+    return loadTrust().trusted.some((entry) => entry.path === target);
+}
+export function trustProject(dir) {
+    const target = normalizeProjectPath(dir);
+    const state = loadTrust();
+    if (!state.trusted.some((entry) => entry.path === target)) {
+        state.trusted.push({ path: target, addedAt: new Date().toISOString() });
+        saveTrust(state);
+    }
+    return target;
+}
+export function untrustProject(dir) {
+    const target = normalizeProjectPath(dir);
+    const state = loadTrust();
+    const next = state.trusted.filter((entry) => entry.path !== target);
+    saveTrust({ trusted: next });
+    return state.trusted.length !== next.length;
+}
+export function listTrusted() {
+    return loadTrust().trusted;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * FastCode entrypoint.
+ *
+ * Parses CLI args, then either runs a one-shot subcommand or boots the
+ * Ink-based TUI. We keep this file tiny so the slow imports (Ink, React)
+ * are not loaded for `fastcode skills list`.
+ */
+import { parseCli } from "./cli.js";
+async function main() {
+    const cli = await parseCli();
+    if (cli.done)
+        return;
+    if (!process.stdout.isTTY) {
+        console.error("FastCode TUI requires a TTY. Pipe-mode prompts aren't supported yet — try `fastcode \"<prompt>\"` from a real terminal.");
+        process.exit(1);
+    }
+    // Lazy-load Ink so subcommands don't pay the React boot cost.
+    const [{ render }, React, { App }] = await Promise.all([
+        import("ink"),
+        import("react"),
+        import("./app.js"),
+    ]);
+    // React.createElement avoids needing a separate .tsx loader for this file.
+    // exitOnCtrlC: false lets the app own Ctrl+C so the documented
+    // "press Ctrl+C twice to quit" behavior actually works.
+    render(React.createElement(App, { initialPrompt: cli.prompt, resume: cli.resume }), { exitOnCtrlC: false });
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/src/lib/diagnostics.ts

@@ -0,0 +1,139 @@
+/**
+ * Environment diagnostics for mobile / Termux troubleshooting.
+ *
+ * `fastcode doctor` prints the values below so a broken mobile install can be
+ * diagnosed without opening the TUI: Node version, Termux detection, whether
+ * stdout is a real terminal, the config root, and which provider keys exist.
+ */
+import { detectPlatform, platformLabel } from "./platform.js";
+import { readPackageMeta } from "./pkg.js";
+import { shouldUseStableTerminalUi } from "./uiMode.js";
+import { getPaths } from "../config/paths.js";
+import { loadConfig, resolveApiKey, resolveProviderKey } from "../config/store.js";
+import { PROVIDERS } from "../providers/index.js";
+import { listInstalledSkills } from "../skills/manager.js";
+import { listInstalledPlugins } from "../plugins/manager.js";
+import { loggingEnabled, listSessions, sessionCacheLimitBytes } from "../session/log.js";
+import { isTrusted } from "../config/trust.js";
+import { DEFAULT_DENY_PATTERNS } from "../agent/guards.js";
+import { toolOutputLimit } from "../agent/limits.js";
+const NODE_REQUIRED = "18.17";
+function readVersion() {
+    return readPackageMeta().version;
+}
+function nodeIsSupported() {
+    const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+    const [reqMajor = 0, reqMinor = 0] = NODE_REQUIRED.split(".").map(Number);
+    return major > reqMajor || (major === reqMajor && minor >= reqMinor);
+}
+export function collectDiagnostics() {
+    const config = loadConfig();
+    let paths;
+    try {
+        paths = getPaths();
+    }
+    catch {
+        paths = undefined;
+    }
+    const provider = PROVIDERS.find((p) => p.id === config.providerId);
+    const keyLookup = provider && provider.authEnv.length > 0
+        ? resolveApiKey(provider.id, config.model, provider.authEnv)
+        : { status: "ok" as const };
+    const keyPresent = Boolean(provider) && (provider.authEnv.length === 0 || keyLookup.status === "ok");
+    let skillsInstalled = 0;
+    let pluginsInstalled = 0;
+    try {
+        skillsInstalled = listInstalledSkills().length;
+    }
+    catch {
+        // A broken skills dir must not break the whole report.
+    }
+    try {
+        pluginsInstalled = listInstalledPlugins().length;
+    }
+    catch {
+        // Same for plugins.
+    }
+    const platform = detectPlatform();
+    return {
+        version: readVersion(),
+        node: process.version,
+        nodeRequired: NODE_REQUIRED,
+        nodeOk: nodeIsSupported(),
+        platform,
+        platformLabel: platformLabel(),
+        termux: platform === "termux",
+        termuxVersion: process.env["TERMUX_VERSION"] ?? null,
+        stableUi: shouldUseStableTerminalUi(),
+        tty: Boolean(process.stdout.isTTY),
+        configRoot: paths?.root,
+        configFile: paths?.config,
+        authFile: paths?.auth,
+        providerId: config.providerId,
+        model: config.model,
+        keyPresent,
+        keyStatus: provider ? keyLookup.status : "missing",
+        keyEnv: provider?.authEnv?.[0],
+        skillsInstalled,
+        pluginsInstalled,
+        enabledSkills: (config.enabledSkills ?? []).length,
+        enabledPlugins: (config.enabledPlugins ?? []).length,
+        sessionLogEnabled: loggingEnabled(),
+        sessionCacheMb: Math.round(sessionCacheLimitBytes() / (1024 * 1024)),
+        sessionsDir: paths?.sessions,
+        sessionsCount: listSessions().length,
+        sessionsBytes: listSessions().reduce((sum, entry) => sum + entry.bytes, 0),
+        trustFile: paths?.trust,
+        trusted: isTrusted(process.cwd()),
+        shellDenyPatterns: DEFAULT_DENY_PATTERNS.length,
+        allowDangerous: ["1", "true", "yes", "on"].includes((process.env["FASTCODE_ALLOW_DANGEROUS"] ?? "").trim().toLowerCase()),
+        toolOutputLimit: toolOutputLimit(),
+        providers: PROVIDERS.map((p) => ({
+            id: p.id,
+            label: p.label,
+            env: p.authEnv,
+            keyPresent: p.authEnv.length === 0 || Boolean(resolveProviderKey(p.id, p.authEnv).key),
+        })),
+    };
+}
+export function formatDiagnostics(info) {
+    const lines = [];
+    lines.push(`FastCode ${info.version} — environment check`);
+    lines.push("");
+    lines.push(`  node          ${info.node}  (needs >= ${info.nodeRequired})  [${info.nodeOk ? "ok" : "TOO OLD"}]`);
+    lines.push(`  platform      ${info.platformLabel}${info.termux ? " (Termux)" : ""}`);
+    lines.push(`  terminal      ${info.tty ? "interactive TTY" : "NOT a TTY — the TUI needs a real terminal"}`);
+    lines.push(`  stable UI     ${info.stableUi ? "on (anti-flicker)" : "off"}`);
+    lines.push("  config root   " + (info.configRoot ?? "(unavailable)"));
+    lines.push("  config file   " + (info.configFile ?? "(unavailable)"));
+    lines.push("  keys file     " + (info.authFile ?? "(unavailable)") + "   (separate, chmod 0600)");
+    lines.push("  trusted cwd   " + (info.trusted ? "yes" : "NO - agent tools ask first or stay off") + "   (" + (info.trustFile ?? "?") + ")");
+    lines.push("  session log   " + (info.sessionLogEnabled ? "on" : "off") + "   cache cap " + info.sessionCacheMb + "MB, " + info.sessionsCount + " file(s), " + (info.sessionsBytes / 1024 / 1024).toFixed(2) + "MB used");
+    lines.push("  session dir   " + (info.sessionsDir ?? "(unavailable)"));
+    lines.push("  shell guard   " + info.shellDenyPatterns + " deny patterns" + (info.allowDangerous ? "   [FASTCODE_ALLOW_DANGEROUS is ON]" : ""));
+    lines.push("  tool output   " + info.toolOutputLimit + " chars max (streaming cap)");
+    lines.push(`  provider      ${info.providerId} · model ${info.model}`);
+    let apiKeyStatus;
+    if (info.keyPresent)
+        apiKeyStatus = "present";
+    else if (info.keyStatus === "unbound")
+        apiKeyStatus = `UNBOUND — a stored ${info.providerId} key isn't tied to a model; re-bind with /login ${info.providerId} ${info.model} <key>`;
+    else
+        apiKeyStatus = `MISSING — set ${info.keyEnv ?? "the provider env var"} or /login ${info.providerId} ${info.model} <key>`;
+    lines.push(`  api key       ${apiKeyStatus}`);
+    lines.push(`  skills        ${info.skillsInstalled} installed, ${info.enabledSkills} enabled`);
+    lines.push(`  plugins       ${info.pluginsInstalled} installed, ${info.enabledPlugins} enabled`);
+    lines.push("");
+    lines.push("  provider keys:");
+    for (const p of info.providers) {
+        lines.push(`    ${p.keyPresent ? "●" : "○"} ${p.id.padEnd(12)} ${p.env.join(" / ") || "(no key needed)"}`);
+    }
+    if (info.termux) {
+        lines.push("");
+        lines.push("  Termux tips:");
+        lines.push("    - pkg install nodejs git");
+        lines.push("    - keep the session alive with: termux-wake-lock");
+        lines.push("    - add an extra-keys row for Esc/Ctrl in ~/.termux/termux.properties");
+    }
+    return lines.join("\n");
+}

package/src/lib/http.ts

@@ -0,0 +1,70 @@
+/**
+ * Tiny fetch helpers. We standardize on globalThis.fetch (Node 18+).
+ *
+ * The `streamSSE` helper parses Server-Sent Events for any provider that uses
+ * the OpenAI-style `data: {...}\n\n` chunk format. Non-SSE providers (e.g.
+ * Anthropic's older streaming) handle their own parsing.
+ */
+export async function fetchJson(url: string, init: any = {}): Promise<any> {
+    const res = await fetch(url, {
+        ...init,
+        headers: { "content-type": "application/json", accept: "application/json", ...(init.headers ?? {}) },
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`${res.status} ${res.statusText}: ${body.slice(0, 500)}`);
+    }
+    return (await res.json());
+}
+/** Async iterator over SSE events from a streaming HTTP response. */
+export async function* streamSSE(res) {
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`${res.status} ${res.statusText}: ${body.slice(0, 500)}`);
+    }
+    if (!res.body)
+        throw new Error("Empty response body");
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        // Normalize CR/LF so both "\n\n" and "\r\n\r\n" frame separators
+        // are detected, including a CR/LF split across two chunks.
+        buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n?/g, "\n");
+        let sep = buffer.indexOf("\n\n");
+        while (sep !== -1) {
+            const chunk = buffer.slice(0, sep);
+            buffer = buffer.slice(sep + 2);
+            const ev = parseSseChunk(chunk);
+            if (ev)
+                yield ev;
+            sep = buffer.indexOf("\n\n");
+        }
+    }
+    // Flush trailing event without final \n\n (some servers do this).
+    const trailing = buffer.trim();
+    if (trailing) {
+        const ev = parseSseChunk(trailing);
+        if (ev)
+            yield ev;
+    }
+}
+function parseSseChunk(chunk) {
+    let event;
+    const dataLines = [];
+    for (const lineRaw of chunk.split("\n")) {
+        const line = lineRaw.replace(/\r$/, "");
+        if (!line || line.startsWith(":"))
+            continue;
+        if (line.startsWith("event:"))
+            event = line.slice(6).trim();
+        else if (line.startsWith("data:"))
+            dataLines.push(line.slice(5).trimStart());
+    }
+    if (dataLines.length === 0)
+        return undefined;
+    return { event, data: dataLines.join("\n") };
+}

package/src/lib/markdown.ts

@@ -0,0 +1,32 @@
+/**
+ * Markdown → ANSI rendering for terminal output.
+ *
+ * We use marked + marked-terminal because it gives us proper code-fence
+ * syntax highlighting (via cli-highlight) without us hand-rolling a
+ * markdown parser. The result is a fully-formatted ANSI string we can
+ * print directly inside an Ink <Text>.
+ */
+import { marked } from "marked";
+import { markedTerminal } from "marked-terminal";
+let configured = false;
+function configure() {
+    if (configured)
+        return;
+    marked.use(markedTerminal({
+        reflowText: false,
+        tab: 2,
+    }) as any);
+    configured = true;
+}
+export function renderMarkdown(md) {
+    configure();
+    try {
+        const out = marked.parse(md) as string;
+        // marked-terminal sometimes appends a stray trailing newline; trim only
+        // trailing whitespace so we don't lose meaningful blank lines.
+        return out.replace(/\s+$/, "");
+    }
+    catch {
+        return md;
+    }
+}

package/src/lib/pkg.ts

@@ -0,0 +1,35 @@
+/**
+ * Read this package's package.json (name + version) from any layout.
+ *
+ * The same source runs three ways, so `import.meta.url` points at different
+ * depths; try every plausible relative path and fall back gracefully.
+ *
+ *   - tsx / dev:    src/lib/pkg.ts        -> ../../package.json
+ *   - tsc output:   dist/lib/pkg.js       -> ../../package.json
+ *   - esbuild bundle: dist/cli.js         -> ../package.json
+ */
+import { readFileSync } from "node:fs";
+
+export interface PackageMeta {
+    name: string;
+    version: string;
+}
+
+    const FALLBACK: PackageMeta = { name: "@datename/fastcode-termux", version: "0.0.0" };
+
+const CANDIDATES = ["../package.json", "../../package.json", "../../../package.json"];
+
+export function readPackageMeta(): PackageMeta {
+    for (const rel of CANDIDATES) {
+        try {
+            const meta = JSON.parse(readFileSync(new URL(rel, import.meta.url), "utf8"));
+            if (meta && typeof meta.version === "string") {
+                return { name: meta.name ?? FALLBACK.name, version: meta.version };
+            }
+        }
+        catch {
+            /* try the next candidate */
+        }
+    }
+    return FALLBACK;
+}

package/src/lib/platform.ts

@@ -0,0 +1,57 @@
+/**
+ * Cross-platform detection and small helpers.
+ *
+ * FastCode targets Termux, Linux, macOS, and Windows. Most of our
+ * environment-aware behavior keys off these flags rather than scattering
+ * `process.platform === "..."` checks across the codebase.
+ */
+import { platform, homedir } from "node:os";
+export function detectPlatform() {
+    // Termux exposes PREFIX=/data/data/com.termux/files/usr. The extra check
+    // makes us robust to users who manually export PREFIX for other reasons.
+    const prefix = process.env["PREFIX"];
+    // Termux exports TERMUX_VERSION; PREFIX=/data/data/com.termux/files/usr is a
+    // strong secondary signal. Neither requires the directory to exist yet.
+    if (process.platform === "android" ||
+        Boolean(process.env["TERMUX_VERSION"]) ||
+        (prefix && prefix.includes("com.termux"))) {
+        return "termux";
+    }
+    switch (process.platform) {
+        case "linux":
+        case "darwin":
+        case "win32":
+            return process.platform;
+        default:
+            return "other";
+    }
+}
+export const isTermux = () => detectPlatform() === "termux";
+export const isWindows = () => process.platform === "win32";
+export const isMac = () => process.platform === "darwin";
+/** Human-readable label for the status bar. */
+export function platformLabel() {
+    const p = detectPlatform();
+    switch (p) {
+        case "termux":
+            return "Termux";
+        case "linux":
+            return "Linux";
+        case "darwin":
+            return "macOS";
+        case "win32":
+            return "Windows";
+        default:
+            return platform();
+    }
+}
+export function safeHome() {
+    // os.homedir() can return undefined on weird CI containers; fall back
+    // to $HOME / %USERPROFILE% / cwd in that order.
+    const fromOs = homedir();
+    if (fromOs)
+        return fromOs;
+    return (process.env["HOME"] ??
+        process.env["USERPROFILE"] ??
+        process.cwd());
+}

package/src/lib/startup.ts

@@ -0,0 +1,25 @@
+import { resolveApiKey } from "../config/store.js";
+import { getProviderOrThrow } from "../providers/index.js";
+export function createStartupTranscript(config) {
+    const messages = [
+        `Welcome to FastCode. Provider: **${config.providerId}** · model: **${config.model}**.\n\nType **/help** to list slash commands, or just start chatting.`,
+    ];
+    const provider = getProviderOrThrow(config.providerId);
+    if (provider.authEnv.length > 0) {
+        const lookup = resolveApiKey(provider.id, config.model, provider.authEnv);
+        if (lookup.status === "unbound") {
+            messages.push(`Stored ${provider.label} key isn't bound to a model, so it won't be used. ` +
+                `Re-bind it with \`/login ${provider.id} ${config.model} <key>\` (or \`/logout ${provider.id}\` to discard it).`);
+        }
+        else if (lookup.status === "missing") {
+            messages.push(`No API key for ${provider.label} · ${config.model}. ` +
+                `Run \`/login ${provider.id} ${config.model} <key>\`, or set ${provider.authEnv[0]} (provider-wide, any model).`);
+        }
+    }
+    return messages.map((content, index) => ({
+        id: index + 1,
+        role: "system",
+        content,
+        markdown: true,
+    }));
+}

package/src/lib/uiMode.ts

@@ -0,0 +1,7 @@
+import { detectPlatform } from "./platform.js";
+export function shouldUseStableTerminalUi(platform = detectPlatform(), env = process.env) {
+    return platform === "termux" || env.FASTCODE_STABLE_UI === "1";
+}
+export function shouldUseLiveStreamingUi(platform = detectPlatform(), env = process.env) {
+    return !shouldUseStableTerminalUi(platform, env);
+}

package/src/plugins/manager.ts

@@ -0,0 +1,101 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { getPaths } from "../config/paths.js";
+export function listInstalledPlugins() {
+    const { plugins } = getPaths();
+    if (!existsSync(plugins))
+        return [];
+    return readdirSync(plugins, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => loadPlugin(join(plugins, entry.name), entry.name))
+        .filter((plugin) => plugin !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function getPlugin(name) {
+    return listInstalledPlugins().find((p) => p.name === name || basename(p.path) === name);
+}
+export function importPlugin(source, name) {
+    const { plugins } = getPaths();
+    const src = resolve(source);
+    if (!existsSync(src))
+        throw new Error(`Plugin source does not exist: ${source}`);
+    if (!statSync(src).isDirectory())
+        throw new Error("Plugin source must be a directory");
+    const folder = slugify(name ?? basename(src));
+    const target = join(plugins, folder);
+    if (existsSync(target))
+        rmSync(target, { recursive: true, force: true });
+    mkdirSync(target, { recursive: true });
+    cpSync(src, target, { recursive: true });
+    writeFileSync(join(target, ".fastcode-source"), src);
+    const loaded = loadPlugin(target, folder);
+    if (!loaded)
+        throw new Error("Plugin must include PLUGIN.md, README.md, or at least one SKILL.md");
+    return loaded;
+}
+export function removePlugin(name) {
+    const plugin = getPlugin(name);
+    if (!plugin)
+        return false;
+    rmSync(plugin.path, { recursive: true, force: true });
+    return true;
+}
+export function buildPluginsPrompt(enabled) {
+    if (enabled.length === 0)
+        return "";
+    const plugins = enabled.map(getPlugin).filter((p) => p !== undefined);
+    if (plugins.length === 0)
+        return "";
+    const chunks = plugins.map((plugin) => {
+        const skills = plugin.skills
+            .map((skill) => `<plugin-skill name="${skill.name}">\n${skill.body.trim()}\n</plugin-skill>`)
+            .join("\n\n");
+        return `<plugin name="${plugin.name}">\n${plugin.body.trim()}\n${skills ? `\n\n${skills}` : ""}\n</plugin>`;
+    });
+    return [
+        "",
+        "## Active plugins",
+        "The following plugins are always-active behavior packs. Follow them when relevant:",
+        "",
+        chunks.join("\n\n"),
+    ].join("\n");
+}
+function loadPlugin(path, fallbackName) {
+    const pluginMd = firstExisting([join(path, "PLUGIN.md"), join(path, "README.md")]);
+    const skillsDir = join(path, "skills");
+    const rootSkill = join(path, "SKILL.md");
+    const skills = [];
+    if (existsSync(rootSkill))
+        skills.push({ name: "root", body: readFileSync(rootSkill, "utf8") });
+    if (existsSync(skillsDir)) {
+        for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const skillPath = join(skillsDir, entry.name, "SKILL.md");
+            if (existsSync(skillPath))
+                skills.push({ name: entry.name, body: readFileSync(skillPath, "utf8") });
+        }
+    }
+    if (!pluginMd && skills.length === 0)
+        return undefined;
+    const body = pluginMd ? readFileSync(pluginMd, "utf8") : `Plugin ${fallbackName}`;
+    return {
+        name: fallbackName,
+        description: firstParagraph(body) || `${fallbackName} plugin`,
+        path,
+        body,
+        skills,
+    };
+}
+function firstExisting(paths) {
+    return paths.find((path) => existsSync(path));
+}
+function firstParagraph(markdown) {
+    return markdown
+        .split(/\n\s*\n/)
+        .map((part) => part.replace(/^#+\s*/, "").trim())
+        .find(Boolean);
+}
+function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "plugin";
+}