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

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,116 +1,25 @@
 /**
- * `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+.
- *
- * The four mutations are GATED: the companion refuses any non-`GET` route that does not present the
- * machine-local token, so they take `RegistryCompanionMutationOptions` and `ping` — a `GET` — does
- * not. See that type for why the credential is required rather than optional.
+ * 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';
 
-/**
- * The header the companion's P-29b token floor reads on a mutating route.
- *
- * A wire contract between two processes that share no package, so it is named at both ends rather
- * than at neither. Its server twin is `COMPANION_TOKEN_HEADER` in the companion's
- * `core/auth/companion-auth-floor.companion.service.ts`; the CLI's is in
- * `wildo-cli/src/services/companion/companion-local-token.utils.ts`. Move one, move all three.
- */
-// semantic-literal-boundary: private companion HTTP protocol, translated only at this client edge.
-const COMPANION_TOKEN_HEADER = 'x-wildo-companion-token';
-
 export interface RegistryCompanionClientOptions {
   baseUrl: string;
   timeoutMs?: number;
 }
 
-/**
- * What a MUTATING companion registry call needs, over and above an address.
- *
- * `companionToken` is REQUIRED, and that is the whole point of this second type. Every non-`GET`
- * route under `/api/companion/**` is refused without it, and the four methods below have no caller
- * yet (the routes answer a not-implemented envelope until Phase 5) — so making it required now costs
- * nothing and means the caller Phase 5 writes cannot be written without the credential. An optional
- * field would have been a rule to remember; a required one is a compile error.
- *
- * The value is the content of `<appRoot>/.wildo-saas/state/companion.token` (mode 0600), which the
- * companion mints on every boot. This package has no notion of an application root, so reading it is
- * deliberately the caller's job: `wildo-cli` already owns a hardened no-follow reader
- * (`readCompanionTokenNoFollow`), and a second copy of a permission-checked read is precisely where
- * the checks quietly diverge.
- */
-export interface RegistryCompanionMutationOptions extends RegistryCompanionClientOptions {
-  companionToken: string;
-}
-
-async function postJson<R>(
-  options: RegistryCompanionMutationOptions,
-  routePath: string,
-  body: unknown,
-): Promise<R> {
-  const url = joinUrl(options.baseUrl, routePath);
-  const res = await fetchWithTimeout(url, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json', [COMPANION_TOKEN_HEADER]: options.companionToken },
-    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
@@ -129,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: RegistryCompanionMutationOptions,
-    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: RegistryCompanionMutationOptions,
-    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: RegistryCompanionMutationOptions,
-    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: RegistryCompanionMutationOptions,
-    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 },