@wildo-ai/wildo-module-client 1.1.4 → 1.1.6

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

@@ -1,21 +1,12 @@
 /**
- * `LockfileRepairService` — Phase 2 read-only lockfile diagnostics.
+ * `LockfileRepairService` — read-only lockfile diagnostics.
  *
- * Backs `wildo registry repair-lockfile` (CLI command lands in a
- * later step). The service does NOT mutate the lockfile by
- * default — its job is to surface a structured diagnostic the
- * operator can act on:
- *   - validate the canonical envelope shape;
- *   - validate `sections.modules` against
- *     `RegistryModulesLockSectionSchema`;
- *   - report which `installed[*].files` are missing on disk
- *     (drift between the lockfile and the source tree);
- *   - report which `installed[*].artifactDigest` strings are not
- *     `Sha256DigestSchema`-shaped (residue from pre-tightening
- *     publishes).
- *
- * Mutating repair is a Phase 7 deliverable — surfacing the gaps is
- * what unblocks the operator now.
+ * Backs `wildo registry repair-lockfile`. Strict envelope and module-section
+ * validation runs before file inspection. Malformed records, including invalid
+ * artifact digests, require restoration from a trusted record; they are never
+ * admitted into the automatic repair path. Valid records can report missing
+ * source files, which the CLI can re-fetch at their recorded exact version.
+ * This inspector does not mutate files.
  *
  * `i18n` validation is intentionally NOT performed here (KD-15 +
  * Review-pass-2 / MEDIUM-5): repair is the wrong place to
@@ -30,7 +21,6 @@ import { z } from 'zod';
 import { formatZodIssuesAsSingleLine } from './_zod-issue-formatting';
 import {
   RegistryModulesLockSectionSchema,
-  Sha256DigestSchema,
   getWildoSaasLockPath,
   type RegistryModulesLockEntry,
   type RegistryModulesLockSection,
@@ -66,12 +56,6 @@ export type LockfileRepairFinding =
       kind: 'module-file-missing';
       moduleId: string;
       filePath: string;
-    }
-  | {
-      severity: 'warn';
-      kind: 'module-digest-not-sha256';
-      moduleId: string;
-      observedDigest: string;
     };
 
 export interface LockfileRepairReport {
@@ -163,7 +147,7 @@ export const LockfileRepairService = {
       findings.push({
         severity: 'error',
         kind: 'modules-section-malformed',
-        message: '`sections.modules` failed schema validation.',
+        message: '`sections.modules` failed schema validation. Restore the affected record from a trusted lockfile revision; automatic repair does not infer missing or invalid metadata.',
         detail: formatZodIssuesAsSingleLine(parsed.error),
       });
       return { lockfilePath, ok: false, findings };
@@ -179,8 +163,7 @@ export const LockfileRepairService = {
   },
 
   /**
-   * Per-entry diagnostic helper. Exposed so Phase 7 mutating-
-   * repair flows can reuse the same predicates.
+   * Missing-file diagnostics for an entry already validated by the strict section schema.
    */
   async collectEntryFindings(
     saasRoot: string,
@@ -188,14 +171,6 @@ export const LockfileRepairService = {
     entry: RegistryModulesLockEntry,
     findings: LockfileRepairFinding[],
   ): Promise<void> {
-    if (!Sha256DigestSchema.safeParse(entry.artifactDigest).success) {
-      findings.push({
-        severity: 'warn',
-        kind: 'module-digest-not-sha256',
-        moduleId,
-        observedDigest: entry.artifactDigest,
-      });
-    }
     for (const filePath of entry.files) {
       const abs = path.resolve(saasRoot, filePath);
       if (!(await fileExists(abs))) {

package/src/services/module-adopter.service.ts

@@ -22,7 +22,7 @@
 
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
-import type { ModuleManifest } from '@wildo-ai/platform-config-lib';
+import { isModuleArtifactPathAllowed, MODULE_BOUNDARY_LAYERS, type ModuleManifest } from '@wildo-ai/platform-config-lib';
 import { ModulePackagerService, type StagingPaths } from './module-packager.service';
 
 export interface AdoptionPlan {
@@ -65,6 +65,9 @@ async function walkBoundary(
     const entries = await fs.readdir(path.resolve(saasRoot, cur), { withFileTypes: true });
     for (const entry of entries) {
       const rel = path.join(cur, entry.name);
+      // Skip what a module never ships, exactly as `wildo registry publish` does — otherwise the
+      // packager (which refuses those paths) throws on a module's own `.env` or `node_modules`.
+      if (!isModuleArtifactPathAllowed(rel.split(path.sep).join('/'))) continue;
       if (entry.isDirectory()) {
         queue.push(rel);
       } else if (entry.isFile()) {
@@ -88,14 +91,8 @@ export const ModuleAdopterService = {
     if (!boundaries) {
       return { files: [], emptyBoundaries: [] };
     }
-    const layers: ReadonlyArray<keyof typeof boundaries> = [
-      'specifications',
-      'shared',
-      'frontend',
-      'backend',
-      'minions',
-      'workers',
-    ];
+    // Every layer the registry knows, not a hand-kept copy: a copy here missed `providers` (#2014).
+    const layers = MODULE_BOUNDARY_LAYERS;
     const aggregate = new Set<string>();
     const empty: string[] = [];
     for (const layer of layers) {

package/src/services/module-packager.service.ts

@@ -31,14 +31,17 @@ import { createHash } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import {
+  flattenModuleBoundaries,
+  isModuleArtifactPathAllowed,
+  isModuleId,
   ModuleManifestSchema,
   RegistryBoundaryViolationError,
   type ModuleManifest,
   type ModuleManifestBoundaries,
+  MODULE_MANIFEST_FILE_NAME as MANIFEST_FILE_NAME,
 } from '@wildo-ai/platform-config-lib';
 
 export const MODULES_ARTIFACTS_RELATIVE_DIR = '.wildo-saas/generated/modules-artifacts';
-const MANIFEST_FILE_NAME = 'wildo.module.json';
 
 export interface StagingPaths {
   /** Absolute path to the per-module staging root. */
@@ -52,7 +55,9 @@ export interface StagingPaths {
  * fs side effects.
  */
 export function getModuleStagingPaths(saasRoot: string, moduleId: string): StagingPaths {
-  if (!moduleId.includes('/')) {
+  // The full `<scope>/<name>` shape, not merely "contains a `/`": `stageFresh` runs a recursive delete
+  // on the path built here, and `a/../../../..` contained a slash.
+  if (!isModuleId(moduleId)) {
     // C-L3 (4th-pass review): `TypeError` is Node's standard for
     // argument-shape violations. The typed `RegistryError` subclasses
     // model registry-runtime conditions (auth, integrity, version
@@ -62,10 +67,14 @@ export function getModuleStagingPaths(saasRoot: string, moduleId: string): Stagi
     // and stops the typed-error vocabulary from absorbing pure
     // argument-validation concerns.
     throw new TypeError(
-      `Module id "${moduleId}" must be in <domain>/<name> form (e.g. "acme/billing").`,
+      `Module id "${moduleId}" must be in <scope>/<name> form (e.g. "acme/billing"), each half lowercase letters, digits, ".", "_" or "-".`,
     );
   }
-  const stagingRoot = path.resolve(saasRoot, MODULES_ARTIFACTS_RELATIVE_DIR, moduleId);
+  const artifactsRoot = path.resolve(saasRoot, MODULES_ARTIFACTS_RELATIVE_DIR);
+  const stagingRoot = path.resolve(artifactsRoot, moduleId);
+  if (!isPathInside(stagingRoot, artifactsRoot) || stagingRoot === artifactsRoot) {
+    throw new TypeError(`Module id "${moduleId}" resolves outside ${MODULES_ARTIFACTS_RELATIVE_DIR}.`);
+  }
   return {
     stagingRoot,
     manifestPath: path.join(stagingRoot, MANIFEST_FILE_NAME),
@@ -114,20 +123,14 @@ export function assertWithinBoundaries(
   boundaries: ModuleManifestBoundaries | undefined,
 ): string {
   const absolute = path.resolve(saasRoot, appRelativePath);
-  // Path must stay inside saasRoot (no `..` escapes).
-  if (!isPathInside(absolute, path.resolve(saasRoot))) {
+  // Path must stay inside saasRoot (no `..` escapes), and be a path a module artifact may carry at
+  // all — no dot-segment (`.env`, `.git`), no `node_modules` — whatever the boundaries say.
+  if (!isPathInside(absolute, path.resolve(saasRoot)) || !isModuleArtifactPathAllowed(appRelativePath.split(path.sep).join('/'))) {
     throw new RegistryBoundaryViolationError(moduleId, appRelativePath);
   }
-  if (!boundaries) return absolute;
-  const allowed: readonly string[] = [
-    ...boundaries.specifications,
-    ...boundaries.shared,
-    ...boundaries.frontend,
-    ...boundaries.backend,
-    ...boundaries.minions,
-    ...boundaries.workers,
-  ];
-  if (allowed.length === 0) return absolute;
+  // No declared boundary means the module may write NOWHERE. This used to return early and admit
+  // every path in the application — the fail-open reading of an absent declaration.
+  const allowed: readonly string[] = flattenModuleBoundaries(boundaries);
   // The candidate must be inside at least one declared boundary.
   const isInside = allowed.some((rel) => isPathInside(absolute, path.resolve(saasRoot, rel)));
   if (!isInside) {

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

@@ -41,7 +41,16 @@ import {
 } from '@wildo-ai/platform-config-lib';
 import type { RegistryClientLogger } from './types';
 
-const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * How long the post-mutation `wildo config sync` may run before it is treated as wedged and killed.
+ *
+ * Five minutes, not two: the budget exists to stop a WEDGED sync, and a wall clock cannot tell wedged
+ * from slow. Measured 2026-09-27 on a scaffolded application (#1765): the same sync took 14.6 s on a
+ * quiet machine, 91 s while the framework's watchers were recompiling, and exceeded the old 120 s during
+ * an install under that load — so a healthy sync was killed part-way and the install reported a provider
+ * sync failure it did not have. The kill stays: a genuinely stuck sync still ends, five minutes on.
+ */
+const DEFAULT_TIMEOUT_MS = 300_000;
 
 export interface ProviderSyncRunnerInput {
   /** Absolute path to the SaaS application root. */
@@ -57,9 +66,8 @@ export interface ProviderSyncRunnerInput {
    */
   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.
+   * Maximum wall-time before SIGTERM. Default {@link DEFAULT_TIMEOUT_MS} (five minutes): it only ever
+   * elapses on a wedged sync, and a healthy one under load has been measured past two minutes.
    */
   timeoutMs?: number;
   /**
@@ -178,7 +186,10 @@ function runWildoConfigSync(
     const startedAt = Date.now();
     const child = spawn(binPath, ['config', 'sync', '--domain', 'config'], {
       cwd,
-      stdio: ['ignore', 'pipe', 'pipe'],
+      // stdout is IGNORED, not piped: nothing here reads it, and an unread pipe fills at the OS buffer
+      // (~64 KB) and blocks the child mid-write — a finished sync then looked like a wedged one and
+      // was killed at the timeout. stderr stays piped because the diagnostic reads it (bounded below).
+      stdio: ['ignore', 'ignore', 'pipe'],
     });
     let stderr = '';
     let signaled = false;

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

@@ -1,33 +1,17 @@
 /**
- * `RegistryCompanionClient` — HTTP client for the local dev
- * companion's registry routes.
+ * `RegistryCompanionClient` — liveness probe for the local dev companion, used by
+ * `wildo registry ping` beside the registry-server probe.
  *
- * 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+.
+ * That is all it is. It used to carry four mutation methods (install / update / remove / publish)
+ * against `/api/companion/registry/*` routes that only ever answered a "Phase 5/6 deliverable"
+ * not-implemented envelope and had no caller. Installation shipped CLI-direct instead
+ * (`wildo registry add` / `update` / `remove` / `publish` do the work themselves), so the routes,
+ * these methods and their wire schemas were deleted on 2026-09-25 rather than left describing a
+ * design that was never built. A future companion-owned mutation lane starts from the CLI commands,
+ * not from this file.
  */
 
-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';
 
@@ -36,47 +20,6 @@ export interface RegistryCompanionClientOptions {
   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
@@ -95,69 +38,4 @@ export const RegistryCompanionClient = {
       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

@@ -25,7 +25,8 @@ import {
   withLockfileSectionMutate,
   readWildoSaasLock,
   type RegistryModulesLockSection,
-  type RegistryModulesLockEntry,
+  RegistryModulesLockEntrySchema,
+  type RegistryModulesLockEntryInput,
 } 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)."
@@ -81,8 +82,13 @@ export const RegistryLockfileService = {
     );
   },
 
-  /** Convenience helper used by Phase 5+ install flow. */
-  async upsertEntry(saasRoot: string, entry: RegistryModulesLockEntry): Promise<void> {
+  /**
+   * Insert or replace one module's entry. The entry is parsed here, so its defaults (`distribution`,
+   * `files`) apply in one place and a malformed entry is refused naming the module, before the lockfile
+   * is touched (`mutate` then re-validates the whole section).
+   */
+  async upsertEntry(saasRoot: string, input: RegistryModulesLockEntryInput): Promise<void> {
+    const entry = RegistryModulesLockEntrySchema.parse(input);
     await this.mutate(saasRoot, (current) => ({
       ...current,
       installed: { ...current.installed, [entry.moduleId]: entry },