@wildo-ai/wildo-module-client 1.1.1

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

@@ -0,0 +1,215 @@
+/**
+ * `LockfileRepairService` — Phase 2 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.
+ *
+ * `i18n` validation is intentionally NOT performed here (KD-15 +
+ * Review-pass-2 / MEDIUM-5): repair is the wrong place to
+ * second-guess companion-owned section semantics. The shared
+ * lockfile library STILL validates i18n on the companion-owned
+ * read path; this service only owns module diagnostics.
+ */
+
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { z } from 'zod';
+import { formatZodIssuesAsSingleLine } from './_zod-issue-formatting';
+import {
+  RegistryModulesLockSectionSchema,
+  Sha256DigestSchema,
+  getWildoSaasLockPath,
+  type RegistryModulesLockEntry,
+  type RegistryModulesLockSection,
+} from '@wildo-ai/platform-config-lib';
+
+/**
+ * Permissive envelope schema used by repair only — it accepts any
+ * `sections.*` payload without delegating to per-section schemas
+ * so the repair flow can isolate "envelope is malformed" from
+ * "envelope is fine but modules section is malformed".
+ */
+const RelaxedEnvelopeSchema = z.strictObject({
+  schemaVersion: z.literal(2),
+  generatedAt: z.iso.datetime({ offset: true }),
+  sections: z.record(z.string(), z.unknown()),
+});
+
+export type LockfileRepairFinding =
+  | {
+      severity: 'error';
+      kind: 'envelope-malformed';
+      message: string;
+      detail?: string;
+    }
+  | {
+      severity: 'error';
+      kind: 'modules-section-malformed';
+      message: string;
+      detail?: string;
+    }
+  | {
+      severity: 'warn';
+      kind: 'module-file-missing';
+      moduleId: string;
+      filePath: string;
+    }
+  | {
+      severity: 'warn';
+      kind: 'module-digest-not-sha256';
+      moduleId: string;
+      observedDigest: string;
+    };
+
+export interface LockfileRepairReport {
+  /** Absolute path the report covers. */
+  lockfilePath: string;
+  /** True when no errors were produced (warnings allowed). */
+  ok: boolean;
+  findings: readonly LockfileRepairFinding[];
+}
+
+async function fileExists(absPath: string): Promise<boolean> {
+  try {
+    await fs.access(absPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const LockfileRepairService = {
+  /** Compute the lockfile path for a saas root. */
+  pathFor(saasRoot: string): string {
+    return getWildoSaasLockPath(saasRoot);
+  },
+
+  /**
+   * Read the envelope + run every diagnostic. Read-only.
+   */
+  async inspect(saasRoot: string): Promise<LockfileRepairReport> {
+    const lockfilePath = getWildoSaasLockPath(saasRoot);
+    const findings: LockfileRepairFinding[] = [];
+
+    // Read raw bytes ourselves so we can produce per-section
+    // diagnostics: a malformed `modules` section under an
+    // otherwise-valid envelope should report `modules-section-malformed`,
+    // NOT `envelope-malformed` (the latter would tell the operator
+    // to re-author the whole file when only one section is bad).
+    let raw: string;
+    try {
+      raw = await fs.readFile(lockfilePath, 'utf8');
+    } catch (err: unknown) {
+      const errno = (err as NodeJS.ErrnoException)?.code;
+      if (errno === 'ENOENT') {
+        // Missing lockfile is "ok" from a repair POV.
+        return { lockfilePath, ok: true, findings: [] };
+      }
+      findings.push({
+        severity: 'error',
+        kind: 'envelope-malformed',
+        message: 'Failed to read lockfile bytes.',
+        detail: err instanceof Error ? err.message : String(err),
+      });
+      return { lockfilePath, ok: false, findings };
+    }
+
+    let parsedJson: unknown;
+    try {
+      parsedJson = JSON.parse(raw);
+    } catch (err) {
+      findings.push({
+        severity: 'error',
+        kind: 'envelope-malformed',
+        message: 'Lockfile is not valid JSON.',
+        detail: err instanceof Error ? err.message : String(err),
+      });
+      return { lockfilePath, ok: false, findings };
+    }
+
+    const envelopeParsed = RelaxedEnvelopeSchema.safeParse(parsedJson);
+    if (!envelopeParsed.success) {
+      findings.push({
+        severity: 'error',
+        kind: 'envelope-malformed',
+        message: 'Top-level envelope failed to parse.',
+        detail: formatZodIssuesAsSingleLine(envelopeParsed.error),
+      });
+      return { lockfilePath, ok: false, findings };
+    }
+    const envelope = envelopeParsed.data;
+
+    const modulesPayload = envelope.sections.modules;
+    if (modulesPayload === undefined) {
+      // No modules section present — nothing to inspect.
+      return { lockfilePath, ok: true, findings };
+    }
+
+    const parsed = RegistryModulesLockSectionSchema.safeParse(modulesPayload);
+    if (!parsed.success) {
+      findings.push({
+        severity: 'error',
+        kind: 'modules-section-malformed',
+        message: '`sections.modules` failed schema validation.',
+        detail: formatZodIssuesAsSingleLine(parsed.error),
+      });
+      return { lockfilePath, ok: false, findings };
+    }
+    const modules: RegistryModulesLockSection = parsed.data;
+
+    for (const [moduleId, entry] of Object.entries(modules.installed)) {
+      await this.collectEntryFindings(saasRoot, moduleId, entry, findings);
+    }
+
+    const ok = findings.every((f) => f.severity !== 'error');
+    return { lockfilePath, ok, findings };
+  },
+
+  /**
+   * Per-entry diagnostic helper. Exposed so Phase 7 mutating-
+   * repair flows can reuse the same predicates.
+   */
+  async collectEntryFindings(
+    saasRoot: string,
+    moduleId: string,
+    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))) {
+        findings.push({
+          severity: 'warn',
+          kind: 'module-file-missing',
+          moduleId,
+          filePath,
+        });
+      }
+    }
+  },
+} as const;
+
+// L6 (third-pass review): re-export removed — barrel-discipline rule
+// says "Never re-export except in the root `index.ts`." Consumers
+// import the symbol directly from `@wildo-ai/platform-config-lib`.

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

