@stigmer/cli 3.0.8

package/src/local/runtime/server.ts

@@ -0,0 +1,172 @@
+// Resolution and on-demand acquisition of the `stigmer-server` control plane.
+//
+// DD-003: a TypeScript CLI cannot `go:embed` a Go binary, so it resolves an
+// existing `stigmer-server` (dev build / Homebrew / a prior download) and, when
+// none is present, downloads the standalone release asset into ~/.stigmer/bin and
+// verifies its sha256 before first use. The fetch/extract mechanics are shared
+// with the Temporal downloader (`../artifact.ts`); the one deliberate difference
+// is the checksum step — this is our own executable, and DD-003 makes integrity
+// non-negotiable.
+//
+// Resolution order (first existing hit wins; download is the last resort):
+//   1. STIGMER_SERVER_BIN — explicit override (tests, custom installs)
+//   2. repo `bin/stigmer-server` — the dev build (`make build`)
+//   3. ~/bin/stigmer-server — a common local install location
+//   4. ~/.stigmer/bin/stigmer-server — a previously-downloaded release asset
+//   5. PATH — `stigmer-server`
+//   6. download the pinned release asset into ~/.stigmer/bin (checksum-verified)
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliExitError } from "../../errors/cli-exit-error.js";
+import { ExitCode } from "../../errors/exit-codes.js";
+import { VERSION } from "../../version.js";
+import { fetchTarballBinary, mapReleaseArch, mapReleaseOs } from "../artifact.js";
+import { binDir } from "../paths.js";
+import { which } from "./which.js";
+
+const SERVER_BINARY = "stigmer-server";
+const GITHUB_REPO = "stigmer/stigmer";
+
+// Platform/arch combos for which `release.cli.yaml` publishes a stigmer-server
+// asset. The npm CLI installs on more platforms than this (e.g. linux-arm64,
+// Windows), so an unsupported `stigmer up` must fail with clear guidance rather
+// than a confusing 404.
+const SUPPORTED_PLATFORMS = new Set(["darwin-arm64", "darwin-amd64", "linux-amd64"]);
+
+/**
+ * Find an already-present `stigmer-server` binary, or null. Pure: never
+ * downloads. `home` is injectable for tests.
+ */
+export function resolveServerBinary(home: string = homedir()): string | null {
+  for (const candidate of serverCandidates(home)) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return which(SERVER_BINARY);
+}
+
+export interface EnsureServerOptions {
+  home?: string;
+  /** Release version to download if needed (defaults to the CLI's own version). */
+  version?: string;
+  /** Override the fetch implementation (tests). */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Ensure a `stigmer-server` binary is available, returning its path. Reuses an
+ * existing binary if found; otherwise downloads the pinned release asset into
+ * ~/.stigmer/bin (checksum-verified). Throws actionable guidance when no binary
+ * exists and a download is not possible (a source/dev build, or an unsupported
+ * platform).
+ */
+export async function ensureServerBinary(opts: EnsureServerOptions = {}): Promise<string> {
+  const home = opts.home ?? homedir();
+  const existing = resolveServerBinary(home);
+  if (existing !== null) return existing;
+
+  const version = opts.version ?? VERSION;
+  if (!isDownloadableRelease(version)) {
+    throw notFoundError();
+  }
+
+  const binPath = join(binDir(home), SERVER_BINARY);
+  await downloadServerBinary({ version, binPath, fetchImpl: opts.fetchImpl });
+  return binPath;
+}
+
+export interface ServerDownloadTarget {
+  /** Release version, e.g. "0.5.0" or "0.5.0-rc.1" (with or without a leading "v"). */
+  version: string;
+  /** Absolute path to write the extracted `stigmer-server` binary to. */
+  binPath: string;
+  /** Node platform (defaults to process.platform). */
+  platform?: NodeJS.Platform;
+  /** Node arch (defaults to process.arch). */
+  arch?: string;
+  /** Override the fetch implementation (tests). */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Download, checksum-verify, and install the standalone `stigmer-server` release
+ * asset. Throws a {@link CliExitError} on an unsupported platform or any
+ * network/checksum/extraction failure.
+ */
+export async function downloadServerBinary(target: ServerDownloadTarget): Promise<void> {
+  const os = mapReleaseOs(target.platform ?? process.platform);
+  const arch = mapReleaseArch(target.arch ?? process.arch);
+  const platformKey = `${os}-${arch}`;
+  if (!SUPPORTED_PLATFORMS.has(platformKey)) {
+    throw unsupportedPlatformError(platformKey);
+  }
+
+  const tag = releaseTag(target.version);
+  const archive = `${SERVER_BINARY}-${tag}-${platformKey}.tar.gz`;
+  const url = `https://github.com/${GITHUB_REPO}/releases/download/${tag}/${archive}`;
+
+  await fetchTarballBinary({
+    url,
+    checksumUrl: `${url}.sha256`,
+    entryName: SERVER_BINARY,
+    binPath: target.binPath,
+    label: SERVER_BINARY,
+    fetchImpl: target.fetchImpl,
+  });
+}
+
+function serverCandidates(home: string): string[] {
+  const candidates: string[] = [];
+  const override = process.env.STIGMER_SERVER_BIN;
+  if (override !== undefined && override !== "") candidates.push(override);
+
+  const root = repoRoot();
+  if (root !== null) candidates.push(join(root, "bin", SERVER_BINARY));
+  candidates.push(join(home, "bin", SERVER_BINARY));
+  candidates.push(join(binDir(home), SERVER_BINARY)); // a previously-downloaded asset
+  return candidates;
+}
+
+// Only tagged releases publish a downloadable asset. A source build reports the
+// "0.0.0-dev" sentinel and the dev npm channel stamps "<v>-dev.<stamp>" versions
+// (release.dev.yaml) that never cut a GitHub release — neither is downloadable.
+function isDownloadableRelease(version: string): boolean {
+  return !version.includes("-dev");
+}
+
+// The npm package version maps to the GitHub release tag by prefixing "v"
+// (npm 0.5.0 -> tag v0.5.0; npm 0.5.0-rc.1 -> tag v0.5.0-rc.1).
+function releaseTag(version: string): string {
+  return version.startsWith("v") ? version : `v${version}`;
+}
+
+function notFoundError(): CliExitError {
+  return new CliExitError(`${SERVER_BINARY} binary not found`, ExitCode.General, [
+    "Build it from the repo with `make build` (produces ./bin/stigmer-server),",
+    "or set STIGMER_SERVER_BIN to an existing binary.",
+    "Automatic download is only available for tagged releases.",
+  ]);
+}
+
+function unsupportedPlatformError(platformKey: string): CliExitError {
+  return new CliExitError(`the local stack does not support this platform (${platformKey})`, ExitCode.General, [
+    "`stigmer up` needs a stigmer-server release asset, which is published for",
+    "macOS (arm64/amd64) and Linux (amd64) only.",
+    "Point STIGMER_SERVER_BIN at a server binary you built yourself to proceed.",
+  ]);
+}
+
+// Walk up from this module to the repo root (the directory containing
+// `bin/stigmer-server` in a dev checkout). Returns null outside a checkout.
+function repoRoot(): string | null {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i += 1) {
+    if (existsSync(join(dir, "bin", SERVER_BINARY))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}

package/src/local/runtime/which.ts

@@ -0,0 +1,30 @@
+// Minimal PATH lookup, the Node analogue of Go's exec.LookPath.
+//
+// Scans the PATH entries for an executable file. POSIX-focused (the local stack
+// targets macOS and Linux); on those platforms a name with no separator is
+// resolved against PATH, and an absolute/relative path is checked directly.
+
+import { accessSync, constants } from "node:fs";
+import { delimiter, isAbsolute, join, sep } from "node:path";
+
+/** Resolve an executable by name via PATH, or null if not found. */
+export function which(name: string): string | null {
+  if (name.includes(sep) || isAbsolute(name)) {
+    return isExecutable(name) ? name : null;
+  }
+  const entries = (process.env.PATH ?? "").split(delimiter).filter((e) => e !== "");
+  for (const dir of entries) {
+    const candidate = join(dir, name);
+    if (isExecutable(candidate)) return candidate;
+  }
+  return null;
+}
+
+function isExecutable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/local/seedpack/apply.test.ts

@@ -0,0 +1,166 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Message } from "@bufbuild/protobuf";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildDeclarativeItems, scanResourceFiles } from "../../resources/apply/declarative.js";
+import type { ControllerFn } from "../../resources/apply/handlers.js";
+import { applySeedpack, resolveSeedpackOrg, seedpackContentHash } from "./apply.js";
+import type { SeedpackContent } from "./content.js";
+import { extractSeedpack, readMarker, resolveSeedpackContent } from "./content.js";
+
+const ORG_YAML = [
+  "apiVersion: tenancy.stigmer.ai/v1",
+  "kind: Organization",
+  "metadata:",
+  "  name: Stigmer",
+  "  slug: stigmer",
+  "spec:",
+  '  description: "System org"',
+  "  management_mode: self_managed",
+  "",
+].join("\n");
+
+const PROJECT_YAML = [
+  "apiVersion: tenancy.stigmer.ai/v1",
+  "kind: Project",
+  "metadata:",
+  "  name: stigmer-seedpack",
+  "  org: stigmer",
+  "spec:",
+  "  description: System seedpack",
+  "",
+].join("\n");
+
+// A seedpack fixture with just an org + the project manifest — enough to exercise
+// both apply phases (organizations via file mode, the project via the declarative
+// reconciler) without pulling in skill-push or MCP discovery.
+function makeContent(): SeedpackContent {
+  const dir = mkdtempSync(join(tmpdir(), "seedpack-apply-"));
+  writeFileSync(join(dir, "stigmer.yaml"), PROJECT_YAML);
+  mkdirSync(join(dir, "organizations"), { recursive: true });
+  writeFileSync(join(dir, "organizations", "stigmer.yaml"), ORG_YAML);
+  return { dir, source: "repo" };
+}
+
+// Records each applied message's proto type name; every controller resolves to
+// the same stub apply (the handlers only call `.apply`).
+function recordingDeps() {
+  const applied: string[] = [];
+  const controller = (() => ({
+    apply: async (m: Message) => {
+      applied.push((m as { $typeName: string }).$typeName);
+      return m;
+    },
+  })) as unknown as ControllerFn;
+  return {
+    applied,
+    deps: {
+      controller,
+      stigmer: {} as never,
+      info: () => {},
+      warn: () => {},
+    },
+  };
+}
+
+let content: SeedpackContent;
+let markerDir: string;
+beforeEach(() => {
+  content = makeContent();
+  markerDir = mkdtempSync(join(tmpdir(), "seedpack-marker-"));
+});
+afterEach(() => {
+  rmSync(content.dir, { recursive: true, force: true });
+  rmSync(markerDir, { recursive: true, force: true });
+});
+
+describe("resolveSeedpackOrg", () => {
+  const saved = process.env.STIGMER_SEEDPACK_ORG;
+  afterEach(() => {
+    if (saved === undefined) delete process.env.STIGMER_SEEDPACK_ORG;
+    else process.env.STIGMER_SEEDPACK_ORG = saved;
+  });
+
+  it("prefers explicit, then env var, then the default", () => {
+    delete process.env.STIGMER_SEEDPACK_ORG;
+    expect(resolveSeedpackOrg("acme")).toBe("acme");
+    expect(resolveSeedpackOrg()).toBe("stigmer");
+    process.env.STIGMER_SEEDPACK_ORG = "from-env";
+    expect(resolveSeedpackOrg()).toBe("from-env");
+    expect(resolveSeedpackOrg("explicit")).toBe("explicit");
+  });
+});
+
+describe("applySeedpack", () => {
+  it("applies the org and project, then writes the marker", async () => {
+    const { applied, deps } = recordingDeps();
+    const result = await applySeedpack(deps, { markerDir, content });
+
+    expect(result.applied).toBe(true);
+    expect(result.org).toBe("stigmer");
+    expect(applied.some((t) => t.endsWith("Organization"))).toBe(true);
+    expect(applied.some((t) => t.endsWith("Project"))).toBe(true);
+    expect(readMarker(markerDir)).toBe(result.hash);
+  });
+
+  it("is idempotent: a matching marker skips the backend entirely", async () => {
+    const { applied, deps } = recordingDeps();
+    await applySeedpack(deps, { markerDir, content });
+
+    const second = recordingDeps();
+    const result = await applySeedpack(second.deps, { markerDir, content });
+    expect(result.applied).toBe(false);
+    expect(second.applied).toHaveLength(0);
+    // The first run did touch the backend.
+    expect(applied.length).toBeGreaterThan(0);
+  });
+
+  it("re-applies when forced even if the marker matches", async () => {
+    const first = recordingDeps();
+    await applySeedpack(first.deps, { markerDir, content });
+
+    const forced = recordingDeps();
+    const result = await applySeedpack(forced.deps, { markerDir, content, force: true });
+    expect(result.applied).toBe(true);
+    expect(forced.applied.length).toBeGreaterThan(0);
+  });
+});
+
+describe("seedpackContentHash", () => {
+  it("hashes the provided content", () => {
+    expect(seedpackContentHash({ content })).toMatch(/^sha256:[0-9a-f]{16}$/);
+  });
+});
+
+// Regression guard for the credential-manifest bootstrap blocker: the *real*
+// seedpack content must pass cleanly through the declarative scanner. Every
+// staged file is a resource (carries a `kind`); any non-resource file (e.g. the
+// CI canary manifest) must live outside the content set, never beside the
+// McpServer YAMLs where `loadDocuments(strict)` would reject it for missing a
+// `kind`. The synthetic fixtures above can't catch this — only real content can.
+describe("real seedpack content loads through the declarative scanner", () => {
+  it("scans + builds apply items without a missing-kind error", () => {
+    const real = resolveSeedpackContent();
+    const stage = mkdtempSync(join(tmpdir(), "seedpack-real-"));
+    try {
+      extractSeedpack(real.dir, stage);
+
+      const files = scanResourceFiles(stage);
+      // The scan must reach mcp-servers/ — the directory that historically held
+      // the kind-less credential-manifest.yaml.
+      expect(files.some((f) => f.includes("mcp-servers"))).toBe(true);
+
+      // The throw site. Before the fix this raises "missing 'kind' field".
+      const items = buildDeclarativeItems(files, () => {});
+      expect(items.length).toBeGreaterThan(0);
+
+      const kinds = new Set(items.map((i) => (i.document as { kind?: string }).kind));
+      expect(kinds).toContain("McpServer");
+      expect(kinds).toContain("Agent");
+      expect(kinds).toContain("Workflow");
+    } finally {
+      rmSync(stage, { recursive: true, force: true });
+    }
+  });
+});

package/src/local/seedpack/apply.ts

@@ -0,0 +1,139 @@
+// In-process seedpack apply.
+//
+// The TS equivalent of Go's seedpackbootstrap.Apply, with one deliberate
+// improvement: instead of shelling out to `stigmer apply` as a subprocess, this
+// drives the same in-process declarative-apply path that `stigmer apply` uses —
+// one code path, no recursion guard, no second process.
+//
+// Two phases respect the resource hierarchy (mirrors the Go bootstrap):
+//   1. organizations/ via file mode — the org must exist before its members.
+//   2. the project (stigmer.yaml + agents/skills/mcp-servers/workflows) via the
+//      declarative reconciler, under the target org.
+//
+// Idempotent: a content-hash marker skips the apply when nothing changed.
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Stigmer } from "@stigmer/sdk";
+import { applyItem, resolveApplyItems } from "../../resources/apply/apply.js";
+import { applyDeclarative, detectTrack } from "../../resources/apply/declarative.js";
+import type { ControllerFn } from "../../resources/apply/handlers.js";
+import {
+  extractSeedpack,
+  hashSeedpackContent,
+  readMarker,
+  resolveSeedpackContent,
+  type SeedpackContent,
+  writeMarker,
+} from "./content.js";
+
+const DEFAULT_ORG = "stigmer";
+const ORG_ENV_VAR = "STIGMER_SEEDPACK_ORG";
+
+export interface SeedpackApplyDeps {
+  /** Raw command-controller accessor (full-proto apply, preserves metadata.id). */
+  readonly controller: ControllerFn;
+  /** High-level client for skill push + post-apply MCP discovery. */
+  readonly stigmer: Stigmer;
+  /** Human progress lines (stderr). */
+  readonly info: (line: string) => void;
+  /** Warnings (stderr). */
+  readonly warn: (line: string) => void;
+}
+
+export interface SeedpackApplyOptions {
+  /** Directory holding the idempotency marker (data dir for local, config dir for cloud). */
+  readonly markerDir: string;
+  /** Target org slug. Defaults to STIGMER_SEEDPACK_ORG, then "stigmer". */
+  readonly org?: string;
+  /** Re-apply even when the content hash is unchanged. */
+  readonly force?: boolean;
+  /** Pre-resolved content (injectable for tests); resolved on demand otherwise. */
+  readonly content?: SeedpackContent;
+  readonly home?: string;
+}
+
+export interface SeedpackApplyResult {
+  /** True when the seedpack was applied; false when skipped as up to date. */
+  readonly applied: boolean;
+  /** The current content hash (stored in the marker on a successful apply). */
+  readonly hash: string;
+  /** The resolved target org. */
+  readonly org: string;
+}
+
+/** Resolve the target org: explicit option > env var > "stigmer". */
+export function resolveSeedpackOrg(explicit?: string): string {
+  if (explicit !== undefined && explicit !== "") return explicit;
+  const env = process.env[ORG_ENV_VAR];
+  if (env !== undefined && env !== "") return env;
+  return DEFAULT_ORG;
+}
+
+/** Compute the current seedpack content hash without applying (drives `status`). */
+export function seedpackContentHash(opts: Pick<SeedpackApplyOptions, "content" | "home"> = {}): string {
+  const content = opts.content ?? resolveSeedpackContent({ home: opts.home });
+  return hashSeedpackContent(content.dir);
+}
+
+/**
+ * Apply the seedpack to the backend the deps connect to. Returns `applied:false`
+ * (without touching the backend) when the marker already matches the content
+ * hash and `force` is not set.
+ */
+export async function applySeedpack(deps: SeedpackApplyDeps, opts: SeedpackApplyOptions): Promise<SeedpackApplyResult> {
+  const org = resolveSeedpackOrg(opts.org);
+  const content = opts.content ?? resolveSeedpackContent({ home: opts.home });
+  const hash = hashSeedpackContent(content.dir);
+
+  if (opts.force !== true && readMarker(opts.markerDir) === hash) {
+    return { applied: false, hash, org };
+  }
+
+  deps.info("Applying system resources (seedpack)…");
+  const stage = mkdtempSync(join(tmpdir(), "stigmer-seedpack-"));
+  try {
+    extractSeedpack(content.dir, stage);
+    await applyOrganizations(deps, stage);
+    await applyProject(deps, stage, org);
+    writeMarker(opts.markerDir, hash);
+  } finally {
+    rmSync(stage, { recursive: true, force: true });
+  }
+
+  deps.info("System resources applied successfully");
+  return { applied: true, hash, org };
+}
+
+// Phase 1: organizations via file mode. Organizations sit above the project and
+// carry no org context themselves, so they apply with an empty org.
+async function applyOrganizations(deps: SeedpackApplyDeps, stageDir: string): Promise<void> {
+  const orgDir = join(stageDir, "organizations");
+  let items: ReturnType<typeof resolveApplyItems>;
+  try {
+    items = resolveApplyItems(orgDir);
+  } catch {
+    return; // No organizations to apply.
+  }
+  for (const item of items) {
+    const outcome = await applyItem(deps.controller, item, "", false);
+    if (outcome.warning !== undefined) deps.warn(outcome.warning);
+  }
+}
+
+// Phase 2: the project (agents, skills, MCP servers, workflows) via the shared
+// declarative reconciler — the same path `stigmer apply` runs for a user project.
+async function applyProject(deps: SeedpackApplyDeps, stageDir: string, org: string): Promise<void> {
+  const detect = detectTrack(stageDir);
+  if (detect.track !== "declarative") {
+    throw new Error(`seedpack is not a declarative project (detected '${detect.track}')`);
+  }
+  await applyDeclarative(detect, {
+    controller: deps.controller,
+    stigmer: deps.stigmer,
+    org,
+    info: deps.info,
+    warn: deps.warn,
+  });
+}

