domain-knowledge-kit 0.2.15 → 0.2.16

package/dist/features/federation/git-fetcher.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Options for {@link sparseFetch}.
+ */
+export interface SparseFetchOptions {
+    /** Git URL (https / ssh). */
+    url: string;
+    /** Branch to track. */
+    branch: string;
+    /**
+     * Sub-path inside the peer repo where the service lives (i.e. the
+     * directory whose child is `.dkk/`). Empty string for repos that
+     * have `.dkk/` at the root.
+     */
+    subpath: string;
+    /**
+     * Absolute destination directory. Will be wiped if it exists.
+     * After fetch, the peer's repo content lives at `<dest>` and the
+     * service's `.dkk/` lives at `<dest>/<subpath>/.dkk` (or
+     * `<dest>/.dkk` when subpath is empty).
+     */
+    dest: string;
+}
+/** Result of a successful sparse fetch. */
+export interface SparseFetchResult {
+    /** Resolved commit SHA at HEAD of the fetched branch. */
+    sha: string;
+}
+/**
+ * Clone a peer repository into `dest` using a sparse-checkout of only
+ * the `.dkk/` subtree. The clone is depth-1 + blobless to keep it fast
+ * and small. Returns the resolved commit SHA.
+ *
+ * Steps:
+ *   1. Wipe `dest` if it exists (a stale partial clone is worse than no clone).
+ *   2. `git clone --filter=blob:none --depth 1 --no-checkout --branch <b> <url> <dest>`.
+ *   3. `git sparse-checkout init --no-cone` inside `dest`.
+ *   4. `git sparse-checkout set <subpath>/.dkk` (or `.dkk` when subpath empty).
+ *   5. `git checkout <branch>` to materialise the sparse set on disk.
+ *   6. `git rev-parse HEAD` to capture the SHA.
+ *
+ * Errors from `git` propagate as thrown exceptions with their stderr
+ * attached, so the caller can surface a meaningful message to the user.
+ */
+export declare function sparseFetch(opts: SparseFetchOptions): SparseFetchResult;
+//# sourceMappingURL=git-fetcher.d.ts.map

package/dist/features/federation/git-fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-fetcher.d.ts","sourceRoot":"","sources":["../../../src/features/federation/git-fetcher.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;CACb;AAcD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,iBAAiB,CAoCvE"}

package/dist/features/federation/git-fetcher.js

@@ -0,0 +1,70 @@
+/**
+ * Sparse-checkout fetcher for git-source peers.
+ *
+ * Clones a peer repository into a local cache, pulling only the
+ * subdirectory containing `.dkk/` to keep disk cost minimal — a
+ * typical peer is well under a megabyte.
+ *
+ * The user's existing git credential helper / SSH agent is what
+ * authenticates the clone. DKK never handles tokens directly.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Run `git` with the given args inside `cwd`. Throws on non-zero exit.
+ * Captures stdout for callers that need it (e.g. `rev-parse`).
+ */
+function git(args, cwd) {
+    return execFileSync("git", args, {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+    }).trim();
+}
+/**
+ * Clone a peer repository into `dest` using a sparse-checkout of only
+ * the `.dkk/` subtree. The clone is depth-1 + blobless to keep it fast
+ * and small. Returns the resolved commit SHA.
+ *
+ * Steps:
+ *   1. Wipe `dest` if it exists (a stale partial clone is worse than no clone).
+ *   2. `git clone --filter=blob:none --depth 1 --no-checkout --branch <b> <url> <dest>`.
+ *   3. `git sparse-checkout init --no-cone` inside `dest`.
+ *   4. `git sparse-checkout set <subpath>/.dkk` (or `.dkk` when subpath empty).
+ *   5. `git checkout <branch>` to materialise the sparse set on disk.
+ *   6. `git rev-parse HEAD` to capture the SHA.
+ *
+ * Errors from `git` propagate as thrown exceptions with their stderr
+ * attached, so the caller can surface a meaningful message to the user.
+ */
+export function sparseFetch(opts) {
+    if (existsSync(opts.dest)) {
+        rmSync(opts.dest, { recursive: true, force: true });
+    }
+    mkdirSync(dirname(opts.dest), { recursive: true });
+    // Step 2: blobless, depth-1, no checkout yet.
+    git([
+        "clone",
+        "--filter=blob:none",
+        "--depth",
+        "1",
+        "--no-checkout",
+        "--branch",
+        opts.branch,
+        opts.url,
+        opts.dest,
+    ], process.cwd());
+    // Steps 3-4: enable sparse-checkout, restrict to the .dkk/ subtree.
+    git(["sparse-checkout", "init", "--no-cone"], opts.dest);
+    const sparsePattern = opts.subpath
+        ? `${opts.subpath.replace(/\/$/, "")}/.dkk/*`
+        : ".dkk/*";
+    git(["sparse-checkout", "set", sparsePattern], opts.dest);
+    // Step 5: materialise.
+    git(["checkout", opts.branch], opts.dest);
+    // Step 6: capture HEAD SHA.
+    const sha = git(["rev-parse", "HEAD"], opts.dest);
+    return { sha };
+}
+//# sourceMappingURL=git-fetcher.js.map

