@decocms/blocks-cli 7.66.1 → 7.66.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.66.1",
+  "version": "7.66.2",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -33,7 +33,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.66.1",
+    "@decocms/blocks": "7.66.2",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/generate-invoke.ts

@@ -46,6 +46,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Project, type PropertyAssignment, SyntaxKind } from "ts-morph";
+import { resolveInvokeSource } from "./lib/invokeSource";
 
 const args = process.argv.slice(2);
 function arg(name: string, fallback: string): string {
@@ -77,28 +78,15 @@ const PRIVILEGED_ACTIONS = new Set([
 
 function resolveAppsDir(): string {
   const explicit = arg("apps-dir", "");
+  const source = resolveInvokeSource(cwd, explicit || null);
+  if (source) return path.dirname(source);
+  // Preserve explicit-path errors and the legacy raw-checkout fallback used
+  // only by direct invocation. Published packages can be local or hoisted,
+  // with invoke.ts at the package root or under src/.
   if (explicit) return path.resolve(cwd, explicit);
-
-  // Try common locations: the installed @decocms/apps-vtex package first,
-  // then a raw apps-start checkout's vtex/ subdirectory as a legacy fallback
-  // for anyone still developing against the pre-split monorepo.
-  //
-  // For each root, invoke.ts may sit directly at the root (legacy dev
-  // checkouts) or under src/ — the published @decocms/apps-vtex tarball
-  // ships its sources under src/ (`"files": ["src"]`, `"main":
-  // "./src/index.ts"`), so on any site with npm-installed 7.x packages the
-  // file lives at node_modules/@decocms/apps-vtex/src/invoke.ts. The src/
-  // nesting doesn't affect the emitted imports: relative `./actions/*`
-  // specifiers are rewritten to `@decocms/apps-vtex/actions/*`, which the
-  // package's exports map points back into src/.
-  const roots = [
-    path.resolve(cwd, "node_modules/@decocms/apps-vtex"),
-    path.resolve(cwd, "../apps-start/vtex"),
-  ];
-  for (const root of roots) {
-    for (const c of [root, path.join(root, "src")]) {
-      if (fs.existsSync(path.join(c, "invoke.ts"))) return c;
-    }
+  const legacy = resolveInvokeSource(cwd, "../apps-start/vtex");
+  if (legacy) {
+    return path.dirname(legacy);
   }
   throw new Error("Could not find @decocms/apps-vtex. Use --apps-dir to specify its location.");
 }

package/scripts/generate-schema-workspaces.test.ts

@@ -0,0 +1,180 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+interface Schema {
+  type?: string;
+  $ref?: string;
+  allOf?: Schema[];
+  properties?: Record<string, Schema>;
+  required?: string[];
+}
+
+interface Meta {
+  manifest: { blocks: { loaders: Record<string, Schema>; apps: Record<string, Schema> } };
+  schema: { definitions: Record<string, Schema> };
+}
+
+describe("generate-schema workspace app packages", () => {
+  let workspace: string;
+  let site: string;
+
+  function write(relative: string, contents: string) {
+    const file = path.join(workspace, relative);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, contents);
+  }
+
+  function installApp(base: string, field: string) {
+    const directory = `${base}/node_modules/@decocms/apps-catalog`;
+    write(
+      `${directory}/package.json`,
+      JSON.stringify({
+        name: "@decocms/apps-catalog",
+        version: "1.0.0",
+        type: "module",
+        exports: { "./mod": "./src/mod.ts" },
+      }),
+    );
+    write(
+      `${directory}/src/mod.ts`,
+      `export interface Props { account: string; }
+       export default function app(_props: Props) { return {}; }`,
+    );
+    write(
+      `${directory}/src/loaders/product.ts`,
+      `export interface Props {
+         ${field}: string;
+         limit?: number;
+       }
+       export interface Product { sku: string; }
+       export default function loader(_props: Props): Product {
+         throw new Error("Fixture loaders must never execute during generation");
+       }`,
+    );
+  }
+
+  function runGenerator(script: string, args: string[] = []): string {
+    const result = spawnSync(
+      process.execPath,
+      ["--import", import.meta.resolve("tsx"), path.resolve(__dirname, script), ...args],
+      { cwd: site, encoding: "utf8", timeout: 30_000 },
+    );
+    expect(result.status, result.error?.message ?? result.stderr).toBe(0);
+    return result.stdout;
+  }
+
+  function readMeta(): Meta {
+    return JSON.parse(readFileSync(path.join(site, ".deco/meta.gen.json"), "utf8"));
+  }
+
+  function generate(): Meta {
+    runGenerator("generate-schema.ts");
+    return readMeta();
+  }
+
+  function definition(meta: Meta, reference: Schema): Schema {
+    expect(reference?.$ref).toBeDefined();
+    return meta.schema.definitions[reference.$ref!.replace("#/definitions/", "")];
+  }
+
+  beforeEach(() => {
+    workspace = mkdtempSync(path.join(tmpdir(), "schema-workspaces-"));
+    site = path.join(workspace, "apps/website");
+    write("package.json", JSON.stringify({ private: true, workspaces: ["apps/*"] }));
+    write(
+      "apps/website/package.json",
+      JSON.stringify({
+        name: "@example/website",
+        private: true,
+        dependencies: { "@decocms/apps-catalog": "1.0.0" },
+      }),
+    );
+    write(
+      "apps/website/tsconfig.json",
+      JSON.stringify({
+        compilerOptions: {
+          target: "ES2022",
+          module: "ESNext",
+          moduleResolution: "Bundler",
+          strict: true,
+        },
+      }),
+    );
+    write(
+      "apps/website/src/apps/catalog.ts",
+      'export { default } from "@decocms/apps-catalog/mod";',
+    );
+    mkdirSync(path.join(site, "src/sections"), { recursive: true });
+  });
+
+  afterEach(() => {
+    if (workspace) rmSync(workspace, { recursive: true, force: true });
+  });
+
+  it("emits loaders and their Props from an app hoisted above the website", () => {
+    installApp(".", "productId");
+
+    const meta = generate();
+    const loader = definition(meta, meta.manifest.blocks.loaders["catalog/loaders/product.ts"]);
+    expect(loader.properties).toMatchObject({
+      productId: { type: "string" },
+      limit: { type: "number" },
+    });
+    expect(loader.required).toEqual(["__resolveType", "productId"]);
+
+    const app = definition(meta, meta.manifest.blocks.apps["site/apps/catalog.ts"]);
+    const props = definition(meta, app.allOf!.find((part) => part.$ref)!);
+    expect(props.properties?.account).toMatchObject({ type: "string" });
+    expect(props.required).toEqual(["account"]);
+  }, 30_000);
+
+  it("uses the nearest app package without merging loaders from the hoisted copy", () => {
+    installApp(".", "parentProductId");
+    write(
+      "node_modules/@decocms/apps-catalog/src/loaders/parentOnly.ts",
+      "export default function loader(): string { return 'parent'; }",
+    );
+    installApp("apps/website", "localProductId");
+
+    const meta = generate();
+    const loader = definition(meta, meta.manifest.blocks.loaders["catalog/loaders/product.ts"]);
+    expect(loader.properties?.localProductId).toMatchObject({ type: "string" });
+    expect(loader.properties?.parentProductId).toBeUndefined();
+    expect(loader.required).toEqual(["__resolveType", "localProductId"]);
+    expect(meta.manifest.blocks.loaders["catalog/loaders/parentOnly.ts"]).toBeUndefined();
+  }, 30_000);
+
+  it("invalidates a warm schema cache when hoisted loader Props change at the same version", () => {
+    installApp(".", "productId");
+    const args = ["--only", "schema"];
+    const key = "catalog/loaders/product.ts";
+    const first = runGenerator("generate.ts", args);
+    expect(first).toMatch(/\[generate\] schema \d+ms \(fresh\)/);
+    const before = readMeta();
+    expect(
+      definition(before, before.manifest.blocks.loaders[key]).properties?.productId,
+    ).toMatchObject({ type: "string" });
+
+    const warm = runGenerator("generate.ts", args);
+    expect(warm).toMatch(/\[generate\] schema \d+ms \(cached(?:, content-verified)?\)/);
+
+    // A linked/workspace app can change its source without a version bump.
+    // Only the hoisted loader changes; the site and package manifest stay put.
+    const relative = "node_modules/@decocms/apps-catalog/src/loaders/product.ts";
+    const source = readFileSync(path.join(workspace, relative), "utf8");
+    write(relative, source.replace("productId: string;", "productId: number; category?: string;"));
+
+    const updated = runGenerator("generate.ts", args);
+    expect(updated).toMatch(/\[generate\] schema \d+ms \(fresh\)/);
+    const after = readMeta();
+    const loader = definition(after, after.manifest.blocks.loaders[key]);
+    expect(loader.properties).toMatchObject({
+      productId: { type: "number" },
+      category: { type: "string" },
+    });
+    expect(loader.required).toEqual(["__resolveType", "productId"]);
+  }, 30_000);
+});

package/scripts/generate-schema.ts

@@ -45,6 +45,7 @@ import {
   type Type,
 } from "ts-morph";
 import { isExcludedCodegenFile } from "./lib/codegenExclusions";
+import { resolvePackageDirectory } from "./lib/installedPackages";
 
 // ---------------------------------------------------------------------------
 // CLI arg parsing
@@ -1062,8 +1063,8 @@ function generateMeta(): MetaResponse {
   // ---------------------------------------------------------------------------
 
   /** Absolute path to the installed @decocms/apps-<namespace> package, if present. */
-  function getAppPkgDir(namespace: string): string {
-    return path.resolve(root, `node_modules/@decocms/apps-${namespace}`);
+  function getAppPkgDir(namespace: string): string | null {
+    return resolvePackageDirectory(root, `@decocms/apps-${namespace}`);
   }
 
   /** Detect installed app namespaces from src/apps/ bridge files. */
@@ -1093,6 +1094,7 @@ function generateMeta(): MetaResponse {
 
     for (const namespace of installed) {
       const pkgDir = getAppPkgDir(namespace);
+      if (!pkgDir) continue;
       const loadersDir = path.join(pkgDir, "src", "loaders");
       if (!fs.existsSync(loadersDir)) continue;
 

package/scripts/generate-workspaces.test.ts

@@ -0,0 +1,179 @@
+// @vitest-environment node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildPlan, parseCliOptions } from "./generate";
+
+const tsx = createRequire(import.meta.url).resolve("tsx/cli");
+const script = fileURLToPath(new URL("./generate.ts", import.meta.url));
+
+describe("generation in a workspace with hoisted dependencies", () => {
+  let workspace: string;
+  let site: string;
+
+  function write(root: string, relative: string, content: string): string {
+    const file = path.join(root, relative);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content);
+    return file;
+  }
+
+  function install(root: string, name: string, version = "7.48.4"): string {
+    const dir = path.join(root, "node_modules", name);
+    // Published packages need not export their root or package.json.
+    write(
+      dir,
+      "package.json",
+      JSON.stringify({ name, version, exports: { "./mod": "./src/mod.ts" } }),
+    );
+    return dir;
+  }
+
+  function plans(args: string[] = []) {
+    return Object.fromEntries(buildPlan(site, parseCliOptions(args)).map((p) => [p.name, p]));
+  }
+
+  function run(args: string[]) {
+    // Exercise --root too: the caller's cwd is the workspace, not the site.
+    const result = spawnSync(process.execPath, [tsx, script, "--root", "apps/website", ...args], {
+      cwd: workspace,
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    expect(result.status, result.stdout + result.stderr).toBe(0);
+    return result.stdout;
+  }
+
+  beforeEach(() => {
+    workspace = fs.mkdtempSync(path.join(os.tmpdir(), "generate-workspaces-"));
+    site = path.join(workspace, "apps", "website");
+    write(workspace, "package.json", JSON.stringify({ private: true, workspaces: ["apps/*"] }));
+    write(site, "package.json", JSON.stringify({ name: "website", type: "module" }));
+    write(site, "tsconfig.json", JSON.stringify({ compilerOptions: { jsx: "react-jsx" } }));
+    write(site, ".deco/blocks/Home.json", JSON.stringify({ name: "Home", path: "/" }));
+    write(site, "src/sections/Hero.tsx", "export default function Hero() { return null; }\n");
+    install(workspace, "@decocms/blocks");
+  });
+
+  afterEach(() => {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  });
+
+  it("detects hoisted Next.js and enables its manifest and section registry", () => {
+    install(workspace, "@decocms/nextjs");
+    const plan = plans();
+    expect(plan.manifest.enabled).toBe(true);
+    expect(plan.blocks.enabled).toBe(false);
+    expect(plan.sections.args).toContain("--registry");
+  });
+
+  it.each([
+    "nextjs",
+    "tanstack",
+  ])("uses the site's %s binding when siblings hoist both frameworks", (framework) => {
+    write(
+      site,
+      "package.json",
+      JSON.stringify({
+        name: "website",
+        dependencies: { [`@decocms/${framework}`]: "7.48.4" },
+      }),
+    );
+    install(workspace, "@decocms/nextjs");
+    install(workspace, "@decocms/tanstack");
+    install(workspace, "@tanstack/react-start");
+    const app = install(workspace, "@decocms/apps-vtex");
+    write(app, "src/invoke.ts", "export const invoke = {} as const;\n");
+    const plan = plans();
+    expect(plan.manifest.enabled).toBe(framework === "nextjs");
+    expect(plan.sections.args.includes("--registry")).toBe(framework === "nextjs");
+    expect(plan.blocks.enabled).toBe(framework === "tanstack");
+    expect(plan.invoke.enabled).toBe(framework === "tanstack");
+  });
+
+  it.each([
+    false,
+    true,
+  ])("generates invoke from hoisted packages (explicit apps directory: %s)", (explicit) => {
+    install(workspace, "@tanstack/react-start", "1.166.8");
+    const app = install(workspace, "@decocms/apps-vtex");
+    write(
+      app,
+      "src/invoke.ts",
+      `
+import { createInvokeFn } from "@decocms/tanstack/sdk/createInvoke";
+import { getOrCreateCart } from "./actions/checkout";
+import type { OrderForm } from "./types";
+export const invoke = {
+  vtex: { actions: {
+    getOrCreateCart: createInvokeFn(
+      (data: { orderFormId?: string }) => getOrCreateCart(data),
+    ) as unknown as (ctx: { data: { orderFormId?: string } }) => Promise<OrderForm>,
+  } },
+} as const;
+`,
+    );
+    expect(plans().invoke.enabled).toBe(true);
+    run([
+      "--only",
+      "invoke",
+      ...(explicit ? ["--apps-dir", "../../node_modules/@decocms/apps-vtex"] : []),
+    ]);
+    const output = fs.readFileSync(path.join(site, "src/server/invoke.gen.ts"), "utf8");
+    expect(output).toContain("getOrCreateCart");
+    expect(output).toContain("@decocms/apps-vtex/actions/checkout");
+  });
+
+  it("does not use a parent invoke contract when a local package shadows it", () => {
+    install(workspace, "@tanstack/react-start");
+    const hoisted = install(workspace, "@decocms/apps-vtex");
+    write(hoisted, "src/invoke.ts", "export const invoke = {};\n");
+    install(site, "@decocms/apps-vtex");
+    expect(plans().invoke.enabled).toBe(false);
+  });
+
+  it("fingerprints hoisted app sources and respects local package precedence and --skip-apps", () => {
+    const hoisted = install(workspace, "@decocms/apps-vtex");
+    const parentSource = write(hoisted, "src/loaders/product.ts", "export default () => [];\n");
+    const inputPaths = (args: string[] = []) =>
+      plans(args)
+        .schema.inputs()
+        .map(([rel]) => path.resolve(site, rel));
+    expect(inputPaths()).toContain(parentSource);
+    expect(inputPaths(["--skip-apps"])).not.toContain(parentSource);
+
+    const local = install(site, "@decocms/apps-vtex", "7.48.5");
+    const localSource = write(local, "src/loaders/local.ts", "export default () => [];\n");
+    expect(inputPaths()).toContain(localSource);
+    expect(inputPaths()).not.toContain(parentSource);
+  });
+
+  it("invalidates cached generation when a hoisted package version changes", () => {
+    run(["--only", "loaders"]);
+    const digests = JSON.parse(
+      fs.readFileSync(path.join(site, ".deco/generate.digests.json"), "utf8"),
+    );
+    expect(digests.generators.loaders.deco).toContain("@decocms/blocks@7.48.4");
+    expect(run(["--only", "loaders", "--dry-run"])).toContain("loaders: skip — cached");
+
+    install(workspace, "@decocms/blocks", "7.48.5");
+    expect(run(["--only", "loaders", "--dry-run"])).toContain("loaders: would run");
+  });
+
+  it("fingerprints the nearest package version, ignoring a shadowed parent's updates", () => {
+    install(site, "@decocms/blocks", "7.48.6");
+    run(["--only", "loaders"]);
+    const digests = JSON.parse(
+      fs.readFileSync(path.join(site, ".deco/generate.digests.json"), "utf8"),
+    );
+    expect(digests.generators.loaders.deco).toContain("@decocms/blocks@7.48.6");
+    expect(digests.generators.loaders.deco).not.toContain("@decocms/blocks@7.48.4");
+
+    install(workspace, "@decocms/blocks", "7.48.7");
+    expect(run(["--only", "loaders", "--dry-run"])).toContain("loaders: skip — cached");
+  });
+});

package/scripts/generate.ts

@@ -88,7 +88,7 @@
  *   - args:   the exact argv forwarded to that generator,
  *   - cli:    blocks-cli's own package version,
  *   - deco:   the resolved versions of every @decocms/* package in the
- *             site's node_modules (a lockstep bump invalidates everything),
+ *             site's module search path (a lockstep bump invalidates everything),
  *   - inputs: sha256 over the sorted (relPath, contentSha256) pairs of the
  *             generator's input set — CONTENT hashes, machine-independent.
  * Because the record is content-addressed, a FRESH CLONE with unchanged
@@ -127,6 +127,8 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { isExcludedCodegenFile } from "./lib/codegenExclusions";
+import { listScopedPackages, resolvePackageDirectory } from "./lib/installedPackages";
+import { resolveInvokeSource } from "./lib/invokeSource";
 
 // Bump when the digests file format or digest recipe changes — recorded in
 // every digest record so old files self-bust instead of mis-validating.
@@ -463,16 +465,9 @@ function readPkgVersion(pkgDir: string): string | null {
 
 function decoPackageVersions(cwd: string): Record<string, string> {
   const versions: Record<string, string> = {};
-  const scopeDir = path.join(cwd, "node_modules", "@decocms");
-  let names: string[];
-  try {
-    names = fs.readdirSync(scopeDir);
-  } catch {
-    return versions;
-  }
-  for (const name of names.sort()) {
-    const v = readPkgVersion(path.join(scopeDir, name));
-    if (v) versions[`@decocms/${name}`] = v;
+  for (const [name, dir] of listScopedPackages(cwd, "@decocms")) {
+    const v = readPkgVersion(dir);
+    if (v) versions[name] = v;
   }
   return versions;
 }
@@ -485,7 +480,25 @@ function ownVersion(): string {
 }
 
 function hasPackage(cwd: string, name: string): boolean {
-  return fs.existsSync(path.join(cwd, "node_modules", ...name.split("/"), "package.json"));
+  const dir = resolvePackageDirectory(cwd, name);
+  return dir !== null && fs.existsSync(path.join(dir, "package.json"));
+}
+
+function isNextjsSite(cwd: string): boolean {
+  // Sibling sites can hoist both bindings. Prefer this site's declaration so
+  // a TanStack workspace does not adopt a sibling's Next.js generation mode.
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+    const dependencies = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+      ...pkg.peerDependencies,
+      ...pkg.optionalDependencies,
+    };
+    if ("@decocms/nextjs" in dependencies) return hasPackage(cwd, "@decocms/nextjs");
+    if ("@decocms/tanstack" in dependencies) return false;
+  } catch {}
+  return hasPackage(cwd, "@decocms/nextjs");
 }
 
 // ---------------------------------------------------------------------------
@@ -508,20 +521,6 @@ export interface GeneratorPlan {
   outputs: string[];
 }
 
-/** Resolve generate-invoke's apps dir exactly like the generator does
- * (minus the legacy ../apps-start/vtex fallback, which is dev-checkout-only). */
-function resolveInvokeSource(cwd: string, appsDir: string | null): string | null {
-  const roots = appsDir
-    ? [path.resolve(cwd, appsDir)]
-    : [path.resolve(cwd, "node_modules/@decocms/apps-vtex")];
-  for (const root of roots) {
-    for (const c of [root, path.join(root, "src")]) {
-      if (fs.existsSync(path.join(c, "invoke.ts"))) return path.join(c, "invoke.ts");
-    }
-  }
-  return null;
-}
-
 export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
   const scriptsDir = path.dirname(fileURLToPath(import.meta.url));
   const blocksDirAbs = path.resolve(cwd, opts.blocksDir);
@@ -531,7 +530,7 @@ export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
 
   const blocksDirExists = fs.existsSync(blocksDirAbs);
   const sectionsDirExists = fs.existsSync(sectionsDirAbs);
-  const isNext = hasPackage(cwd, "@decocms/nextjs");
+  const isNext = isNextjsSite(cwd);
   const hasTanstackStart = hasPackage(cwd, "@tanstack/react-start");
 
   const blocksGenJson = path.join(".deco", "blocks.gen.json");
@@ -635,10 +634,12 @@ export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
       args: opts.appsDir ? ["--apps-dir", opts.appsDir] : [],
       stage: 1,
       ...enabledIf(
-        invokeSource !== null && hasTanstackStart,
+        invokeSource !== null && hasTanstackStart && !isNext,
         invokeSource === null
           ? "no apps invoke.ts found (@decocms/apps-vtex not installed and no --apps-dir)"
-          : "@tanstack/react-start not installed (invoke.gen.ts targets TanStack Start)",
+          : isNext
+            ? "@decocms/nextjs site (invoke.gen.ts targets TanStack Start)"
+            : "@tanstack/react-start not installed (invoke.gen.ts targets TanStack Start)",
       ),
       // invoke.ts is the file the generator parses; the surrounding package's
       // action/type sources are fingerprinted via the @decocms/* version set
@@ -692,13 +693,10 @@ export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
           ),
         ];
         if (!opts.skipApps) {
-          const scopeDir = path.join(cwd, "node_modules", "@decocms");
-          let names: string[] = [];
-          try {
-            names = fs.readdirSync(scopeDir).filter((n) => n.startsWith("apps-"));
-          } catch {}
-          for (const name of names.sort()) {
-            entries.push(...walkTree(cwd, path.join(scopeDir, name, "src"), [".ts", ".tsx"]));
+          for (const [name, dir] of listScopedPackages(cwd, "@decocms")) {
+            if (name.startsWith("@decocms/apps-")) {
+              entries.push(...walkTree(cwd, path.join(dir, "src"), [".ts", ".tsx"]));
+            }
           }
         }
         return sortEntries(entries);

package/scripts/lib/installedPackages.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/** Search from the consuming site, including ancestor node_modules directories
+ * used by workspace hoisting. Directory lookup also works with source-only
+ * checkouts and packages whose exports expose neither the root nor package.json. */
+function moduleDirectories(cwd: string, name: string): string[] {
+  return createRequire(path.resolve(cwd, "package.json")).resolve.paths(name) ?? [];
+}
+
+export function resolvePackageDirectory(cwd: string, name: string): string | null {
+  for (const modules of moduleDirectories(cwd, name)) {
+    const dir = path.join(modules, name);
+    if (fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory()) return dir;
+  }
+  return null;
+}
+
+/** Installed packages in a scope, keyed by full package name. The nearest
+ * copy wins, matching resolvePackageDirectory even with mixed local/hoisted
+ * installs; shadowed ancestor copies must not enter codegen fingerprints. */
+export function listScopedPackages(cwd: string, scope: string): Map<string, string> {
+  const packages = new Map<string, string>();
+  for (const modules of moduleDirectories(cwd, `${scope}/_`)) {
+    const scopeDir = path.join(modules, scope);
+    let names: string[];
+    try {
+      names = fs.readdirSync(scopeDir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      const fullName = `${scope}/${name}`;
+      const dir = path.join(scopeDir, name);
+      if (!packages.has(fullName) && fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory()) {
+        packages.set(fullName, dir);
+      }
+    }
+  }
+  return new Map([...packages].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}

package/scripts/lib/invokeSource.ts

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolvePackageDirectory } from "./installedPackages";
+
+/** Both the orchestrator and its child must parse the same invoke contract.
+ * Resolve the package first so a local copy without invoke.ts cannot silently
+ * pick up a different contract from a shadowed ancestor package. */
+export function resolveInvokeSource(cwd: string, appsDir: string | null): string | null {
+  const root = appsDir
+    ? path.resolve(cwd, appsDir)
+    : resolvePackageDirectory(cwd, "@decocms/apps-vtex");
+  if (!root) return null;
+  for (const dir of [root, path.join(root, "src")]) {
+    const file = path.join(dir, "invoke.ts");
+    if (fs.existsSync(file)) return file;
+  }
+  return null;
+}