package/src/local/seedpack/content.test.ts

@@ -0,0 +1,148 @@
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { classify, ExitCode } from "../../errors/index.js";
+import {
+  acquireSeedpack,
+  extractSeedpack,
+  hashSeedpackContent,
+  listContentFiles,
+  readMarker,
+  resolveSeedpackContent,
+  SEEDPACK_ENTRIES,
+  writeMarker,
+} from "./content.js";
+
+// Build a minimal seedpack content tree with one non-canonical sibling (tools/)
+// to prove the canonical-entry filtering.
+function makeFixture(): string {
+  const dir = mkdtempSync(join(tmpdir(), "seedpack-content-"));
+  writeFileSync(join(dir, "stigmer.yaml"), "kind: Project\n");
+  mkdirSync(join(dir, "organizations"), { recursive: true });
+  writeFileSync(join(dir, "organizations", "stigmer.yaml"), "kind: Organization\n");
+  mkdirSync(join(dir, "skills", "demo"), { recursive: true });
+  writeFileSync(join(dir, "skills", "demo", "SKILL.md"), "---\nname: demo\n---\n");
+  mkdirSync(join(dir, "agents"), { recursive: true });
+  writeFileSync(join(dir, "agents", "a.yaml"), "kind: Agent\n");
+  // Non-canonical siblings that must never be hashed/extracted.
+  mkdirSync(join(dir, "tools"), { recursive: true });
+  writeFileSync(join(dir, "tools", "gen.sh"), "echo hi\n");
+  mkdirSync(join(dir, "icons"), { recursive: true });
+  writeFileSync(join(dir, "icons", "logo.svg"), "<svg/>\n");
+  return dir;
+}
+
+let fixture: string;
+beforeEach(() => {
+  fixture = makeFixture();
+});
+afterEach(() => {
+  rmSync(fixture, { recursive: true, force: true });
+});
+
+describe("listContentFiles", () => {
+  it("lists only canonical entries, lexically sorted", () => {
+    const files = listContentFiles(fixture);
+    expect(files).toEqual([
+      "agents/a.yaml",
+      "organizations/stigmer.yaml",
+      "skills/demo/SKILL.md",
+      "stigmer.yaml",
+    ]);
+    expect(files.some((f) => f.startsWith("tools/") || f.startsWith("icons/"))).toBe(false);
+  });
+});
+
+describe("hashSeedpackContent", () => {
+  it("is deterministic and sha256-prefixed", () => {
+    expect(hashSeedpackContent(fixture)).toBe(hashSeedpackContent(fixture));
+    expect(hashSeedpackContent(fixture)).toMatch(/^sha256:[0-9a-f]{16}$/);
+  });
+
+  it("changes when content changes but ignores non-canonical files", () => {
+    const before = hashSeedpackContent(fixture);
+    writeFileSync(join(fixture, "tools", "extra.sh"), "noise\n");
+    expect(hashSeedpackContent(fixture)).toBe(before);
+    writeFileSync(join(fixture, "agents", "b.yaml"), "kind: Agent\n");
+    expect(hashSeedpackContent(fixture)).not.toBe(before);
+  });
+});
+
+describe("extractSeedpack", () => {
+  it("copies only canonical entries and hashes identically to the source", () => {
+    const dest = mkdtempSync(join(tmpdir(), "seedpack-extract-"));
+    try {
+      extractSeedpack(fixture, dest);
+      for (const entry of readdirSync(dest)) {
+        expect(SEEDPACK_ENTRIES).toContain(entry as (typeof SEEDPACK_ENTRIES)[number]);
+      }
+      expect(existsSync(join(dest, "tools"))).toBe(false);
+      expect(hashSeedpackContent(dest)).toBe(hashSeedpackContent(fixture));
+    } finally {
+      rmSync(dest, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("marker", () => {
+  it("round-trips and returns null when absent", () => {
+    const dir = mkdtempSync(join(tmpdir(), "seedpack-marker-"));
+    try {
+      expect(readMarker(dir)).toBeNull();
+      writeMarker(dir, "sha256:abc123");
+      expect(readMarker(dir)).toBe("sha256:abc123");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("resolveSeedpackContent", () => {
+  it("uses the repo seedpack tree in dev", () => {
+    const content = resolveSeedpackContent();
+    expect(content.source).toBe("repo");
+    expect(existsSync(join(content.dir, "stigmer.yaml"))).toBe(true);
+  });
+
+  it("excludes the non-resource canary manifest from the content set", () => {
+    // The CI canary manifest has no `kind`; if it were staged it would break the
+    // declarative-apply bootstrap. It lives in canary/ (outside SEEDPACK_ENTRIES).
+    const files = listContentFiles(resolveSeedpackContent().dir);
+    expect(files.some((f) => f.startsWith("canary/"))).toBe(false);
+    expect(files.some((f) => f.endsWith("credential-manifest.yaml"))).toBe(false);
+  });
+});
+
+describe("acquireSeedpack", () => {
+  it("refuses a non-release (dev) build", () => {
+    const err = (() => {
+      try {
+        acquireSeedpack({ home: fixture, version: "0.0.0-dev" });
+      } catch (e) {
+        return e;
+      }
+    })();
+    expect(classify(err)?.exitCode).toBe(ExitCode.General);
+  });
+
+  it("installs on demand and is idempotent on the second call", () => {
+    const home = mkdtempSync(join(tmpdir(), "seedpack-home-"));
+    let installs = 0;
+    const install = (installDir: string) => {
+      installs += 1;
+      const pkgDir = join(installDir, "node_modules", "@stigmer", "seedpack");
+      mkdirSync(pkgDir, { recursive: true });
+      writeFileSync(join(pkgDir, "stigmer.yaml"), "kind: Project\n");
+    };
+    try {
+      const dir1 = acquireSeedpack({ home, version: "1.2.3", install });
+      const dir2 = acquireSeedpack({ home, version: "1.2.3", install });
+      expect(dir1).toBe(dir2);
+      expect(existsSync(join(dir1, "stigmer.yaml"))).toBe(true);
+      expect(installs).toBe(1);
+    } finally {
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+});