package/dist/features/federation/git-fetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-fetcher.js","sourceRoot":"","sources":["../../../src/features/federation/git-fetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BpC;;;GAGG;AACH,SAAS,GAAG,CAAC,IAAc,EAAE,GAAW;IACtC,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE;QAC/B,GAAG;QACH,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;QACjC,QAAQ,EAAE,OAAO;KAClB,CAAC,CAAC,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,IAAwB;IAClD,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEnD,8CAA8C;IAC9C,GAAG,CACD;QACE,OAAO;QACP,oBAAoB;QACpB,SAAS;QACT,GAAG;QACH,eAAe;QACf,UAAU;QACV,IAAI,CAAC,MAAM;QACX,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;KACV,EACD,OAAO,CAAC,GAAG,EAAE,CACd,CAAC;IAEF,oEAAoE;IACpE,GAAG,CAAC,CAAC,iBAAiB,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACzD,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO;QAChC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS;QAC7C,CAAC,CAAC,QAAQ,CAAC;IACb,GAAG,CAAC,CAAC,iBAAiB,EAAE,KAAK,EAAE,aAAa,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAE1D,uBAAuB;IACvB,GAAG,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAE1C,4BAA4B;IAC5B,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAElD,OAAO,EAAE,GAAG,EAAE,CAAC;AACjB,CAAC"}

package/dist/features/federation/loader.d.ts

