@finchip.ai/foga 0.0.0-stage → 0.6.0-alpha.4

package/artifacts/bundle.sha256

@@ -0,0 +1 @@
+b09770ec43673cca94f9f6feb5ad6050a24aee510792078fd5c87bed389cdcd2  bundle.json

package/bin/foga.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Launcher for the published package: runs the compiled CLI.
+// During development use `npm run foga -- <args>` (tsx) instead.
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const dist = join(here, "..", "dist", "cli.js");
+if (!existsSync(dist)) {
+  console.error("foga: compiled CLI not found. Run `npm run build` first, or use `npm run foga -- <args>`.");
+  process.exit(1);
+}
+await import(dist);

package/build/known-interface-ids.json

@@ -0,0 +1,18 @@
+{
+  "skill-token-standard": {
+    "source": "README.md (compiler-verified ids published upstream; the repository has no vectors file)",
+    "ids": {
+      "ISkillToken": "0x734553a6",
+      "IOnchainSkillDocument": "0x7050dd2c"
+    }
+  },
+  "task-token-standard": {
+    "source": "README.md and examples/DEPLOYMENTS.md (published upstream; the repository has no vectors file)",
+    "ids": {
+      "ITaskToken": "0xcdaeb26d",
+      "ITaskTender": "0xc319d532",
+      "ITaskVerifier": "0x9977db15",
+      "IOnchainTaskDocument": "0xeb078d05"
+    }
+  }
+}

package/build/profiles.json

@@ -0,0 +1,120 @@
+{
+  "schema": "foga.build-profiles/1",
+  "note": "One entry per upstream repository. `native` runs `forge build` inside the vendored repository with its own foundry.toml (tests and scripts skipped). `staged` is used for repositories whose upstream toolchain is solc-js: the contract tree is copied into a throw-away Foundry project whose settings mirror the upstream compile script exactly (same solc version, optimizer, runs, EVM version, metadata). Compile conditions are never changed by FOGA; only the orchestration is.",
+  "foundry": {
+    "skip": ["test", "script"],
+    "solcDirEnv": "FOGA_SOLC_DIR",
+    "solcBinaryPattern": "solc-{version}"
+  },
+  "repos": [
+    {
+      "repo": "skill-token-standard",
+      "erc": 8338,
+      "mode": "native",
+      "solc": "0.8.24",
+      "contractsRoot": "contracts",
+      "vectors": [],
+      "extras": {}
+    },
+    {
+      "repo": "task-token-standard",
+      "erc": 8414,
+      "mode": "native",
+      "solc": "0.8.24",
+      "contractsRoot": "contracts",
+      "vectors": [],
+      "extras": {}
+    },
+    {
+      "repo": "kya-standard",
+      "erc": 8419,
+      "mode": "staged",
+      "solc": "0.8.28",
+      "contractsRoot": "assets/erc-kya/contracts",
+      "stage": {
+        "copy": [
+          { "from": "assets/erc-kya/contracts", "to": "." },
+          { "from": "companions/zk-kya-groth16/build/Groth16Verifier.sol", "to": "companions/Groth16Verifier.sol" }
+        ],
+        "settings": { "optimizer": true, "runs": 200, "viaIr": false, "evmVersion": "cancun", "bytecodeHash": "ipfs" },
+        "mirrors": "tools/compile.js"
+      },
+      "vectors": ["assets/erc-kya/vectors/vectors.json"],
+      "extras": {}
+    },
+    {
+      "repo": "aid-standard",
+      "erc": 8434,
+      "mode": "staged",
+      "solc": "0.8.28",
+      "contractsRoot": "assets/erc-aid/contracts",
+      "stage": {
+        "copy": [{ "from": "assets/erc-aid/contracts", "to": "." }],
+        "settings": { "optimizer": true, "runs": 200, "viaIr": false, "evmVersion": "cancun", "bytecodeHash": "ipfs" },
+        "mirrors": "scripts/compile.js"
+      },
+      "vectors": ["assets/erc-aid/vectors/aid-vectors.json"],
+      "extras": {}
+    },
+    {
+      "repo": "acd-framework",
+      "erc": 8436,
+      "mode": "native",
+      "solc": "0.8.24",
+      "contractsRoot": "assets/erc-acdf/contracts",
+      "vectors": ["assets/erc-acdf/vectors/interface-ids.json"],
+      "extras": {}
+    },
+    {
+      "repo": "ard-onchain-framework",
+      "erc": 8444,
+      "mode": "native",
+      "solc": "0.8.24",
+      "contractsRoot": "assets/erc-8444/contracts",
+      "vectors": ["assets/erc-8444/vectors/interface-ids.json"],
+      "extras": { "kindIds": "assets/erc-8444/vectors/kind-ids.json" }
+    },
+    {
+      "repo": "swarm-ai-framework",
+      "erc": 8447,
+      "mode": "native",
+      "solc": "0.8.24",
+      "contractsRoot": "assets/erc-8447/contracts",
+      "vectors": ["assets/erc-8447/vectors/interface-ids.json"],
+      "extras": { "termIds": "assets/erc-8447/vectors/term-ids.json" }
+    },
+    {
+      "repo": "aifi-unit-framework",
+      "erc": 8454,
+      "mode": "native",
+      "solc": "0.8.30",
+      "contractsRoot": "assets/erc-auf/contracts",
+      "vectors": ["assets/erc-auf/vectors/interface-ids.json"],
+      "extras": { "identifiers": "assets/erc-auf/vectors/identifiers.json" }
+    },
+    {
+      "repo": "agent-safety-framework",
+      "erc": 8468,
+      "mode": "native",
+      "solc": "0.8.30",
+      "contractsRoot": "assets/erc-asf/contracts",
+      "vectors": ["assets/erc-asf/vectors/interface-ids.json"],
+      "extras": {}
+    },
+    {
+      "repo": "ai-dispute-resolution",
+      "erc": 8471,
+      "mode": "native",
+      "solc": "0.8.30",
+      "contractsRoot": "assets/erc-adrf/contracts",
+      "vectors": ["assets/erc-adrf/vectors/interface-ids.json"],
+      "extras": {}
+    }
+  ],
+  "local": {
+    "note": "FOGA's own local-only contracts (contracts/), compiled with contracts/foundry.toml. They never stand in for a public-chain deployment.",
+    "solc": "0.8.30",
+    "project": "contracts",
+    "contractsRoot": "src"
+  }
+}

