loadout-ai 0.1.0

package/dist/src/shared/schemas.js

@@ -0,0 +1,336 @@
+import { z } from "zod";
+/**
+ * Runtime schemas for data that crosses a trust boundary: catalog JSON,
+ * manifests and lockfiles shared between machines, persisted install state,
+ * and install plans passed between Loadout modules.  These schemas deliberately
+ * do not model secrets; MCP environment values are never persisted here.
+ */
+export const agentIdSchema = z.enum([
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "opencode",
+    "hermes",
+    "windsurf",
+    "cline",
+    "github-copilot",
+    "roo-code",
+    "kiro-cli",
+    "junie",
+]);
+export const packageTierSchema = z.enum([
+    "official",
+    "stable",
+    "trending",
+    "community",
+]);
+export const operatingSystemSchema = z.enum(["windows", "macos", "linux"]);
+export const componentTypeSchema = z.enum([
+    "skill",
+    "rule",
+    "command",
+    "agent",
+    "mcp",
+    "plugin",
+    "root",
+]);
+export const componentCompatibilitySchema = z.enum([
+    "native",
+    "adapted",
+    "unsupported",
+]);
+export const safetyRiskLevelSchema = z.enum(["safe", "review", "blocked"]);
+const text = z.string().trim().min(1, "must not be empty");
+const optionalText = text.optional();
+const sha256 = z.string().regex(/^[a-f0-9]{64}$/i, "must be a SHA-256 hash");
+const gitSha = z.string().regex(/^[a-f0-9]{40}$/i, "must be a full Git SHA");
+const repository = z
+    .string()
+    .regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/, "must be owner/repository");
+const safeRepositoryPath = z
+    .string()
+    .min(1)
+    .refine((value) => !value.startsWith("/") &&
+    !value.startsWith("\\") &&
+    !value.split(/[\\/]/).includes(".."), "must be a safe repository-relative path");
+const secretLikeValue = /^(?:(?:sk|rk|pk)[_-]|ghp_|github_pat_)[A-Za-z0-9_-]{12,}$/i;
+const safeModelText = z
+    .string()
+    .trim()
+    .min(1, "must not be empty")
+    .max(200, "must be at most 200 characters")
+    .refine((value) => !secretLikeValue.test(value), "must not contain a credential value");
+const providerIdSchema = safeModelText.regex(/^[a-z0-9]+(?:[a-z0-9-]*[a-z0-9])?$/, "must be a lowercase provider identifier");
+const environmentVariableNameSchema = z
+    .string()
+    .regex(/^[A-Z_][A-Z0-9_]*$/, "must be an environment variable name, not its value")
+    .max(128);
+const httpsEndpointSchema = z.url("must be a URL").refine((value) => {
+    const endpoint = new URL(value);
+    return (endpoint.protocol === "https:" &&
+        !endpoint.username &&
+        !endpoint.password &&
+        !endpoint.search &&
+        !endpoint.hash);
+}, "must be an HTTPS URL without credentials, query parameters, or fragments");
+export const credentialReferenceSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("environment"),
+        name: environmentVariableNameSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("os-keychain"),
+        service: safeModelText,
+        account: safeModelText.optional(),
+    })
+        .strict(),
+]);
+export const providerModelSelectionSchema = z
+    .object({
+    id: providerIdSchema,
+    provider: providerIdSchema,
+    model: safeModelText,
+    endpoint: httpsEndpointSchema,
+    credential: credentialReferenceSchema.optional(),
+    targetAgents: z.array(agentIdSchema).min(1).optional(),
+})
+    .strict();
+/**
+ * This deliberately has no apiKey/token/header fields. It is safe to put in a
+ * shared Loadout because it contains only metadata and credential references.
+ */
+export const providerModelConfigurationSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    selections: z.array(providerModelSelectionSchema).min(1),
+})
+    .strict()
+    .superRefine((value, context) => {
+    const seen = new Set();
+    for (const [index, selection] of value.selections.entries()) {
+        if (seen.has(selection.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["selections", index, "id"],
+                message: "must be unique",
+            });
+        }
+        seen.add(selection.id);
+    }
+});
+export const catalogSourceEvidenceSchema = z
+    .object({
+    type: z.literal("github"),
+    url: z.url("must be a URL"),
+    defaultBranch: z
+        .string()
+        .regex(/^[A-Za-z0-9._/-]+$/, "contains unsupported characters"),
+    commit: gitSha,
+    evidencePaths: z.array(safeRepositoryPath).min(1),
+    verifiedAt: z.iso.datetime("must be an ISO timestamp"),
+})
+    .passthrough();
+export const catalogPackageSchema = z
+    .object({
+    id: z
+        .string()
+        .regex(/^[a-z0-9]+(?:[a-z0-9-]*[a-z0-9])?$/, "must be lowercase kebab-case"),
+    displayName: text,
+    repository,
+    description: text,
+    category: text,
+    tier: packageTierSchema,
+    license: optionalText,
+    components: z.array(componentTypeSchema).min(1).optional(),
+    operatingSystems: z.array(operatingSystemSchema).min(1).optional(),
+    source: catalogSourceEvidenceSchema.optional(),
+    stars: z.number().finite().nonnegative().optional(),
+    lastUpdatedAt: z.iso.datetime("must be an ISO timestamp").optional(),
+    pushedAt: z.iso.datetime("must be an ISO timestamp").optional(),
+    topics: z.array(text).optional(),
+    openIssues: z.number().int().nonnegative().optional(),
+    archived: z.boolean().optional(),
+})
+    .passthrough();
+export const catalogSchema = z.array(catalogPackageSchema);
+export const plannedFileSchema = z
+    .object({
+    source: text,
+    target: text,
+    targetAgent: agentIdSchema.optional(),
+    componentType: componentTypeSchema.optional(),
+    compatibility: componentCompatibilitySchema.optional(),
+    skillName: optionalText,
+})
+    .passthrough();
+export const conflictDiagnosticSchema = z
+    .object({
+    severity: z.enum(["blocking", "warning"]),
+    code: z.enum(["target-collision", "duplicate-skill-name"]),
+    message: text,
+    packageIds: z.array(text).min(1),
+    targets: z.array(text).min(1),
+})
+    .passthrough();
+export const installPlanSchema = z
+    .object({
+    packageId: text,
+    files: z.array(plannedFileSchema),
+    targetAgents: z.array(agentIdSchema),
+    warnings: z.array(z.string()),
+    conflicts: z.array(conflictDiagnosticSchema).optional(),
+})
+    .passthrough();
+export const packageSourceSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("catalog"), id: text }),
+    z.object({
+        type: z.literal("github"),
+        repository,
+        ref: optionalText,
+        path: optionalText,
+    }),
+    z.object({
+        type: z.literal("git"),
+        url: text,
+        ref: optionalText,
+        path: optionalText,
+    }),
+    z.object({ type: z.literal("registry"), name: text, version: text }),
+    z.object({
+        type: z.literal("remote-registry"),
+        registry: text,
+        name: text,
+        version: text,
+    }),
+    z.object({ type: z.literal("local"), path: text }),
+]);
+const manifestPackageSchema = z
+    .object({
+    id: text,
+    source: packageSourceSchema,
+    agents: z.array(agentIdSchema).optional(),
+    dependsOn: z.array(text).optional(),
+    includeDevDependencies: z.boolean().optional(),
+    mcp: z
+        .object({ config: text, servers: z.array(text).optional() })
+        .optional(),
+    rootFiles: z.array(z.object({ source: text, target: text })).optional(),
+    enabled: z.boolean().optional(),
+})
+    .passthrough();
+export const loadoutManifestSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    name: text,
+    scope: z.enum(["project", "global"]),
+    agents: z.array(agentIdSchema),
+    profile: optionalText,
+    packages: z.array(manifestPackageSchema),
+    policy: z
+        .object({
+        allowRisk: z.array(safetyRiskLevelSchema).optional(),
+        blockedDomains: z.array(text).optional(),
+        blockedCommands: z.array(text).optional(),
+        allowPackages: z.array(text).optional(),
+        allowRepositories: z.array(text).optional(),
+        deniedPackages: z.array(text).optional(),
+        deniedRepositories: z.array(text).optional(),
+        requiredApprovals: z.number().int().min(0).optional(),
+    })
+        // Preserve unknown policy keys so portable-export secret scanning can
+        // reject them rather than silently dropping them during validation.
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const fileHashSchema = z.object({ path: text, sha256 });
+export const installRecordSchema = z
+    .object({
+    packageId: text,
+    repository: optionalText,
+    resolvedCommit: optionalText,
+    targetAgents: z.array(agentIdSchema),
+    files: z.array(fileHashSchema),
+    snapshotId: text,
+    installedAt: text,
+})
+    .passthrough();
+export const mcpInstallRecordSchema = z
+    .object({
+    packageId: text,
+    configPath: text,
+    serverName: text,
+    fingerprint: sha256,
+    snapshotId: text,
+    installedAt: text,
+})
+    .passthrough();
+export const managedActivationRecordSchema = z
+    .object({
+    packageId: text,
+    unitId: optionalText,
+    agent: agentIdSchema,
+    cacheState: z.enum(["missing", "downloaded"]),
+    reviewState: z.enum(["unreviewed", "reviewed", "quarantined"]),
+    installationState: z.enum(["installed", "removed"]),
+    activationState: z.enum(["active", "disabled"]),
+    libraryPath: text,
+    targets: z.array(z
+        .object({
+        activePath: text,
+        libraryRelativePath: text.refine((value) => value !== "." && value !== ".." && !/[\\/]/.test(value), "must be a single safe path segment"),
+    })
+        .passthrough()),
+    libraryFiles: z.array(fileHashSchema),
+    updatedAt: text,
+    snapshotId: optionalText,
+})
+    .passthrough();
+export const installStateSchema = z
+    .object({
+    version: z.literal(1),
+    installs: z.array(installRecordSchema),
+    mcpInstalls: z.array(mcpInstallRecordSchema).default([]),
+    activations: z.array(managedActivationRecordSchema).default([]),
+})
+    .passthrough();
+const lockedPackageSchema = z
+    .object({
+    id: text,
+    source: packageSourceSchema,
+    repository: optionalText,
+    resolvedCommit: optionalText,
+    targetAgents: z.array(agentIdSchema),
+    files: z.array(fileHashSchema),
+    installedAt: text,
+    dependencies: z.array(text).optional(),
+})
+    .passthrough();
+export const loadoutLockfileSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    manifestName: text,
+    // Older lockfiles predate this field.  Read them safely as an explicit
+    // legacy value; every new lockfile writer still emits an ISO timestamp.
+    generatedAt: text.optional().default("unknown"),
+    packages: z.array(lockedPackageSchema),
+    mcpServers: z
+        .array(z.object({
+        packageId: text,
+        configPath: text,
+        serverName: text,
+        fingerprint: sha256,
+    }))
+        .optional(),
+})
+    .passthrough();
+/** Compact, path-aware errors suitable for CLI and persisted-data diagnostics. */
+export function formatSchemaError(error) {
+    return error.issues
+        .map((issue) => `${issue.path.length ? issue.path.join(".") : "value"}: ${issue.message}`)
+        .join("; ");
+}

