loadout-ai 0.1.0

package/dist/src/core/mcp.js

@@ -0,0 +1,287 @@
+import { readFile, readdir, mkdir, rename, writeFile, rm, } from "node:fs/promises";
+import { join, resolve, dirname, basename } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { loadoutHome } from "./paths.js";
+import { runMutationTransaction, withMutationLock } from "./transaction.js";
+const missingConfigMarker = "loadout:mcp-config:missing";
+async function configFingerprint(path) {
+    let content;
+    try {
+        content = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            content = missingConfigMarker;
+        else
+            throw error;
+    }
+    return createHash("sha256").update(content).digest("hex");
+}
+const MANIFEST_NAMES = new Set([
+    "mcp.json",
+    ".mcp.json",
+    "claude_desktop_config.json",
+]);
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function normalizeServer(name, value, sourcePath) {
+    const warnings = [];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {
+            name,
+            args: [],
+            env: {},
+            sourcePath,
+            warnings: ["server entry must be an object"],
+        };
+    }
+    const raw = value;
+    const command = asString(raw.command);
+    const url = asString(raw.url) ?? asString(raw.endpoint);
+    if (!command && !url)
+        warnings.push("server has neither a command nor a URL");
+    if (command && url)
+        warnings.push("server has both command and URL; command will be preferred by clients");
+    const args = Array.isArray(raw.args)
+        ? raw.args.filter((arg) => typeof arg === "string")
+        : [];
+    if (raw.args !== undefined &&
+        (!Array.isArray(raw.args) || args.length !== raw.args.length))
+        warnings.push("non-string args were ignored");
+    const env = {};
+    if (raw.env && typeof raw.env === "object" && !Array.isArray(raw.env)) {
+        for (const [key, entry] of Object.entries(raw.env)) {
+            if (typeof entry === "string")
+                env[key] = entry;
+            else
+                warnings.push(`environment value ${key} was ignored because it is not a string`);
+        }
+    }
+    else if (raw.env !== undefined)
+        warnings.push("env must be an object");
+    return { name, command, url, args, env, sourcePath, warnings };
+}
+export function parseMcpManifest(value, sourcePath) {
+    const warnings = [];
+    const root = value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+    if (root !== value)
+        warnings.push("manifest root must be an object");
+    const rawServers = root.mcpServers ?? root.servers;
+    if (!rawServers ||
+        typeof rawServers !== "object" ||
+        Array.isArray(rawServers)) {
+        warnings.push("manifest has no mcpServers object");
+        return { path: sourcePath, servers: [], warnings };
+    }
+    const servers = Object.entries(rawServers).map(([name, server]) => normalizeServer(name, server, sourcePath));
+    return { path: sourcePath, servers, warnings };
+}
+async function findManifestFiles(root) {
+    const found = [];
+    async function visit(directory, depth) {
+        if (depth > 5)
+            return;
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === ".git" || entry.name === "node_modules")
+                continue;
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                await visit(path, depth + 1);
+            else if (entry.isFile() && MANIFEST_NAMES.has(entry.name))
+                found.push(path);
+        }
+    }
+    await visit(resolve(root), 0);
+    return found;
+}
+export async function discoverMcpManifests(root) {
+    const manifests = [];
+    for (const path of await findManifestFiles(root)) {
+        try {
+            manifests.push(parseMcpManifest(JSON.parse(await readFile(path, "utf8")), path));
+        }
+        catch (error) {
+            manifests.push({
+                path,
+                servers: [],
+                warnings: [
+                    `invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+                ],
+            });
+        }
+    }
+    return manifests;
+}
+/** Safe for terminal/UI output: never emits environment values or secrets. */
+export function summarizeMcpManifest(manifest) {
+    const lines = [`${manifest.path}: ${manifest.servers.length} MCP server(s)`];
+    for (const server of manifest.servers) {
+        const transport = server.command
+            ? `command ${server.command}`
+            : server.url
+                ? `URL ${server.url}`
+                : "invalid transport";
+        lines.push(`  - ${server.name} (${transport}${server.env ? `, ${Object.keys(server.env).length} env var(s)` : ""})`);
+        for (const warning of server.warnings)
+            lines.push(`    warning: ${warning}`);
+    }
+    for (const warning of manifest.warnings)
+        lines.push(`  warning: ${warning}`);
+    return lines.join("\n");
+}
+function safeName(name) {
+    if (!/^[A-Za-z0-9._-]{1,128}$/.test(name))
+        throw new Error("MCP server name may contain only letters, numbers, ., _, and -");
+}
+/** Build a mutation without touching disk. Existing top-level config keys are preserved. */
+export async function planMcpConfig(path, server, name = server.name) {
+    return planMcpConfigBatch(path, [{ server, name }]);
+}
+export async function planMcpConfigBatch(path, entries) {
+    if (!entries.length)
+        throw new Error("MCP configuration batch is empty");
+    for (const entry of entries)
+        safeName(entry.name ?? entry.server.name);
+    const target = resolve(path);
+    let current = {};
+    let baseSha256;
+    try {
+        const content = await readFile(target, "utf8");
+        baseSha256 = createHash("sha256").update(content).digest("hex");
+        const parsed = JSON.parse(content);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("config root must be an object");
+        current = parsed;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            baseSha256 = createHash("sha256")
+                .update(missingConfigMarker)
+                .digest("hex");
+        else
+            throw new Error(`Cannot read MCP config ${target}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const existing = current.mcpServers;
+    if (existing !== undefined &&
+        (!existing || typeof existing !== "object" || Array.isArray(existing)))
+        throw new Error("mcpServers must be an object");
+    const servers = { ...(existing ?? {}) };
+    const changes = [];
+    const warnings = [];
+    for (const item of entries) {
+        const server = item.server;
+        const name = item.name ?? server.name;
+        const had = Object.prototype.hasOwnProperty.call(servers, name);
+        const entry = server.url
+            ? {
+                url: server.url,
+                ...(server.args.length ? { args: server.args } : {}),
+                ...(Object.keys(server.env).length ? { env: server.env } : {}),
+            }
+            : {
+                command: server.command,
+                ...(server.args.length ? { args: server.args } : {}),
+                ...(Object.keys(server.env).length ? { env: server.env } : {}),
+            };
+        servers[name] = entry;
+        changes.push({
+            serverName: name,
+            action: had ? "replace" : "add",
+            summary: `${had ? "Replace" : "Add"} MCP server '${name}' (${server.url ? "URL" : "command"}; ${Object.keys(server.env).length} environment variable(s))`,
+        });
+        warnings.push(...server.warnings);
+    }
+    const proposed = { ...current, mcpServers: servers };
+    return {
+        path: target,
+        baseSha256,
+        serverName: changes[0].serverName,
+        changes,
+        warnings: [...new Set(warnings)],
+        proposed,
+    };
+}
+export function summarizeMcpConfigPlan(plan) {
+    return [
+        `MCP config: ${plan.path}`,
+        ...plan.changes.map((change) => `  - ${change.summary}`),
+        ...plan.warnings.map((warning) => `  warning: ${warning}`),
+    ].join("\n");
+}
+async function snapshotPath(id) {
+    return join(loadoutHome(), "mcp-snapshots", `${id}.json`);
+}
+export async function applyMcpConfigPlan(plan) {
+    const applied = await runMutationTransaction(async () => {
+        await mkdir(dirname(plan.path), { recursive: true });
+        let existed = true;
+        let content;
+        try {
+            content = await readFile(plan.path, "utf8");
+            if (content.length > 10_000_000)
+                throw new Error("MCP config is unexpectedly large");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                existed = false;
+            else
+                throw error;
+        }
+        const snapshot = {
+            id: randomUUID(),
+            path: plan.path,
+            existed,
+            content,
+            createdAt: new Date().toISOString(),
+        };
+        const stored = await snapshotPath(snapshot.id);
+        return {
+            targets: [plan.path, stored],
+            value: { plan, snapshot, stored },
+        };
+    }, async ({ plan: freshPlan, snapshot, stored }) => {
+        await writeMcpConfigPlan(freshPlan);
+        await mkdir(dirname(stored), { recursive: true });
+        await writeFile(stored, JSON.stringify(snapshot), { mode: 0o600 });
+        return snapshot;
+    });
+    return applied.result;
+}
+/** Write an already-reviewed plan atomically; transaction callers own snapshot/rollback. */
+export async function writeMcpConfigPlan(plan) {
+    if (plan.baseSha256 &&
+        (await configFingerprint(plan.path)) !== plan.baseSha256)
+        throw new Error(`MCP configuration changed after preview; prepare the plan again: ${plan.path}`);
+    await mkdir(dirname(plan.path), { recursive: true });
+    const temporary = join(dirname(plan.path), `.${basename(plan.path)}.loadout-${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, `${JSON.stringify(plan.proposed, null, 2)}\n`, {
+            mode: 0o600,
+        });
+        await rename(temporary, plan.path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+export async function restoreMcpConfig(snapshot) {
+    await withMutationLock(async () => {
+        if (snapshot.existed) {
+            await mkdir(dirname(snapshot.path), { recursive: true });
+            await writeFile(snapshot.path, snapshot.content ?? "", { mode: 0o600 });
+        }
+        else
+            await rm(snapshot.path, { force: true });
+    });
+}

package/dist/src/core/model-config.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { formatSchemaError, providerModelConfigurationSchema, } from "../shared/schemas.js";
+import { writeFileAtomically } from "./atomic-file.js";
+import { ensureDirectory, loadoutHome } from "./paths.js";
+import { runMutationTransaction } from "./transaction.js";
+export const defaultModelConfigurationPath = () => join(loadoutHome(), "models.json");
+/**
+ * Validate a portable, provider-neutral model configuration. This is not a
+ * provider adapter: it never reads environment variables, queries a keychain,
+ * sends a request, or writes an agent configuration file.
+ */
+export function parseProviderModelConfiguration(value) {
+    try {
+        return providerModelConfigurationSchema.parse(value);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new Error(`Model configuration is invalid: ${formatSchemaError(error)}`);
+        }
+        throw error;
+    }
+}
+export async function readProviderModelConfiguration(path = defaultModelConfigurationPath()) {
+    try {
+        return parseProviderModelConfiguration(JSON.parse(await readFile(path, "utf8")));
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function planProviderModelSelection(selection, path = defaultModelConfigurationPath()) {
+    const current = await readProviderModelConfiguration(path);
+    const replacing = Boolean(current?.selections.some((item) => item.id === selection.id));
+    const configuration = parseProviderModelConfiguration({
+        schemaVersion: 1,
+        selections: [
+            ...(current?.selections.filter((item) => item.id !== selection.id) ?? []),
+            selection,
+        ],
+    });
+    return { path, selection, configuration, replacing };
+}
+export async function applyProviderModelSelection(plan) {
+    const applied = await runMutationTransaction(async () => {
+        const fresh = await planProviderModelSelection(plan.selection, plan.path);
+        if (JSON.stringify(fresh.configuration) !==
+            JSON.stringify(plan.configuration))
+            throw new Error("Model configuration changed after preview; prepare the plan again.");
+        return { targets: [plan.path], value: fresh.configuration };
+    }, async (configuration) => {
+        await ensureDirectory(dirname(plan.path));
+        await writeFileAtomically(plan.path, `${JSON.stringify(configuration, null, 2)}\n`);
+    });
+    return applied.snapshotId;
+}
+export function formatProviderModelConfiguration(configuration) {
+    if (!configuration)
+        return "No provider model selections are configured.";
+    return [
+        `Model selections: ${configuration.selections.length}`,
+        ...configuration.selections.map((selection) => `${selection.id} — ${selection.provider}/${selection.model} — credential:${selection.credential
+            ? selection.credential.kind === "environment"
+                ? `environment:${selection.credential.name}`
+                : `os-keychain:${selection.credential.service}`
+            : "missing"} — agents:${selection.targetAgents?.join(",") ?? "any"}`),
+    ].join("\n");
+}
+/**
+ * OpenRouter adapter. Credentials are resolved just-in-time by the caller and
+ * exist only in the outbound request; this module never persists or logs them.
+ */
+export async function requestOpenRouter(configuration, selectionId, messages, options) {
+    const selection = configuration.selections.find((item) => item.id === selectionId);
+    if (!selection)
+        throw new Error(`Unknown model selection '${selectionId}'`);
+    if (selection.provider !== "openrouter")
+        throw new Error(`Provider '${selection.provider}' has no adapter in this build`);
+    if (!selection.credential)
+        throw new Error("OpenRouter selection requires a credential reference");
+    const token = await options.resolveCredential(selection.credential);
+    if (!token)
+        throw new Error("OpenRouter credential reference did not resolve");
+    const response = await (options.fetcher ?? fetch)(`${selection.endpoint.replace(/\/$/, "")}/chat/completions`, {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+            authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ model: selection.model, messages }),
+    });
+    if (!response.ok)
+        throw new Error(`OpenRouter request failed (${response.status})`);
+    return response.json();
+}

package/dist/src/core/observations.js

@@ -0,0 +1,87 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fetchGitHubReleaseMetadata, } from "./github.js";
+import { writeFileAtomically } from "./atomic-file.js";
+import { loadoutHome } from "./paths.js";
+const MAX_OBSERVATIONS_PER_REPOSITORY = 90;
+function observationPath(repository) {
+    return join(loadoutHome(), "observations", `${repository.replace("/", "__")}.json`);
+}
+export async function readCatalogObservations(repository) {
+    try {
+        const value = JSON.parse(await readFile(observationPath(repository), "utf8"));
+        if (!Array.isArray(value))
+            return [];
+        return value.filter((item) => Boolean(item) &&
+            typeof item === "object" &&
+            typeof item.repository === "string" &&
+            typeof item.observedAt === "string" &&
+            typeof item.stars === "number" &&
+            typeof item.latestReleaseDownloads === "number");
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Persist one daily-like observation per repository. Existing observations on
+ * the same UTC date are replaced, so repeated refreshes do not fake velocity.
+ */
+export async function recordCatalogObservations(packages, options = {}) {
+    const failures = [];
+    let recorded = 0;
+    const observedAt = new Date().toISOString();
+    const day = observedAt.slice(0, 10);
+    for (const pkg of packages) {
+        if (typeof pkg.stars !== "number")
+            continue;
+        try {
+            const release = await fetchGitHubReleaseMetadata(pkg.repository, options);
+            const observation = {
+                repository: pkg.repository,
+                observedAt,
+                stars: pkg.stars,
+                latestReleaseTag: release.tag,
+                latestReleasePublishedAt: release.publishedAt,
+                latestReleaseDownloads: release.downloadCount,
+            };
+            const prior = await readCatalogObservations(pkg.repository);
+            const retained = prior.filter((item) => item.observedAt.slice(0, 10) !== day);
+            retained.push(observation);
+            retained.sort((left, right) => left.observedAt.localeCompare(right.observedAt));
+            await writeFileAtomically(observationPath(pkg.repository), `${JSON.stringify(retained.slice(-MAX_OBSERVATIONS_PER_REPOSITORY), null, 2)}\n`);
+            recorded++;
+        }
+        catch (error) {
+            failures.push({
+                repository: pkg.repository,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { recorded, failures };
+}
+const SPARKS = "▁▂▃▄▅▆▇█";
+/** A compact terminal chart. One observation cannot establish a trend. */
+export function formatStarHistory(observations) {
+    if (!observations.length)
+        return "No observations yet. Run `loadout catalog --refresh`.";
+    const values = observations.map((item) => item.stars);
+    const minimum = Math.min(...values);
+    const maximum = Math.max(...values);
+    const chart = values
+        .map((value) => {
+        if (maximum === minimum)
+            return SPARKS[0];
+        return SPARKS[Math.round(((value - minimum) / (maximum - minimum)) * (SPARKS.length - 1))];
+    })
+        .join("");
+    const latest = observations.at(-1);
+    const previous = observations.at(-2);
+    const delta = previous ? latest.stars - previous.stars : undefined;
+    return [
+        `${latest.repository}  ${chart}`,
+        `stars ${latest.stars}${delta === undefined ? " (first observation)" : ` (${delta >= 0 ? "+" : ""}${delta} since previous)`}`,
+        `latest release ${latest.latestReleaseTag ?? "none"} · downloads ${latest.latestReleaseDownloads}`,
+    ].join("\n");
+}

package/dist/src/core/outcomes.js

@@ -0,0 +1,164 @@
+import { readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { writeFileAtomically } from "./atomic-file.js";
+import { ensureDirectory, loadoutHome } from "./paths.js";
+import { withFileLock } from "./file-lock.js";
+const outcomePath = () => join(loadoutHome(), "outcomes.json");
+const outcomeLockPath = () => join(loadoutHome(), "outcomes.lock");
+const RESULTS = new Set([
+    "accept",
+    "reject",
+    "success",
+    "failure",
+    "activation",
+    "disable",
+    "rollback",
+]);
+const TASKS = new Set([
+    "general",
+    "frontend",
+    "testing",
+    "javascript",
+    "python",
+    "backend",
+    "security",
+    "documentation",
+]);
+const AGENTS = new Set([
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "opencode",
+    "hermes",
+    "windsurf",
+    "cline",
+    "github-copilot",
+    "roo-code",
+    "kiro-cli",
+    "junie",
+]);
+function validEvent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const event = value;
+    return (typeof event.id === "string" &&
+        typeof event.recordedAt === "string" &&
+        typeof event.selector === "string" &&
+        AGENTS.has(event.agent) &&
+        TASKS.has(event.taskFamily) &&
+        RESULTS.has(event.result));
+}
+export async function readLocalOutcomes() {
+    try {
+        const value = JSON.parse(await readFile(outcomePath(), "utf8"));
+        if (!value ||
+            typeof value !== "object" ||
+            Array.isArray(value) ||
+            value.schemaVersion !== 1 ||
+            !Array.isArray(value.events) ||
+            !value.events.every(validEvent))
+            throw new Error("outcome schema is invalid");
+        return value;
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return {
+                schemaVersion: 1,
+                events: [],
+                privacy: "local-only-no-project-or-content",
+            };
+        throw new Error(`Loadout outcomes are invalid at ${outcomePath()}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function validateSelector(selector) {
+    if (!/^[a-z0-9][a-z0-9._-]*\/[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(selector))
+        throw new Error("Outcome selector must be package/skill, not a path");
+}
+export async function recordLocalOutcome(event, now = new Date()) {
+    validateSelector(event.selector);
+    if (!TASKS.has(event.taskFamily))
+        throw new Error(`Unknown task family: ${event.taskFamily}`);
+    if (!RESULTS.has(event.result))
+        throw new Error(`Unknown outcome result: ${event.result}`);
+    return withFileLock(outcomeLockPath(), async () => {
+        const store = await readLocalOutcomes();
+        const recorded = {
+            ...event,
+            id: randomUUID(),
+            recordedAt: now.toISOString(),
+        };
+        store.events = [...store.events.slice(-999), recorded];
+        await ensureDirectory(dirname(outcomePath()));
+        await writeFileAtomically(outcomePath(), `${JSON.stringify(store, null, 2)}\n`);
+        return recorded;
+    });
+}
+export function projectTaskFamilies(project) {
+    const families = new Set(["general"]);
+    if (project.languages.includes("javascript/typescript"))
+        families.add("javascript");
+    if (project.languages.includes("python"))
+        families.add("python");
+    if (project.languages.some((item) => ["go", "rust", "java", ".net"].includes(item)))
+        families.add("backend");
+    if (project.frameworks.length)
+        families.add("frontend");
+    if (project.frameworks.includes("playwright"))
+        families.add("testing");
+    return [...families];
+}
+export function outcomeAdjustment(store, selector, agent, taskFamilies) {
+    const relevant = store.events.filter((event) => event.selector === selector &&
+        event.agent === agent &&
+        (event.taskFamily === "general" ||
+            taskFamilies.includes(event.taskFamily)));
+    const weights = {
+        accept: 18,
+        reject: -30,
+        success: 15,
+        failure: -25,
+        activation: 2,
+        disable: -8,
+        rollback: -35,
+    };
+    const raw = relevant.reduce((total, event) => total + weights[event.result], 0);
+    const score = Math.max(-60, Math.min(60, raw));
+    return {
+        score,
+        evidence: relevant.length
+            ? [
+                `${relevant.length} local outcome(s) in the same agent/task scope: ${score >= 0 ? "+" : ""}${score}`,
+            ]
+            : [],
+    };
+}
+/** Aggregate package/skill outcomes without retaining project paths or content. */
+export function packageOutcomeAdjustment(store, packageId, agent, taskFamilies) {
+    const events = store.events.filter((event) => event.selector.startsWith(`${packageId}/`) &&
+        event.agent === agent &&
+        (event.taskFamily === "general" ||
+            taskFamilies.includes(event.taskFamily)));
+    const weights = {
+        accept: 18,
+        reject: -30,
+        success: 15,
+        failure: -25,
+        activation: 2,
+        disable: -8,
+        rollback: -35,
+    };
+    const score = Math.max(-60, Math.min(60, events.reduce((total, event) => total + weights[event.result], 0)));
+    return {
+        score,
+        evidence: events.length
+            ? [
+                `${events.length} local-only package outcome(s) for ${agent} in the same task scope: ${score >= 0 ? "+" : ""}${score}`,
+            ]
+            : [],
+    };
+}