package/dist/build/bundle.js

@@ -0,0 +1,417 @@
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { canonicalJson, copyTree, ensureDir, exists, readJson, repoRoot, rmrf, walk, writeJson } from "../util/fs.js";
+import { sha256Hex } from "../util/hash.js";
+import { codeSize, runtimeIdentity } from "../util/bytecode.js";
+import { log } from "../util/log.js";
+import { loadLock, verifyVendor } from "./vendor.js";
+function sh(cmd, args, cwd, env = {}) {
+    return execFileSync(cmd, args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: 64 * 1024 * 1024,
+        env: { ...process.env, NO_COLOR: "1", FOUNDRY_PROFILE: "default", SEPOLIA_RPC_URL: process.env.SEPOLIA_RPC_URL ?? "http://127.0.0.1:1", ...env },
+    });
+}
+function forgeVersion() {
+    try {
+        const out = sh("forge", ["--version"], repoRoot());
+        const m = out.match(/Version:\s*([^\s]+)/) ?? out.match(/forge\s+([^\s]+)/);
+        return m ? m[1] : out.split("\n")[0].trim();
+    }
+    catch {
+        throw new Error("forge not found on PATH. Install Foundry (https://getfoundry.sh) or use the Docker image.");
+    }
+}
+function solcBinary(profiles, version, solcDir) {
+    const dir = solcDir ?? process.env[profiles.foundry.solcDirEnv];
+    if (!dir)
+        return undefined;
+    const bin = join(dir, profiles.foundry.solcBinaryPattern.replace("{version}", version));
+    return exists(bin) ? bin : undefined;
+}
+function forgeBuild(projectDir, outDir, skip, solcPath, extraArgs = []) {
+    rmrf(outDir);
+    ensureDir(outDir);
+    const args = ["build", "--ast", "--no-cache", "--out", outDir, ...extraArgs];
+    for (const s of skip)
+        args.push("--skip", s);
+    if (solcPath)
+        args.push("--use", solcPath);
+    try {
+        sh("forge", args, projectDir);
+    }
+    catch (e) {
+        const msg = (e.stderr?.toString?.() ?? "") + (e.stdout?.toString?.() ?? "");
+        throw new Error(`forge build failed in ${projectDir}:\n${msg.slice(-4000)}`);
+    }
+}
+function writeStagedProject(profile, repoDir, stageDir) {
+    if (!profile.stage)
+        throw new Error(`${profile.repo}: staged profile without stage spec`);
+    rmrf(stageDir);
+    ensureDir(stageDir);
+    for (const c of profile.stage.copy)
+        copyTree(join(repoDir, c.from), join(stageDir, c.to));
+    const s = profile.stage.settings;
+    const toml = [
+        "[profile.default]",
+        'src = "."',
+        'out = "out"',
+        "libs = []",
+        'test = "__no_tests__"',
+        'script = "__no_scripts__"',
+        "auto_detect_remappings = false",
+        "remappings = []",
+        `solc_version = "${profile.solc}"`,
+        `optimizer = ${s.optimizer}`,
+        `optimizer_runs = ${s.runs}`,
+        `via_ir = ${s.viaIr}`,
+        `evm_version = "${s.evmVersion}"`,
+        `bytecode_hash = "${s.bytecodeHash}"`,
+        "cbor_metadata = true",
+        "",
+    ].join("\n");
+    writeFileSync(join(stageDir, "foundry.toml"), toml);
+}
+function normalizeMetadata(raw) {
+    if (!raw)
+        return null;
+    if (typeof raw === "string") {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    return raw;
+}
+function classifyRole(kind, abstract, path, name) {
+    if (kind === "interface")
+        return "interface";
+    if (kind === "library")
+        return "library";
+    if (abstract)
+        return "abstract";
+    const p = "/" + path.replace(/\\/g, "/");
+    if (/\/mocks?\//i.test(p) || /^Mock/.test(name) || /Mock$/.test(name))
+        return "mock";
+    if (p.includes("/adapters/"))
+        return "adapter";
+    if (p.includes("/modules/"))
+        return "module";
+    if (p.includes("/bridges/"))
+        return "bridge";
+    if (p.includes("/verifiers/"))
+        return "verifier";
+    if (p.includes("/examples/"))
+        return "example";
+    if (p.includes("/companions/"))
+        return "companion";
+    if (p.includes("/judgment/"))
+        return "authority";
+    if (p.includes("/account/"))
+        return "account";
+    if (/Registry$/.test(name))
+        return "registry";
+    if (/Token$/.test(name) || /Vault$/.test(name))
+        return "kernel";
+    return "contract";
+}
+function xorSelectors(node) {
+    let acc = 0n;
+    let n = 0;
+    for (const child of node.nodes ?? []) {
+        if (child.nodeType === "FunctionDefinition" && typeof child.functionSelector === "string") {
+            acc ^= BigInt("0x" + child.functionSelector);
+            n++;
+        }
+    }
+    if (n === 0)
+        return null;
+    return "0x" + acc.toString(16).padStart(8, "0");
+}
+function extractArtifacts(opts) {
+    const contracts = [];
+    const solcVersions = new Set();
+    for (const file of walk(opts.outDir)) {
+        if (!file.endsWith(".json"))
+            continue;
+        if (file.includes(`${opts.outDir}/build-info/`))
+            continue;
+        const art = readJson(file);
+        const metadata = normalizeMetadata(art.metadata);
+        if (!metadata?.settings?.compilationTarget)
+            continue;
+        const targetEntries = Object.entries(metadata.settings.compilationTarget);
+        if (targetEntries.length !== 1)
+            continue;
+        const [sourcePath, name] = targetEntries[0];
+        if (name !== basename(file, ".json"))
+            continue;
+        const norm = sourcePath.replace(/\\/g, "/");
+        // Scope: only the contract tree each profile declares; never tests, scripts or vendored fixtures.
+        if (/^(test|script|lib)\//.test(norm) || /\/(test|script)\//.test(norm))
+            continue;
+        let upstreamPath = norm;
+        if (opts.mode === "native" || opts.mode === "local") {
+            if (!norm.startsWith(opts.contractsRoot.replace(/\/$/, "") + "/"))
+                continue;
+        }
+        else {
+            const copy = (opts.stageCopies ?? []).find((c) => c.to !== "." && norm.startsWith(c.to.replace(/\/$/, "")));
+            upstreamPath = copy ? join(copy.from, norm.slice(copy.to.length)).replace(/\\/g, "/") : `${opts.contractsRoot}/${norm}`;
+        }
+        let kind = "contract";
+        let abstract = false;
+        let baseContracts = [];
+        let interfaceId = null;
+        const ast = art.ast;
+        if (ast?.nodes) {
+            const node = ast.nodes.find((n) => n.nodeType === "ContractDefinition" && n.name === name);
+            if (node) {
+                kind = node.contractKind;
+                abstract = Boolean(node.abstract);
+                baseContracts = (node.baseContracts ?? []).map((b) => b.baseName?.name).filter(Boolean);
+                interfaceId = kind === "interface" ? xorSelectors(node) : null;
+            }
+        }
+        else {
+            const bc = art.bytecode?.object ?? "0x";
+            if (bc === "0x" && (art.abi?.length ?? 0) > 0)
+                kind = "interface";
+        }
+        const bytecode = art.bytecode?.object ?? "0x";
+        const deployedBytecode = art.deployedBytecode?.object ?? "0x";
+        const linkReferences = art.bytecode?.linkReferences ?? {};
+        const deployedLinkReferences = art.deployedBytecode?.linkReferences ?? {};
+        const immutableReferences = art.deployedBytecode?.immutableReferences ?? {};
+        const compiler = metadata.compiler?.version ?? "unknown";
+        solcVersions.add(compiler);
+        const s = metadata.settings ?? {};
+        const settings = {
+            optimizer: Boolean(s.optimizer?.enabled),
+            runs: typeof s.optimizer?.runs === "number" ? s.optimizer.runs : null,
+            viaIr: Boolean(s.viaIR),
+            evmVersion: s.evmVersion ?? null,
+            bytecodeHash: s.metadata?.bytecodeHash ?? null,
+            remappings: s.remappings ?? [],
+        };
+        const sourceKeccak = metadata.sources?.[sourcePath]?.keccak256 ?? null;
+        const role = opts.mode === "local" ? "local-stub" : classifyRole(kind, abstract, upstreamPath, name);
+        contracts.push({
+            key: `${opts.repo}:${name}`,
+            repo: opts.repo,
+            erc: opts.erc,
+            name,
+            upstreamPath,
+            kind,
+            abstract,
+            role,
+            deployable: bytecode !== "0x" && !abstract && kind !== "interface",
+            baseContracts,
+            interfaceId,
+            abi: art.abi ?? [],
+            methodIdentifiers: art.methodIdentifiers ?? {},
+            bytecode,
+            deployedBytecode,
+            linkReferences,
+            deployedLinkReferences,
+            immutableReferences,
+            runtimeIdentity: deployedBytecode === "0x" ? "0x" : runtimeIdentity(deployedBytecode, deployedLinkReferences, immutableReferences),
+            creationCodeSize: codeSize(bytecode),
+            runtimeCodeSize: codeSize(deployedBytecode),
+            compiler,
+            settings,
+            sourceKeccak,
+        });
+    }
+    contracts.sort((a, b) => a.key.localeCompare(b.key));
+    return { contracts, solcVersions };
+}
+/** Search a vectors JSON tree for `<InterfaceName>: 0x????????` pairs. */
+function scanInterfaceIds(tree, names, out) {
+    if (!tree || typeof tree !== "object")
+        return;
+    for (const [k, v] of Object.entries(tree)) {
+        if (typeof v === "string" && names.has(k) && /^0x[0-9a-fA-F]{8}$/.test(v))
+            out.set(k, v.toLowerCase());
+        else if (v && typeof v === "object")
+            scanInterfaceIds(v, names, out);
+    }
+}
+export function bundleHash(contracts, sources) {
+    const subset = {};
+    for (const [k, c] of Object.entries(contracts)) {
+        subset[k] = {
+            abi: c.abi,
+            bytecode: c.bytecode,
+            deployedBytecode: c.deployedBytecode,
+            linkReferences: c.linkReferences,
+            deployedLinkReferences: c.deployedLinkReferences,
+            immutableReferences: c.immutableReferences,
+            compiler: c.compiler,
+            settings: c.settings,
+            sourceKeccak: c.sourceKeccak,
+            upstreamPath: c.upstreamPath,
+        };
+    }
+    const src = sources.map((s) => ({ repo: s.repo, commit: s.commit, mode: s.mode, solc: s.solc }));
+    return sha256Hex(canonicalJson({ contracts: subset, sources: src }));
+}
+export async function buildBundle(opts = {}) {
+    const root = repoRoot();
+    const profiles = readJson(opts.profilesPath ?? join(root, "build", "profiles.json"));
+    const lock = loadLock(opts.lockPath);
+    const vendorDir = opts.vendorDir ?? join(root, "vendor");
+    const workDir = opts.workDir ?? join(root, ".foga-build");
+    const outPath = opts.outPath ?? join(root, "artifacts", "bundle.json");
+    const problems = verifyVendor({ lockPath: opts.lockPath, vendorDir });
+    if (problems.length)
+        throw new Error("vendor tree does not match vendor/LOCK.json:\n  " + problems.join("\n  "));
+    const forge = forgeVersion();
+    log.info(`forge ${forge}`);
+    const contracts = {};
+    const sources = [];
+    const interfaceIds = {};
+    const extras = {};
+    const solcUsed = {};
+    const known = exists(join(root, "build", "known-interface-ids.json"))
+        ? readJson(join(root, "build", "known-interface-ids.json"))
+        : {};
+    for (const profile of profiles.repos) {
+        if (opts.only && !opts.only.includes(profile.repo))
+            continue;
+        const lockEntry = lock.sources.find((s) => s.repo === profile.repo);
+        if (!lockEntry)
+            throw new Error(`profile ${profile.repo} has no lock entry`);
+        const repoDir = join(vendorDir, profile.repo);
+        const outDir = join(workDir, "out", profile.repo);
+        const solcPath = solcBinary(profiles, profile.solc, opts.solcDir);
+        log.info(`building ${profile.repo} (ERC-${profile.erc}, ${profile.mode}, solc ${profile.solc}${solcPath ? ", local binary" : ""})`);
+        let projectDir = repoDir;
+        if (profile.mode === "staged") {
+            projectDir = join(workDir, "stage", profile.repo);
+            writeStagedProject(profile, repoDir, projectDir);
+            forgeBuild(projectDir, outDir, [], solcPath);
+        }
+        else {
+            forgeBuild(projectDir, outDir, profiles.foundry.skip, solcPath);
+        }
+        const ex = extractArtifacts({
+            outDir,
+            repo: profile.repo,
+            erc: profile.erc,
+            mode: profile.mode,
+            contractsRoot: profile.contractsRoot,
+            stageCopies: profile.stage?.copy,
+        });
+        for (const v of ex.solcVersions)
+            solcUsed[v.split("+")[0]] = v;
+        for (const c of ex.contracts)
+            contracts[c.key] = c;
+        log.step(`${ex.contracts.length} compilation targets kept from ${relative(root, outDir)}`);
+        sources.push({
+            erc: profile.erc,
+            repo: profile.repo,
+            url: lockEntry.url,
+            commit: lockEntry.commit,
+            contractsRoot: profile.contractsRoot,
+            mode: profile.mode,
+            upstreamToolchain: lockEntry.upstreamToolchain,
+            solc: profile.solc,
+            mirrors: profile.stage?.mirrors,
+        });
+        // Interface ids: computed from the AST, cross-checked against the upstream vectors (or README-published values).
+        const names = new Set(ex.contracts.filter((c) => c.kind === "interface").map((c) => c.name));
+        const upstream = new Map();
+        let source = null;
+        for (const v of profile.vectors) {
+            const p = join(repoDir, v);
+            if (!exists(p))
+                continue;
+            scanInterfaceIds(readJson(p), names, upstream);
+            source = v;
+        }
+        if (known[profile.repo]) {
+            for (const [n, id] of Object.entries(known[profile.repo].ids))
+                if (!upstream.has(n))
+                    upstream.set(n, id.toLowerCase());
+            source = source ?? known[profile.repo].source;
+        }
+        const rec = {};
+        for (const c of ex.contracts) {
+            if (c.kind !== "interface" || !c.interfaceId)
+                continue;
+            const up = upstream.get(c.name) ?? null;
+            rec[c.name] = { computed: c.interfaceId, upstream: up, match: up ? up === c.interfaceId : null, source: up ? source : null };
+            if (up && up !== c.interfaceId)
+                log.warn(`${profile.repo}: ${c.name} id ${c.interfaceId} differs from upstream ${up}`);
+        }
+        interfaceIds[profile.repo] = rec;
+        for (const [k, rel] of Object.entries(profile.extras)) {
+            const p = join(repoDir, rel);
+            if (exists(p)) {
+                extras[profile.repo] = extras[profile.repo] ?? {};
+                extras[profile.repo][k] = readJson(p);
+            }
+        }
+    }
+    // FOGA's own local-only contracts.
+    if (!opts.only || opts.only.includes("foga")) {
+        const projectDir = join(root, profiles.local.project);
+        const outDir = join(workDir, "out", "foga");
+        const solcPath = solcBinary(profiles, profiles.local.solc, opts.solcDir);
+        log.info(`building local contracts (${profiles.local.project}, solc ${profiles.local.solc})`);
+        forgeBuild(projectDir, outDir, ["test", "script"], solcPath);
+        const ex = extractArtifacts({ outDir, repo: "foga", erc: "foga", mode: "local", contractsRoot: profiles.local.contractsRoot });
+        for (const v of ex.solcVersions)
+            solcUsed[v.split("+")[0]] = v;
+        for (const c of ex.contracts)
+            contracts[c.key] = c;
+        sources.push({
+            erc: "foga",
+            repo: "foga",
+            url: null,
+            commit: null,
+            contractsRoot: `${profiles.local.project}/${profiles.local.contractsRoot}`,
+            mode: "local",
+            upstreamToolchain: "foundry (this repository)",
+            solc: profiles.local.solc,
+        });
+        log.step(`${ex.contracts.length} local contracts`);
+    }
+    const ordered = {};
+    for (const k of Object.keys(contracts).sort())
+        ordered[k] = contracts[k];
+    const bundle = {
+        schema: "foga.bundle/1",
+        builtAt: new Date().toISOString(),
+        builtWith: { forge, solc: solcUsed },
+        sources,
+        contracts: ordered,
+        interfaceIds,
+        extras,
+        hash: bundleHash(ordered, sources),
+    };
+    if (opts.verify) {
+        if (!exists(outPath))
+            throw new Error(`nothing to verify: ${outPath} does not exist`);
+        const committed = readJson(outPath);
+        const verifyPath = join(workDir, "bundle.verify.json");
+        writeJson(verifyPath, bundle);
+        const ok = committed.hash === bundle.hash;
+        if (ok)
+            log.info(`bundle hash verified: ${bundle.hash}`);
+        else
+            log.error(`bundle hash mismatch: committed ${committed.hash}, rebuilt ${bundle.hash} (fresh build written to ${relative(root, verifyPath)})`);
+        return { bundle, path: verifyPath, verified: ok };
+    }
+    writeJson(outPath, bundle);
+    writeFileSync(outPath.replace(/\.json$/, ".sha256"), `${bundle.hash.slice(2)}  ${basename(outPath)}\n`);
+    log.info(`wrote ${relative(root, outPath)} (${Object.keys(ordered).length} contracts, hash ${bundle.hash})`);
+    return { bundle, path: outPath };
+}

package/dist/build/vendor.js

@@ -0,0 +1,74 @@
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { ensureDir, exists, readJson, repoRoot, rmrf } from "../util/fs.js";
+import { log } from "../util/log.js";
+export function loadLock(path) {
+    const p = path ?? join(repoRoot(), "vendor", "LOCK.json");
+    const lock = readJson(p);
+    if (lock.schema !== "foga.vendor-lock/1")
+        throw new Error(`unsupported lock schema in ${p}`);
+    return lock;
+}
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+export function headCommit(dir) {
+    try {
+        return git(dir, ["rev-parse", "HEAD"]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Materialize every locked source under vendor/<repo>/ at exactly the locked commit.
+ * Existing directories already at the right commit are left untouched; anything else is replaced.
+ */
+export function syncVendor(opts = {}) {
+    const lock = loadLock(opts.lockPath);
+    const vendorDir = opts.vendorDir ?? join(repoRoot(), "vendor");
+    ensureDir(vendorDir);
+    for (const src of lock.sources) {
+        if (opts.only && !opts.only.includes(src.repo))
+            continue;
+        const dir = join(vendorDir, src.repo);
+        const have = exists(dir) ? headCommit(dir) : null;
+        if (have === src.commit) {
+            log.step(`${src.repo} already at ${src.commit.slice(0, 7)}`);
+            continue;
+        }
+        if (exists(dir)) {
+            log.step(`${src.repo}: replacing ${have ? have.slice(0, 7) : "non-git directory"} with ${src.commit.slice(0, 7)}`);
+            rmrf(dir);
+        }
+        else {
+            log.step(`${src.repo}: fetching ${src.commit.slice(0, 7)}`);
+        }
+        ensureDir(dir);
+        git(dir, ["init", "-q"]);
+        git(dir, ["remote", "add", "origin", src.url]);
+        // GitHub serves fetches by commit id, so this is a one-commit shallow fetch of exactly the lock.
+        git(dir, ["-c", "advice.detachedHead=false", "fetch", "-q", "--depth", "1", "origin", src.commit]);
+        git(dir, ["-c", "advice.detachedHead=false", "checkout", "-q", "FETCH_HEAD"]);
+        const now = headCommit(dir);
+        if (now !== src.commit)
+            throw new Error(`${src.repo}: expected ${src.commit}, got ${now}`);
+    }
+}
+/** Verify that every vendored tree is present and at the locked commit; returns the problems found. */
+export function verifyVendor(opts = {}) {
+    const lock = loadLock(opts.lockPath);
+    const vendorDir = opts.vendorDir ?? join(repoRoot(), "vendor");
+    const problems = [];
+    for (const src of lock.sources) {
+        const dir = join(vendorDir, src.repo);
+        if (!exists(dir)) {
+            problems.push(`${src.repo}: missing (run \`foga vendor sync\`)`);
+            continue;
+        }
+        const have = headCommit(dir);
+        if (have !== src.commit)
+            problems.push(`${src.repo}: at ${have ?? "unknown"}, lock says ${src.commit}`);
+    }
+    return problems;
+}

package/dist/bundle/load.js

@@ -0,0 +1,24 @@
+import { join } from "node:path";
+import { readJson, repoRoot, exists } from "../util/fs.js";
+export function defaultBundlePath() {
+    return join(repoRoot(), "artifacts", "bundle.json");
+}
+export function loadBundle(path) {
+    const p = path ?? defaultBundlePath();
+    if (!exists(p))
+        throw new Error(`bundle not found at ${p}; run \`foga build\` (needs \`foga vendor sync\` first)`);
+    const bundle = readJson(p);
+    if (bundle.schema !== "foga.bundle/1")
+        throw new Error(`unsupported bundle schema ${String(bundle.schema)}`);
+    return bundle;
+}
+export function getContract(bundle, key) {
+    const c = bundle.contracts[key];
+    if (!c)
+        throw new Error(`bundle has no contract ${key}`);
+    return c;
+}
+/** Find a bundle contract by repo and name (libraries are resolved this way when linking). */
+export function findByName(bundle, repo, name) {
+    return bundle.contracts[`${repo}:${name}`];
+}

package/dist/bundle/types.js

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