package/dist/src/shared/types.js

@@ -0,0 +1 @@
+export {};

package/docs/ACTIVE_SET.md

@@ -0,0 +1,53 @@
+# Reviewed library and active-set contract
+
+Loadout separates four facts that package managers often collapse into one word:
+
+- **cache**: `missing` or `downloaded` says whether Loadout has a private byte-for-byte
+  library copy;
+- **review**: `unreviewed`, `reviewed`, or `quarantined` records evidence policy and
+  never follows popularity alone;
+- **installation**: `installed` or `removed` records whether Loadout still manages the
+  package; and
+- **activation**: `active` or `disabled` is per skill unit and per agent, because one
+  skill from a collection can be visible to Claude Code while another stays disabled
+  for Codex.
+
+Maximum Library starts reviewed skill units as `downloaded + reviewed + installed +
+disabled`. It can therefore hold hundreds of candidates without exposing hundreds of
+instructions to an agent. Power is an intentionally broader active profile; Stable is
+the smallest active foundation.
+
+An initial install is active and may have `cache:missing`. On the first disable,
+Loadout verifies that every managed file is unchanged and that no untracked file would
+be removed, copies the complete skill directories into its private library, verifies
+their hashes, and only then removes the agent-visible copies. This is the explicit
+migration boundary for older installations.
+
+`enable` verifies the private library hashes and refuses to overwrite any occupied
+agent target. It restores the exact cached bytes but keeps the library copy. Both
+commands are dry-run by default, can change several packages and agents under one
+snapshot, write a durable transaction journal before mutation, and can be reversed by
+`loadout rollback --snapshot <id>`.
+
+Only Loadout-managed skill directories participate. Existing unmanaged content is
+never silently adopted, moved, or deleted. MCP entries and other executable/configured
+components are deliberately outside active-set toggling; they retain their existing
+explicit configuration and removal workflows.
+
+A disabled package must be enabled before its tracked source can be updated. This
+prevents the update workflow from silently recreating agent-visible files and makes the
+activation transition explicit.
+
+## Commands
+
+```bash
+loadout library
+loadout disable <package-or-package/skill> [more-selectors] [--agents codex,claude-code]
+loadout disable <package-or-package/skill> --yes
+loadout enable <package-or-package/skill> --yes
+loadout activate --project . --limit 40
+loadout optimize --project .
+loadout rollback --snapshot <id>
+```
+
+Machine-readable planning and results are available with `--json`.