@@ -0,0 +1,155 @@
+/**
+ * `ModuleAdopterService` — Phase 2 CLI-direct adoption flow.
+ *
+ * `wildo registry adopt` takes existing app code that fits the
+ * Wildo module-artifact shape and prepares it for publication
+ * (KD-14). Adoption is intentionally CLI-DIRECT (Review-pass-3 /
+ * MEDIUM-G) — it only reads source slices and stages files. AST
+ * mutations on the host app's source are NOT part of adopt; if a
+ * future flow needs them, they go through the companion HTTP
+ * surface like every other source-mutating verb.
+ *
+ * Service surface:
+ *   - `discoverModuleFiles(saasRoot, manifest)` — walks each
+ *     declared `boundaries.*` allow-list and returns the set of
+ *     files that exist on disk and are within the boundary.
+ *   - `adoptToStaging(saasRoot, manifest)` — clears + populates
+ *     `<saasRoot>/.wildo-saas/generated/modules-artifacts/<id>/`
+ *     with the manifest + every discovered file, then computes
+ *     the staging digest. Phase 6 plugs this into the publish
+ *     flow.
+ */
+
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import type { ModuleManifest } from '@wildo-ai/platform-config-lib';
+import { ModulePackagerService, type StagingPaths } from './module-packager.service';
+
+export interface AdoptionPlan {
+  /** Per-layer file list, relative to saas root. */
+  files: readonly string[];
+  /** Empty when every declared boundary contributed at least one file. */
+  emptyBoundaries: readonly string[];
+}
+
+export interface AdoptionResult {
+  manifest: ModuleManifest;
+  staging: StagingPaths;
+  /** Files that were copied into the staging root. */
+  staged: readonly string[];
+  /** sha256 digest of the staged tree (matches `Sha256DigestSchema`). */
+  digest: string;
+}
+
+async function fileExists(absPath: string): Promise<boolean> {
+  try {
+    const stat = await fs.stat(absPath);
+    return stat.isFile() || stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function walkBoundary(
+  saasRoot: string,
+  appRelative: string,
+): Promise<string[]> {
+  const abs = path.resolve(saasRoot, appRelative);
+  if (!(await fileExists(abs))) return [];
+  const stat = await fs.stat(abs);
+  if (stat.isFile()) return [appRelative];
+  const out: string[] = [];
+  const queue: string[] = [appRelative];
+  while (queue.length > 0) {
+    const cur = queue.shift()!;
+    const entries = await fs.readdir(path.resolve(saasRoot, cur), { withFileTypes: true });
+    for (const entry of entries) {
+      const rel = path.join(cur, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(rel);
+      } else if (entry.isFile()) {
+        out.push(rel);
+      }
+    }
+  }
+  return out;
+}
+
+export const ModuleAdopterService = {
+  /**
+   * Walk every declared `boundaries.*` allow-list and return the
+   * files that actually exist on disk.
+   */
+  async discoverModuleFiles(
+    saasRoot: string,
+    manifest: ModuleManifest,
+  ): Promise<AdoptionPlan> {
+    const boundaries = manifest.boundaries;
+    if (!boundaries) {
+      return { files: [], emptyBoundaries: [] };
+    }
+    const layers: ReadonlyArray<keyof typeof boundaries> = [
+      'specifications',
+      'shared',
+      'frontend',
+      'backend',
+      'minions',
+      'workers',
+    ];
+    const aggregate = new Set<string>();
+    const empty: string[] = [];
+    for (const layer of layers) {
+      const allows = boundaries[layer];
+      let layerCount = 0;
+      for (const rel of allows) {
+        const collected = await walkBoundary(saasRoot, rel);
+        for (const file of collected) aggregate.add(file);
+        layerCount += collected.length;
+      }
+      if (allows.length > 0 && layerCount === 0) empty.push(layer);
+    }
+    return {
+      files: [...aggregate].sort(),
+      emptyBoundaries: empty,
+    };
+  },
+
+  /**
+   * Stage the module from existing app source. Idempotent — calling
+   * twice with the same source produces the same digest.
+   */
+  async adoptToStaging(
+    saasRoot: string,
+    manifest: ModuleManifest,
+  ): Promise<AdoptionResult> {
+    const plan = await this.discoverModuleFiles(saasRoot, manifest);
+    const { staging, written } = await this.runAdoptionPlan(saasRoot, manifest, plan);
+    const digest = await ModulePackagerService.computeStagingDigest(saasRoot, manifest.id);
+    return { manifest, staging, staged: written, digest };
+  },
+
+  /**
+   * Re-usable apply step: writes manifest + copies every file in
+   * the plan. Exposed so Phase 6 publish can reuse it after a
+   * separate staging-prep step.
+   */
+  async runAdoptionPlan(
+    saasRoot: string,
+    manifest: ModuleManifest,
+    plan: AdoptionPlan,
+  ): Promise<{ staging: StagingPaths; written: readonly string[] }> {
+    const staging = await ModulePackagerService.stageFresh(saasRoot, manifest.id);
+    await ModulePackagerService.writeManifest({ saasRoot, manifest });
+    const written: string[] = [];
+    for (const appRelativePath of plan.files) {
+      const result = await ModulePackagerService.copyFile({
+        saasRoot,
+        moduleId: manifest.id,
+        appRelativePath,
+        manifest,
+      });
+      written.push(result.appRelativePath);
+    }
+    return { staging, written };
+  },
+} as const;

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

@@ -0,0 +1,251 @@
+/**
+ * `ModulePackagerService` — Phase 2 staging logic for module
+ * publishing.
+ *
+ * Per KD-8 / `module-registry-analysis.md`:
+ *   - Published artifacts are zip archives staged under
+ *     `<saasRoot>/.wildo-saas/generated/modules-artifacts/<module.id>/`.
+ *   - The staged folder is the source of the artifact. It must
+ *     include the `wildo.module.json` manifest, copied source
+ *     files, and dependency declarations.
+ *
+ * Phase 2 ships the staging-folder primitives (path resolution,
+ * stage-fresh, copy-source-tree, write-manifest, compute-digest).
+ * Phase 6 wires `wildo registry publish` to call these and the zip
+ * step. Phase 5 install consumes the same digest.
+ *
+ * Hard contracts:
+ *   - Staging is always a fresh tree per call (`stageFresh`
+ *     removes the destination first). The artifact's content
+ *     digest is over-the-wire deterministic — leftover bytes
+ *     from a previous failed stage MUST NOT leak into the digest.
+ *   - The staged tree is a CHILD of `<saasRoot>/.wildo-saas/`,
+ *     never reaches outside `saasRoot`.
+ *   - Boundary enforcement (KD-12) lives in this service: the
+ *     staging primitive rejects file paths that escape the
+ *     declared `boundaries.<layer>` allow-list, so a publish
+ *     can never claim app surface it doesn't own.
+ */
+
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import {
+  ModuleManifestSchema,
+  RegistryBoundaryViolationError,
+  type ModuleManifest,
+  type ModuleManifestBoundaries,
+} 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. */
+  stagingRoot: string;
+  /** Absolute path to the manifest file inside the staging root. */
+  manifestPath: string;
+}
+
+/**
+ * Resolve the per-module staging paths. Pure path arithmetic — no
+ * fs side effects.
+ */
+export function getModuleStagingPaths(saasRoot: string, moduleId: string): StagingPaths {
+  if (!moduleId.includes('/')) {
+    // 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
+    // not found); a malformed `moduleId` argument is a developer
+    // contract violation that downstream `isRegistryError(err)`
+    // handlers should NOT catch. `TypeError` keeps the error visible
+    // 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").`,
+    );
+  }
+  const stagingRoot = path.resolve(saasRoot, MODULES_ARTIFACTS_RELATIVE_DIR, moduleId);
+  return {
+    stagingRoot,
+    manifestPath: path.join(stagingRoot, MANIFEST_FILE_NAME),
+  };
+}
+
+/**
+ * Returns `true` iff `child` is the same path as `parent` or
+ * a descendant of it. Both arguments are expected to be absolute,
+ * already resolved (no `..` segments). Tail-`/` arithmetic prevents
+ * the classic `/foo/barx` → `/foo/bar` false-positive.
+ *
+ * Extracted as a helper (5th-pass C-L2) so the boundary check below
+ * and the future zip-slip / symlink-escape guards in this package
+ * share one reading of the containment rule.
+ *
+ * 6th-pass C-L1 — root edge case: when `parent` is the filesystem
+ * root (`/` on POSIX, `C:\` on Windows), appending `path.sep` would
+ * produce `//` or `C:\\` and `startsWith` would reject every child.
+ * Treat the root as a special case: any absolute child path is
+ * "inside" the root by definition. Vanishingly unlikely in practice
+ * (containerized SaaS roots are not literally `/`) but the helper
+ * is also reusable for zip-slip guards where the assumption is
+ * weaker.
+ */
+function isPathInside(child: string, parent: string): boolean {
+  // Special-case the filesystem root: any absolute child is inside it.
+  if (parent === path.sep || /^[a-zA-Z]:[\\/]?$/.test(parent)) {
+    return path.isAbsolute(child);
+  }
+  const childWithSep = child + path.sep;
+  const parentWithSep = parent + path.sep;
+  return childWithSep.startsWith(parentWithSep);
+}
+
+/**
+ * Verify a candidate file path is contained inside one of the
+ * manifest's declared `boundaries` (KD-12). Returns the resolved
+ * absolute path on success; throws `RegistryBoundaryViolationError`
+ * otherwise.
+ */
+export function assertWithinBoundaries(
+  saasRoot: string,
+  moduleId: string,
+  appRelativePath: string,
+  boundaries: ModuleManifestBoundaries | undefined,
+): string {
+  const absolute = path.resolve(saasRoot, appRelativePath);
+  // Path must stay inside saasRoot (no `..` escapes).
+  if (!isPathInside(absolute, path.resolve(saasRoot))) {
+    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;
+  // The candidate must be inside at least one declared boundary.
+  const isInside = allowed.some((rel) => isPathInside(absolute, path.resolve(saasRoot, rel)));
+  if (!isInside) {
+    throw new RegistryBoundaryViolationError(moduleId, appRelativePath);
+  }
+  return absolute;
+}
+
+export const ModulePackagerService = {
+  /**
+   * Compute the per-module staging paths.
+   */
+  paths(saasRoot: string, moduleId: string): StagingPaths {
+    return getModuleStagingPaths(saasRoot, moduleId);
+  },
+
+  /**
+   * Remove and recreate the staging root. The freshness guarantee
+   * is critical for digest determinism — `stageFresh` is the only
+   * way to enter the per-module staging root.
+   */
+  async stageFresh(saasRoot: string, moduleId: string): Promise<StagingPaths> {
+    const paths = getModuleStagingPaths(saasRoot, moduleId);
+    await fs.rm(paths.stagingRoot, { recursive: true, force: true });
+    await fs.mkdir(paths.stagingRoot, { recursive: true });
+    return paths;
+  },
+
+  /**
+   * Copy a single file from the app source into the staging tree.
+   * Path is verified against the manifest's declared boundaries
+   * (KD-12) — files outside `boundaries.*` are rejected with
+   * `RegistryBoundaryViolationError`. The relative path INSIDE the
+   * staging root mirrors the relative path inside the saas root,
+   * so callers don't need to translate paths between the two
+   * trees.
+   */
+  async copyFile(args: {
+    saasRoot: string;
+    moduleId: string;
+    appRelativePath: string;
+    manifest: ModuleManifest;
+  }): Promise<{ stagedAbsolute: string; appRelativePath: string }> {
+    const { saasRoot, moduleId, appRelativePath, manifest } = args;
+    const sourceAbsolute = assertWithinBoundaries(
+      saasRoot,
+      moduleId,
+      appRelativePath,
+      manifest.boundaries,
+    );
+    const { stagingRoot } = getModuleStagingPaths(saasRoot, moduleId);
+    const destAbsolute = path.join(stagingRoot, appRelativePath);
+    await fs.mkdir(path.dirname(destAbsolute), { recursive: true });
+    await fs.copyFile(sourceAbsolute, destAbsolute);
+    return { stagedAbsolute: destAbsolute, appRelativePath };
+  },
+
+  /**
+   * Validate the manifest, then write `wildo.module.json` into the
+   * staging root. Manifest authors who pass a typo-laden object
+   * get a Zod parse error here, before any zip work.
+   */
+  async writeManifest(args: {
+    saasRoot: string;
+    manifest: ModuleManifest;
+  }): Promise<{ manifestPath: string; manifest: ModuleManifest }> {
+    const validated = ModuleManifestSchema.parse(args.manifest);
+    const { manifestPath, stagingRoot } = getModuleStagingPaths(args.saasRoot, validated.id);
+    await fs.mkdir(stagingRoot, { recursive: true });
+    await fs.writeFile(manifestPath, JSON.stringify(validated, null, 2) + '\n', 'utf8');
+    return { manifestPath, manifest: validated };
+  },
+
+  /**
+   * Compute the sha256 digest of every file in the staging tree, in
+   * stable lexicographic path order. Returns the canonical
+   * `sha256:<64-hex>` form.
+   *
+   * The digest is over-the-wire deterministic for the same set of
+   * staged files because:
+   *   1. File order is sorted lexicographically (no fs traversal
+   *      randomness leaks in).
+   *   2. The path prefix is the relative-from-staging-root path
+   *      (no absolute-path noise).
+   *   3. We append the file content bytes verbatim.
+   */
+  async computeStagingDigest(saasRoot: string, moduleId: string): Promise<string> {
+    const { stagingRoot } = getModuleStagingPaths(saasRoot, moduleId);
+    const files = await collectFilesRelative(stagingRoot, '');
+    // Normalize separators to POSIX before sorting + hashing — the
+    // digest must reproduce across platforms for the same staged
+    // tree, so the bytes fed into the hash cannot depend on the
+    // publisher's OS path-separator convention.
+    const normalized = files.map((f) => f.split(path.sep).join(path.posix.sep));
+    normalized.sort();
+    const hash = createHash('sha256');
+    for (const rel of normalized) {
+      const abs = path.join(stagingRoot, rel.split(path.posix.sep).join(path.sep));
+      hash.update(rel);
+      hash.update('\0');
+      hash.update(await fs.readFile(abs));
+      hash.update('\0');
+    }
+    return `sha256:${hash.digest('hex')}`;
+  },
+} as const;
+
+async function collectFilesRelative(rootAbs: string, prefix: string): Promise<string[]> {
+  const here = path.join(rootAbs, prefix);
+  const entries = await fs.readdir(here, { withFileTypes: true });
+  const out: string[] = [];
+  for (const entry of entries) {
+    const rel = path.join(prefix, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...(await collectFilesRelative(rootAbs, rel)));
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out;
+}

package/src/services/provider-materialization-hook.ts

@@ -0,0 +1,54 @@
+/**
+ * `runProviderMaterializationHook` — Phase 0.5 dry-run hook.
+ *
+ * Phase 2 superseded this by `runProviderSync` (the real
+ * `wildo config sync --domain config` shell-out with classified
+ * failure surfaces). This file is kept as a thin
+ * `dryRun: true` forwarder so the Phase 0.5 lockfile-smoke
+ * command and any external caller continue to work unchanged.
+ *
+ * @deprecated Phase 2+ flows MUST call `runProviderSync` directly.
+ *   This forwarder will be removed once Wonder Todos's
+ *   `lockfile-smoke` command is rewritten in the Phase 4 CLI
+ *   read-flow series.
+ */
+
+import { PROVIDER_LOCK_SECTION_PATH } from '@wildo-ai/platform-config-lib';
+import { runProviderSync } from './provider-sync-runner';
+import type { RegistryClientLogger } from './types';
+
+export interface ProviderMaterializationHookInput {
+  saasRoot: string;
+  reason: 'install' | 'update' | 'remove' | 'adopt' | 'smoke';
+  log?: RegistryClientLogger;
+}
+
+export interface ProviderMaterializationHookResult {
+  invoked: true;
+  mode: 'dry-run' | 'shell-out';
+  performedFsWrite: false;
+  providerJsonRelativePaths: readonly string[];
+  providerSourceRelativePath: string;
+  providerLockSectionPath: typeof PROVIDER_LOCK_SECTION_PATH;
+  reason: ProviderMaterializationHookInput['reason'];
+}
+
+export async function runProviderMaterializationHook(
+  input: ProviderMaterializationHookInput,
+): Promise<ProviderMaterializationHookResult> {
+  const result = await runProviderSync({
+    saasRoot: input.saasRoot,
+    reason: input.reason,
+    log: input.log,
+    dryRun: true,
+  });
+  return {
+    invoked: true,
+    mode: result.mode,
+    performedFsWrite: false,
+    providerJsonRelativePaths: result.providerJsonRelativePaths,
+    providerSourceRelativePath: result.providerSourceRelativePath,
+    providerLockSectionPath: result.providerLockSectionPath,
+    reason: result.reason,
+  };
+}