loadout-ai 0.1.0

package/dist/src/core/demo.js

@@ -0,0 +1,136 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { buildSkillPlan, applySkillInstall } from "./install.js";
+import { loadEffectiveCatalog } from "./catalog.js";
+import { agentSkillsDirectory } from "./paths.js";
+import { fetchRepositorySnapshot } from "./source.js";
+import { readInstallState } from "./state.js";
+import { restoreSnapshot } from "./snapshot.js";
+import { withMutationLock } from "./transaction.js";
+const DEFAULT_REPOSITORY = "obra/superpowers";
+const DEFAULT_PACKAGE_ID = "obra-superpowers";
+function isWithin(root, path) {
+    const resolvedRoot = resolve(root);
+    const resolvedPath = resolve(path);
+    return (resolvedPath === resolvedRoot ||
+        resolvedPath.startsWith(`${resolvedRoot}${sep}`));
+}
+/**
+ * Run a real install and rollback inside a disposable profile. This function
+ * deliberately creates virtual agent targets instead of detecting local
+ * binaries: the demo proves the installer while never treating a user's real
+ * Codex, Claude, or other agent profile as a demo target.
+ */
+export async function runIsolatedDemo(options = {}) {
+    if (options.source && options.repository)
+        throw new Error("Demo accepts either a local source or a repository, not both");
+    const profile = await mkdtemp(join(tmpdir(), "loadout-demo-"));
+    const demoLoadoutHome = join(profile, ".loadout");
+    const packageId = options.packageId ?? DEFAULT_PACKAGE_ID;
+    const agentIds = options.agents?.length
+        ? options.agents
+        : ["codex"];
+    const previousUserHome = process.env.LOADOUT_USER_HOME;
+    const previousLoadoutHome = process.env.LOADOUT_HOME;
+    let completed = false;
+    process.env.LOADOUT_USER_HOME = profile;
+    process.env.LOADOUT_HOME = demoLoadoutHome;
+    try {
+        const requestedRepository = options.repository ?? DEFAULT_REPOSITORY;
+        const catalog = options.source
+            ? []
+            : (options.catalog ?? (await loadEffectiveCatalog()));
+        const reviewedPackage = catalog.find((pkg) => pkg.repository.toLowerCase() === requestedRepository.toLowerCase() &&
+            Boolean(pkg.source?.commit));
+        if (!options.source && !options.repository && !reviewedPackage)
+            throw new Error(`The default demo repository ${DEFAULT_REPOSITORY} is missing its reviewed catalog commit`);
+        const fetched = options.source
+            ? undefined
+            : await (options.fetchSnapshot ?? fetchRepositorySnapshot)(requestedRepository, reviewedPackage?.source?.commit
+                ? { ref: reviewedPackage.source.commit }
+                : undefined);
+        if (reviewedPackage?.source?.commit &&
+            fetched.commit.toLowerCase() !==
+                reviewedPackage.source.commit.toLowerCase())
+            throw new Error(`Demo resolved ${fetched.commit}, expected reviewed commit ${reviewedPackage.source.commit}`);
+        const source = options.source ?? fetched.path;
+        const repository = fetched?.repository ?? `local source: ${resolve(source)}`;
+        const targets = agentIds.map((id) => ({
+            id,
+            displayName: `${id} (isolated demo target)`,
+            installed: true,
+            skillsDirectory: agentSkillsDirectory(id, profile),
+        }));
+        const plan = await buildSkillPlan(source, packageId, targets);
+        if (plan.files.some((file) => !isWithin(profile, file.target))) {
+            throw new Error("Demo safety check failed: a planned target escaped the isolated profile");
+        }
+        const snapshotId = await applySkillInstall(plan, fetched
+            ? { repository: fetched.repository, resolvedCommit: fetched.commit }
+            : undefined);
+        const state = await readInstallState();
+        const record = state.installs.find((item) => item.packageId === packageId && item.snapshotId === snapshotId);
+        if (!record)
+            throw new Error("Demo safety check failed: the isolated install was not recorded");
+        if (record.files.some((file) => !isWithin(profile, file.path))) {
+            throw new Error("Demo safety check failed: managed state escaped the isolated profile");
+        }
+        let rolledBack = false;
+        if (!options.keep) {
+            const snapshotPath = join(demoLoadoutHome, "snapshots", `${snapshotId}.json`);
+            const snapshot = JSON.parse(await readFile(snapshotPath, "utf8"));
+            await withMutationLock(() => restoreSnapshot(snapshot));
+            rolledBack = true;
+        }
+        completed = true;
+        return {
+            profile,
+            loadoutHome: demoLoadoutHome,
+            packageId,
+            repository,
+            resolvedCommit: fetched?.commit,
+            reviewed: Boolean(reviewedPackage),
+            targetAgents: agentIds,
+            plannedFiles: plan.files.length,
+            installedFiles: record.files.length,
+            snapshotId,
+            rolledBack,
+            cleanedUp: !options.keep,
+        };
+    }
+    finally {
+        if (previousUserHome === undefined)
+            delete process.env.LOADOUT_USER_HOME;
+        else
+            process.env.LOADOUT_USER_HOME = previousUserHome;
+        if (previousLoadoutHome === undefined)
+            delete process.env.LOADOUT_HOME;
+        else
+            process.env.LOADOUT_HOME = previousLoadoutHome;
+        // The default mode has completed its rollback before removal. On an error
+        // we also remove the partial profile; source repositories are never deleted.
+        if (!options.keep || !completed)
+            await rm(profile, { recursive: true, force: true });
+    }
+}
+export function formatDemoResult(result) {
+    const source = result.resolvedCommit
+        ? `${result.repository} @ ${result.resolvedCommit}`
+        : result.repository;
+    const ending = result.rolledBack
+        ? "Rollback verified and the temporary profile was removed."
+        : `Isolated profile retained at ${result.profile}. Delete it when finished.`;
+    return [
+        "Loadout safe demo complete.",
+        `${result.reviewed ? "Reviewed source" : "Source"}: ${source}`,
+        `Virtual targets: ${result.targetAgents.join(", ")}`,
+        `Installed ${result.plannedFiles} planned skill directory(ies); tracking ${result.installedFiles} file(s).`,
+        `Snapshot: ${result.snapshotId}`,
+        ending,
+    ].join("\n");
+}
+export const demoDefaults = {
+    repository: DEFAULT_REPOSITORY,
+    packageId: DEFAULT_PACKAGE_ID,
+};