package/docs/ACTIVE_SET_POLICY.md

@@ -0,0 +1,45 @@
+# Active-set selection policy
+
+Loadout treats the reviewed library as inventory and the active set as a constrained,
+per-agent decision. It never equates repository popularity with universal quality.
+The policy is deterministic, local by default, explainable in the preview, and ordered
+by these constraints:
+
+1. Block quarantined, removed, incompatible, missing-cache, and unreviewed candidates.
+2. Honor an explicit full `package/skill` pin before defaults. A short skill-name pin
+   may match a reviewed equivalent, but cannot bypass a safety blocker.
+3. Preserve verified hard conflicts and choose only one default from equivalent skill
+   names. Other reviewed sources remain disabled and are shown as alternatives.
+4. Score project language/framework signals and broad task families such as planning,
+   debugging, testing, review, security, documentation, architecture, and delivery.
+   A generic word match is supporting evidence, not enough to activate a specialized
+   domain tool by itself.
+5. Add cross-project foundations and stop at the user-specified per-agent capacity.
+   Capacity is a ceiling, never a quota; unused slots are safer than irrelevant skills.
+6. Use category-specific evaluation confidence when evidence exists; no benchmark is
+   treated as universal across tasks, agents, models, or versions.
+7. Apply explicit local human outcomes only within the same task/agent scope. Pins,
+   rollback, rejection, and later re-activation outweigh aggregate popularity. Until
+   the privacy-safe outcome store is complete, this term is neutral rather than
+   guessed.
+8. Use maintenance and bounded adoption evidence only as a final tie-breaker. Stars
+   cannot override safety, compatibility, conflicts, pins, evaluations, or local
+   outcomes.
+
+The current project selector implements steps 1–5 and exposes its scores, reasons,
+equivalent-source decisions, exact activation delta, hash verification, and rollback
+snapshot. Steps 6–7 are deliberately connected to P12-15 through P12-20 rather than
+filled with fake benchmark or feedback data.
+
+## Commands
+
+```bash
+loadout activate --project . --limit 40
+loadout activate --project . --pin openai-skills/playwright
+loadout optimize --project .
+loadout optimize --project . --yes
+```
+
+All commands are dry-run unless `--yes` is present. Project scanning reads only
+well-known root metadata files and does not require GitHub, upload source code, or
+execute a skill.