@@ -0,0 +1,60 @@
+import type { DomainModel } from "../../shared/types/domain.js";
+import type { FederationManifest, PeerSpec } from "../../shared/types/federation.js";
+/** Per-peer resolution outcome surfaced to the loader/caller. */
+export interface PeerResolution {
+    /** The peer's repo root on disk (where its `.dkk/` lives), if reachable. */
+    peerRoot: string | null;
+    /** True when the peer's `.dkk/` directory exists on disk. */
+    reachable: boolean;
+    /** A short reason string used for warnings (e.g. "git cache empty"). */
+    reason?: string;
+}
+/**
+ * Read `.dkk/federation.yml` (if present), validate it against
+ * `federation.schema.json`, and return the parsed manifest. Returns
+ * `null` for unfederated repos.
+ *
+ * Throws when the file exists but does not conform to the schema —
+ * the message includes Ajv's error list so the user can fix the
+ * manifest directly.
+ */
+export declare function loadFederation(root?: string): FederationManifest | null;
+/**
+ * Resolve a single peer spec into an absolute repo-root path on disk.
+ *
+ * - `local` sources resolve relative to the local repo root (so
+ *   `../order-svc` in `billing-svc/.dkk/federation.yml` points at the
+ *   sibling directory regardless of `cwd`). Env-var override
+ *   `DKK_PEER_<SERVICE_NAME_UPPER>` (uppercase, hyphens → underscores)
+ *   takes precedence over the manifest's `source.path`.
+ * - `git` sources resolve to the cache directory
+ *   `.dkk/imports/<service>/` populated by `dkk pull`.
+ *
+ * The returned `peerRoot` points at the peer's repository root (so
+ * `<peerRoot>/.dkk/` is where the peer's domain lives).
+ */
+export declare function resolvePeerRoot(spec: PeerSpec, localRepoRoot: string): PeerResolution;
+/**
+ * Load a peer's domain model in "peer mode": one level deep (peer's
+ * own `federation.yml` is skipped) and resilient to minor schema
+ * drift. The peer's model is structurally identical to a local model
+ * so the same `loadDomainModel` is reused; the federation pass is
+ * suppressed via the `followPeers: false` option.
+ */
+export declare function loadPeerModel(peerRoot: string): DomainModel;
+/**
+ * Resolve and load every peer declared in the manifest. Unreachable
+ * peers are reported via `warnings` (each line is one peer) but never
+ * abort the load — the caller (typically the main loader) attaches
+ * the resulting map to `model.peers`.
+ */
+export declare function loadAllPeers(localRepoRoot: string, manifest: FederationManifest): {
+    peers: Map<string, DomainModel>;
+    warnings: string[];
+};
+/**
+ * Build the env-var key used to override a peer's source path.
+ * Exposed for tests and for the `peers status` command.
+ */
+export declare function peerEnvKey(serviceName: string): string;
+//# sourceMappingURL=loader.d.ts.map

package/dist/features/federation/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/features/federation/loader.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EACV,kBAAkB,EAClB,QAAQ,EACT,MAAM,kCAAkC,CAAC;AAuB1C,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAC;IACnB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAkBvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAoDrF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,kBAAkB,GAC3B;IAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAoBzD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/features/federation/loader.js

