@wildo-ai/wildo-module-client 1.1.1

package/src/services/provider-sync-runner.ts

@@ -0,0 +1,298 @@
+/**
+ * `runProviderSync` — Phase 2 real shell-out to
+ * `wildo config sync --domain config`.
+ *
+ * Module-registry install/update/remove/adopt flows mutate app
+ * source. When that source changes provider implementations,
+ * provider companion exports, or provider scopes, the
+ * provider-runtime delivery layer must regenerate its outputs
+ * (KD-18). The canonical command is owned by the provider
+ * workstream — module-registry MUST delegate, not fork.
+ *
+ * Phase 0.5 / 1 shipped a no-op `runProviderMaterializationHook`
+ * that recorded intent. Phase 2 replaces it with a real
+ * `child_process.spawn`-based runner that:
+ *   - resolves the `wildo` CLI binary from the saas root's
+ *     `node_modules/.bin/wildo` (the workspace's own version);
+ *   - shells `wildo config sync --domain config` in the saas root;
+ *   - times out at the operator-configurable budget;
+ *   - classifies stderr-tail patterns into the
+ *     `RegistryProviderSyncFailedError.failureKind` discriminator
+ *     (`companion-discovery` / `runtime-import-reachability` /
+ *     `invalid-scope` / `unknown`) so callers report repairable
+ *     failures with first-class UX rather than generic install
+ *     noise (`module-registry-analysis.md` / Provider Migration
+ *     WIP Seams §1).
+ *
+ * Hard contract (KD-18): the runner NEVER writes provider runtime
+ * artifacts itself. It only invokes the provider workstream's
+ * canonical command. Tests assert no provider artifact is touched
+ * by this code path.
+ */
+
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import {
+  PROVIDER_LOCK_SECTION_PATH,
+  PROVIDER_RUNTIME_ARTIFACT_RELATIVE_PATHS,
+  PROVIDER_RUNTIME_GENERATED_MODULE_RELATIVE_PATH,
+  RegistryProviderSyncFailedError,
+} from '@wildo-ai/platform-config-lib';
+import type { RegistryClientLogger } from './types';
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export interface ProviderSyncRunnerInput {
+  /** Absolute path to the SaaS application root. */
+  saasRoot: string;
+  /** Reason for the call — drives diagnostic copy. */
+  reason: 'install' | 'update' | 'remove' | 'adopt' | 'smoke';
+  /** Optional logger. Defaults to no-op. */
+  log?: RegistryClientLogger;
+  /**
+   * Override the wildo CLI binary path. Defaults to
+   * `<saasRoot>/node_modules/.bin/wildo`. Phase 2 tests override
+   * this to point at a stub script.
+   */
+  wildoBinPath?: string;
+  /**
+   * Maximum wall-time before SIGTERM. Default 120s — provider sync
+   * can be heavy on first run (artifact generation + cleanup),
+   * but every additional second is operator-visible.
+   */
+  timeoutMs?: number;
+  /**
+   * If true, do NOT actually shell out — log the intent and
+   * resolve as `mode: 'dry-run'`. Used by the Phase 0.5 smoke
+   * command which intentionally cannot rely on a working
+   * `wildo` binary in the smoke sandbox.
+   */
+  dryRun?: boolean;
+}
+
+export interface ProviderSyncRunnerResult {
+  invoked: true;
+  /**
+   * `'shell-out'` when the runner spawned `wildo config sync`.
+   * `'dry-run'` when `dryRun: true` was passed (smoke flow).
+   */
+  mode: 'shell-out' | 'dry-run';
+  /** Exit code reported by the wildo binary (0 on success). */
+  exitCode: number | null;
+  /** Wall-clock duration (ms). */
+  durationMs: number;
+  /** Reason that was passed in. */
+  reason: ProviderSyncRunnerInput['reason'];
+  /** Provider-output paths the canonical sync would refresh. */
+  providerJsonRelativePaths: readonly string[];
+  /** Source module the Node-runtime consumes. */
+  providerSourceRelativePath: string;
+  /** Provider lock section the materializer owns end-to-end. */
+  providerLockSectionPath: typeof PROVIDER_LOCK_SECTION_PATH;
+}
+
+/**
+ * Provider artifact paths sourced from the canonical
+ * `PROVIDER_RUNTIME_ARTIFACT_RELATIVE_PATHS` constant in
+ * `platform-config-lib`. Refactored on 2026-05-06 to import the
+ * single source of truth instead of duplicating the literal paths
+ * here — the artifacts moved from `.wildo-saas/providers/` to
+ * `.wildo-saas/generated/providers/` and any duplication would
+ * silently drift.
+ */
+const PROVIDER_JSON_RELATIVE_PATHS = Object.values(
+  PROVIDER_RUNTIME_ARTIFACT_RELATIVE_PATHS,
+) as readonly string[];
+
+const PROVIDER_SOURCE_RELATIVE_PATH = PROVIDER_RUNTIME_GENERATED_MODULE_RELATIVE_PATH;
+
+/**
+ * Classify a `wildo config sync` failure based on its stderr tail.
+ * The matchers mirror the failure modes the provider workstream
+ * surfaces today; new modes get a new branch + a new
+ * discriminator value (out of `RegistryProviderSyncFailedError`).
+ */
+function classifyStderr(
+  stderr: string,
+): 'companion-discovery' | 'runtime-import-reachability' | 'invalid-scope' | 'unknown' {
+  const tail = stderr.slice(-2000);
+  // Companion-export discovery failure — the provider sync walks
+  // each owner package's `./companion` export to discover provider
+  // contributions. A package whose export contract is broken
+  // surfaces a "companion export" / "DiscoveredProviderCompanionContribution"
+  // error.
+  if (
+    /companion[- ]export|DiscoveredProviderCompanionContribution|companion-discovery/i.test(tail)
+  ) {
+    return 'companion-discovery';
+  }
+  // Runtime-import reachability — the materializer can't resolve a
+  // contributed `runtimeImport` against the owning runtime package
+  // graph. Typical messages mention `runtimeImport`, `Cannot find
+  // module`, or `MODULE_NOT_FOUND`.
+  if (
+    /runtimeImport|MODULE_NOT_FOUND|Cannot find module|cannot resolve/i.test(tail)
+  ) {
+    return 'runtime-import-reachability';
+  }
+  // Scope validation — `defineSaaSProviders({ scopes })` rejects
+  // malformed scope inputs ahead of materialization.
+  if (
+    /defineSaaSProviders|invalid[- ]scope|providers\.scopes/i.test(tail)
+  ) {
+    return 'invalid-scope';
+  }
+  return 'unknown';
+}
+
+async function resolveWildoBin(input: ProviderSyncRunnerInput): Promise<string> {
+  if (input.wildoBinPath) return input.wildoBinPath;
+  const candidate = path.join(input.saasRoot, 'node_modules', '.bin', 'wildo');
+  try {
+    await fs.access(candidate);
+    return candidate;
+  } catch {
+    // Fall back to PATH-resolved `wildo`. spawn will raise ENOENT
+    // if it's not on PATH either, surfaced as
+    // `RegistryProviderSyncFailedError(failureKind: 'unknown')`.
+    return 'wildo';
+  }
+}
+
+/**
+ * Grace window between SIGTERM and SIGKILL. A well-behaved
+ * `wildo config sync` should react to SIGTERM in well under a
+ * second — the grace exists for tools that need to flush a buffer
+ * or release a file lock. After the window we escalate to SIGKILL
+ * so a hung child cannot pin the parent forever.
+ */
+const SIGKILL_GRACE_MS = 5_000;
+
+function runWildoConfigSync(
+  binPath: string,
+  cwd: string,
+  timeoutMs: number,
+): Promise<{ exitCode: number | null; stderr: string; durationMs: number; signaled: boolean }> {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    const child = spawn(binPath, ['config', 'sync', '--domain', 'config'], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stderr = '';
+    let signaled = false;
+    let killTimer: NodeJS.Timeout | undefined;
+    child.stderr?.on('data', (b: Buffer) => {
+      // Cap captured stderr so a runaway sync can't OOM the parent.
+      stderr += b.toString();
+      if (stderr.length > 16_384) stderr = stderr.slice(-16_384);
+    });
+    const termTimer = setTimeout(() => {
+      // Soft-kill first; record so the caller can synthesize a
+      // diagnostic message that distinguishes a TERM-induced exit
+      // from a normal one.
+      signaled = true;
+      stderr += `\n[provider-sync] timeout ${timeoutMs}ms exceeded — sent SIGTERM.`;
+      child.kill('SIGTERM');
+      // Escalate to SIGKILL if the child doesn't react within the
+      // grace window. Without this a child stuck in a syscall (or
+      // deliberately ignoring SIGTERM) would leave the parent
+      // blocked on the spawn promise forever.
+      killTimer = setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null) {
+          stderr += `\n[provider-sync] SIGTERM grace ${SIGKILL_GRACE_MS}ms exceeded — escalating to SIGKILL.`;
+          try {
+            child.kill('SIGKILL');
+          } catch {
+            /* swallow — best-effort escalation */
+          }
+        }
+      }, SIGKILL_GRACE_MS);
+    }, timeoutMs);
+    child.on('exit', (code) => {
+      clearTimeout(termTimer);
+      if (killTimer) clearTimeout(killTimer);
+      resolve({
+        exitCode: code,
+        stderr,
+        durationMs: Date.now() - startedAt,
+        signaled,
+      });
+    });
+    child.on('error', (err) => {
+      clearTimeout(termTimer);
+      if (killTimer) clearTimeout(killTimer);
+      resolve({
+        exitCode: null,
+        stderr: stderr + `\n[spawn error] ${err.message}`,
+        durationMs: Date.now() - startedAt,
+        signaled,
+      });
+    });
+  });
+}
+
+/**
+ * Run the canonical provider-sync command. Throws
+ * `RegistryProviderSyncFailedError` (with classified `failureKind`)
+ * when the spawned process exits non-zero or fails to start.
+ */
+export async function runProviderSync(
+  input: ProviderSyncRunnerInput,
+): Promise<ProviderSyncRunnerResult> {
+  const log = input.log;
+  const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const baseResult = {
+    invoked: true as const,
+    reason: input.reason,
+    providerJsonRelativePaths: PROVIDER_JSON_RELATIVE_PATHS,
+    providerSourceRelativePath: PROVIDER_SOURCE_RELATIVE_PATH,
+    providerLockSectionPath: PROVIDER_LOCK_SECTION_PATH,
+  };
+
+  if (input.dryRun) {
+    log?.info?.(
+      `[registry] post-${input.reason} provider sync (dry-run): would shell ` +
+      `\`wildo config sync --domain config\` in ${input.saasRoot}.`,
+    );
+    return { ...baseResult, mode: 'dry-run', exitCode: 0, durationMs: 0 };
+  }
+
+  const binPath = await resolveWildoBin(input);
+  log?.info?.(
+    `[registry] post-${input.reason} provider sync: spawning ` +
+    `${binPath} config sync --domain config (cwd=${input.saasRoot}, timeout=${timeoutMs}ms)`,
+  );
+  const { exitCode, stderr, durationMs, signaled } = await runWildoConfigSync(
+    binPath,
+    input.saasRoot,
+    timeoutMs,
+  );
+
+  if (exitCode === 0) {
+    log?.success?.(`[registry] provider sync succeeded in ${durationMs}ms.`);
+    return { ...baseResult, mode: 'shell-out', exitCode, durationMs };
+  }
+
+  // H5: distinguish a timeout-signaled exit from a generic non-zero
+  // exit. `classifyStderr` runs regex against the appended
+  // `[provider-sync] timeout ... SIGTERM/SIGKILL` lines but those
+  // tails match no failure-mode regex — so prior to this branch
+  // operators saw `failureKind: 'unknown'` for a hard timeout. The
+  // typed error now carries the discriminator + a hint to either
+  // raise the timeout or investigate the wedge.
+  const failureKind = signaled ? ('timeout' as const) : classifyStderr(stderr);
+  log?.error?.(
+    `[registry] provider sync failed (${failureKind}, exit=${exitCode}, ${durationMs}ms).`,
+  );
+  const messageSuffix = failureKind === 'timeout'
+    ? `Wall-clock exceeded ${timeoutMs}ms; child was sent SIGTERM (then SIGKILL after grace). ` +
+      'Either raise `timeoutMs` for legitimately heavy syncs or investigate why the sync wedged.'
+    : 'Run `wildo config sync --domain config` manually to inspect.';
+  throw new RegistryProviderSyncFailedError(
+    `Post-${input.reason} provider sync failed (${failureKind}). ${messageSuffix}`,
+    failureKind,
+    stderr.slice(-1024),
+  );
+}

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

