@celilo/cli 0.11.0-alpha.0 → 0.12.0

package/src/manifest/schema.ts

@@ -214,7 +214,7 @@ export const EnsureSchema = z.object({
 export type Ensure = z.infer<typeof EnsureSchema>;
 
 /**
- * A computed capability field (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md D1).
+ * A computed capability field (openspec/specs/internal-dns-split-horizon/spec.md D1).
  *
  * Declared alongside `data`, but derived ON ACCESS from other values via the
  * `value:` DSL (see src/variables/computed/) and never persisted. The result
@@ -275,7 +275,7 @@ export const LifecycleHookSchema = z.object({
 /**
  * Build-bus upstream-publish hook. Fires when a publish event lands
  * on the local event bus from the receiver daemon
- * ([[v2/BUILD_BUS.md]] Phase 4). Each module can declare multiple
+ * ([[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4). Each module can declare multiple
  * entries, each with its own match rule + action script.
  *
  * The action script runs with `CELILO_EVENT_PAYLOAD` in its env (the
@@ -326,7 +326,7 @@ export const SystemResourceSchema = z.object({
 });
 
 /**
- * One system a module deploys (v2/MODULE_SYSTEMS_ADDRESSING.md). A module
+ * One system a module deploys (openspec/specs/module-systems-addressing/spec.md). A module
  * declares 0..N of these under `requires.systems`. `name` is the stable
  * authoring-time handle — referenced in templates via `$infra:<name>.…` and the
  * per-system key in `module_systems`. `resources` carries the per-system machine
@@ -390,7 +390,7 @@ export const ModuleSubscriptionSchema = z
     handler: z.string().min(1).optional(),
     /**
      * Name of one of THIS module's own hooks to invoke when a matching event
-     * fires (v2/EVENT_DRIVEN_HOOK_SUBSCRIPTIONS.md). The framework synthesizes
+     * fires (openspec/specs/event-driven-hook-subscriptions/spec.md). The framework synthesizes
      * a `celilo events run-hook` handler that runs the hook in a
      * fault-isolated subprocess with backend access (DB, capabilities,
      * secrets). Mutually exclusive with `handler`.
@@ -445,7 +445,7 @@ export const ModuleManifestSchema = z
 
     /**
      * How `manifest.yml#version` (the PAYLOAD version) is determined — see
-     * v2/MODULE_VERSIONING.md / ISS-0151. The capability *contract* version
+     * openspec/changes/module-version-semantics/proposal.md / ISS-0151. The capability *contract* version
      * lives in `provides.capabilities[].version` and is unrelated to this.
      *
      * - `changeset` — first-party apps/content (lunacycle): the version is
@@ -471,7 +471,7 @@ export const ModuleManifestSchema = z
       .object({
         capabilities: z.array(CapabilityRequirementSchema).default([]),
         /**
-         * The 0..N systems this module deploys (v2/MODULE_SYSTEMS_ADDRESSING.md).
+         * The 0..N systems this module deploys (openspec/specs/module-systems-addressing/spec.md).
          * Preferred over the singular `system`. A module declaring
          * `systems` gets one host per entry, each addressable as `$infra:<name>`.
          */
@@ -545,7 +545,7 @@ export const ModuleManifestSchema = z
          * to (de)register a single host's A records when celilo's bridge
          * delivers a system.created/destroyed event. Inputs (hostname,
          * target_ip, op) come from the contract — see contracts/v1.ts and
-         * [[v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md]] D5.
+         * [[openspec/specs/internal-dns-split-horizon/spec.md]] D5.
          */
         on_system_event: LifecycleHookSchema.optional(),
         /**
@@ -553,7 +553,7 @@ export const ModuleManifestSchema = z
          * change event. The caddy `public_web` provider declares this to
          * re-render its Caddyfile from web_routes when a consumer registers or
          * unregisters a route (ISS-0035). See
-         * [[v2/PUBLIC_WEB_PROVIDER_RECONCILE.md]].
+         * [[openspec/specs/public-web-provider-reconcile/spec.md]].
          */
         reconcile_routes: LifecycleHookSchema.optional(),
         /**
@@ -569,7 +569,7 @@ export const ModuleManifestSchema = z
         /**
          * Build-bus upstream publish hooks. Array (a module can react
          * to multiple upstream packages with different actions). See
-         * [[v2/BUILD_BUS.md]] Phase 4.
+         * [[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4.
          */
         on_upstream_publish: z.array(UpstreamPublishHookSchema).optional(),
       })
