@wildo-ai/wildo-module-client 1.1.1

package/src/services/registry-server-client.ts

@@ -0,0 +1,334 @@
+/**
+ * `RegistryServerClient` — HTTP client for the central registry
+ * server (`platform-module-registry`, KD-7).
+ *
+ * Phase 2 fills out the read + download surface (`resolve`,
+ * `info`, `search`, `download`). The wire shapes mirror the
+ * gateway endpoints documented in the analysis plan's "Registry
+ * HTTP API" section. The actual server (Phase 3) ships these
+ * routes; until it does, the client throws typed errors when it
+ * can't reach the server.
+ *
+ * Auth (KD-11): if `authToken` is supplied, every request adds
+ * `Authorization: Bearer <token>`. Public read paths work without
+ * a token; restricted paths return 401/403, surfaced as
+ * `RegistryAuthRequiredError` / `RegistryAuthForbiddenError`.
+ */
+
+import { z } from 'zod';
+import { formatZodIssuesAsSingleLine } from './_zod-issue-formatting';
+import {
+  ModuleManifestSchema,
+  ModuleVersionRecordSchema,
+  RegistryArtifactIntegrityMismatchError,
+  RegistryAuthForbiddenError,
+  RegistryAuthRequiredError,
+  RegistryError,
+  RegistryMalformedPayloadError,
+  RegistryModuleNotFoundError,
+  RegistryUnexpectedStatusError,
+  RegistryVersionNotFoundError,
+  Sha256DigestSchema,
+  type ModuleManifest,
+  type ModuleVersionRecord,
+} from '@wildo-ai/platform-config-lib';
+import { fetchJsonOk, fetchWithTimeout, joinUrl } from './_http-client';
+
+/**
+ * Zod schema for the `info()` response payload — mirrors
+ * `RegistryInfoResult` and is enforced at the client boundary so a
+ * server schema drift fails fast instead of returning malformed data
+ * to downstream consumers.
+ */
+const RegistryInfoResponseSchema = z.object({
+  moduleId: z.string().min(1),
+  manifest: ModuleManifestSchema,
+  versions: z.array(ModuleVersionRecordSchema),
+  tags: z.record(z.string(), z.string()),
+});
+
+const RegistrySearchResponseSchema = z.object({
+  hits: z.array(
+    z.object({
+      moduleId: z.string().min(1),
+      description: z.string().optional(),
+      latestVersion: z.string(),
+    }),
+  ),
+});
+
+const DIAGNOSTIC_LABEL = 'Registry';
+
+export interface RegistryServerClientOptions {
+  /** Registry origin (e.g. `https://registry.wildo.ai`). */
+  baseUrl: string;
+  /** Optional bearer / API-key. CLI credentials are per-machine (KD-11). */
+  authToken?: string;
+  /** Request timeout in ms. */
+  timeoutMs?: number;
+}
+
+function authHeaders(options: RegistryServerClientOptions): Record<string, string> {
+  return options.authToken ? { Authorization: `Bearer ${options.authToken}` } : {};
+}
+
+async function classifyAuthError(res: Response, registryUrl: string, action: string): Promise<RegistryError | null> {
+  if (res.status === 401) return new RegistryAuthRequiredError(registryUrl);
+  if (res.status === 403) return new RegistryAuthForbiddenError(action);
+  return null;
+}
+
+/**
+ * 6th-pass M3: typed JSON-parse helper. A misconfigured proxy that
+ * returns HTML at 2xx (or a truncated stream) would otherwise throw a
+ * bare `SyntaxError` from `await res.json()`, bypassing every
+ * `isRegistryError(err)` handler. This helper translates the parse
+ * failure into a `RegistryMalformedPayloadError` so the typed-error
+ * contract is universal across the client surface.
+ */
+async function parseJsonOrThrow(
+  res: Response,
+  registryUrl: string,
+  action: string,
+): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch (err) {
+    throw new RegistryMalformedPayloadError(
+      registryUrl,
+      action,
+      `response is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export interface RegistryResolveResult {
+  /** Resolved exact version (matches `Sha256DigestSchema` for digest). */
+  version: string;
+  artifactDigest: string;
+}
+
+export interface RegistryInfoResult {
+  moduleId: string;
+  manifest: ModuleManifest;
+  versions: readonly ModuleVersionRecord[];
+  /** dist-tag → version map (e.g. `latest → 1.2.3`). */
+  tags: Readonly<Record<string, string>>;
+}
+
+export interface RegistrySearchHit {
+  moduleId: string;
+  description?: string;
+  latestVersion: string;
+}
+
+export const RegistryServerClient = {
+  /**
+   * Liveness probe against `/health`. Returns boolean — used by
+   * `wildo registry ping` smoke. The registry server now relies on
+   * the framework's auto-mounted `HealthController` at the engine
+   * root (`GET /health` always 200; `GET /health/ready` enforces
+   * dependency readiness), so the path has NO `/v1` prefix.
+   */
+  async ping(options: RegistryServerClientOptions): Promise<boolean> {
+    try {
+      await fetchJsonOk(joinUrl(options.baseUrl, '/health'), {
+        method: 'GET',
+        timeoutMs: options.timeoutMs,
+        diagnosticLabel: DIAGNOSTIC_LABEL,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Resolve a semver range / tag against a registry domain. The
+   * server returns the concrete version + artifact digest so the
+   * caller can verify the download against `artifactDigest`.
+   */
+  async resolve(
+    options: RegistryServerClientOptions,
+    args: { domain: string; moduleId: string; range: string },
+  ): Promise<RegistryResolveResult> {
+    const url = joinUrl(
+      options.baseUrl,
+      `/v1/registry/${encodeURIComponent(args.domain)}/modules/${encodeURIComponent(args.moduleId)}/resolve?range=${encodeURIComponent(args.range)}`,
+    );
+    const res = await fetchWithTimeout(url, {
+      method: 'GET',
+      headers: authHeaders(options),
+      timeoutMs: options.timeoutMs,
+      diagnosticLabel: DIAGNOSTIC_LABEL,
+    });
+    if (res.status === 404) {
+      throw new RegistryVersionNotFoundError(args.moduleId, args.range);
+    }
+    const authErr = await classifyAuthError(res, options.baseUrl, `resolve ${args.moduleId}`);
+    if (authErr) throw authErr;
+    if (!res.ok) {
+      throw new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, `resolve ${args.moduleId}`);
+    }
+    // 6th-pass M3: typed JSON-parse (was bare `SyntaxError` for
+    // malformed proxy responses).
+    const json = (await parseJsonOrThrow(res, options.baseUrl, `resolve ${args.moduleId}`)) as {
+      version?: unknown;
+      artifactDigest?: unknown;
+    };
+    const digest = String(json.artifactDigest ?? '');
+    // 6th-pass M4: typed digest validation (was bare `ZodError`).
+    const digestParse = Sha256DigestSchema.safeParse(digest);
+    if (!digestParse.success) {
+      throw new RegistryMalformedPayloadError(
+        options.baseUrl,
+        `resolve ${args.moduleId}`,
+        `artifactDigest is not a valid sha256:<64-hex> string: ${formatZodIssuesAsSingleLine(digestParse.error)}`,
+      );
+    }
+    if (typeof json.version !== 'string' || json.version.length === 0) {
+      // 3rd-pass M6: typed `RegistryMalformedPayloadError` instead of
+      // bare `Error` so callers' `isRegistryError(err)` handlers fire
+      // correctly.
+      throw new RegistryMalformedPayloadError(
+        options.baseUrl,
+        `resolve ${args.moduleId}`,
+        'response missing required `version` string',
+      );
+    }
+    return { version: json.version, artifactDigest: digest };
+  },
+
+  /**
+   * Fetch full info for a module: manifest, every published
+   * version, dist-tags. Used by `wildo registry info` (Phase 4).
+   */
+  async info(
+    options: RegistryServerClientOptions,
+    args: { domain: string; moduleId: string },
+  ): Promise<RegistryInfoResult> {
+    const url = joinUrl(
+      options.baseUrl,
+      `/v1/registry/${encodeURIComponent(args.domain)}/modules/${encodeURIComponent(args.moduleId)}`,
+    );
+    const res = await fetchWithTimeout(url, {
+      method: 'GET',
+      headers: authHeaders(options),
+      timeoutMs: options.timeoutMs,
+      diagnosticLabel: DIAGNOSTIC_LABEL,
+    });
+    if (res.status === 404) throw new RegistryModuleNotFoundError(args.moduleId);
+    const authErr = await classifyAuthError(res, options.baseUrl, `info ${args.moduleId}`);
+    if (authErr) throw authErr;
+    if (!res.ok) {
+      throw new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, `info ${args.moduleId}`);
+    }
+    // 6th-pass M3: typed JSON-parse.
+    const json = await parseJsonOrThrow(res, options.baseUrl, `info ${args.moduleId}`);
+    const parsed = RegistryInfoResponseSchema.safeParse(json);
+    if (!parsed.success) {
+      throw new RegistryMalformedPayloadError(
+        options.baseUrl,
+        `info ${args.moduleId}`,
+        formatZodIssuesAsSingleLine(parsed.error),
+      );
+    }
+    return parsed.data;
+  },
+
+  /**
+   * Search the registry's metadata index. The shape is
+   * intentionally narrow until Phase 4 designs the search UX.
+   */
+  async search(
+    options: RegistryServerClientOptions,
+    args: { domain: string; query: string },
+  ): Promise<readonly RegistrySearchHit[]> {
+    const url = joinUrl(
+      options.baseUrl,
+      `/v1/registry/${encodeURIComponent(args.domain)}/modules?q=${encodeURIComponent(args.query)}`,
+    );
+    const res = await fetchWithTimeout(url, {
+      method: 'GET',
+      headers: authHeaders(options),
+      timeoutMs: options.timeoutMs,
+      diagnosticLabel: DIAGNOSTIC_LABEL,
+    });
+    const authErr = await classifyAuthError(res, options.baseUrl, `search`);
+    if (authErr) throw authErr;
+    if (!res.ok) {
+      throw new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, 'search');
+    }
+    // 6th-pass M3: typed JSON-parse.
+    const json = await parseJsonOrThrow(res, options.baseUrl, 'search');
+    const parsed = RegistrySearchResponseSchema.safeParse(json);
+    if (!parsed.success) {
+      throw new RegistryMalformedPayloadError(
+        options.baseUrl,
+        'search',
+        formatZodIssuesAsSingleLine(parsed.error),
+      );
+    }
+    return parsed.data.hits;
+  },
+
+  /**
+   * Stream-download a published artifact's bytes and verify the
+   * sha256 integrity matches `expectedDigest`. Throws
+   * `RegistryArtifactIntegrityMismatchError` on mismatch — the
+   * digest check is non-negotiable per KD-9 / Security model.
+   */
+  async download(
+    options: RegistryServerClientOptions,
+    args: {
+      domain: string;
+      moduleId: string;
+      version: string;
+      expectedDigest: string;
+    },
+  ): Promise<{ bytes: Uint8Array; integrity: string }> {
+    // 7th-pass C-M1: caller-supplied digest is a developer-contract
+    // violation if malformed, not a registry-runtime condition.
+    // Throw `TypeError` (matching `C-L3` precedent for
+    // `getModuleStagingPaths` argument-shape violations) so the
+    // typed `RegistryError` vocabulary stays reserved for
+    // registry-runtime errors. Prior `Sha256DigestSchema.parse(...)`
+    // leaked a bare `ZodError` that bypassed
+    // `isRegistryError(err)` handlers but ALSO confused
+    // typed-handler maintainers about the contract.
+    const digestParse = Sha256DigestSchema.safeParse(args.expectedDigest);
+    if (!digestParse.success) {
+      throw new TypeError(
+        `download() expectedDigest must be a valid sha256:<64-hex> string (got: ${JSON.stringify(args.expectedDigest)}). ${formatZodIssuesAsSingleLine(digestParse.error)}`,
+      );
+    }
+    const url = joinUrl(
+      options.baseUrl,
+      `/v1/registry/${encodeURIComponent(args.domain)}/modules/${encodeURIComponent(args.moduleId)}/${encodeURIComponent(args.version)}/artifact`,
+    );
+    const res = await fetchWithTimeout(url, {
+      method: 'GET',
+      headers: authHeaders(options),
+      timeoutMs: options.timeoutMs,
+      diagnosticLabel: DIAGNOSTIC_LABEL,
+    });
+    if (res.status === 404) throw new RegistryVersionNotFoundError(args.moduleId, args.version);
+    const authErr = await classifyAuthError(res, options.baseUrl, `download ${args.moduleId}@${args.version}`);
+    if (authErr) throw authErr;
+    if (!res.ok) {
+      throw new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, `download ${args.moduleId}@${args.version}`);
+    }
+    const buf = new Uint8Array(await res.arrayBuffer());
+    const { createHash } = await import('node:crypto');
+    const observed = `sha256:${createHash('sha256').update(buf).digest('hex')}`;
+    if (observed !== args.expectedDigest) {
+      throw new RegistryArtifactIntegrityMismatchError(
+        args.moduleId,
+        args.version,
+        args.expectedDigest,
+        observed,
+      );
+    }
+    return { bytes: buf, integrity: observed };
+  },
+} as const;

package/src/services/types.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared structural types consumed across `wildo-module-client`
+ * services.
+ *
+ * The package intentionally avoids importing the CLI's full
+ * `CommandContext` (defined in `wildo-cli/src/kernel/types.ts`)
+ * to keep the dependency arrow CLI → wildo-module-client (KD-3
+ * forbids a reverse edge). Phase 2 services accept a structural
+ * subset of whatever the host (CLI / companion) needs to pass
+ * down — typically just `saasRoot` + a logger sink.
+ *
+ * The single shared type today is `RegistryClientLogger`. Adding
+ * more shared structural types here is fine; importing
+ * `wildo-cli` types is not.
+ */
+
+export interface RegistryClientLogger {
+  info: (msg: string) => void;
+  success?: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+}