@@ -0,0 +1,163 @@
+/**
+ * `RegistryCompanionClient` — HTTP client for the local dev
+ * companion's registry routes.
+ *
+ * Distinct from `RegistryServerClient` (which talks to the central
+ * `platform-module-registry` server). The companion client targets
+ * `/api/companion/registry/*` on `http://localhost:<companion-port>`
+ * for AST/source mutations the CLI delegates to the companion
+ * (KD-6).
+ *
+ * Phase 2 ships the four mutation routes as method calls; the
+ * companion controller (under
+ * `platform/factory/wildo-dev-companion/src/companion-api/controllers/`)
+ * implements them with the actual ts-morph + filesystem work in
+ * Phase 5+.
+ */
+
+import {
+  REGISTRY_COMPANION_ROUTES,
+  RegistryMalformedPayloadError,
+  RegistryRouteResultSchema,
+  RegistryUnexpectedStatusError,
+  type RegistryInstallRequest,
+  type RegistryPublishRequest,
+  type RegistryRemoveRequest,
+  type RegistryRouteResult,
+  type RegistryUpdateRequest,
+} from '@wildo-ai/platform-config-lib';
+import { fetchWithTimeout, joinUrl } from './_http-client';
+import { formatZodIssuesAsSingleLine } from './_zod-issue-formatting';
+
+const DIAGNOSTIC_LABEL = 'Companion registry';
+
+export interface RegistryCompanionClientOptions {
+  baseUrl: string;
+  timeoutMs?: number;
+}
+
+async function postJson<R>(
+  options: RegistryCompanionClientOptions,
+  routePath: string,
+  body: unknown,
+): Promise<R> {
+  const url = joinUrl(options.baseUrl, routePath);
+  const res = await fetchWithTimeout(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+    timeoutMs: options.timeoutMs,
+    diagnosticLabel: DIAGNOSTIC_LABEL,
+  });
+  if (!res.ok) {
+    // 3rd-pass M5: typed `RegistryUnexpectedStatusError` instead of
+    // bare `new Error(...)` so callers can `isRegistryError(err)` and
+    // discriminate by status code without re-parsing message text.
+    // The companion deliberately reuses the same error vocabulary
+    // as `RegistryServerClient` since the wire shape (status + URL +
+    // action) is identical even though the lane is different.
+    throw new RegistryUnexpectedStatusError(
+      options.baseUrl,
+      res.status,
+      res.statusText,
+      `companion ${routePath}`,
+    );
+  }
+  // 6th-pass M3: typed JSON-parse — a misconfigured proxy returning
+  // HTML at 2xx would otherwise throw a bare `SyntaxError` that
+  // bypasses the typed-error contract.
+  try {
+    return (await res.json()) as R;
+  } catch (err) {
+    throw new RegistryMalformedPayloadError(
+      options.baseUrl,
+      `companion ${routePath}`,
+      `response is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export const RegistryCompanionClient = {
+  /**
+   * Liveness probe against `/health` (the same endpoint the
+   * dev-supervisor monitors). Used by `wildo registry ping`.
+   */
+  async ping(options: RegistryCompanionClientOptions): Promise<boolean> {
+    const url = joinUrl(options.baseUrl, '/health');
+    try {
+      const res = await fetchWithTimeout(url, {
+        method: 'GET',
+        timeoutMs: options.timeoutMs,
+        diagnosticLabel: DIAGNOSTIC_LABEL,
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Ask the companion to install a module: download bytes, copy
+   * source, mutate `wildo.saas.config.ts > moduleRegistries` +
+   * the three `modules-registry.*.ts` files, refresh
+   * `sections.modules`, run provider sync.
+   */
+  async install(
+    options: RegistryCompanionClientOptions,
+    request: RegistryInstallRequest,
+  ): Promise<RegistryRouteResult> {
+    const raw = await postJson<unknown>(options, REGISTRY_COMPANION_ROUTES.install, request);
+    return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.install, raw);
+  },
+
+  async update(
+    options: RegistryCompanionClientOptions,
+    request: RegistryUpdateRequest,
+  ): Promise<RegistryRouteResult> {
+    const raw = await postJson<unknown>(options, REGISTRY_COMPANION_ROUTES.update, request);
+    return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.update, raw);
+  },
+
+  async remove(
+    options: RegistryCompanionClientOptions,
+    request: RegistryRemoveRequest,
+  ): Promise<RegistryRouteResult> {
+    const raw = await postJson<unknown>(options, REGISTRY_COMPANION_ROUTES.remove, request);
+    return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.remove, raw);
+  },
+
+  async publish(
+    options: RegistryCompanionClientOptions,
+    request: RegistryPublishRequest,
+  ): Promise<RegistryRouteResult> {
+    const raw = await postJson<unknown>(options, REGISTRY_COMPANION_ROUTES.publish, request);
+    return parseCompanionResult(options.baseUrl, REGISTRY_COMPANION_ROUTES.publish, raw);
+  },
+} as const;
+
+/**
+ * M5: thin wrapper around `RegistryRouteResultSchema.parse(raw)` that
+ * converts a Zod parse failure into the typed
+ * `RegistryMalformedPayloadError` instead of letting a bare `ZodError`
+ * bubble up. Keeps the typed-handler contract aligned with
+ * `RegistryServerClient`.
+ */
+function parseCompanionResult(
+  baseUrl: string,
+  routePath: string,
+  raw: unknown,
+): RegistryRouteResult {
+  const parsed = RegistryRouteResultSchema.safeParse(raw);
+  if (!parsed.success) {
+    // 7th-pass C-L2: format the issues array for operator
+    // readability instead of using Zod 4's JSON-stringified
+    // `error.message`.
+    const detail = formatZodIssuesAsSingleLine(parsed.error);
+    throw new RegistryMalformedPayloadError(
+      baseUrl,
+      `companion ${routePath}`,
+      detail,
+    );
+  }
+  return parsed.data;
+}

package/src/services/registry-lockfile.service.ts

@@ -0,0 +1,122 @@
+/**
+ * `RegistryLockfileService` — section-scoped reader/writer for the
+ * `sections.modules` slice of `wildo-saas.lock.json` (KD-4).
+ *
+ * Phase 1 graduates the locking + atomic-write primitives into
+ * `@wildo-ai/platform-config-lib` (validated by the Phase 0.B
+ * contention spike). This service is a thin wrapper around
+ * `withLockfileSectionMutate` that pre-binds the `modules` section
+ * key + schema, so module-registry callers cannot accidentally
+ * touch sibling sections.
+ *
+ * Hard contracts (KD-4 / KD-15 / KD-18):
+ *   - Mutates ONLY `sections.modules`. The shared library preserves
+ *     `sections.providers`, `sections.i18n`, and every unknown
+ *     `sections.*` payload verbatim — no defensive logic needed
+ *     here.
+ *   - Never writes `.wildo-saas/generated/providers/*.runtime-providers.generated.json`
+ *     or `src/generated/wildo-provider-runtime.generated.ts` —
+ *     those are produced by the provider materialization workflow.
+ *   - Never mutates `sections.providers.runtimeScopes`.
+ */
+
+import {
+  RegistryModulesLockSectionSchema,
+  withLockfileSectionMutate,
+  readWildoSaasLock,
+  type RegistryModulesLockSection,
+  type RegistryModulesLockEntry,
+} from '@wildo-ai/platform-config-lib';
+// L6 (third-pass review): the package's barrel-discipline rule says
+// "Never re-export (except in the root `index.ts` of each package)."
+// The previous `export { WILDO_SAAS_LOCK_RELATIVE_PATH }` here AND in
+// `lockfile-repair.service.ts` surfaced the symbol twice from
+// `wildo-module-client`'s root. Consumers that need it can import
+// directly from `@wildo-ai/platform-config-lib`, OR rely on the root
+// `index.ts` to re-export it once.
+
+const SECTION_KEY = 'modules' as const;
+
+function emptySection(): RegistryModulesLockSection {
+  return RegistryModulesLockSectionSchema.parse({});
+}
+
+export const RegistryLockfileService = {
+  /**
+   * Read the current `sections.modules` payload (or an empty section
+   * when missing). Unsynchronized — callers needing read-after-write
+   * coherence should read INSIDE `mutate`.
+   */
+  async read(saasRoot: string): Promise<RegistryModulesLockSection> {
+    const envelope = await readWildoSaasLock({ saasRoot });
+    const raw = envelope.sections.modules;
+    if (raw === undefined) return emptySection();
+    return RegistryModulesLockSectionSchema.parse(raw);
+  },
+
+  /**
+   * Run `mutator` against the current `sections.modules` payload
+   * under an OS-level lock + atomic-write commit. The mutator can
+   * either mutate-in-place or return a new value; either way the
+   * result is re-validated against `RegistryModulesLockSectionSchema`
+   * before commit.
+   */
+  async mutate(
+    saasRoot: string,
+    mutator: (
+      current: RegistryModulesLockSection,
+    ) =>
+      | RegistryModulesLockSection
+      | void
+      | Promise<RegistryModulesLockSection | void>,
+  ): Promise<RegistryModulesLockSection> {
+    return withLockfileSectionMutate(
+      {
+        saasRoot,
+        sectionKey: SECTION_KEY,
+        sectionSchema: RegistryModulesLockSectionSchema,
+        initialSection: emptySection,
+      },
+      mutator,
+    );
+  },
+
+  /** Convenience helper used by Phase 5+ install flow. */
+  async upsertEntry(saasRoot: string, entry: RegistryModulesLockEntry): Promise<void> {
+    await this.mutate(saasRoot, (current) => ({
+      ...current,
+      installed: { ...current.installed, [entry.moduleId]: entry },
+    }));
+  },
+
+  /**
+   * Find every other lockfile entry whose `files[]` claims any of the
+   * given paths. Used by `update`/`remove` to skip deletes that would
+   * silently pull files out from under modules that own them too
+   * (cross-module file overlap).
+   *
+   * Returns a `Map<relPath, owners[]>` where `owners` excludes
+   * `excludeModuleId`. Empty array → uniquely owned by the excluded
+   * module, safe to delete.
+   */
+  async findFileOwners(args: {
+    saasRoot: string;
+    paths: readonly string[];
+    excludeModuleId: string;
+  }): Promise<Map<string, string[]>> {
+    const section = await this.read(args.saasRoot);
+    const claimedBy = new Map<string, string[]>();
+    for (const p of args.paths) claimedBy.set(p, []);
+    for (const otherModuleId of Object.keys(section.installed)) {
+      if (otherModuleId === args.excludeModuleId) continue;
+      const otherEntry = section.installed[otherModuleId];
+      if (!otherEntry) continue;
+      for (const otherFile of otherEntry.files) {
+        if (claimedBy.has(otherFile)) {
+          claimedBy.get(otherFile)!.push(otherModuleId);
+        }
+      }
+    }
+    return claimedBy;
+  },
+} as const;