@@ -645,7 +645,7 @@ export const ModuleManifestSchema = z
 
     /**
      * Event-bus subscriptions this module wants registered. See
-     * `infra/design/SQLITE_EVENT_BUS.md`. Truly optional so existing
+     * `infra/openspec/specs/event-bus/spec.md`. Truly optional so existing
      * test fixtures and manifests don't need a churn-pass; readers
      * use `manifest.subscriptions ?? []`.
      */
@@ -654,7 +654,7 @@ export const ModuleManifestSchema = z
     /**
      * Optional base-module aspect — lightweight fleet-configuration
      * code applied to OTHER systems in declared zones, on top of
-     * the module's primary deployment. See v2/CELILO_BASE.md.
+     * the module's primary deployment. See openspec/specs/base-module-aspects/spec.md.
      *
      * Modules without this block work exactly as today. When
      * declared, the operator approves the aspect's scope at
@@ -723,7 +723,7 @@ export const ModuleManifestSchema = z
         ansible_vars: z.record(z.string(), z.string()).optional(),
 
         /**
-         * Optional Proxmox reconciliation (v2/CELILO_BASE.md D5).
+         * Optional Proxmox reconciliation (openspec/specs/base-module-aspects/spec.md D5).
          *
          * When an aspect manages a setting that Proxmox also owns
          * authoritatively (DNS resolver via `proxmox_lxc.nameserver`
@@ -779,7 +779,7 @@ export type BaseModuleAspect = NonNullable<ModuleManifest['base_module_aspect']>
 export type BaseModuleAspectTrigger = BaseModuleAspect['triggers'][number];
 
 /**
- * Normalize a manifest's declared systems (v2/MODULE_SYSTEMS_ADDRESSING.md).
+ * Normalize a manifest's declared systems (openspec/specs/module-systems-addressing/spec.md).
  * Returns `requires.systems` if present; else the singular `requires.system`
  * as one entry named `main`; else `[]` (config-only module like namecheap).
  * This is the single place the system→systems sugar lives, so the rest of the

package/src/manifest/template-validator.ts

@@ -72,7 +72,7 @@ const AUTO_ALLOCATED_VARIABLES = new Set([
   'vlan', // Auto-derived from zone configuration
   'gateway', // Auto-derived from zone configuration
   'target_node', // Can be auto-derived from system config
-  'lxc_nameserver', // Composed at generate time from dns_internal + dns.primary (v2/LXC_INTERNAL_DNS.md)
+  'lxc_nameserver', // Composed at generate time from dns_internal + dns.primary (openspec/specs/lxc-dns-at-birth/spec.md)
   // Instance sizing (ISS-0150): the instance Terraform reads $self:{cores,memory,
   // disk,storage}, which are injected during resolution from the module_systems
   // table (falling back to requires.system.*) — see variables/context.ts. Like

package/src/module/packaging/build.ts

@@ -10,6 +10,7 @@ import { validateModuleDirectory } from '../import';
 import { computeFileChecksum } from './checksum';
 import { includeNodeModulesPath } from './package-rules';
 import { signChecksums } from './signature';
+import { rewriteWorkspaceDeps } from './workspace-deps';
 
 /**
  * Checksums data structure
@@ -222,6 +223,24 @@ export async function buildModule(options: ModuleBuildOptions): Promise<ModuleBu
     const manifest = parseYaml(manifestContent);
     if (manifest.build?.command || manifest.build?.script) {
       log.info(`Building module (${manifest.build.command ? 'command' : 'script'})...`);
+
+      // Resolve `workspace:` build deps (ISS-0147 / celilo#216). The staged
+      // buildDir has no workspace root, so a sibling monorepo package pulled in
+      // via `workspace:^` won't resolve during the build's `bun install`.
+      // Rewrite those specs to `file:` paths pointing at the live monorepo
+      // members — always-fresh, no npm-pin lag, no hand-rolled
+      // CELILO_MODULE_SOURCE_DIR dance. Fails loudly naming any unresolvable dep.
+      try {
+        for (const rewrite of rewriteWorkspaceDeps(buildDir, sourceDir)) {
+          log.info(`Resolved workspace dep: ${rewrite}`);
+        }
+      } catch (rewriteError) {
+        return {
+          success: false,
+          error: rewriteError instanceof Error ? rewriteError.message : String(rewriteError),
+        };
+      }
+
       // The build runs in a staged copy of the module (buildDir), so
       // relative paths that reach outside the module (e.g. sibling packages
       // in a monorepo) don't resolve. Expose the ORIGINAL unstaged source

package/src/module/packaging/workspace-deps.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Packager resolves `workspace:` build deps in an isolated staging dir by
+ * rewriting them to `file:` paths pointing at the live monorepo member
+ * (ISS-0147 / celilo#216).
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { rewriteWorkspaceDeps } from './workspace-deps';
+
+describe('rewriteWorkspaceDeps', () => {
+  let repo: string; // fake monorepo root
+  let sourceDir: string; // module source under the monorepo
+  let buildDir: string; // isolated staging copy
+
+  function write(base: string, rel: string, obj: unknown): void {
+    const full = join(base, rel);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, typeof obj === 'string' ? obj : JSON.stringify(obj, null, 2));
+  }
+
+  beforeEach(() => {
+    repo = mkdtempSync(join(tmpdir(), 'celilo-ws-repo-'));
+    // Monorepo root with workspace globs mirroring the real repo.
+    write(repo, 'package.json', {
+      name: 'infra',
+      private: true,
+      workspaces: ['packages/*', 'modules/*/site'],
+    });
+    // A sibling workspace package.
+    write(repo, 'packages/visualizer/package.json', {
+      name: '@celilo/visualizer',
+      version: '0.1.0',
+    });
+    sourceDir = join(repo, 'modules/website');
+    mkdirSync(sourceDir, { recursive: true });
+
+    // Isolated staging copy of the module (what the packager builds in).
+    buildDir = mkdtempSync(join(tmpdir(), 'celilo-ws-stage-'));
+    write(buildDir, 'site/package.json', {
+      name: 'website',
+      dependencies: { '@celilo/visualizer': 'workspace:^', astro: '^5.7.0' },
+    });
+  });
+
+  afterEach(() => {
+    for (const d of [repo, buildDir]) {
+      try {
+        rmSync(d, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    }
+  });
+
+  it('rewrites a workspace: spec to a file: path at the live member', () => {
+    const rewrites = rewriteWorkspaceDeps(buildDir, sourceDir);
+
+    const pkg = JSON.parse(readFileSync(join(buildDir, 'site/package.json'), 'utf-8'));
+    expect(pkg.dependencies['@celilo/visualizer']).toBe(
+      `file:${join(repo, 'packages/visualizer')}`,
+    );
+    // Non-workspace deps untouched.
+    expect(pkg.dependencies.astro).toBe('^5.7.0');
+    expect(rewrites).toHaveLength(1);
+  });
+
+  it('is a no-op when there are no workspace deps', () => {
+    write(buildDir, 'site/package.json', {
+      name: 'website',
+      dependencies: { astro: '^5.7.0' },
+    });
+    expect(rewriteWorkspaceDeps(buildDir, sourceDir)).toEqual([]);
+  });
+
+  it('fails loudly naming an unresolvable workspace dep', () => {
+    write(buildDir, 'site/package.json', {
+      name: 'website',
+      dependencies: { '@celilo/ghost': 'workspace:*' },
+    });
+    expect(() => rewriteWorkspaceDeps(buildDir, sourceDir)).toThrow(/@celilo\/ghost/);
+  });
+
+  it('handles the workspaces:{packages:[]} object form', () => {
+    write(repo, 'package.json', {
+      name: 'infra',
+      workspaces: { packages: ['packages/*', 'modules/*/site'] },
+    });
+    const rewrites = rewriteWorkspaceDeps(buildDir, sourceDir);
+    expect(rewrites).toHaveLength(1);
+  });
+});