package/dist/src/core/diff.js

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+const MCP_NAMES = new Set([
+    "mcp.json",
+    ".mcp.json",
+    "claude_desktop_config.json",
+]);
+function classify(path) {
+    const name = path.split("/").at(-1) ?? path;
+    if (name === "SKILL.md")
+        return "skill";
+    if (MCP_NAMES.has(name))
+        return "mcp";
+    if (/config\.(json|ya?ml)$/i.test(name))
+        return "config";
+    return undefined;
+}
+async function files(root) {
+    const result = new Map();
+    const base = resolve(root);
+    async function visit(directory, depth) {
+        if (depth > 8)
+            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 absolute = resolve(directory, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                await visit(absolute, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const path = relative(base, absolute).split("\\").join("/");
+            if (!classify(path))
+                continue;
+            try {
+                const info = await stat(absolute);
+                if (info.size > 2_000_000)
+                    continue;
+                const content = await readFile(absolute);
+                result.set(path, createHash("sha256").update(content).digest("hex"));
+            }
+            catch {
+                /* a concurrently removed file is simply omitted */
+            }
+        }
+    }
+    await visit(base, 0);
+    return result;
+}
+/** Compare two repository revisions using hashes only; never executes repository code. */
+export async function diffRepositorySnapshots(oldPath, newPath) {
+    const [oldFiles, newFiles] = await Promise.all([
+        files(oldPath),
+        files(newPath),
+    ]);
+    const paths = [...new Set([...oldFiles.keys(), ...newFiles.keys()])].sort();
+    return paths.flatMap((path) => {
+        const oldHash = oldFiles.get(path);
+        const newHash = newFiles.get(path);
+        const kind = classify(path);
+        if (!kind)
+            return [];
+        if (!oldHash)
+            return [{ path, kind, status: "added" }];
+        if (!newHash)
+            return [{ path, kind, status: "removed" }];
+        if (oldHash !== newHash)
+            return [{ path, kind, status: "changed" }];
+        return [];
+    });
+}

package/dist/src/core/discovery-connector.js

@@ -0,0 +1,165 @@
+import { readFile, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { writeFileAtomically } from "./atomic-file.js";
+import { ensureDirectory } from "./paths.js";
+export class ConnectorRequestError extends Error {
+    status;
+    retryAfterSeconds;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "ConnectorRequestError";
+        this.status = options.status;
+        this.retryAfterSeconds = options.retryAfterSeconds;
+    }
+}
+function nonnegativeInteger(value) {
+    if (!value || !/^\d+$/.test(value))
+        return undefined;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+export function rateLimitFromHeaders(headers) {
+    const limit = nonnegativeInteger(headers.get("x-ratelimit-limit"));
+    const remaining = nonnegativeInteger(headers.get("x-ratelimit-remaining"));
+    const resetAfterSeconds = nonnegativeInteger(headers.get("x-ratelimit-reset"));
+    return limit !== undefined ||
+        remaining !== undefined ||
+        resetAfterSeconds !== undefined
+        ? { limit, remaining, resetAfterSeconds }
+        : undefined;
+}
+function retryAfter(headers) {
+    const seconds = nonnegativeInteger(headers.get("retry-after"));
+    if (seconds !== undefined)
+        return seconds;
+    const date = headers.get("retry-after");
+    if (!date)
+        return undefined;
+    const parsed = Date.parse(date);
+    if (!Number.isFinite(parsed))
+        return undefined;
+    return Math.max(0, Math.ceil((parsed - Date.now()) / 1000));
+}
+/** Fetch one same-origin JSON page with a shared timeout and decoded body cap. */
+export async function fetchBoundedJson(source, options = {}) {
+    const original = new URL(source);
+    if (original.protocol !== "https:" || original.username || original.password)
+        throw new ConnectorRequestError("Discovery endpoints must use credential-free HTTPS");
+    const signal = AbortSignal.timeout(Math.max(250, Math.min(options.timeoutMs ?? 10_000, 120_000)));
+    const maximum = Math.max(1_024, Math.min(options.maximumBytes ?? 5 * 1024 * 1024, 20 * 1024 * 1024));
+    const maximumRedirects = Math.max(0, Math.min(options.maximumRedirects ?? 3, 5));
+    let current = original;
+    let response;
+    for (let redirects = 0; redirects <= maximumRedirects; redirects++) {
+        try {
+            response = await (options.fetcher ?? fetch)(current, {
+                method: "GET",
+                headers: options.headers,
+                redirect: "manual",
+                signal,
+            });
+        }
+        catch (error) {
+            throw new ConnectorRequestError(`Discovery request failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (response.status < 300 || response.status >= 400)
+            break;
+        const location = response.headers.get("location");
+        if (!location)
+            throw new ConnectorRequestError("Discovery redirect has no Location header", {
+                status: response.status,
+            });
+        if (redirects === maximumRedirects)
+            throw new ConnectorRequestError("Discovery request exceeded its redirect limit");
+        const next = new URL(location, current);
+        if (next.protocol !== "https:" ||
+            next.origin !== original.origin ||
+            next.username ||
+            next.password)
+            throw new ConnectorRequestError("Discovery request refused a cross-origin or non-HTTPS redirect");
+        current = next;
+    }
+    if (!response)
+        throw new ConnectorRequestError("Discovery request did not produce a response");
+    if (!response.ok)
+        throw new ConnectorRequestError(`Discovery request failed with HTTP ${response.status}`, {
+            status: response.status,
+            retryAfterSeconds: retryAfter(response.headers),
+        });
+    const declared = nonnegativeInteger(response.headers.get("content-length"));
+    if (declared !== undefined && declared > maximum)
+        throw new ConnectorRequestError(`Discovery response exceeds the ${maximum} byte limit`, { status: response.status });
+    if (!response.body)
+        throw new ConnectorRequestError("Discovery response has no body", {
+            status: response.status,
+        });
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    while (true) {
+        let chunk;
+        try {
+            chunk = await reader.read();
+        }
+        catch (error) {
+            throw new ConnectorRequestError(`Discovery response could not be read: ${error instanceof Error ? error.message : String(error)}`, { status: response.status });
+        }
+        if (chunk.done)
+            break;
+        length += chunk.value.byteLength;
+        if (length > maximum) {
+            await reader.cancel().catch(() => undefined);
+            throw new ConnectorRequestError(`Discovery response exceeds the ${maximum} byte limit`, { status: response.status });
+        }
+        chunks.push(chunk.value);
+    }
+    let value;
+    try {
+        value = JSON.parse(Buffer.concat(chunks.map((chunk) => Buffer.from(chunk))).toString("utf8"));
+    }
+    catch {
+        throw new ConnectorRequestError("Discovery response is not valid JSON", {
+            status: response.status,
+        });
+    }
+    return { value, headers: response.headers, url: current.toString() };
+}
+export async function readDiscoveryConnectorCache(path, source, validate, maximumRecords = 2_000) {
+    try {
+        const info = await stat(path);
+        if (!info.isFile() || info.size > 10 * 1024 * 1024)
+            return undefined;
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        const cache = value;
+        if (cache.schemaVersion !== 1 ||
+            cache.source !== source ||
+            typeof cache.cachedAt !== "string" ||
+            !Number.isFinite(Date.parse(cache.cachedAt)) ||
+            !Array.isArray(cache.records) ||
+            cache.records.length > maximumRecords ||
+            !cache.records.every(validate))
+            return undefined;
+        return cache;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeDiscoveryConnectorCache(path, source, records, now = new Date()) {
+    await ensureDirectory(dirname(path));
+    await writeFileAtomically(path, `${JSON.stringify({
+        schemaVersion: 1,
+        source,
+        cachedAt: now.toISOString(),
+        records,
+    }, null, 2)}\n`);
+}
+/** Remove records already represented by another source without re-ranking. */
+export function filterDiscoveryRecordsAgainstKeys(records, occupiedKeys) {
+    const occupied = new Set([...occupiedKeys].map((key) => key.trim().toLowerCase()).filter(Boolean));
+    return records.filter((record) => !occupied.has(record.identityKey.toLowerCase()) &&
+        (!record.repositoryKey ||
+            !occupied.has(record.repositoryKey.toLowerCase())));
+}

package/dist/src/core/doctor.js

@@ -0,0 +1,95 @@
+import { access, constants } from "node:fs/promises";
+import { dirname } from "node:path";
+import { detectAgents, directoryExists, loadoutHome, userHome, } from "./paths.js";
+import { inspectAgents } from "./agent-inspection.js";
+async function writable(path) {
+    // A not-yet-created directory is healthy when any existing ancestor is
+    // writable; this handles first-run paths such as ~/.agents/skills.
+    let candidate = path;
+    while (true) {
+        try {
+            await access(candidate, constants.W_OK);
+            return true;
+        }
+        catch {
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return false;
+            candidate = parent;
+        }
+    }
+}
+export async function runDoctor() {
+    const home = userHome();
+    const stateHome = loadoutHome();
+    const loadoutHomeExists = await directoryExists(stateHome);
+    const loadoutHomeWritable = await writable(stateHome);
+    const agents = await detectAgents();
+    const inventories = await inspectAgents(agents);
+    const diagnosedAgents = await Promise.all(agents.map(async (agent, index) => {
+        const exists = await directoryExists(agent.skillsDirectory);
+        const canWrite = await writable(agent.skillsDirectory);
+        const issues = [];
+        if (!agent.installed)
+            issues.push(`Install or configure ${agent.displayName} to enable it.`);
+        if (!exists)
+            issues.push("Skills directory does not exist yet; Loadout will create it during install.");
+        if (!canWrite)
+            issues.push("Skills directory is not writable; check permissions or choose another home.");
+        return {
+            agent,
+            inventory: inventories[index],
+            skillsRootExists: exists,
+            writable: canWrite,
+            issues,
+        };
+    }));
+    const issues = [];
+    if (!loadoutHomeExists)
+        issues.push("Loadout state directory does not exist yet; it will be created on first install.");
+    if (!loadoutHomeWritable)
+        issues.push("Loadout state directory is not writable; check LOADOUT_HOME permissions.");
+    if (!diagnosedAgents.some(({ agent }) => agent.installed)) {
+        issues.push("No supported agent executable was detected on PATH.");
+    }
+    return {
+        platform: process.platform,
+        userHome: home,
+        loadoutHome: stateHome,
+        loadoutHomeExists,
+        loadoutHomeWritable,
+        agents: diagnosedAgents,
+        issues,
+    };
+}
+export function formatDoctorReport(report) {
+    const lines = [
+        "Loadout doctor",
+        `Platform: ${report.platform}`,
+        `User home: ${report.userHome}`,
+        `State home: ${report.loadoutHome}`,
+    ];
+    lines.push(`State status: ${report.loadoutHomeExists ? "present" : "not created"} (${report.loadoutHomeWritable ? "writable" : "not writable"})`, "", "Agents:");
+    for (const entry of report.agents) {
+        const status = entry.agent.installed ? "detected" : "not found";
+        lines.push(`  ${entry.agent.installed ? "✓" : "○"} ${entry.agent.displayName}: ${status}`, `    skills: ${entry.agent.skillsDirectory} (${entry.skillsRootExists ? "present" : "will be created"}, ${entry.writable ? "writable" : "not writable"})`);
+        for (const component of entry.inventory.components) {
+            const detail = component.scanned
+                ? `${component.directoryExists ? `${component.entries.length} filesystem item(s)` : "not created"}${component.directory ? ` at ${component.directory}` : ""}`
+                : (component.note ?? "not inspected");
+            lines.push(`    ${component.type}: ${component.compatibility}; ${detail}`);
+        }
+        for (const warning of entry.inventory.warnings)
+            lines.push(`    ! ${warning}`);
+        for (const issue of entry.issues)
+            lines.push(`    ! ${issue}`);
+    }
+    if (report.issues.length) {
+        lines.push("", "Recommendations:");
+        for (const issue of report.issues)
+            lines.push(`  ! ${issue}`);
+    }
+    else
+        lines.push("", "No global blocking issues found.");
+    return lines.join("\n");
+}