@@ -0,0 +1,193 @@
+/**
+ * Federation loader — resolves peer services declared in
+ * `.dkk/federation.yml` and loads each peer's `.dkk/` as a read-only
+ * sub-model attached at `model.peers.get(serviceName)`.
+ *
+ * Peer loading is exactly one level deep: a peer's own `federation.yml`
+ * is intentionally NOT followed. Peers are loaded in lenient mode so
+ * that DKK schema drift across services (peer YAML using fields the
+ * local DKK version doesn't understand) degrades to a warning rather
+ * than failing the consumer's load.
+ *
+ * Two source types are supported:
+ *  - `local`: a filesystem path (absolute or relative to repo root).
+ *  - `git`:   resolved against the cache at `.dkk/imports/<service>/`
+ *             populated by `dkk pull` (Phase 3).
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { isAbsolute, resolve, join } from "node:path";
+import { createRequire } from "node:module";
+import { parseYaml } from "../../shared/yaml.js";
+import { federationFile, importedServiceDir, schemaDir, repoRoot } from "../../shared/paths.js";
+import { loadDomainModel, setFederationHook } from "../../shared/loader.js";
+// ajv is a CJS package — use createRequire for ESM interop.
+const require = createRequire(import.meta.url);
+const Ajv = require("ajv").default;
+const addFormats = require("ajv-formats").default;
+/** Cached Ajv instance for federation.yml validation. */
+let cachedAjv = null;
+function getAjv() {
+    if (cachedAjv)
+        return cachedAjv;
+    const ajv = new Ajv({ allErrors: true, strict: true });
+    addFormats(ajv);
+    const dir = schemaDir();
+    for (const f of readdirSync(dir).filter((n) => n.endsWith(".schema.json"))) {
+        const schema = JSON.parse(readFileSync(join(dir, f), "utf-8"));
+        ajv.addSchema(schema, schema.$id);
+    }
+    cachedAjv = ajv;
+    return ajv;
+}
+/**
+ * Read `.dkk/federation.yml` (if present), validate it against
+ * `federation.schema.json`, and return the parsed manifest. Returns
+ * `null` for unfederated repos.
+ *
+ * Throws when the file exists but does not conform to the schema —
+ * the message includes Ajv's error list so the user can fix the
+ * manifest directly.
+ */
+export function loadFederation(root) {
+    const path = federationFile(root);
+    if (!existsSync(path))
+        return null;
+    const text = readFileSync(path, "utf-8");
+    const parsed = parseYaml(text);
+    const ajv = getAjv();
+    const valid = ajv.validate("federation.schema.json", parsed);
+    if (!valid) {
+        const details = (ajv.errors ?? [])
+            .map((e) => `  - ${e.instancePath || "/"}: ${e.message ?? "invalid"}`)
+            .join("\n");
+        throw new Error(`Invalid ${path}:\n${details}\n\nExpected shape: { peers: [{ name, source: { type: "local" | "git", ... } }] }`);
+    }
+    return parsed;
+}
+/**
+ * Resolve a single peer spec into an absolute repo-root path on disk.
+ *
+ * - `local` sources resolve relative to the local repo root (so
+ *   `../order-svc` in `billing-svc/.dkk/federation.yml` points at the
+ *   sibling directory regardless of `cwd`). Env-var override
+ *   `DKK_PEER_<SERVICE_NAME_UPPER>` (uppercase, hyphens → underscores)
+ *   takes precedence over the manifest's `source.path`.
+ * - `git` sources resolve to the cache directory
+ *   `.dkk/imports/<service>/` populated by `dkk pull`.
+ *
+ * The returned `peerRoot` points at the peer's repository root (so
+ * `<peerRoot>/.dkk/` is where the peer's domain lives).
+ */
+export function resolvePeerRoot(spec, localRepoRoot) {
+    const source = spec.source;
+    // Env-var override: applies to any source type for the convenience of
+    // developers who want to point at a local checkout regardless of
+    // what the committed manifest says.
+    const envKey = `DKK_PEER_${spec.name.toUpperCase().replace(/-/g, "_")}`;
+    const envOverride = process.env[envKey];
+    if (envOverride && envOverride.length > 0) {
+        const peerRoot = isAbsolute(envOverride)
+            ? envOverride
+            : resolve(localRepoRoot, envOverride);
+        const reachable = existsSync(peerRoot + "/.dkk");
+        return {
+            peerRoot,
+            reachable,
+            reason: reachable ? undefined : `env override ${envKey} points at ${peerRoot} but it has no .dkk/`,
+        };
+    }
+    if (source.type === "local") {
+        const peerRoot = isAbsolute(source.path)
+            ? source.path
+            : resolve(localRepoRoot, source.path);
+        const reachable = existsSync(peerRoot + "/.dkk");
+        return {
+            peerRoot,
+            reachable,
+            reason: reachable ? undefined : `local path ${peerRoot} has no .dkk/`,
+        };
+    }
+    if (source.type === "git") {
+        const cacheRoot = importedServiceDir(spec.name, localRepoRoot);
+        // When the peer's `.dkk/` lives in a sub-directory of its repo
+        // (monorepo case), the manifest's `source.path` names that
+        // sub-directory; the sparse-checkout pulls it into the cache at
+        // the same relative location.
+        const peerRoot = source.path
+            ? `${cacheRoot}/${source.path.replace(/\/$/, "")}`
+            : cacheRoot;
+        const reachable = existsSync(peerRoot + "/.dkk");
+        return {
+            peerRoot,
+            reachable,
+            reason: reachable ? undefined : `git cache empty for "${spec.name}" — run \`dkk pull ${spec.name}\``,
+        };
+    }
+    // Exhaustiveness check — future source types should be added here.
+    const exhaustive = source;
+    return { peerRoot: null, reachable: false, reason: `unknown source type: ${JSON.stringify(exhaustive)}` };
+}
+/**
+ * Load a peer's domain model in "peer mode": one level deep (peer's
+ * own `federation.yml` is skipped) and resilient to minor schema
+ * drift. The peer's model is structurally identical to a local model
+ * so the same `loadDomainModel` is reused; the federation pass is
+ * suppressed via the `followPeers: false` option.
+ */
+export function loadPeerModel(peerRoot) {
+    return loadDomainModel({ root: peerRoot, followPeers: false });
+}
+/**
+ * Resolve and load every peer declared in the manifest. Unreachable
+ * peers are reported via `warnings` (each line is one peer) but never
+ * abort the load — the caller (typically the main loader) attaches
+ * the resulting map to `model.peers`.
+ */
+export function loadAllPeers(localRepoRoot, manifest) {
+    const peers = new Map();
+    const warnings = [];
+    for (const spec of manifest.peers ?? []) {
+        const resolution = resolvePeerRoot(spec, localRepoRoot);
+        if (!resolution.reachable || !resolution.peerRoot) {
+            warnings.push(`peer "${spec.name}" unreachable: ${resolution.reason ?? "unknown"}`);
+            continue;
+        }
+        try {
+            const model = loadPeerModel(resolution.peerRoot);
+            peers.set(spec.name, model);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            warnings.push(`peer "${spec.name}" failed to load: ${msg}`);
+        }
+    }
+    return { peers, warnings };
+}
+/**
+ * Build the env-var key used to override a peer's source path.
+ * Exposed for tests and for the `peers status` command.
+ */
+export function peerEnvKey(serviceName) {
+    return `DKK_PEER_${serviceName.toUpperCase().replace(/-/g, "_")}`;
+}
+// ── Hook registration ────────────────────────────────────────────────
+//
+// Register the peer-hydration hook with the shared loader at module
+// initialisation. Any CLI command that imports this slice (directly or
+// transitively via the federation commands wired in cli.ts) will cause
+// `loadDomainModel` to start populating `model.peers`. Scripts that
+// import the shared loader without the federation slice get plain
+// unfederated behaviour — no surprises, no cycles.
+setFederationHook((root, model) => {
+    const manifest = loadFederation(root);
+    if (!manifest)
+        return;
+    const resolvedRoot = repoRoot(root);
+    const { peers, warnings } = loadAllPeers(resolvedRoot, manifest);
+    if (peers.size > 0)
+        model.peers = peers;
+    for (const w of warnings) {
+        console.warn(`dkk: ${w}`);
+    }
+});
+//# sourceMappingURL=loader.js.map

