@mirrowel/opencode-souk 0.1.0

package/dist/install.js

@@ -0,0 +1,719 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, basename, extname, relative } from "node:path";
+import { homedir } from "node:os";
+import { parse, stringify } from "comment-json";
+import { debugLog } from "./config.js";
+const OPENCODE_SCHEMA = "https://opencode.ai/config.json";
+const TUI_SCHEMA = "https://opencode.ai/tui.json";
+const THEME_SCHEMA = "https://opencode.ai/theme.json";
+export async function previewNativeInstall(items, scope, settings) {
+    const plans = await Promise.all(items.map((item) => planInstall(item, scope, settings)));
+    return {
+        supported: plans.some((plan) => plan.supported),
+        summary: plans.flatMap((plan) => plan.actions.length ? plan.actions : [`${plan.item.name}: no deterministic native action`]).join("\n"),
+        warnings: plans.flatMap((plan) => plan.warnings),
+    };
+}
+export async function nativeInstall(api, items, scope, callbacks = {}, settings) {
+    debugLog("Native install start", `${items.length} item(s) -> ${scopeLabel(scope)}`);
+    const installed = [];
+    const failed = [];
+    const planned = await Promise.all(items.map(async (item) => ({ item, plan: await planInstall(item, scope, settings).catch((error) => ({ item, supported: false, actions: [], warnings: [error instanceof Error ? error.message : String(error)] })) })));
+    const supported = planned.filter(({ plan }) => plan.supported && plan.execute);
+    let backupPath;
+    if (supported.length) {
+        backupPath = createInstallBackup(scope, supported.map(({ item }) => item));
+        installed.push(`Pre-install backup created at ${backupPath}`);
+    }
+    for (const { item, plan } of planned) {
+        try {
+            if (!plan.supported || !plan.execute) {
+                failed.push(`${item.name}: ${plan.warnings[0] ?? "no deterministic native installer"}`);
+                continue;
+            }
+            installed.push(...await plan.execute(api, callbacks));
+        }
+        catch (error) {
+            failed.push(`${item.name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    debugLog("Native install result", `installed=${installed.length}; failed=${failed.length}`);
+    return { installed, failed };
+}
+function createInstallBackup(scope, items) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const root = join(globalConfigDir(), "souk-install-backups", `${stamp}-${scope.kind}`);
+    mkdirSync(root, { recursive: true });
+    const candidates = scope.kind === "global" ? globalBackupCandidates() : projectBackupCandidates(scope.path);
+    const copied = [];
+    for (const candidate of candidates) {
+        if (!existsSync(candidate.path))
+            continue;
+        const target = join(root, candidate.label);
+        mkdirSync(dirname(target), { recursive: true });
+        cpSync(candidate.path, target, { recursive: true, force: false, errorOnExist: true });
+        copied.push(candidate.label);
+    }
+    writeTextAtomic(join(root, "manifest.json"), `${JSON.stringify({
+        createdAt: new Date().toISOString(),
+        scope,
+        items: items.map((item) => ({ id: item.id, name: item.name, kind: item.kind, source: item.source, repoUrl: item.repoUrl })),
+        copied,
+    }, null, 2)}\n`);
+    debugLog("Install backup created", `${root}; copied=${copied.length}`);
+    return root;
+}
+function globalBackupCandidates() {
+    const dir = globalConfigDir();
+    return [
+        "opencode.jsonc",
+        "opencode.json",
+        "config.json",
+        "tui.jsonc",
+        "tui.json",
+        "agents",
+        "agent",
+        "commands",
+        "command",
+        "skills",
+        "skill",
+        "themes",
+        "plugins",
+        "plugin",
+    ].map((name) => ({ path: join(dir, name), label: name }));
+}
+function projectBackupCandidates(project) {
+    return [
+        "opencode.jsonc",
+        "opencode.json",
+        "tui.jsonc",
+        "tui.json",
+        ".opencode",
+    ].map((name) => ({ path: join(project, name), label: relative(project, join(project, name)) }));
+}
+async function planInstall(item, scope, settings) {
+    if (item.kind === "plugin")
+        return planPluginInstall(item, scope);
+    if (item.kind === "mcp")
+        return planMcpInstall(item, scope, settings);
+    if (item.kind === "agent")
+        return planAgentInstall(item, scope);
+    if (item.kind === "command")
+        return planCommandInstall(item, scope);
+    if (item.kind === "theme")
+        return planThemeInstall(item, scope);
+    if (item.kind === "skill")
+        return planSkillInstall(item, scope);
+    return unsupported(item, `Native ${item.kind} install is not deterministic yet. Use Forge with Kāf for this item.`);
+}
+async function planAgentInstall(item, scope) {
+    const agentConfig = extractAgentConfig(item);
+    if (agentConfig && Object.keys(agentConfig).length) {
+        const target = opencodeConfigPath(scope);
+        return {
+            item,
+            supported: true,
+            actions: Object.keys(agentConfig).map((name) => `AGENT ${name} -> ${target}`),
+            warnings: item.warnings,
+            execute: async () => {
+                patchJsonc(target, OPENCODE_SCHEMA, (doc) => {
+                    const agent = ensureRecord(doc, "agent");
+                    setConfigEntries(agent, agentConfig, "agent");
+                });
+                return [`${item.name}: installed ${Object.keys(agentConfig).length} agent config entrie(s) into ${target}`];
+            },
+        };
+    }
+    return planMarkdownInstall(item, scope, "agent");
+}
+function planPluginInstall(item, scope) {
+    const spec = item.install?.spec ?? inferNpmSpec(item);
+    if (!spec)
+        return unsupported(item, "No plugin package/file spec found.");
+    return {
+        item,
+        supported: true,
+        actions: [`PLUGIN ${spec} -> ${scopeLabel(scope)} plugin config via OpenCode native installer`],
+        warnings: item.warnings,
+        execute: async (api) => {
+            const pluginApi = api.plugins;
+            if (pluginApi?.install) {
+                const out = await pluginApi.install(spec, { global: scope.kind === "global" });
+                if (!out.ok)
+                    throw new Error(out.message);
+                const lines = [`${item.name}: installed plugin ${spec}`];
+                if (out.tui) {
+                    const ok = await pluginApi.add(spec);
+                    lines.push(ok ? `${item.name}: TUI plugin loaded in this session` : `${item.name}: installed; restart OpenCode if runtime TUI load did not activate`);
+                }
+                return lines;
+            }
+            const target = opencodeConfigPath(scope);
+            patchJsonc(target, OPENCODE_SCHEMA, (doc) => appendPluginSpec(doc, spec));
+            return [`${item.name}: added plugin ${spec} to ${target}. Restart OpenCode for config-time plugin loading.`];
+        },
+    };
+}
+async function planMcpInstall(item, scope, settings) {
+    const extracted = extractMcpConfig(item);
+    if (extracted.requiresConversionApproval && settings?.allow_claude_mcp_conversion === "never")
+        return unsupported(item, "Claude mcpServers conversion is disabled by Souk config.");
+    if (!extracted.config || Object.keys(extracted.config).length === 0)
+        return unsupported(item, "No valid OpenCode MCP config or convertible Claude mcpServers config found.");
+    const target = opencodeConfigPath(scope);
+    return {
+        item,
+        supported: true,
+        actions: Object.keys(extracted.config).map((name) => `MCP ${name} -> ${target}`),
+        warnings: [...item.warnings, ...extracted.warnings],
+        execute: async (api, callbacks) => {
+            if (extracted.requiresConversionApproval) {
+                const ok = await callbacks.confirm?.("Convert Claude MCP config?", `${item.name} contains Claude-style mcpServers config. Souk can convert it to OpenCode mcp config.\n\nThe souk can make mistakes. Review the converted server names and commands before approving.`);
+                if (!ok)
+                    throw new Error("Claude mcpServers conversion was not approved.");
+            }
+            patchJsonc(target, OPENCODE_SCHEMA, (doc) => {
+                const mcp = ensureRecord(doc, "mcp");
+                setConfigEntries(mcp, extracted.config, "MCP server");
+            });
+            if (settings?.runtime_mcp_connect !== false)
+                await addRuntimeMcp(api, extracted.config, scope);
+            return [`${item.name}: installed ${Object.keys(extracted.config).length} MCP server(s) into ${target}`];
+        },
+    };
+}
+async function planMarkdownInstall(item, scope, kind) {
+    const files = await markdownFilesFor(item, kind);
+    if (!files.length)
+        return unsupported(item, `No ${kind} markdown file or config snippet found.`);
+    const dir = scopedDir(scope, kind);
+    const targets = files.map((file) => ({ source: file, target: uniqueTargetPath(dir, `${safeName(stripKnownPrefix(file.path, kind))}.md`) }));
+    return {
+        item,
+        supported: true,
+        actions: targets.map(({ source, target }) => `${kind.toUpperCase()} ${source.path} -> ${target}`),
+        warnings: item.warnings,
+        execute: async (_api, callbacks) => {
+            const lines = [];
+            for (const { source, target } of targets) {
+                writeNewFile(target, ensureMarkdownFrontmatter(source.content, item, kind));
+                lines.push(`${item.name}: installed ${kind} ${basename(target, ".md")} into ${target}`);
+            }
+            return lines;
+        },
+    };
+}
+async function planCommandInstall(item, scope) {
+    const commandConfig = extractCommandConfig(item);
+    if (commandConfig && Object.keys(commandConfig).length) {
+        const target = opencodeConfigPath(scope);
+        return {
+            item,
+            supported: true,
+            actions: Object.keys(commandConfig).map((name) => `COMMAND ${name} -> ${target}`),
+            warnings: item.warnings,
+            execute: async () => {
+                patchJsonc(target, OPENCODE_SCHEMA, (doc) => {
+                    const command = ensureRecord(doc, "command");
+                    setConfigEntries(command, commandConfig, "command");
+                });
+                return [`${item.name}: installed ${Object.keys(commandConfig).length} command(s) into ${target}`];
+            },
+        };
+    }
+    return planMarkdownInstall(item, scope, "command");
+}
+function extractAgentConfig(item) {
+    for (const snippet of candidateObjects(item)) {
+        const agent = asRecord(snippet.agent);
+        if (agent)
+            return Object.fromEntries(Object.entries(agent).flatMap(([name, value]) => {
+                const config = asRecord(value);
+                if (!config)
+                    return [];
+                return [[safeName(name), config]];
+            }));
+    }
+    return undefined;
+}
+async function planThemeInstall(item, scope) {
+    const themes = await themeFilesFor(item);
+    if (!themes.length)
+        return unsupported(item, "No valid OpenCode theme JSON found.");
+    const dir = scopedDir(scope, "theme");
+    const targets = themes.map((file) => ({ source: file, target: uniqueTargetPath(dir, `${safeName(basename(file.path, extname(file.path)) || item.name)}.json`) }));
+    return {
+        item,
+        supported: true,
+        actions: targets.map(({ source, target }) => `THEME ${source.path} -> ${target}`),
+        warnings: [...item.warnings, "Theme is installed but not activated automatically; set tui.json theme if desired."],
+        execute: async (_api, callbacks) => {
+            const lines = [];
+            for (const { source, target } of targets) {
+                writeNewFile(target, normalizeThemeJson(source.content));
+                lines.push(`${item.name}: installed theme ${basename(target, ".json")} into ${target}`);
+            }
+            if (targets.length === 1) {
+                const themeName = basename(targets[0].target, ".json");
+                const ok = await callbacks.confirm?.("Activate theme?", `Activate theme "${themeName}" in ${scopeLabel(scope)} tui config?\n\nThis writes the theme field to tui.jsonc and requires restarting or reopening OpenCode TUI if the running UI does not refresh it.`);
+                if (ok) {
+                    const tuiPath = tuiConfigPath(scope);
+                    patchJsonc(tuiPath, TUI_SCHEMA, (doc) => { doc.theme = themeName; });
+                    lines.push(`${item.name}: activated theme ${themeName} in ${tuiPath}`);
+                }
+            }
+            return lines;
+        },
+    };
+}
+async function planSkillInstall(item, scope) {
+    const skills = await skillFilesFor(item);
+    if (!skills.length)
+        return unsupported(item, "No SKILL.md file found.");
+    const dir = scopedDir(scope, "skill");
+    const targets = skills.map((skill) => {
+        const folder = safeName(skill.name || item.name);
+        const files = skill.files.map((file) => ({ source: file, target: join(dir, folder, relativeWithinSkill(file.path, skill.root)) }));
+        return { name: folder, files };
+    });
+    return {
+        item,
+        supported: true,
+        actions: targets.flatMap((skill) => skill.files.map(({ source, target }) => `SKILL ${skill.name}/${source.path} -> ${target}`)),
+        warnings: item.warnings,
+        execute: async () => {
+            const lines = [];
+            for (const skill of targets) {
+                for (const { source, target } of skill.files)
+                    writeNewFile(target, source.content);
+                lines.push(`${item.name}: installed skill ${skill.name} with ${skill.files.length} file(s)`);
+            }
+            return lines;
+        },
+    };
+}
+function extractMcpConfig(item) {
+    const warnings = [];
+    const snippets = candidateObjects(item);
+    for (const snippet of snippets) {
+        const mcp = asRecord(snippet.mcp);
+        if (mcp)
+            return { config: normalizeMcpMap(mcp, warnings), warnings, requiresConversionApproval: false };
+        const direct = normalizeMcpEntry(snippet, warnings);
+        if (direct)
+            return { config: { [safeName(item.install?.name ?? item.name)]: direct }, warnings, requiresConversionApproval: false };
+        const claude = asRecord(snippet.mcpServers);
+        if (claude)
+            return { config: convertClaudeMcp(claude, warnings), warnings, requiresConversionApproval: true };
+    }
+    if (item.install?.config && item.install.type === "mcp")
+        return { config: normalizeMcpMap(item.install.config, warnings), warnings, requiresConversionApproval: false };
+    return { config: {}, warnings, requiresConversionApproval: false };
+}
+function extractCommandConfig(item) {
+    for (const snippet of candidateObjects(item)) {
+        const command = asRecord(snippet.command);
+        if (command)
+            return Object.fromEntries(Object.entries(command).flatMap(([name, value]) => {
+                const config = asRecord(value);
+                if (!config || typeof config.template !== "string")
+                    return [];
+                return [[safeName(name), config]];
+            }));
+    }
+    return undefined;
+}
+async function markdownFilesFor(item, kind) {
+    const fromBlocks = markdownBlocks(item.installationMarkdown).filter((block) => looksLikeMarkdownEntry(block, kind));
+    if (fromBlocks.length)
+        return fromBlocks.map((content, index) => ({ path: `${safeName(item.name)}${index ? `-${index + 1}` : ""}.md`, content }));
+    const repo = await githubFiles(item.repoUrl, kind);
+    return repo.filter((file) => looksLikeKnownPath(file.path, kind));
+}
+async function themeFilesFor(item) {
+    const fromBlocks = codeBlocks(item.installationMarkdown).filter((block) => isThemeJsonText(block));
+    if (fromBlocks.length)
+        return fromBlocks.map((content, index) => ({ path: `${safeName(item.name)}${index ? `-${index + 1}` : ""}.json`, content }));
+    return (await githubFiles(item.repoUrl, "theme")).filter((file) => isThemeJsonText(file.content));
+}
+async function skillFilesFor(item) {
+    const fromBlocks = markdownBlocks(item.installationMarkdown).filter((block) => /---[\s\S]*name\s*:/m.test(block) && /---[\s\S]*description\s*:/m.test(block));
+    if (fromBlocks.length)
+        return fromBlocks.map((content) => ({ name: skillNameFromText(content) ?? safeName(item.name), root: "", files: [{ path: "SKILL.md", content }] }));
+    const repo = await githubFiles(item.repoUrl, "skill");
+    const skillRoots = repo.filter((file) => basename(file.path) === "SKILL.md").map((file) => dirname(file.path));
+    return skillRoots.map((root) => {
+        const files = repo.filter((file) => file.path === join(root, "SKILL.md").replace(/\\/g, "/") || file.path.startsWith(`${root}/`));
+        const skillMd = files.find((file) => basename(file.path) === "SKILL.md");
+        return { name: skillNameFromText(skillMd?.content ?? "") ?? safeName(basename(root) || item.name), root, files };
+    });
+}
+async function githubFiles(repoUrl, kind) {
+    const parsed = parseGitHubRepo(repoUrl);
+    if (!parsed)
+        return [];
+    const repoInfo = await fetchJson(`https://api.github.com/repos/${parsed.owner}/${parsed.repo}`);
+    const defaultBranch = typeof repoInfo.default_branch === "string" ? repoInfo.default_branch : "main";
+    const tree = await fetchJson(`https://api.github.com/repos/${parsed.owner}/${parsed.repo}/git/trees/${encodeURIComponent(parsed.branch ?? defaultBranch)}?recursive=1`);
+    const entries = Array.isArray(tree.tree) ? tree.tree : [];
+    const paths = entries.flatMap((entry) => {
+        const rec = asRecord(entry);
+        if (!rec || rec.type !== "blob" || typeof rec.path !== "string")
+            return [];
+        return [rec.path];
+    }).filter((path) => candidatePath(path, kind));
+    const selected = narrowCandidates(paths, parsed.path, kind);
+    return Promise.all(selected.map(async (path) => ({ path, content: await fetchText(`https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/${encodeURIComponent(parsed.branch ?? defaultBranch).replace(/%2F/g, "/")}/${path}`) })));
+}
+function candidatePath(path, kind) {
+    const lower = path.toLowerCase();
+    if (kind === "agent")
+        return /(^|\/)(agent|agents)\/.*\.md$/.test(lower);
+    if (kind === "command")
+        return /(^|\/)(command|commands)\/.*\.md$/.test(lower);
+    if (kind === "skill")
+        return /(^|\/)(skill|skills)\/.*$/.test(lower) || /(^|\/)skill\.md$/.test(lower);
+    if (kind === "theme")
+        return /(^|\/)themes\/.*\.json$/.test(lower) || /theme.*\.json$/.test(lower);
+    return false;
+}
+function narrowCandidates(paths, requestedPath, kind) {
+    const scoped = requestedPath ? paths.filter((path) => path === requestedPath || path.startsWith(`${requestedPath.replace(/\/$/, "")}/`)) : paths;
+    const source = scoped.length ? scoped : paths;
+    if (kind === "skill")
+        return source.slice(0, 100);
+    return source.slice(0, 25);
+}
+function candidateObjects(item) {
+    const objects = [];
+    if (item.install?.config)
+        objects.push(item.install.config);
+    for (const block of codeBlocks(item.installationMarkdown)) {
+        const parsed = parseLooseObject(block);
+        if (parsed)
+            objects.push(parsed);
+    }
+    const whole = parseLooseObject(item.installationMarkdown);
+    if (whole)
+        objects.push(whole);
+    return objects;
+}
+function codeBlocks(text) {
+    if (!text)
+        return [];
+    const blocks = [];
+    for (const match of text.matchAll(/```(?:jsonc?|ya?ml|toml|md|markdown)?\s*([\s\S]*?)```/gi)) {
+        if (match[1]?.trim())
+            blocks.push(match[1].trim());
+    }
+    return blocks.length ? blocks : [text.trim()].filter(Boolean);
+}
+function markdownBlocks(text) {
+    return codeBlocks(text).filter((block) => block.includes("---") || block.split(/\r?\n/).length > 3);
+}
+function parseLooseObject(text) {
+    if (!text)
+        return undefined;
+    const candidates = [text, stripJsonAssignment(text), extractBraced(text)].filter((candidate) => !!candidate);
+    for (const candidate of candidates) {
+        try {
+            const parsed = parse(candidate);
+            if (isRecord(parsed))
+                return parsed;
+        }
+        catch {
+            // keep trying candidates
+        }
+    }
+    return undefined;
+}
+function stripJsonAssignment(text) {
+    return text.replace(/^\s*(?:const|let|var|export\s+default)?\s*[\w-]+\s*=\s*/m, "").trim();
+}
+function extractBraced(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    return start >= 0 && end > start ? text.slice(start, end + 1) : undefined;
+}
+function normalizeMcpMap(map, warnings) {
+    return Object.fromEntries(Object.entries(map).flatMap(([name, value]) => {
+        const entry = normalizeMcpEntry(value, warnings);
+        if (!entry) {
+            warnings.push(`${name}: skipped invalid MCP config.`);
+            return [];
+        }
+        return [[safeName(name), entry]];
+    }));
+}
+function normalizeMcpEntry(value, warnings) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    if (record.type === "local") {
+        const command = normalizeCommandArray(record.command, asArray(record.args));
+        if (!command.length)
+            return undefined;
+        return cleanObject({ type: "local", command, environment: stringMap(record.environment ?? record.env), enabled: record.enabled ?? true, timeout: positiveInt(record.timeout) });
+    }
+    if (record.type === "remote") {
+        const url = typeof record.url === "string" ? record.url : undefined;
+        if (!url)
+            return undefined;
+        return cleanObject({ type: "remote", url, headers: stringMap(record.headers), oauth: record.oauth, enabled: record.enabled ?? true, timeout: positiveInt(record.timeout) });
+    }
+    if (typeof record.url === "string")
+        return cleanObject({ type: "remote", url: record.url, headers: stringMap(record.headers), oauth: record.oauth, enabled: record.enabled ?? true, timeout: positiveInt(record.timeout) });
+    const command = normalizeCommandArray(record.command, asArray(record.args));
+    if (command.length) {
+        warnings.push("Converted command/args MCP entry to OpenCode local MCP config.");
+        return cleanObject({ type: "local", command, environment: stringMap(record.environment ?? record.env), enabled: record.enabled ?? true, timeout: positiveInt(record.timeout) });
+    }
+    return undefined;
+}
+function convertClaudeMcp(map, warnings) {
+    warnings.push("Claude mcpServers config requires explicit conversion approval.");
+    return Object.fromEntries(Object.entries(map).flatMap(([name, value]) => {
+        const entry = normalizeMcpEntry(value, warnings);
+        return entry ? [[safeName(name), entry]] : [];
+    }));
+}
+function patchJsonc(path, schema, mutate) {
+    const doc = readJsonc(path, schema);
+    mutate(doc);
+    writeTextAtomic(path, `${stringify(doc, null, 2)}\n`);
+}
+function setConfigEntries(target, entries, label) {
+    for (const [name, value] of Object.entries(entries)) {
+        const existing = target[name];
+        if (existing !== undefined && stableJson(existing) !== stableJson(value)) {
+            throw new Error(`${label} "${name}" already exists with different config. Refusing to overwrite.`);
+        }
+        target[name] = value;
+    }
+}
+function appendPluginSpec(doc, spec) {
+    const plugin = doc.plugin;
+    if (plugin !== undefined && !Array.isArray(plugin))
+        throw new Error("opencode config plugin field exists but is not an array. Refusing to overwrite.");
+    const list = Array.isArray(plugin) ? plugin : [];
+    const exists = list.some((entry) => Array.isArray(entry) ? entry[0] === spec : entry === spec);
+    if (!exists)
+        list.push(spec);
+    doc.plugin = list;
+}
+async function addRuntimeMcp(api, configs, scope) {
+    const client = api.client;
+    if (!client.mcp?.add)
+        return;
+    for (const [name, config] of Object.entries(configs)) {
+        try {
+            await client.mcp.add({ name, config, ...(scope.kind === "project" ? { directory: scope.path } : {}) });
+            if (client.mcp.connect)
+                await client.mcp.connect({ name, ...(scope.kind === "project" ? { directory: scope.path } : {}) }).catch(() => undefined);
+        }
+        catch {
+            // Persistent config is the source of truth. Runtime MCP add is best-effort because
+            // some servers require restart, auth, env, or credentials before connecting.
+        }
+    }
+}
+function readJsonc(path, schema) {
+    if (!existsSync(path))
+        return { $schema: schema };
+    const parsed = parse(readFileSync(path, "utf8"));
+    if (!isRecord(parsed))
+        throw new Error(`${path} does not contain a JSON object.`);
+    if (!parsed.$schema)
+        parsed.$schema = schema;
+    return parsed;
+}
+function ensureRecord(doc, key) {
+    const existing = doc[key];
+    if (isRecord(existing))
+        return existing;
+    doc[key] = {};
+    return doc[key];
+}
+function writeNewFile(path, content) {
+    if (existsSync(path)) {
+        const current = readFileSync(path, "utf8");
+        if (normalizeNewlines(current) === normalizeNewlines(content))
+            return;
+        throw new Error(`${path} already exists with different content. Refusing to overwrite.`);
+    }
+    writeTextAtomic(path, content.endsWith("\n") ? content : `${content}\n`);
+}
+function writeTextAtomic(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(temp, content, "utf8");
+    renameSync(temp, path);
+}
+function opencodeConfigPath(scope) {
+    return scope.kind === "global" ? join(globalConfigDir(), "opencode.jsonc") : join(scope.path, ".opencode", "opencode.jsonc");
+}
+function tuiConfigPath(scope) {
+    return scope.kind === "global" ? join(globalConfigDir(), "tui.jsonc") : join(scope.path, ".opencode", "tui.jsonc");
+}
+function scopedDir(scope, kind) {
+    if (scope.kind === "global") {
+        if (kind === "theme")
+            return join(globalConfigDir(), "themes");
+        if (kind === "skill")
+            return join(globalConfigDir(), "skills");
+        return join(globalConfigDir(), `${kind}s`);
+    }
+    if (kind === "theme")
+        return join(scope.path, ".opencode", "themes");
+    if (kind === "skill")
+        return join(scope.path, ".opencode", "skills");
+    return join(scope.path, ".opencode", `${kind}s`);
+}
+function globalConfigDir() {
+    if (process.env.OPENCODE_CONFIG_DIR)
+        return process.env.OPENCODE_CONFIG_DIR;
+    if (process.env.XDG_CONFIG_HOME)
+        return join(process.env.XDG_CONFIG_HOME, "opencode");
+    if (process.platform === "win32" && process.env.APPDATA)
+        return join(process.env.APPDATA, "opencode");
+    return join(homedir(), ".config", "opencode");
+}
+function looksLikeMarkdownEntry(content, kind) {
+    if (kind === "agent")
+        return /---[\s\S]*description\s*:/m.test(content) || /---[\s\S]*mode\s*:/m.test(content);
+    return /\$ARGUMENTS|---[\s\S]*(description|agent|model|subtask)\s*:/m.test(content);
+}
+function looksLikeKnownPath(path, kind) {
+    const lower = path.toLowerCase();
+    return kind === "agent" ? /(^|\/)(agent|agents)\/.*\.md$/.test(lower) : /(^|\/)(command|commands)\/.*\.md$/.test(lower);
+}
+function ensureMarkdownFrontmatter(content, item, kind) {
+    if (/^---\s*\r?\n/.test(content))
+        return content;
+    const desc = item.description.replace(/\r?\n/g, " ").replace(/"/g, "'");
+    if (kind === "agent")
+        return `---\ndescription: "${desc || `Installed by OpenCode Souk from ${item.source}`}"\nmode: subagent\n---\n\n${content}`;
+    return `---\ndescription: "${desc || `Installed by OpenCode Souk from ${item.source}`}"\n---\n\n${content}`;
+}
+function normalizeThemeJson(content) {
+    const parsed = parse(content);
+    if (!isRecord(parsed) || !isRecord(parsed.theme))
+        throw new Error("Invalid theme JSON; expected object with theme field.");
+    if (!parsed.$schema)
+        parsed.$schema = THEME_SCHEMA;
+    return `${stringify(parsed, null, 2)}\n`;
+}
+function isThemeJsonText(content) {
+    try {
+        const parsed = parse(content);
+        return isRecord(parsed) && isRecord(parsed.theme);
+    }
+    catch {
+        return false;
+    }
+}
+function skillNameFromText(content) {
+    return /^---[\s\S]*?\nname:\s*["']?([^"'\n]+)["']?/m.exec(content)?.[1]?.trim();
+}
+function relativeWithinSkill(path, root) {
+    if (!root)
+        return basename(path) || "SKILL.md";
+    const rel = path.startsWith(`${root}/`) ? path.slice(root.length + 1) : basename(path);
+    return rel || "SKILL.md";
+}
+function parseGitHubRepo(url) {
+    if (!url)
+        return undefined;
+    try {
+        const parsed = new URL(url);
+        if (parsed.hostname !== "github.com")
+            return undefined;
+        const parts = parsed.pathname.split("/").filter(Boolean);
+        const owner = parts[0];
+        const repo = parts[1]?.replace(/\.git$/, "");
+        if (!owner || !repo)
+            return undefined;
+        const treeIndex = parts.indexOf("tree");
+        const blobIndex = parts.indexOf("blob");
+        if (treeIndex >= 0)
+            return { owner, repo, branch: parts[treeIndex + 1], path: parts.slice(treeIndex + 2).join("/") || undefined };
+        if (blobIndex >= 0)
+            return { owner, repo, branch: parts[blobIndex + 1], path: parts.slice(blobIndex + 2).join("/") || undefined };
+        return { owner, repo, branch: undefined, path: undefined };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function fetchJson(url) {
+    const response = await fetch(url, { headers: { accept: "application/vnd.github+json" } });
+    if (!response.ok)
+        throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+    return await response.json();
+}
+async function fetchText(url) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+    return await response.text();
+}
+function unsupported(item, reason) {
+    return { item, supported: false, actions: [], warnings: [`${item.name}: ${reason}`] };
+}
+function scopeLabel(scope) {
+    return scope.kind === "global" ? "global" : `project (${scope.path})`;
+}
+export { scopeLabel };
+function inferNpmSpec(item) {
+    if (item.install?.type === "plugin" && item.install.spec)
+        return item.install.spec;
+    return undefined;
+}
+function stripKnownPrefix(path, kind) {
+    const normalized = path.replace(/\\/g, "/");
+    return normalized.replace(new RegExp(`^.*(?:${kind}|${kind}s)/`, "i"), "").replace(/\.md$/i, "");
+}
+function uniqueTargetPath(dir, file) {
+    return join(dir, safeName(basename(file, extname(file))) + extname(file));
+}
+function safeName(value) {
+    return value.toLowerCase().trim().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "item";
+}
+function normalizeCommandArray(command, args) {
+    if (Array.isArray(command))
+        return command.filter((part) => typeof part === "string" && part.length > 0);
+    if (typeof command === "string" && command.length > 0)
+        return [command, ...args.filter((part) => typeof part === "string")];
+    return [];
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function stringMap(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    return Object.fromEntries(Object.entries(record).flatMap(([key, raw]) => typeof raw === "string" ? [[key, raw]] : []));
+}
+function positiveInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+function cleanObject(record) {
+    return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
+}
+function asRecord(value) {
+    return isRecord(value) ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeNewlines(value) {
+    return value.replace(/\r\n/g, "\n");
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (isRecord(value))
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+    return JSON.stringify(value);
+}