loadout-ai 0.1.0

package/dist/src/core/recommend.js

@@ -0,0 +1,181 @@
+import { readFile, readdir } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { STABLE_BOOST_PACKAGE_IDS } from "./profiles.js";
+import { packageOutcomeAdjustment, projectTaskFamilies, } from "./outcomes.js";
+const SIGNAL_FILES = new Set([
+    "package.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "go.mod",
+    "Cargo.toml",
+    "Gemfile",
+    "pom.xml",
+    "build.gradle",
+    "next.config.js",
+    "next.config.mjs",
+    "vite.config.ts",
+    "playwright.config.ts",
+    ".git",
+]);
+export async function scanProject(root = process.cwd()) {
+    const absolute = resolve(root);
+    const entries = await readdir(absolute, { withFileTypes: true });
+    const files = entries
+        .map((entry) => entry.name)
+        .filter((name) => SIGNAL_FILES.has(name) || name.endsWith(".sln"))
+        .sort();
+    const languages = new Set();
+    const frameworks = new Set();
+    if (files.includes("package.json")) {
+        languages.add("javascript/typescript");
+        try {
+            const pkg = JSON.parse(await readFile(resolve(absolute, "package.json"), "utf8"));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (deps.next)
+                frameworks.add("next.js");
+            if (deps.react)
+                frameworks.add("react");
+            if (deps.vue)
+                frameworks.add("vue");
+            if (deps.svelte)
+                frameworks.add("svelte");
+            if (deps.playwright || deps["@playwright/test"])
+                frameworks.add("playwright");
+        }
+        catch {
+            /* malformed project metadata is reported through an empty framework set */
+        }
+    }
+    if (files.includes("pyproject.toml") || files.includes("requirements.txt"))
+        languages.add("python");
+    if (files.includes("go.mod"))
+        languages.add("go");
+    if (files.includes("Cargo.toml"))
+        languages.add("rust");
+    if (files.includes("Gemfile"))
+        languages.add("ruby");
+    if (files.includes("pom.xml") || files.includes("build.gradle"))
+        languages.add("java");
+    if (files.some((file) => file.endsWith(".sln")))
+        languages.add(".net");
+    if (files.some((file) => file.startsWith("next.config")))
+        frameworks.add("next.js");
+    if (files.includes("playwright.config.ts"))
+        frameworks.add("playwright");
+    return {
+        root: absolute,
+        languages: [...languages],
+        frameworks: [...frameworks],
+        files,
+    };
+}
+export function recommendPackages(signals, catalog) {
+    const ids = new Set(catalog.map((pkg) => pkg.id));
+    const result = [];
+    const add = (packageId, reason, confidence) => {
+        if (ids.has(packageId) &&
+            !result.some((item) => item.packageId === packageId))
+            result.push({ packageId, reason, confidence });
+    };
+    add("superpowers", "Useful engineering planning, testing, and review workflows for most repositories.", "high");
+    add("context7", "Current library documentation helps agents avoid outdated APIs.", signals.languages.length ? "high" : "medium");
+    if (signals.frameworks.some((item) => ["react", "next.js", "vue", "svelte"].includes(item)))
+        add("ui-ux-pro-max", `Frontend framework detected: ${signals.frameworks.join(", ")}.`, "high");
+    if (signals.frameworks.includes("playwright") ||
+        signals.languages.includes("javascript/typescript"))
+        add("playwright-mcp", "Browser verification is useful for this web-capable project.", signals.frameworks.includes("playwright") ? "high" : "medium");
+    if (signals.files.includes(".git"))
+        add("github-mcp-server", "A Git repository was detected; GitHub tools may help with issues and pull requests.", "medium");
+    return result;
+}
+function confidenceRank(confidence) {
+    return { low: 0, medium: 1, high: 2 }[confidence];
+}
+function confidenceAt(rank) {
+    return ["low", "medium", "high"][Math.max(0, Math.min(2, rank))];
+}
+/**
+ * Personalize the explainable baseline with local outcomes only. A negative
+ * outcome can lower or reorder a recommendation, but it cannot introduce an
+ * unreviewed discovery candidate into the catalog.
+ */
+export function personalizeRecommendations(recommendations, signals, outcomes, agent) {
+    const taskFamilies = projectTaskFamilies(signals);
+    return recommendations
+        .map((recommendation, originalIndex) => {
+        const adjustment = packageOutcomeAdjustment(outcomes, recommendation.packageId, agent, taskFamilies);
+        const confidenceShift = adjustment.score >= 20 ? 1 : adjustment.score <= -20 ? -1 : 0;
+        return {
+            ...recommendation,
+            confidence: confidenceAt(confidenceRank(recommendation.confidence) + confidenceShift),
+            ...(adjustment.evidence.length
+                ? {
+                    localOutcomeAdjustment: adjustment.score,
+                    evidence: adjustment.evidence,
+                    reason: `${recommendation.reason} Local outcomes adjusted confidence for ${agent}; they are not global quality evidence.`,
+                }
+                : {}),
+            _order: originalIndex,
+            _adjustment: adjustment.score,
+        };
+    })
+        .sort((left, right) => right._adjustment - left._adjustment || left._order - right._order)
+        .map((item) => ({
+        packageId: item.packageId,
+        reason: item.reason,
+        confidence: item.confidence,
+        ...(item.localOutcomeAdjustment !== undefined
+            ? { localOutcomeAdjustment: item.localOutcomeAdjustment }
+            : {}),
+        ...(item.evidence ? { evidence: item.evidence } : {}),
+    }));
+}
+export const TESTED_PROFILES = {
+    stable: {
+        description: "Recommended 30-skill daily driver from four pinned, SPDX-identified sources with no extra static-risk approvals.",
+        packages: [...STABLE_BOOST_PACKAGE_IDS],
+    },
+    web: {
+        description: "Planning, documentation, interface guidance, and browser verification for web projects.",
+        packages: ["superpowers", "context7", "ui-ux-pro-max", "playwright-mcp"],
+    },
+    collaboration: {
+        description: "Engineering workflow plus GitHub collaboration tools.",
+        packages: ["superpowers", "context7", "github-mcp-server"],
+    },
+    maximum: {
+        description: "Broad reviewed toolkit; always review MCP permissions before applying.",
+        packages: [
+            "superpowers",
+            "context7",
+            "playwright-mcp",
+            "ui-ux-pro-max",
+            "github-mcp-server",
+        ],
+    },
+};
+export function profileManifestPackages(profile, catalog) {
+    const selected = TESTED_PROFILES[profile];
+    if (!selected)
+        throw new Error(`Unknown profile '${profile}'. Choose: ${Object.keys(TESTED_PROFILES).join(", ")}`);
+    const byId = new Map(catalog.map((pkg) => [pkg.id, pkg]));
+    return selected.packages.map((id) => {
+        const pkg = byId.get(id);
+        if (!pkg)
+            throw new Error(`Profile '${profile}' references missing catalog package '${id}'`);
+        return { id, repository: pkg.repository };
+    });
+}
+export function formatRecommendations(signals, recommendations) {
+    const lines = [
+        `Project: ${basename(signals.root)}`,
+        `Detected: ${[...signals.languages, ...signals.frameworks].join(", ") || "no known project signals"}`,
+        "",
+        "Recommendations:",
+    ];
+    if (!recommendations.length)
+        lines.push("  No matching catalog packages found.");
+    for (const item of recommendations)
+        lines.push(`  ${item.packageId} [${item.confidence}] — ${item.reason}`);
+    return lines.join("\n");
+}