package/dist/features/federation/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../src/features/federation/loader.ts"],"names":[],"mappings":"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"}

package/dist/features/federation/lock.d.ts

@@ -0,0 +1,12 @@
+import type { FederationLock, LockEntry } from "../../shared/types/federation.js";
+/**
+ * Read the lockfile from disk. Returns an empty record when the file
+ * is absent. Malformed JSON throws (the file is committed, so a parse
+ * failure should be loud).
+ */
+export declare function readLock(root?: string): FederationLock;
+/** Write the lockfile to disk with stable formatting. */
+export declare function writeLock(lock: FederationLock, root?: string): void;
+/** Build a fresh lock entry from a fetch result. */
+export declare function makeEntry(source: LockEntry["source"], sha: string | undefined): LockEntry;
+//# sourceMappingURL=lock.d.ts.map

package/dist/features/federation/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../src/features/federation/lock.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAElF;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,CAMtD;AAED,yDAAyD;AACzD,wBAAgB,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CASnE;AAED,oDAAoD;AACpD,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,SAAS,CAKX"}

package/dist/features/federation/lock.js

@@ -0,0 +1,48 @@
+/**
+ * Federation lockfile (.dkk/federation.lock.json).
+ *
+ * Records the resolved commit SHA each git-source peer was fetched at,
+ * along with a snapshot of the source spec used. Committing the
+ * lockfile means two developers running `dkk pull` see the same peer
+ * state until someone explicitly re-pulls with `--refresh`.
+ *
+ * Local-source peers have no lockfile entry — they're always live from
+ * disk.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { federationLockFile } from "../../shared/paths.js";
+/**
+ * Read the lockfile from disk. Returns an empty record when the file
+ * is absent. Malformed JSON throws (the file is committed, so a parse
+ * failure should be loud).
+ */
+export function readLock(root) {
+    const path = federationLockFile(root);
+    if (!existsSync(path))
+        return {};
+    const text = readFileSync(path, "utf-8");
+    if (text.trim().length === 0)
+        return {};
+    return JSON.parse(text);
+}
+/** Write the lockfile to disk with stable formatting. */
+export function writeLock(lock, root) {
+    const path = federationLockFile(root);
+    mkdirSync(dirname(path), { recursive: true });
+    // Stable key ordering (sorted by service name) keeps diffs minimal.
+    const sorted = {};
+    for (const key of Object.keys(lock).sort()) {
+        sorted[key] = lock[key];
+    }
+    writeFileSync(path, JSON.stringify(sorted, null, 2) + "\n", "utf-8");
+}
+/** Build a fresh lock entry from a fetch result. */
+export function makeEntry(source, sha) {
+    const entry = { source };
+    if (sha)
+        entry.sha = sha;
+    entry.fetchedAt = new Date().toISOString();
+    return entry;
+}
+//# sourceMappingURL=lock.js.map