package/src/module/packaging/workspace-deps.ts

@@ -0,0 +1,185 @@
+/**
+ * Resolve bun `workspace:` protocol build deps in an isolated staging build
+ * (ISS-0147 / celilo#216).
+ *
+ * `celilo package <module>` stages the module into an isolated temp dir and
+ * runs the manifest `build:` there. A module whose build depends on a sibling
+ * monorepo package via `workspace:` (e.g. celilo-website's site/package.json
+ * `@celilo/visualizer: workspace:^`) then fails: the staging dir has no
+ * workspace root, so `bun install` errors with "Workspace dependency not
+ * found".
+ *
+ * Fix: before the staged build runs, rewrite every `workspace:` spec in the
+ * staged package.json files to a `file:<abs path>` pointing at the live
+ * monorepo member. bun installs local path deps from the current source — so
+ * the bundle reflects the CURRENT workspace version, never a stale published
+ * one (unlike an npm pin). No hand-rolled CELILO_MODULE_SOURCE_DIR dance.
+ */
+
+import { type Dirent, existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+const DEP_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+] as const;
+
+interface WorkspaceInfo {
+  root: string;
+  /** package name -> absolute member directory */
+  members: Map<string, string>;
+}
+
+/**
+ * Walk up from `startDir` to find the monorepo root — the nearest ancestor
+ * package.json declaring a `workspaces` field — and map every member package
+ * name to its absolute directory. Returns null if no workspace root exists.
+ */
+function findWorkspaceRoot(startDir: string): WorkspaceInfo | null {
+  let dir = resolve(startDir);
+  for (;;) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      const patterns = readWorkspacePatterns(pkgPath);
+      if (patterns) {
+        return { root: dir, members: collectMembers(dir, patterns) };
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function readWorkspacePatterns(pkgPath: string): string[] | null {
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    // npm/bun accept both `workspaces: [...]` and `workspaces: { packages: [...] }`.
+    if (Array.isArray(pkg.workspaces)) return pkg.workspaces;
+    if (Array.isArray(pkg.workspaces?.packages)) return pkg.workspaces.packages;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function collectMembers(root: string, patterns: string[]): Map<string, string> {
+  const members = new Map<string, string>();
+  for (const pattern of patterns) {
+    for (const memberDir of expandGlob(root, pattern)) {
+      const pkgPath = join(memberDir, 'package.json');
+      if (!existsSync(pkgPath)) continue;
+      try {
+        const name = JSON.parse(readFileSync(pkgPath, 'utf-8')).name;
+        if (typeof name === 'string' && name.length > 0) members.set(name, memberDir);
+      } catch {
+        /* member without a valid package.json — skip */
+      }
+    }
+  }
+  return members;
+}
+
+/**
+ * Expand a workspace glob against `root`. Supports only the single `*`
+ * per-segment wildcard bun/npm workspace patterns actually use (e.g.
+ * "packages/[star]" or "modules/[star]/site"). ponytail: no globstar/brace
+ * support — no workspace config uses them; add if one ever does.
+ */
+function expandGlob(root: string, pattern: string): string[] {
+  let dirs = [root];
+  for (const segment of pattern.split('/')) {
+    const next: string[] = [];
+    for (const dir of dirs) {
+      if (segment === '*') {
+        let entries: Dirent[];
+        try {
+          entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+          continue;
+        }
+        for (const entry of entries) {
+          if (entry.isDirectory()) next.push(join(dir, entry.name));
+        }
+      } else {
+        const candidate = join(dir, segment);
+        if (existsSync(candidate)) next.push(candidate);
+      }
+    }
+    dirs = next;
+  }
+  return dirs;
+}
+
+function findPackageJsonFiles(dir: string): string[] {
+  const found: string[] = [];
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      found.push(...findPackageJsonFiles(full));
+    } else if (entry.name === 'package.json') {
+      found.push(full);
+    }
+  }
+  return found;
+}
+
+/**
+ * Rewrite every `workspace:` dep in the staged build dir's package.json files
+ * to a `file:` path pointing at the live monorepo member.
+ *
+ * @param buildDir - isolated staging dir being built
+ * @param sourceDir - original (unstaged) module dir, used to locate the monorepo root
+ * @returns human-readable list of rewrites performed (for logging)
+ * @throws if a `workspace:` dep can't be resolved to a monorepo member —
+ *   loud failure naming the offending dep, never a cryptic downstream error.
+ */
+export function rewriteWorkspaceDeps(buildDir: string, sourceDir: string): string[] {
+  const rewrites: string[] = [];
+  let workspace: WorkspaceInfo | null | undefined;
+
+  for (const pkgPath of findPackageJsonFiles(buildDir)) {
+    let pkg: Record<string, unknown>;
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    } catch {
+      continue;
+    }
+
+    let changed = false;
+    for (const field of DEP_FIELDS) {
+      const deps = pkg[field];
+      if (!deps || typeof deps !== 'object') continue;
+      for (const [name, spec] of Object.entries(deps as Record<string, unknown>)) {
+        if (typeof spec !== 'string' || !spec.startsWith('workspace:')) continue;
+
+        // Lazily locate the workspace root only once a workspace dep exists.
+        if (workspace === undefined) workspace = findWorkspaceRoot(sourceDir);
+        const memberDir = workspace?.members.get(name);
+        if (!memberDir) {
+          throw new Error(
+            `Module build depends on workspace package "${name}" (${field}: "${spec}"), ` +
+              `but it could not be resolved to a monorepo member from ${sourceDir}.\n` +
+              `Ensure "${name}" is a workspace member, or replace the "workspace:" spec with a published version range.`,
+          );
+        }
+        (deps as Record<string, string>)[name] = `file:${memberDir}`;
+        rewrites.push(`${name}: ${spec} -> file:${memberDir}`);
+        changed = true;
+      }
+    }
+
+    if (changed) writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+  }
+
+  return rewrites;
+}