package/docs/CANDIDATE_INTELLIGENCE.md

@@ -0,0 +1,139 @@
+# Candidate intelligence and catalog trust
+
+Loadout deliberately separates discovery, inspection, catalog admission, and
+installation. A repository can be popular or fast-growing without being useful,
+compatible, licensed for the intended use, safe, or better than a catalog package.
+
+## Evidence pipeline
+
+```text
+daily GitHub observations
+  -> candidate list (triage only)
+  -> immutable source snapshot
+  -> static dossier
+  -> human-reviewed proposal
+  -> technically screened catalog JSON
+  -> Ed25519-signed release
+  -> explicit local diff and apply
+  -> normal preview/install/rollback workflow
+```
+
+No step silently skips the next authority boundary.
+
+## Triage today's feed
+
+```bash
+loadout candidate list --limit 20
+loadout candidate list --query "codex skills" --json
+```
+
+The displayed `triagePriority` is deterministic discovery ordering, not a quality or
+safety score. It is capped at 100 points: up to 30 for bounded-query coverage, 35 for
+the disclosed star-growth signal, 25 for log-scaled adoption, and 10 for appearing in
+the latest run. Before a complete observation day exists, growth is labelled
+`lifetime-star-average`; it is never mislabelled as measured velocity.
+
+## Inspect real source safely
+
+```bash
+loadout candidate inspect owner/repository --output ./candidate-dossier.json
+```
+
+Loadout performs a shallow public Git clone, resolves the result to a full immutable
+commit, and scans files statically. The dossier records:
+
+- discovery date, queries, adoption and growth evidence;
+- immutable repository, commit, branch, and evidence paths;
+- installability as portable components, explicit runtime setup, or unsupported
+  source shape;
+- observed skills, rules, commands, agents, plugin manifests, and MCP declarations;
+- secret/instruction/static-safety findings and explicit uncertainty;
+- possible catalog overlaps based on disclosed shared terms; and
+- reasons a human must block or review the candidate.
+
+Absolute cache paths are removed from the dossier. Copy the path printed by `--write`,
+or use `--output` as above for a shell- and platform-independent path. Loadout does not
+run install scripts, package lifecycle commands, hooks, MCP servers, candidate models,
+or arbitrary repository executables.
+
+An `explicit-runtime-setup` or `unsupported-source-shape` result is not a dead end and
+does not authorize execution. A maintainer may create a separately reviewed runtime
+recipe with an immutable executable artifact, bounded commands, isolated state,
+credential stripping, preview, verification, rollback, and removal. Graphify 0.9.17
+is the first such recipe and is invoked with `loadout tool graphify`; it is not part
+of broad `setup`.
+
+Candidate fetches use a two-minute timeout and an isolated Git environment: system
+and global config, templates, hooks, credential helpers, inherited `GIT_*` overrides,
+and LFS smudging cannot affect provenance or execute during checkout. Before blob
+materialization, a bounded GitHub tree-API response must be complete and prove every
+blob size, at most 100 MiB total, and at most 20,000 files. The checked-out snapshot
+is measured again before static analysis; rejected temporary clones are removed.
+
+## Create a human-gated proposal
+
+```bash
+loadout candidate propose ./candidate-dossier.json \
+  --id package-id --category workflow \
+  --platforms windows,macos,linux
+
+loadout candidate propose ./candidate-dossier.json \
+  --id package-id --category workflow \
+  --platforms windows,macos,linux \
+  --approve --output ./package-id.proposal.json
+```
+
+Platforms are mandatory human claims; Loadout does not infer them from stars or a
+successful clone. Before proposal preview or output, Loadout reopens the exact pinned
+commit and recomputes the complete inspection and static evaluation; edited evidence
+is rejected. A blocked dossier cannot become a proposal. `--approve` only writes an
+isolated proposal record—it never edits the bundled catalog and never installs the
+candidate. A maintainer must still review usefulness, overlap, license, runtime
+powers, platform behavior, category, and catalog policy.
+
+## Distribute a trusted catalog release
+
+Maintainers sign a technically screened full catalog array with an Ed25519 key kept outside the
+repository:
+
+```bash
+loadout keygen --private-key /secure/catalog-private.pem \
+  --public-key ./catalog-public.pem
+loadout catalog-sign --catalog ./catalog/packages.json \
+  --private-key /secure/catalog-private.pem \
+  --output ./catalog.signed.json
+```
+
+Users preview the verified release before trusting it:
+
+```bash
+loadout catalog-update --source ./catalog.signed.json \
+  --public-key ./catalog-public.pem
+loadout catalog-update --source ./catalog.signed.json \
+  --public-key ./catalog-public.pem --yes
+```
+
+`--source` also accepts HTTPS with a 15-second timeout and streaming 5 MiB limit; other remote
+schemes are rejected. The command verifies the signature, fingerprint, complete
+catalog schema, immutable evidence, and exact add/update/remove diff. Removals require
+the separate `--allow-removals` acknowledgement. Apply rejects replayed/older releases,
+snapshots previous state, writes atomically, journals the transaction, and re-verifies
+the stored signature whenever the effective catalog loads. The first successful apply
+pins the signing key and a non-rollback replay high-water mark; signer changes require
+an explicit trust-reset/key-rotation decision outside the normal update command.
+
+The public key is stored beside the signed envelope because it is verification data,
+not a secret. Trust in that key still has to come from a separately authenticated
+project release channel.
+
+## Local personalization
+
+```bash
+loadout recommend --project . --agent codex --json
+```
+
+When an agent is supplied, baseline project recommendations are adjusted only by the
+local outcome store for the same agent and task family. The evidence contains no
+project paths, prompts, code, or source content. It can reorder or lower confidence in
+catalog packages, but it cannot promote a discovery candidate or create a global
+popularity loop.