loadout-ai 0.1.0

package/dist/src/core/compatibility-intelligence.js

@@ -0,0 +1,465 @@
+import { z } from "zod";
+import { agentIdSchema, componentTypeSchema } from "../shared/schemas.js";
+import { signPayload, verifyEnvelope } from "./signing.js";
+const MAX_COMPATIBILITY_BYTES = 1024 * 1024;
+const identifier = z
+    .string()
+    .trim()
+    .min(1)
+    .max(160)
+    .regex(/^[a-z0-9][a-z0-9._/-]*$/i, "must be a bounded identifier");
+const safeRelativePath = z
+    .string()
+    .trim()
+    .min(1)
+    .max(500)
+    .refine((value) => !value.startsWith("/") &&
+    !value.startsWith("\\") &&
+    !/^[A-Za-z]:[\\/]/.test(value) &&
+    !value.split(/[\\/]/).includes("..") &&
+    !Array.from(value).some((character) => {
+        const code = character.charCodeAt(0);
+        return code < 32 || code === 127;
+    }), "must be a safe agent-relative path");
+const semanticVersion = z
+    .string()
+    .regex(/^\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?$/, "must be a bounded semantic version");
+const boundedText = z.string().trim().min(1).max(500);
+const versionRangeSchema = z
+    .strictObject({
+    minInclusive: semanticVersion.optional(),
+    maxExclusive: semanticVersion.optional(),
+    includePrerelease: z.boolean().default(false),
+})
+    .refine((range) => range.minInclusive !== undefined || range.maxExclusive !== undefined, "version range must declare at least one boundary");
+const affectedSelectorSchema = z.strictObject({
+    packageIds: z.array(identifier).max(100).default([]),
+    componentTypes: z.array(componentTypeSchema).max(7).default([]),
+    pathPrefixes: z.array(safeRelativePath).max(50).default([]),
+    recipeIds: z.array(identifier).max(100).default([]),
+    providerIds: z.array(identifier).max(50).default([]),
+    modelIds: z.array(z.string().trim().min(1).max(200)).max(100).default([]),
+});
+const migrationSchema = z
+    .strictObject({
+    kind: z.enum(["move", "copy", "rewrite-config", "manual"]),
+    fromPath: safeRelativePath.optional(),
+    toPath: safeRelativePath.optional(),
+    instructions: z.array(boundedText).min(1).max(20),
+    automaticEligible: z.boolean().default(false),
+})
+    .superRefine((migration, context) => {
+    if (migration.kind !== "manual" &&
+        (!migration.fromPath || !migration.toPath))
+        context.addIssue({
+            code: "custom",
+            message: "non-manual migrations require fromPath and toPath",
+        });
+    if (migration.fromPath && migration.fromPath === migration.toPath)
+        context.addIssue({
+            code: "custom",
+            message: "migration source and destination must differ",
+        });
+});
+export const compatibilityNoticeSchema = z
+    .strictObject({
+    schemaVersion: z.literal(1),
+    id: identifier,
+    agent: agentIdSchema,
+    kind: z.enum([
+        "path-change",
+        "config-format",
+        "deprecation",
+        "model-provider",
+        "recipe-breakage",
+    ]),
+    severity: z.enum(["information", "warning", "breaking"]),
+    summary: boundedText,
+    issuedAt: z.iso.datetime({ offset: true }),
+    expiresAt: z.iso.datetime({ offset: true }),
+    versionRange: versionRangeSchema,
+    platforms: z
+        .array(z.enum(["windows", "macos", "linux"]))
+        .min(1)
+        .max(3),
+    affected: affectedSelectorSchema,
+    evidence: z.strictObject({
+        sourceUrl: z
+            .url()
+            .refine((value) => new URL(value).protocol === "https:", "must use HTTPS"),
+        observedAt: z.iso.datetime({ offset: true }),
+        confidence: z.enum(["verified", "likely", "uncertain"]),
+    }),
+    migration: migrationSchema.optional(),
+    uncertainty: boundedText,
+})
+    .superRefine((notice, context) => {
+    if (Date.parse(notice.expiresAt) <= Date.parse(notice.issuedAt))
+        context.addIssue({
+            code: "custom",
+            path: ["expiresAt"],
+            message: "must be later than issuedAt",
+        });
+    if (notice.kind === "path-change" && !notice.migration)
+        context.addIssue({
+            code: "custom",
+            path: ["migration"],
+            message: "path changes require a migration preview definition",
+        });
+});
+export const compatibilityNoticeSetSchema = z
+    .strictObject({
+    schemaVersion: z.literal(1),
+    generatedAt: z.iso.datetime({ offset: true }),
+    expiresAt: z.iso.datetime({ offset: true }),
+    notices: z.array(compatibilityNoticeSchema).max(500),
+})
+    .superRefine((feed, context) => {
+    if (Date.parse(feed.expiresAt) <= Date.parse(feed.generatedAt))
+        context.addIssue({
+            code: "custom",
+            path: ["expiresAt"],
+            message: "must be later than generatedAt",
+        });
+    const seen = new Set();
+    feed.notices.forEach((notice, index) => {
+        if (seen.has(notice.id))
+            context.addIssue({
+                code: "custom",
+                path: ["notices", index, "id"],
+                message: "notice ids must be unique",
+            });
+        seen.add(notice.id);
+        if (Date.parse(notice.issuedAt) > Date.parse(feed.generatedAt))
+            context.addIssue({
+                code: "custom",
+                path: ["notices", index, "issuedAt"],
+                message: "notice cannot be issued after feed generation",
+            });
+    });
+});
+export function parseCompatibilityNoticeSet(value) {
+    const bytes = Buffer.byteLength(JSON.stringify(value));
+    if (bytes > MAX_COMPATIBILITY_BYTES)
+        throw new Error("Compatibility notice set exceeds the 1 MiB limit");
+    return compatibilityNoticeSetSchema.parse(value);
+}
+const signedEnvelopeSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    algorithm: z.literal("Ed25519"),
+    createdAt: z.iso.datetime({ offset: true }),
+    publicKeyFingerprint: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    payload: z.unknown(),
+    signature: z.string().min(1).max(1024),
+});
+export function signCompatibilityNoticeSet(value, privateKeyPem, createdAt) {
+    const payload = parseCompatibilityNoticeSet(value);
+    return signPayload(payload, privateKeyPem, createdAt);
+}
+export function verifySignedCompatibilityNoticeSet(value, publicKeyPem) {
+    const bounded = Buffer.byteLength(JSON.stringify(value));
+    if (bounded > MAX_COMPATIBILITY_BYTES)
+        throw new Error("Signed compatibility notice set exceeds the 1 MiB limit");
+    const raw = signedEnvelopeSchema.parse(value);
+    const envelope = raw;
+    const verification = verifyEnvelope(envelope, publicKeyPem);
+    if (!verification.valid)
+        throw new Error("Compatibility notice signature is invalid");
+    return {
+        feed: parseCompatibilityNoticeSet(envelope.payload),
+        fingerprint: verification.fingerprint,
+        signedAt: envelope.createdAt,
+    };
+}
+function parsedVersion(value) {
+    const matched = value.match(/^(\d+)\.(\d+)(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?$/);
+    if (!matched)
+        return undefined;
+    return {
+        numeric: [Number(matched[1]), Number(matched[2]), Number(matched[3] ?? 0)],
+        ...(matched[4] ? { prerelease: matched[4] } : {}),
+    };
+}
+function compareVersions(left, right) {
+    const a = parsedVersion(left);
+    const b = parsedVersion(right);
+    if (!a || !b)
+        return undefined;
+    for (let index = 0; index < 3; index++) {
+        if (a.numeric[index] !== b.numeric[index])
+            return a.numeric[index] < b.numeric[index] ? -1 : 1;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (!a.prerelease)
+        return 1;
+    if (!b.prerelease)
+        return -1;
+    return a.prerelease.localeCompare(b.prerelease, undefined, { numeric: true });
+}
+function versionApplicability(evidence, notice) {
+    if (!evidence || evidence.status !== "detected" || !evidence.version)
+        return {
+            applicability: "potential",
+            reason: "The installed version is unavailable, so this notice cannot be excluded safely.",
+        };
+    const current = evidence.version;
+    const range = notice.versionRange;
+    const belowMinimum = range.minInclusive
+        ? compareVersions(current, range.minInclusive)
+        : 0;
+    const atOrAboveMaximum = range.maxExclusive
+        ? compareVersions(current, range.maxExclusive)
+        : -1;
+    if (belowMinimum === undefined || atOrAboveMaximum === undefined)
+        return {
+            applicability: "potential",
+            reason: "The detected version could not be compared to every signed range boundary.",
+        };
+    if (belowMinimum < 0 || atOrAboveMaximum >= 0)
+        return {
+            applicability: "not-applicable",
+            reason: `Detected version ${current} is outside the signed notice range.`,
+        };
+    if (evidence.releaseChannel === "prerelease" && !range.includePrerelease)
+        return {
+            applicability: "potential",
+            reason: `Detected version ${current} is a prerelease not explicitly covered by this notice.`,
+        };
+    return {
+        applicability: "applies",
+        reason: `Detected version ${current} is inside the signed notice range.`,
+    };
+}
+function platformName(platform) {
+    if (platform === "win32")
+        return "windows";
+    if (platform === "darwin")
+        return "macos";
+    if (platform === "linux")
+        return "linux";
+    return undefined;
+}
+function normalizedPath(value) {
+    return value.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+function pathMatches(path, relativePrefix) {
+    const normalized = normalizedPath(path).toLowerCase();
+    const prefix = normalizedPath(relativePrefix)
+        .replace(/^\.\//, "")
+        .toLowerCase();
+    return (normalized === prefix ||
+        normalized.endsWith(`/${prefix}`) ||
+        normalized.includes(`/${prefix}/`));
+}
+function selectedPaths(paths, notice) {
+    if (notice.affected.pathPrefixes.length === 0)
+        return [...new Set(paths)].sort();
+    return [
+        ...new Set(paths.filter((path) => notice.affected.pathPrefixes.some((prefix) => pathMatches(path, prefix)))),
+    ].sort();
+}
+function packageSelected(packageId, notice) {
+    const ids = new Set([
+        ...notice.affected.packageIds,
+        ...notice.affected.recipeIds,
+    ]);
+    return ids.size === 0 || ids.has(packageId);
+}
+export function affectedManagedContent(notice, state) {
+    const results = [];
+    const componentTypes = new Set(notice.affected.componentTypes);
+    for (const install of state.installs) {
+        if (!install.targetAgents.includes(notice.agent) ||
+            !packageSelected(install.packageId, notice) ||
+            (componentTypes.size > 0 && !componentTypes.has("skill")))
+            continue;
+        const paths = selectedPaths(install.files.map((file) => file.path), notice);
+        if (paths.length || notice.affected.pathPrefixes.length === 0)
+            results.push({
+                noticeId: notice.id,
+                packageId: install.packageId,
+                agent: notice.agent,
+                source: "install",
+                componentType: "skill",
+                paths,
+            });
+    }
+    for (const activation of state.activations ?? []) {
+        if (activation.agent !== notice.agent ||
+            !packageSelected(activation.packageId, notice) ||
+            (componentTypes.size > 0 && !componentTypes.has("skill")))
+            continue;
+        const paths = selectedPaths(activation.targets.map((target) => target.activePath), notice);
+        if (paths.length || notice.affected.pathPrefixes.length === 0)
+            results.push({
+                noticeId: notice.id,
+                packageId: activation.packageId,
+                agent: notice.agent,
+                source: "activation",
+                componentType: "skill",
+                paths,
+            });
+    }
+    for (const mcp of state.mcpInstalls ?? []) {
+        if (!packageSelected(mcp.packageId, notice) ||
+            (componentTypes.size > 0 && !componentTypes.has("mcp")))
+            continue;
+        const paths = selectedPaths([mcp.configPath], notice);
+        if (paths.length || notice.affected.pathPrefixes.length === 0)
+            results.push({
+                noticeId: notice.id,
+                packageId: mcp.packageId,
+                agent: notice.agent,
+                source: "mcp",
+                componentType: "mcp",
+                paths,
+            });
+    }
+    return results.sort((left, right) => left.packageId.localeCompare(right.packageId) ||
+        left.source.localeCompare(right.source));
+}
+function migratedPath(path, fromPath, toPath) {
+    const normalized = normalizedPath(path);
+    const from = normalizedPath(fromPath).replace(/^\.\//, "");
+    const lower = normalized.toLowerCase();
+    const target = from.toLowerCase();
+    const marker = `/${target}`;
+    const index = lower.lastIndexOf(marker);
+    if (index < 0 && lower !== target)
+        return undefined;
+    const start = index < 0 ? 0 : index + 1;
+    return `${normalized.slice(0, start)}${toPath}${normalized.slice(start + from.length)}`;
+}
+export function previewCompatibilityMigration(notice, affected) {
+    const migration = notice.migration;
+    if (!migration)
+        return [];
+    const steps = [];
+    for (const content of affected) {
+        if (migration.kind === "manual") {
+            steps.push({
+                noticeId: notice.id,
+                packageId: content.packageId,
+                agent: content.agent,
+                kind: migration.kind,
+                instructions: migration.instructions,
+                automaticEligible: false,
+                requiresApproval: true,
+            });
+            continue;
+        }
+        for (const sourcePath of content.paths) {
+            const targetPath = migratedPath(sourcePath, migration.fromPath, migration.toPath);
+            if (!targetPath)
+                continue;
+            steps.push({
+                noticeId: notice.id,
+                packageId: content.packageId,
+                agent: content.agent,
+                kind: migration.kind,
+                sourcePath,
+                targetPath,
+                instructions: migration.instructions,
+                automaticEligible: migration.automaticEligible,
+                requiresApproval: true,
+            });
+        }
+    }
+    return steps;
+}
+export function compatibilityFreshness(feed, sourceStatus, now = new Date()) {
+    if (sourceStatus === "invalid")
+        return {
+            status: "invalid",
+            sourceStatus,
+            message: "Compatibility input failed signature or schema verification; no notice is trusted.",
+        };
+    if (!feed || sourceStatus === "missing")
+        return {
+            status: "unavailable",
+            sourceStatus: "missing",
+            message: "No verified compatibility notice set is available; compatibility is unknown.",
+        };
+    const ageHours = Math.max(0, (now.getTime() - Date.parse(feed.generatedAt)) / (60 * 60 * 1000));
+    if (Date.parse(feed.generatedAt) > now.getTime() + 5 * 60 * 1000)
+        return {
+            status: "invalid",
+            sourceStatus,
+            generatedAt: feed.generatedAt,
+            expiresAt: feed.expiresAt,
+            message: "Compatibility notice generation time is too far in the future for the local clock.",
+        };
+    const stale = now.getTime() > Date.parse(feed.expiresAt);
+    return {
+        status: stale ? "stale" : "fresh",
+        sourceStatus,
+        generatedAt: feed.generatedAt,
+        expiresAt: feed.expiresAt,
+        ageHours: Number(ageHours.toFixed(2)),
+        message: stale
+            ? "The last verified compatibility notice set is expired; findings are historical and treated as uncertain."
+            : sourceStatus === "offline-cache"
+                ? "A fresh previously verified notice set is available offline; events after its generation time may be missing."
+                : "Compatibility notices are verified and within their declared freshness window.",
+    };
+}
+export function buildCompatibilityIntelligence(options) {
+    const now = options.now ?? new Date();
+    const freshness = compatibilityFreshness(options.feed, options.sourceStatus, now);
+    const platform = platformName(options.platform ?? process.platform);
+    const versionByAgent = new Map(options.versions.map((evidence) => [evidence.agent, evidence]));
+    const assessments = (options.feed?.notices ?? []).map((notice) => {
+        let result = versionApplicability(versionByAgent.get(notice.agent), notice);
+        if (!platform || !notice.platforms.includes(platform))
+            result = {
+                applicability: "not-applicable",
+                reason: platform
+                    ? `Notice does not target ${platform}.`
+                    : "This operating system has no declared compatibility mapping.",
+            };
+        if (result.applicability === "applies" &&
+            (freshness.status !== "fresh" ||
+                now.getTime() > Date.parse(notice.expiresAt)))
+            result = {
+                applicability: "potential",
+                reason: `${result.reason} ${now.getTime() > Date.parse(notice.expiresAt)
+                    ? "The individual notice has expired"
+                    : `The verified notice set is ${freshness.status}`}, so current applicability is uncertain.`,
+            };
+        const affected = result.applicability === "not-applicable"
+            ? []
+            : affectedManagedContent(notice, options.state);
+        return {
+            notice,
+            ...result,
+            affectedManagedContent: affected,
+            migrationPreview: previewCompatibilityMigration(notice, affected),
+        };
+    });
+    const affected = assessments.flatMap((assessment) => assessment.affectedManagedContent);
+    const migrationPreview = assessments.flatMap((assessment) => assessment.migrationPreview);
+    const uncertainty = [
+        freshness.message,
+        ...assessments
+            .filter((assessment) => assessment.applicability === "potential")
+            .map((assessment) => `${assessment.notice.id}: ${assessment.reason}`),
+        ...assessments.map((assessment) => `${assessment.notice.id}: ${assessment.notice.uncertainty}`),
+        ...(options.versions.some((version) => version.releaseChannel === "prerelease")
+            ? [
+                "At least one detected agent is a prerelease; absence of a notice is not compatibility evidence.",
+            ]
+            : []),
+    ];
+    return {
+        schemaVersion: 1,
+        generatedAt: now.toISOString(),
+        versions: options.versions,
+        freshness,
+        assessments,
+        affectedManagedContent: affected,
+        migrationPreview,
+        uncertainty: [...new Set(uncertainty)],
+        mutationPerformed: false,
+    };
+}

package/dist/src/core/completion.js

@@ -0,0 +1,160 @@
+const commands = [
+    "setup",
+    "upgrade",
+    "init",
+    "lock",
+    "export",
+    "import",
+    "audit",
+    "create",
+    "pack",
+    "publish",
+    "registry-serve",
+    "search",
+    "add",
+    "unadd",
+    "list",
+    "demo",
+    "test-drive",
+    "scan",
+    "status",
+    "versions",
+    "intelligence",
+    "compatibility",
+    "skill-audit",
+    "interop",
+    "benchmark",
+    "doctor",
+    "health",
+    "compare",
+    "optimize",
+    "activate",
+    "enable",
+    "disable",
+    "adopt",
+    "library",
+    "update",
+    "rollback",
+    "discover",
+    "candidate",
+    "review-queue",
+    "review",
+    "alerts",
+    "alert-ignore",
+    "alert-pin",
+    "alert-unpin",
+    "alert-pins",
+    "mcp",
+    "mcp-recipe",
+    "mcp-config",
+    "models",
+    "credentials",
+    "schedule",
+    "unschedule",
+    "autopilot",
+    "tool",
+    "report",
+    "share",
+    "card",
+    "compare-loadouts",
+    "badge",
+    "claims",
+    "head-to-head",
+    "keygen",
+    "catalog-sign",
+    "catalog-verify",
+    "catalog-update",
+    "inspect",
+    "evaluate",
+    "watch",
+    "sandbox-run",
+    "codex-mcp-config",
+    "plan",
+    "install",
+    "convert",
+    "canary",
+    "capabilities",
+    "catalog",
+    "profiles",
+    "recommend",
+    "improve",
+    "improve-feedback",
+    "sync",
+    "outcome",
+    "outcomes",
+    "remove",
+    "dashboard",
+    "serve",
+    "completion",
+];
+const modelCommands = ["status", "set", "verify"];
+const credentialCommands = ["status", "set", "check", "delete"];
+const candidateCommands = ["list", "inspect", "propose"];
+const benchmarkCommands = ["plan"];
+export function renderShellCompletion(shell) {
+    const words = commands.join(" ");
+    switch (shell) {
+        case "bash":
+            return `# Loadout command completion
+_loadout() {
+  local current="\${COMP_WORDS[COMP_CWORD]}"
+  local commands="${words}"
+  if [[ COMP_CWORD -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "$commands" -- "$current") )
+  elif [[ COMP_CWORD -eq 2 && "\${COMP_WORDS[1]}" == "models" ]]; then
+    COMPREPLY=( $(compgen -W "${modelCommands.join(" ")}" -- "$current") )
+  elif [[ COMP_CWORD -eq 2 && "\${COMP_WORDS[1]}" == "credentials" ]]; then
+    COMPREPLY=( $(compgen -W "${credentialCommands.join(" ")}" -- "$current") )
+  elif [[ COMP_CWORD -eq 2 && "\${COMP_WORDS[1]}" == "candidate" ]]; then
+    COMPREPLY=( $(compgen -W "${candidateCommands.join(" ")}" -- "$current") )
+  elif [[ COMP_CWORD -eq 2 && "\${COMP_WORDS[1]}" == "benchmark" ]]; then
+    COMPREPLY=( $(compgen -W "${benchmarkCommands.join(" ")}" -- "$current") )
+  fi
+}
+complete -F _loadout loadout
+`;
+        case "zsh":
+            return `#compdef loadout
+typeset -a commands model_commands credential_commands candidate_commands benchmark_commands
+commands=(${commands.map((command) => `'${command}'`).join(" ")})
+model_commands=(${modelCommands.map((command) => `'${command}'`).join(" ")})
+credential_commands=(${credentialCommands.map((command) => `'${command}'`).join(" ")})
+candidate_commands=(${candidateCommands.map((command) => `'${command}'`).join(" ")})
+benchmark_commands=(${benchmarkCommands.map((command) => `'${command}'`).join(" ")})
+if (( CURRENT == 2 )); then
+  _describe 'command' commands
+elif (( CURRENT == 3 )) && [[ $words[2] == models ]]; then
+  _describe 'models command' model_commands
+elif (( CURRENT == 3 )) && [[ $words[2] == credentials ]]; then
+  _describe 'credentials command' credential_commands
+elif (( CURRENT == 3 )) && [[ $words[2] == candidate ]]; then
+  _describe 'candidate command' candidate_commands
+elif (( CURRENT == 3 )) && [[ $words[2] == benchmark ]]; then
+  _describe 'benchmark command' benchmark_commands
+fi
+`;
+        case "fish":
+            return [
+                ...commands.map((command) => `complete -c loadout -f -n '__fish_use_subcommand' -a ${command}`),
+                ...modelCommands.map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from models' -a ${command}`),
+                ...credentialCommands.map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from credentials' -a ${command}`),
+                ...candidateCommands.map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from candidate' -a ${command}`),
+                ...benchmarkCommands.map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from benchmark' -a ${command}`),
+            ]
+                .join("\n")
+                .concat("\n");
+        case "powershell":
+            return `Register-ArgumentCompleter -Native -CommandName loadout -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $elements = @($commandAst.CommandElements | ForEach-Object { $_.Extent.Text })
+  $candidates = if ($elements.Count -ge 2 -and $elements[1] -eq 'models') { @(${modelCommands.map((command) => `'${command}'`).join(", ")}) } elseif ($elements.Count -ge 2 -and $elements[1] -eq 'credentials') { @(${credentialCommands.map((command) => `'${command}'`).join(", ")}) } elseif ($elements.Count -ge 2 -and $elements[1] -eq 'candidate') { @(${candidateCommands.map((command) => `'${command}'`).join(", ")}) } elseif ($elements.Count -ge 2 -and $elements[1] -eq 'benchmark') { @(${benchmarkCommands.map((command) => `'${command}'`).join(", ")}) } else { @(${commands.map((command) => `'${command}'`).join(", ")}) }
+  $candidates | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+}
+`;
+    }
+}
+export function parseCompletionShell(value) {
+    if (["bash", "zsh", "fish", "powershell"].includes(value))
+        return value;
+    throw new Error("Supported shells: bash, zsh, fish, powershell");
+}