package/src/module/versioning/changeset-version.ts

@@ -1,5 +1,5 @@
 /**
- * Changeset-driven module versioning (ISS-0151 / v2/MODULE_VERSIONING.md).
+ * Changeset-driven module versioning (ISS-0151 / openspec/changes/module-version-semantics/proposal.md).
  *
  * For `version_source: { kind: changeset }` modules, the payload version is
  * authored via `.changeset/*.md` files — the same on-disk format the changesets

package/src/policy/no-hand-built-ssh.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Recurrence gate for openspec/changes/unified-management-no-ssh/proposal.md: **modules never hand-build SSH.**
+ *
+ * Module hooks reach a remote box through the typed primitives in
+ * `@celilo/capabilities` (probe / serviceCtl / applyRenderedConfig / … — see
+ * apps/celilo/MODULE_PRIMITIVES.md), never a raw `ssh root@…` string, `ssh2`, or
+ * an ad-hoc `child_process` shell-out. This test scans every production module
+ * script and fails if a banned pattern reappears, so the SSH-elimination work
+ * can't silently erode.
+ *
+ * Precise on purpose: `noRestrictedImports` can't see raw ssh *strings* (the real
+ * risk). We ban the SSH shapes themselves — an `ssh root@…` string catches
+ * hand-built SSH however it's invoked (child_process, execSync, or the Runner),
+ * and `ssh2` catches the library route. We do NOT ban `child_process` outright:
+ * many modules' on_install legitimately shell LOCAL `celilo`/system commands
+ * (`celilo system apply-config`), which isn't remote SSH.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/** Walk up from this test to the repo root (the dir holding both modules/ and apps/). */
+function repoRoot(): string {
+  let dir = import.meta.dir;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'modules')) && existsSync(join(dir, 'apps'))) return dir;
+    dir = resolve(dir, '..');
+  }
+  throw new Error('could not locate repo root (no ancestor with modules/ + apps/)');
+}
+
+/** Every production `.ts` under modules/<m>/scripts/ (excludes node_modules + tests). */
+function moduleScripts(): string[] {
+  const modulesRoot = join(repoRoot(), 'modules');
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      if (entry === 'node_modules') continue;
+      const p = join(dir, entry);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (p.endsWith('.ts') && !p.endsWith('.test.ts')) out.push(p);
+    }
+  };
+  for (const mod of readdirSync(modulesRoot)) {
+    const scripts = join(modulesRoot, mod, 'scripts');
+    if (existsSync(scripts) && statSync(scripts).isDirectory()) walk(scripts);
+  }
+  return out;
+}
+
+const BANNED = [
+  {
+    name: 'raw ssh invocation (StrictHostKeyChecking)',
+    re: /StrictHostKeyChecking/,
+    hint: 'Use a remote-ops primitive (remoteExec/probe/serviceCtl/…). See MODULE_PRIMITIVES.md.',
+  },
+  {
+    name: 'raw ssh invocation (ssh … root@)',
+    re: /\bssh\s+(?:-\S+\s+|\S*root@)/,
+    hint: 'Use a remote-ops primitive, not a hand-built ssh string. See MODULE_PRIMITIVES.md.',
+  },
+  {
+    name: "'ssh2' import",
+    re: /(?:from|require\()\s*['"]ssh2['"]/,
+    hint: 'Modules never open their own SSH connection — use the primitives. See MODULE_PRIMITIVES.md.',
+  },
+];
+
+describe('recurrence gate: modules never hand-build SSH', () => {
+  const scripts = moduleScripts();
+
+  test('scans a non-trivial set of module scripts (sanity — the scan actually ran)', () => {
+    expect(scripts.length).toBeGreaterThan(10);
+  });
+
+  test('no production module script hand-builds SSH (ssh string / ssh2)', () => {
+    const violations: string[] = [];
+    for (const file of scripts) {
+      const src = readFileSync(file, 'utf-8');
+      for (const b of BANNED) {
+        if (b.re.test(src)) violations.push(`${file}\n    → ${b.name}. ${b.hint}`);
+      }
+    }
+    expect(
+      violations,
+      `Hand-built SSH found in module scripts:\n  ${violations.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});

package/src/registry/client.test.ts

@@ -226,3 +226,89 @@ describe('RegistryClient.publish — Cargo binary protocol', () => {
     ).rejects.toThrow('token invalid');
   });
 });
+
+// ── module-owner admin endpoints (ce-1ch) ─────────────────────────────────────
+
+describe('RegistryClient owner methods', () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = spyOn(globalThis, 'fetch');
+  });
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  test('listOwners GETs /owners with the admin token and returns the array', async () => {
+    const owners = [
+      {
+        moduleName: 'homebridge',
+        ownerSub: 'alice',
+        claimedAt: 'T',
+        sourceGroup: 'celilo-authors',
+      },
+    ];
+    fetchSpy.mockResolvedValue(new Response(JSON.stringify({ owners }), { status: 200 }));
+    const client = new RegistryClient('https://reg.example.com');
+    const result = await client.listOwners('admin-tok');
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('https://reg.example.com/api/v1/modules/owners');
+    expect((init.headers as Record<string, string>).Authorization).toBe('admin-tok');
+    expect(result).toEqual(owners);
+  });
+
+  test('listOwners throws the server error detail on failure', async () => {
+    fetchSpy.mockResolvedValue(
+      new Response(JSON.stringify({ errors: [{ detail: 'Unauthorized' }] }), { status: 401 }),
+    );
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.listOwners('nope')).rejects.toThrow('Unauthorized');
+  });
+
+  test('getOwner returns null on 404 (unclaimed)', async () => {
+    fetchSpy.mockResolvedValue(new Response(null, { status: 404 }));
+    const client = new RegistryClient('https://reg.example.com');
+    expect(await client.getOwner('never-claimed', 'admin-tok')).toBeNull();
+  });
+
+  test('getOwner returns the owner entry on 200', async () => {
+    const owner = {
+      moduleName: 'caddy',
+      ownerSub: 'bob',
+      claimedAt: 'T',
+      sourceGroup: 'celilo-admins',
+    };
+    fetchSpy.mockResolvedValue(new Response(JSON.stringify({ owner }), { status: 200 }));
+    const client = new RegistryClient('https://reg.example.com');
+    expect(await client.getOwner('caddy', 'admin-tok')).toEqual(owner);
+  });
+
+  test('setOwner POSTs ownerSub and returns the updated entry', async () => {
+    const owner = {
+      moduleName: 'homebridge',
+      ownerSub: 'carol',
+      claimedAt: 'T',
+      sourceGroup: 'admin-reassign',
+    };
+    fetchSpy.mockResolvedValue(new Response(JSON.stringify({ ok: true, owner }), { status: 200 }));
+    const client = new RegistryClient('https://reg.example.com');
+    const result = await client.setOwner('homebridge', 'carol', 'admin-tok');
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('https://reg.example.com/api/v1/modules/owners/homebridge');
+    expect(init.method).toBe('POST');
+    expect(JSON.parse(init.body as string)).toEqual({ ownerSub: 'carol' });
+    expect(result).toEqual(owner);
+  });
+
+  test('setOwner throws the server error detail on failure', async () => {
+    fetchSpy.mockResolvedValue(
+      new Response(JSON.stringify({ errors: [{ detail: 'ownerSub is required' }] }), {
+        status: 400,
+      }),
+    );
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.setOwner('homebridge', '', 'admin-tok')).rejects.toThrow(
+      'ownerSub is required',
+    );
+  });
+});