package/dist/features/federation/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/features/federation/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG3D;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAmB,CAAC;AAC5C,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,SAAS,CAAC,IAAoB,EAAE,IAAa;IAC3D,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACtC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,oEAAoE;IACpE,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IACD,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AACvE,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,SAAS,CACvB,MAA2B,EAC3B,GAAuB;IAEvB,MAAM,KAAK,GAAc,EAAE,MAAM,EAAE,CAAC;IACpC,IAAI,GAAG;QAAE,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC;IACzB,KAAK,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/features/federation/tests/git-fetcher.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=git-fetcher.test.d.ts.map

package/dist/features/federation/tests/git-fetcher.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-fetcher.test.d.ts","sourceRoot":"","sources":["../../../../src/features/federation/tests/git-fetcher.test.ts"],"names":[],"mappings":""}

package/dist/features/federation/tests/git-fetcher.test.js

@@ -0,0 +1,167 @@
+/**
+ * Tests for the sparse-checkout git fetcher.
+ *
+ * Uses a local bare repository as the "remote" so the test runs
+ * fully offline. Verifies that:
+ *  - sparseFetch clones with a `.dkk/` sparse pattern.
+ *  - Only `.dkk/` content is materialised; other top-level files are
+ *    excluded by the sparse rule.
+ *  - The returned SHA matches `HEAD` of the configured branch.
+ *  - `dkk pull` populates the cache and writes a lockfile entry.
+ *  - A subsequent `dkk pull` is a no-op (the SHA in the lock matches).
+ *  - `dkk pull --refresh` re-fetches.
+ *
+ * If `git` is not available on PATH, the test is skipped (we don't
+ * fail CI on environments without git).
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { sparseFetch } from "../git-fetcher.js";
+let passed = 0;
+let failed = 0;
+let skipped = false;
+function assert(label, condition, detail) {
+    if (condition) {
+        console.log(`  OK: ${label}`);
+        passed++;
+    }
+    else {
+        console.error(`FAIL: ${label}${detail ? ` — ${detail}` : ""}`);
+        failed++;
+    }
+}
+function gitAvailable() {
+    try {
+        execFileSync("git", ["--version"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+if (!gitAvailable()) {
+    console.log("git not available on PATH — skipping git-fetcher tests");
+    skipped = true;
+}
+if (!skipped) {
+    const RAW_TMP = join(tmpdir(), `dkk-git-${Date.now()}`);
+    mkdirSync(RAW_TMP, { recursive: true });
+    const TMP = realpathSync(RAW_TMP);
+    // Layout:
+    //   <TMP>/remote/         — a bare git repo (the "remote")
+    //   <TMP>/source/         — a regular repo we'll push from
+    //     .dkk/               — the only content sparseFetch should pull
+    //       service.yml
+    //       domain/.../OrderPlaced.yml
+    //     README.md           — should NOT appear in the cache
+    //   <TMP>/local/.dkk/imports/ordering/  — destination cache
+    const REMOTE = join(TMP, "remote");
+    const SOURCE = join(TMP, "source");
+    const LOCAL = join(TMP, "local");
+    const CACHE_DIR = join(LOCAL, ".dkk", "imports", "ordering");
+    function run(args, cwd) {
+        const result = spawnSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+        if (result.status !== 0) {
+            throw new Error(`git ${args.join(" ")} failed in ${cwd}\nstderr: ${result.stderr}`);
+        }
+        return result.stdout.trim();
+    }
+    try {
+        // Create the bare remote.
+        mkdirSync(REMOTE, { recursive: true });
+        run(["init", "--bare", "--initial-branch=main"], REMOTE);
+        // Create the source repo with .dkk/ content + a noise file.
+        mkdirSync(join(SOURCE, ".dkk", "domain", "contexts", "ordering", "events"), {
+            recursive: true,
+        });
+        writeFileSync(join(SOURCE, ".dkk", "service.yml"), "name: ordering\nexports:\n  - ordering\n");
+        writeFileSync(join(SOURCE, ".dkk", "domain", "index.yml"), "contexts:\n  - name: ordering\n    description: Ordering context\nflows: []\n");
+        writeFileSync(join(SOURCE, ".dkk", "domain", "actors.yml"), "actors: []\n");
+        writeFileSync(join(SOURCE, ".dkk", "domain", "contexts", "ordering", "context.yml"), "name: ordering\ndescription: Ordering bounded context\n");
+        writeFileSync(join(SOURCE, ".dkk", "domain", "contexts", "ordering", "events", "OrderPlaced.yml"), "name: OrderPlaced\ndescription: Raised when an order is placed.\n");
+        writeFileSync(join(SOURCE, "README.md"), "# Should NOT be in the sparse checkout\n");
+        run(["init", "--initial-branch=main"], SOURCE);
+        run(["config", "user.email", "test@example.com"], SOURCE);
+        run(["config", "user.name", "Test"], SOURCE);
+        run(["config", "commit.gpgsign", "false"], SOURCE);
+        run(["add", "."], SOURCE);
+        run(["commit", "-m", "initial"], SOURCE);
+        run(["remote", "add", "origin", REMOTE], SOURCE);
+        run(["push", "-u", "origin", "main"], SOURCE);
+        const sourceHead = run(["rev-parse", "HEAD"], SOURCE);
+        // ── sparseFetch pulls only .dkk/ ──────────────────────────────────
+        console.log("\n=== sparseFetch ===");
+        const result = sparseFetch({
+            url: REMOTE,
+            branch: "main",
+            subpath: "",
+            dest: CACHE_DIR,
+        });
+        assert("returned SHA matches source HEAD", result.sha === sourceHead);
+        assert(".dkk/ exists in cache", existsSync(join(CACHE_DIR, ".dkk")));
+        assert("service.yml present", existsSync(join(CACHE_DIR, ".dkk", "service.yml")));
+        assert("OrderPlaced.yml present", existsSync(join(CACHE_DIR, ".dkk", "domain", "contexts", "ordering", "events", "OrderPlaced.yml")));
+        assert("README.md NOT in cache (sparse rule excluded it)", !existsSync(join(CACHE_DIR, "README.md")));
+        // ── dkk pull integrates the fetcher + lockfile ────────────────────
+        console.log("\n=== dkk pull (CLI integration) ===");
+        // Set up a `local` repo with a federation manifest pointing at the
+        // bare remote. Wipe the cache from the previous step so `pull` has
+        // to re-fetch.
+        rmSync(join(LOCAL, ".dkk"), { recursive: true, force: true });
+        mkdirSync(join(LOCAL, ".dkk", "domain"), { recursive: true });
+        writeFileSync(join(LOCAL, ".dkk", "service.yml"), "name: billing\nexports:\n  - billing\n");
+        writeFileSync(join(LOCAL, ".dkk", "federation.yml"), [
+            "peers:",
+            "  - name: ordering",
+            "    source:",
+            "      type: git",
+            `      url: ${REMOTE}`,
+            "      branch: main",
+        ].join("\n") + "\n");
+        const cliEntry = join(process.cwd(), "src", "cli.ts");
+        const pullResult = spawnSync("npx", ["tsx", cliEntry, "pull", "--root", LOCAL, "--json"], { encoding: "utf-8" });
+        if (pullResult.status !== 0) {
+            throw new Error(`dkk pull failed: ${pullResult.stderr}\n${pullResult.stdout}`);
+        }
+        const pullReport = JSON.parse(pullResult.stdout);
+        assert("pull report has one peer", pullReport.peers.length === 1);
+        assert("ordering peer fetched", pullReport.peers[0].name === "ordering" && pullReport.peers[0].outcome === "fetched");
+        assert("lockfile sha matches source HEAD", pullReport.peers[0].sha === sourceHead);
+        assert("lockfile written to disk", existsSync(join(LOCAL, ".dkk", "federation.lock.json")));
+        // Subsequent pull is a no-op.
+        const pullAgain = spawnSync("npx", ["tsx", cliEntry, "pull", "--root", LOCAL, "--json"], { encoding: "utf-8" });
+        const pullAgainReport = JSON.parse(pullAgain.stdout);
+        assert("second pull is cached (no-op)", pullAgainReport.peers[0].outcome === "cached");
+        // --refresh forces re-fetch even when cached.
+        const pullRefresh = spawnSync("npx", ["tsx", cliEntry, "pull", "--root", LOCAL, "--refresh", "--json"], { encoding: "utf-8" });
+        const pullRefreshReport = JSON.parse(pullRefresh.stdout);
+        assert("--refresh re-fetches even when cached", pullRefreshReport.peers[0].outcome === "fetched");
+        // --offline with cache present is a no-op.
+        const pullOffline = spawnSync("npx", ["tsx", cliEntry, "pull", "--root", LOCAL, "--offline", "--json"], { encoding: "utf-8" });
+        const pullOfflineReport = JSON.parse(pullOffline.stdout);
+        assert("--offline with cache returns skipped-offline-cached", pullOfflineReport.peers[0].outcome === "skipped-offline-cached");
+        // Verify lockfile contents.
+        const lock = JSON.parse(readFileSync(join(LOCAL, ".dkk", "federation.lock.json"), "utf-8"));
+        assert("lockfile has ordering entry", lock.ordering !== undefined);
+        assert("lockfile entry has git source", lock.ordering.source.type === "git");
+        assert("lockfile entry has sha", typeof lock.ordering.sha === "string" && lock.ordering.sha.length > 0);
+        // ── Federation loader sees the cached peer ────────────────────────
+        console.log("\n=== loader sees cached peer ===");
+        const showResult = spawnSync("npx", ["tsx", cliEntry, "show", "ordering:OrderPlaced", "--root", LOCAL, "--json"], { encoding: "utf-8" });
+        if (showResult.status !== 0) {
+            throw new Error(`dkk show failed: ${showResult.stderr}\n${showResult.stdout}`);
+        }
+        const shown = JSON.parse(showResult.stdout);
+        assert("peer item resolved via cache", shown.data?.name === "OrderPlaced");
+        assert("peer label includes [peer: ordering]", shown.label.includes("peer: ordering"));
+    }
+    finally {
+        rmSync(RAW_TMP, { recursive: true, force: true });
+    }
+}
+console.log(`\n${passed} passed, ${failed} failed${skipped ? " (test suite skipped)" : ""}`);
+if (failed > 0)
+    process.exit(1);
+//# sourceMappingURL=git-fetcher.test.js.map