package/dist/src/core/registry-api.js

@@ -0,0 +1,97 @@
+import { createServer, } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRegistryBundle, importRegistryBundle, publishLocalPackage, resolveRegistryPackage, } from "./registry.js";
+function send(response, status, value) {
+    const body = JSON.stringify(value);
+    response.writeHead(status, {
+        "content-type": "application/json; charset=utf-8",
+        "content-length": Buffer.byteLength(body),
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+    });
+    response.end(body);
+}
+function tokenMatches(request, token) {
+    const header = request.headers.authorization;
+    if (!header?.startsWith("Bearer "))
+        return false;
+    const provided = Buffer.from(header.slice(7));
+    const expected = Buffer.from(token);
+    return (provided.length === expected.length && timingSafeEqual(provided, expected));
+}
+async function requestJson(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += value.length;
+        if (size > 35_000_000)
+            throw new Error("Request exceeds registry limit");
+        chunks.push(value);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+export async function startRegistryServer(options = {}) {
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? 0;
+    const token = options.token ?? randomBytes(32).toString("hex");
+    if (host !== "127.0.0.1" && host !== "::1" && !options.token)
+        throw new Error("A publish token is required when binding beyond loopback");
+    const server = createServer(async (request, response) => {
+        try {
+            const url = new URL(request.url ?? "/", "http://registry.local");
+            const match = url.pathname.match(/^\/v1\/packages\/([a-z0-9][a-z0-9._-]*)\/([^/]+)$/);
+            if (request.method === "GET" && match) {
+                const resolved = await resolveRegistryPackage(match[1], decodeURIComponent(match[2]));
+                send(response, 200, await createRegistryBundle(resolved.path));
+                return;
+            }
+            if (request.method === "POST" && url.pathname === "/v1/packages") {
+                if (!tokenMatches(request, token)) {
+                    request.resume();
+                    await new Promise((resolve) => request.once("end", resolve));
+                    send(response, 401, { error: "Invalid registry token" });
+                    return;
+                }
+                const temporary = await mkdtemp(join(tmpdir(), "loadout-registry-upload-"));
+                try {
+                    const packed = await importRegistryBundle(await requestJson(request), join(temporary, "package"));
+                    const published = await publishLocalPackage(packed.root, {
+                        approveRisk: request.headers["x-loadout-approve-risk"] === "true",
+                    });
+                    send(response, 201, {
+                        name: published.descriptor.name,
+                        version: published.descriptor.version,
+                        digest: published.digest,
+                    });
+                }
+                finally {
+                    await rm(temporary, { recursive: true, force: true });
+                }
+                return;
+            }
+            send(response, 404, { error: "Not found" });
+        }
+        catch (error) {
+            send(response, 400, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Could not determine registry address");
+    return {
+        server,
+        host,
+        port: address.port,
+        close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve()))),
+    };
+}

package/dist/src/core/registry.js

@@ -0,0 +1,316 @@
+import { createHash } from "node:crypto";
+import { cp, lstat, mkdir, readFile, readdir, rm, writeFile, } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { loadoutHome } from "./paths.js";
+import { analyzeUpdateSafety } from "./safety.js";
+const NAME = /^[a-z0-9][a-z0-9._-]*$/;
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
+export function parsePackageDescriptor(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("Package descriptor must be an object");
+    const item = value;
+    if (item.schemaVersion !== 1)
+        throw new Error("Package schemaVersion must be 1");
+    if (typeof item.name !== "string" || !NAME.test(item.name))
+        throw new Error("Package name must use lowercase letters, numbers, dots, underscores, or dashes");
+    if (typeof item.version !== "string" || !VERSION.test(item.version))
+        throw new Error("Package version must be semantic version such as 1.0.0");
+    if (typeof item.description !== "string" || !item.description.trim())
+        throw new Error("Package description is required");
+    for (const field of ["dependencies", "devDependencies"]) {
+        const dependencies = item[field];
+        if (dependencies !== undefined &&
+            (!dependencies ||
+                typeof dependencies !== "object" ||
+                Array.isArray(dependencies) ||
+                Object.entries(dependencies).some(([name, version]) => !NAME.test(name) ||
+                    typeof version !== "string" ||
+                    !VERSION.test(version))))
+            throw new Error(`Package ${field} must map names to exact semantic versions`);
+    }
+    return {
+        schemaVersion: 1,
+        name: item.name,
+        version: item.version,
+        description: item.description.trim(),
+        ...(typeof item.license === "string" ? { license: item.license } : {}),
+        ...(item.dependencies
+            ? { dependencies: item.dependencies }
+            : {}),
+        ...(item.devDependencies
+            ? { devDependencies: item.devDependencies }
+            : {}),
+    };
+}
+export async function createPackage(root, options) {
+    const directory = resolve(root);
+    const descriptor = parsePackageDescriptor({
+        schemaVersion: 1,
+        name: options.name,
+        version: options.version ?? "0.1.0",
+        description: options.description ?? `${options.name} Loadout package`,
+    });
+    await mkdir(directory, { recursive: false });
+    await Promise.all([
+        mkdir(join(directory, "skills", descriptor.name), { recursive: true }),
+        ...["rules", "commands", "agents"].map((name) => mkdir(join(directory, name))),
+    ]);
+    await writeFile(join(directory, "loadout-package.json"), `${JSON.stringify(descriptor, null, 2)}\n`);
+    await writeFile(join(directory, "README.md"), `# ${descriptor.name}\n\n${descriptor.description}\n`);
+    await writeFile(join(directory, "skills", descriptor.name, "SKILL.md"), `---\nname: ${descriptor.name}\ndescription: ${JSON.stringify(descriptor.description)}\n---\n\n# ${descriptor.name}\n\nReplace this paragraph with the focused workflow this skill should follow.\n`);
+    return descriptor;
+}
+async function inventory(root) {
+    const base = resolve(root);
+    const files = [];
+    async function visit(directory) {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            if (entry.name === ".git" ||
+                entry.name === "node_modules" ||
+                entry.name === ".loadout-record.json")
+                continue;
+            const absolute = join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw new Error(`Refusing symlink in package: ${absolute}`);
+            if (entry.isDirectory())
+                await visit(absolute);
+            else if (entry.isFile()) {
+                const content = await readFile(absolute);
+                files.push({
+                    path: relative(base, absolute).split(sep).join("/"),
+                    sha256: createHash("sha256").update(content).digest("hex"),
+                    size: content.length,
+                });
+            }
+        }
+    }
+    await visit(base);
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+export async function packPackage(root) {
+    const directory = resolve(root);
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error("Package root must be a real directory");
+    const descriptor = parsePackageDescriptor(JSON.parse(await readFile(join(directory, "loadout-package.json"), "utf8")));
+    const files = await inventory(directory);
+    const digest = createHash("sha256")
+        .update(files
+        .map((file) => `${file.path}\0${file.sha256}\0${file.size}`)
+        .join("\n"))
+        .digest("hex");
+    return { descriptor, root: directory, digest, files };
+}
+const registryRoot = () => join(loadoutHome(), "registry");
+export async function publishLocalPackage(root, options = {}) {
+    const packed = await packPackage(root);
+    const safety = await analyzeUpdateSafety(undefined, packed.root);
+    if (safety.approvalRequired && !options.approveRisk)
+        throw new Error(`Publishing requires explicit risk approval: ${safety.findings
+            .filter((finding) => finding.severity === "blocking")
+            .map((finding) => finding.message)
+            .join(" ")}`);
+    const target = join(registryRoot(), packed.descriptor.name, packed.descriptor.version);
+    try {
+        const existing = JSON.parse(await readFile(join(target, ".loadout-record.json"), "utf8"));
+        if (existing.digest === packed.digest)
+            return packed;
+        throw new Error(`Registry version ${packed.descriptor.name}@${packed.descriptor.version} already exists with different content`);
+    }
+    catch (error) {
+        if (!(error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT"))
+            throw error;
+    }
+    const temporary = `${target}.staging-${process.pid}-${Date.now()}`;
+    await mkdir(temporary, { recursive: true });
+    try {
+        for (const file of packed.files) {
+            const source = resolve(packed.root, file.path);
+            const destination = resolve(temporary, file.path);
+            if (!destination.startsWith(`${resolve(temporary)}${sep}`))
+                throw new Error(`Package file escapes registry target: ${file.path}`);
+            await mkdir(resolve(destination, ".."), { recursive: true });
+            await cp(source, destination);
+        }
+        await writeFile(join(temporary, ".loadout-record.json"), `${JSON.stringify({ name: packed.descriptor.name, version: packed.descriptor.version, digest: packed.digest, publishedAt: new Date().toISOString(), safety }, null, 2)}\n`);
+        await mkdir(join(registryRoot(), packed.descriptor.name), {
+            recursive: true,
+        });
+        await cp(temporary, target, { recursive: true, errorOnExist: true });
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+    return packed;
+}
+export async function resolveRegistryPackage(name, version) {
+    if (!NAME.test(name) || !VERSION.test(version))
+        throw new Error("Invalid registry package name or version");
+    const path = join(registryRoot(), name, version);
+    try {
+        const record = JSON.parse(await readFile(join(path, ".loadout-record.json"), "utf8"));
+        if (!record.digest)
+            throw new Error("missing digest");
+        const packed = await packPackage(path);
+        if (packed.digest !== record.digest)
+            throw new Error("registry package content does not match its immutable digest");
+        return { path, digest: record.digest };
+    }
+    catch (error) {
+        throw new Error(`Could not resolve registry package ${name}@${version}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function searchLocalRegistry(query = "") {
+    const results = [];
+    let names = [];
+    try {
+        names = await readdir(registryRoot());
+    }
+    catch {
+        return results;
+    }
+    for (const name of names.sort()) {
+        let versions = [];
+        try {
+            versions = await readdir(join(registryRoot(), name));
+        }
+        catch {
+            continue;
+        }
+        for (const version of versions.sort()) {
+            try {
+                const descriptor = parsePackageDescriptor(JSON.parse(await readFile(join(registryRoot(), name, version, "loadout-package.json"), "utf8")));
+                if (!query ||
+                    `${descriptor.name} ${descriptor.description}`
+                        .toLowerCase()
+                        .includes(query.toLowerCase()))
+                    results.push({ name, version, description: descriptor.description });
+            }
+            catch {
+                /* ignore corrupt entries; resolve reports exact errors */
+            }
+        }
+    }
+    return results;
+}
+export async function createRegistryBundle(root) {
+    const packed = await packPackage(root);
+    const files = await Promise.all(packed.files.map(async (file) => ({
+        ...file,
+        content: (await readFile(resolve(packed.root, file.path))).toString("base64"),
+    })));
+    return {
+        schemaVersion: 1,
+        descriptor: packed.descriptor,
+        digest: packed.digest,
+        files,
+    };
+}
+export async function importRegistryBundle(bundle, destination) {
+    if (!bundle || bundle.schemaVersion !== 1 || !Array.isArray(bundle.files))
+        throw new Error("Registry bundle schema is invalid");
+    parsePackageDescriptor(bundle.descriptor);
+    if (bundle.files.length > 10_000 ||
+        bundle.files.reduce((total, file) => total + (file.size ?? 0), 0) >
+            25_000_000)
+        throw new Error("Registry bundle exceeds package limits");
+    const root = resolve(destination);
+    await mkdir(root, { recursive: false });
+    try {
+        for (const file of bundle.files) {
+            if (!file ||
+                typeof file.path !== "string" ||
+                typeof file.sha256 !== "string" ||
+                typeof file.size !== "number" ||
+                typeof file.content !== "string")
+                throw new Error("Registry bundle contains an invalid file record");
+            const target = resolve(root, file.path);
+            if (target === root || !target.startsWith(`${root}${sep}`))
+                throw new Error(`Registry bundle path escapes destination: ${file.path}`);
+            const content = Buffer.from(file.content, "base64");
+            if (content.length !== file.size ||
+                createHash("sha256").update(content).digest("hex") !== file.sha256)
+                throw new Error(`Registry bundle file verification failed: ${file.path}`);
+            await mkdir(resolve(target, ".."), { recursive: true });
+            await writeFile(target, content);
+        }
+        const packed = await packPackage(root);
+        if (packed.digest !== bundle.digest ||
+            packed.descriptor.name !== bundle.descriptor.name ||
+            packed.descriptor.version !== bundle.descriptor.version)
+            throw new Error("Registry bundle digest or identity verification failed");
+        return packed;
+    }
+    catch (error) {
+        await rm(root, { recursive: true, force: true });
+        throw error;
+    }
+}
+function registryUrl(input) {
+    const url = new URL(input);
+    const loopback = url.hostname === "127.0.0.1" ||
+        url.hostname === "localhost" ||
+        url.hostname === "::1";
+    if (url.protocol !== "https:" && !(loopback && url.protocol === "http:"))
+        throw new Error("Remote registries require HTTPS outside loopback development");
+    url.pathname = url.pathname.replace(/\/$/, "");
+    return url;
+}
+function registryEndpoint(base, path) {
+    const endpoint = new URL(base);
+    endpoint.pathname = `${base.pathname.replace(/\/$/, "")}${path}`;
+    endpoint.search = "";
+    endpoint.hash = "";
+    return endpoint;
+}
+export async function fetchRemoteRegistryPackage(registry, name, version) {
+    if (!NAME.test(name) || !VERSION.test(version))
+        throw new Error("Invalid remote registry package name or version");
+    const base = registryUrl(registry);
+    const response = await fetch(registryEndpoint(base, `/v1/packages/${encodeURIComponent(name)}/${encodeURIComponent(version)}`));
+    if (!response.ok)
+        throw new Error(`Remote registry returned ${response.status}`);
+    const bundle = (await response.json());
+    const key = createHash("sha256")
+        .update(base.origin + base.pathname)
+        .digest("hex");
+    const target = join(loadoutHome(), "cache", "registry", key, name, version, bundle.digest);
+    try {
+        const packed = await packPackage(target);
+        if (packed.digest === bundle.digest)
+            return { path: target, digest: bundle.digest };
+    }
+    catch {
+        /* import below */
+    }
+    await mkdir(resolve(target, ".."), { recursive: true });
+    await rm(target, { recursive: true, force: true });
+    await importRegistryBundle(bundle, target);
+    return { path: target, digest: bundle.digest };
+}
+export async function publishRemotePackage(root, registry, token, options = {}) {
+    if (!token)
+        throw new Error("Remote registry token is required");
+    const bundle = await createRegistryBundle(root);
+    const base = registryUrl(registry);
+    const response = await fetch(registryEndpoint(base, "/v1/packages"), {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${token}`,
+            "content-type": "application/json",
+            ...(options.approveRisk ? { "x-loadout-approve-risk": "true" } : {}),
+        },
+        body: JSON.stringify(bundle),
+    });
+    const result = (await response.json());
+    if (!response.ok)
+        throw new Error(result.error ?? `Remote registry returned ${response.status}`);
+    return {
+        name: result.name,
+        version: result.version,
+        digest: result.digest,
+    };
+}