@ws-test-realm/admin-kit 0.1.8 → 0.1.11

package/bin/ws-modules.js

@@ -142,10 +142,11 @@ async function main() {
     process.exit(1);
   }
 
+  // No positional but step flags present → implicit `all`. Lets npm scripts
+  // like `"wire": "ws-modules --build --pack --deploy"` run cleanly without
+  // requiring callers to remember `-- all`.
   if (!argv.positional.length) {
-    console.error("ws-modules: need module names or `all`.");
-    console.error(USAGE);
-    process.exit(1);
+    argv.positional.push("all");
   }
 
   let restrictTo;

package/bin/ws-purge.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// ws-purge — strip prior federation contributions across an admin-modules
+// workspace's deploy targets (jars + ext dirs) + the host's .federation/<id>/
+// types dirs. Mirrors `ws-modules --deploy`'s target-resolution exactly so the
+// two stay in lockstep (same wsconfig override > package.json rules).
+//
+// Usage:
+//   ws-purge                       # all remotes, each by own resolved target
+//   ws-purge jar                   # only jar-targeted remotes
+//   ws-purge ext                   # only ext-targeted remotes
+//   ws-purge jar <pathtojar>       # purge a specific jar by path (drops every
+//                                    META-INF/federation/<*>/, regardless of
+//                                    which project owned it)
+//   ws-purge <name>...             # restrict to those modules (each by own
+//                                    target)
+//   ws-purge <name>... jar         # restrict + require jar-targeted; errors
+//                                    on mismatch with hint to use
+//                                    `ws-purge jar <pathtojar>`
+//   ws-purge <name>... ext         # restrict + require ext-targeted
+//
+// End-of-run report lists every target acted on (path + entries dropped or
+// dir removed), every skipped target with reason, and every error.
+
+const path = require("path");
+const fs = require("fs");
+const { purgeRemotes, purgeJarPath } = require("../lib/purge-remotes");
+
+const USAGE = `ws-purge [<name>...] [jar | ext] [<pathtojar>]
+
+Strip prior federation contributions across the workspace's deploy targets.
+
+Modes:
+  (default)                  every remote, each by its own resolved target
+  jar                        only jar-targeted remotes
+  ext                        only ext-targeted remotes
+  jar <pathtojar>            purge a specific jar by path (no module resolution)
+
+Restrict to specific modules by listing names first:
+  ws-purge crm shop-common
+  ws-purge crm jar             # errors if crm isn't jar-targeted
+  ws-purge crm ext             # errors if crm isn't ext-targeted
+
+The end-of-run report lists exactly what was purged.
+`;
+
+function parseArgv(argv) {
+  const tokens = argv.slice(2);
+  let mode = null;
+  let jarPath = null;
+  const names = [];
+
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === "--help" || t === "-h") {
+      process.stdout.write(USAGE);
+      process.exit(0);
+    }
+    if (t === "jar" || t === "ext") {
+      if (mode) {
+        throw new Error(`mode specified twice: ${mode} then ${t}`);
+      }
+      mode = t;
+      // Look ahead: if jar and next looks like a path, consume it
+      const next = tokens[i + 1];
+      if (mode === "jar" && next && /[/.]/.test(next)) {
+        jarPath = next;
+        i++;
+      }
+      continue;
+    }
+    names.push(t);
+  }
+
+  if (jarPath && names.length) {
+    throw new Error(
+      `\`jar <pathtojar>\` can't be combined with module names — the jar path purges that file regardless of which module owned it.`
+    );
+  }
+
+  return { mode, jarPath, names };
+}
+
+function main() {
+  let parsed;
+  try {
+    parsed = parseArgv(process.argv);
+  } catch (e) {
+    console.error(`ws-purge: ${e.message}`);
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  if (parsed.jarPath) {
+    const abs = path.resolve(parsed.jarPath);
+    if (!fs.existsSync(abs)) {
+      console.error(`ws-purge: jar not found at ${abs}`);
+      process.exit(1);
+    }
+    const { errors } = purgeJarPath(abs);
+    process.exit(errors.length ? 1 : 0);
+  }
+
+  const workspaceDir = process.cwd();
+  const { errors } = purgeRemotes({
+    workspaceDir,
+    restrictTo: parsed.names,
+    modeFilter: parsed.mode,
+    strict: parsed.mode !== null && parsed.names.length > 0,
+  });
+  process.exit(errors.length ? 1 : 0);
+}
+
+main();

package/lib/deploy-remotes.js

@@ -4,13 +4,31 @@ const { packIntoJar } = require("./pack-into-jar");
 const { loadOrder, partitionByKind } = require("./build-modules");
 const { findMatches } = require("./jar-glob");
 const { loadDeployContext, resolveTarget } = require("./target-resolution");
+const { promotePeerDeps, syncFederationWorkspace } = require("./federation-peers");
 
 function copyTypes(distLib, hostFederationDir) {
+  // Preserve any existing node_modules dir under the staged location —
+  // npm's workspace install populated it and the next syncFederationWorkspace
+  // run will reconcile. Replacing it on every type-copy would force a
+  // fresh per-lib install instead of letting npm hoist across siblings.
+  const preservedNodeModules = path.join(hostFederationDir, "node_modules");
+  let cached = null;
+  if (fs.existsSync(preservedNodeModules)) {
+    cached = preservedNodeModules + `.preserve-${process.pid}`;
+    fs.renameSync(preservedNodeModules, cached);
+  }
   if (fs.existsSync(hostFederationDir)) {
     fs.rmSync(hostFederationDir, { recursive: true, force: true });
   }
   fs.mkdirSync(hostFederationDir, { recursive: true });
   fs.cpSync(distLib, hostFederationDir, { recursive: true });
+  if (cached) {
+    fs.renameSync(cached, preservedNodeModules);
+  }
+  // Promote peerDependencies → dependencies in the staged package.json so
+  // npm's workspace install actually installs them. The producer's source
+  // package.json is untouched; this only affects the host-staged copy.
+  promotePeerDeps(hostFederationDir);
 }
 
 // Copy the federation artifact (dist/admin-remotes/<id>/) to the ext target
@@ -154,6 +172,21 @@ function deployRemotes({ workspaceDir, restrictTo = [], withDeps = false }) {
   }
 
   console.log(`\nDeployed ${results.length} module(s).`);
+
+  // Now that the .federation/<id>/ dirs are fresh, run a single workspace
+  // install at .federation/ to populate node_modules. npm hoists shared
+  // versions to .federation/node_modules/ and only nests on per-lib version
+  // conflicts. Consumers' TypeScript walks up from .federation/<id>/ and
+  // resolves transitive types without consumer-side dep management.
+  try {
+    syncFederationWorkspace(ctx.adminDir);
+  } catch (e) {
+    console.warn(
+      `\x1b[33mWarning:\x1b[0m federation peer install failed: ${e.message}`
+    );
+    console.warn(`  Consumer workspaces may fail to type-check federated libs.`);
+  }
+
   return { results };
 }
 

package/lib/federation-peers.js

@@ -0,0 +1,80 @@
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+// Mirror a federation lib's peerDependencies into its dependencies in the
+// STAGED package.json under <adminDir>/.federation/<id>/. ng-packagr emits
+// peerDependencies — the canonical contract for a published library — but
+// for our publish-less federation we want npm to actually INSTALL those
+// peers (so consuming workspaces' TypeScript can resolve their types via
+// walk-up from .federation/<id>/). Promoting peer → dep in the staged copy
+// only doesn't touch the producer's source.
+function promotePeerDeps(libDir) {
+  const pkgPath = path.join(libDir, "package.json");
+  if (!fs.existsSync(pkgPath)) return false;
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  if (!pkg.peerDependencies || !Object.keys(pkg.peerDependencies).length) {
+    return false;
+  }
+  pkg.dependencies = Object.assign({}, pkg.dependencies, pkg.peerDependencies);
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  return true;
+}
+
+// Reconcile the entire .federation/ dir as an npm workspace root. Lists
+// every lib subdir as a workspace, then runs `npm install` once — npm
+// hoists shared peer versions to .federation/node_modules/ and nests only
+// where individual libs disagree, automatically scoping conflicts the way
+// npm normally would.
+//
+// Idempotent. Re-runs at the end of every deploy.
+function syncFederationWorkspace(adminDir) {
+  const federationDir = path.join(adminDir, ".federation");
+  if (!fs.existsSync(federationDir)) return { installed: false };
+
+  const libs = listFederationLibs(federationDir);
+  if (!libs.length) return { installed: false };
+
+  writeWorkspaceManifest(federationDir, libs);
+
+  console.log(
+    `\n=== federation peers: install (${libs.length} workspace${libs.length === 1 ? "" : "s"}) ===`
+  );
+  console.log(`  at ${federationDir}`);
+  execSync("npm install --no-package-lock --no-audit --no-fund", {
+    cwd: federationDir,
+    stdio: "inherit",
+  });
+  return { installed: true, libs };
+}
+
+function listFederationLibs(federationDir) {
+  return fs
+    .readdirSync(federationDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((name) => {
+      if (name === "node_modules") return false;
+      return fs.existsSync(path.join(federationDir, name, "package.json"));
+    })
+    .sort();
+}
+
+function writeWorkspaceManifest(federationDir, libs) {
+  const pkg = {
+    name: "ws-federation-host",
+    private: true,
+    version: "0.0.0",
+    workspaces: libs.map((id) => `./${id}`),
+  };
+  fs.writeFileSync(
+    path.join(federationDir, "package.json"),
+    JSON.stringify(pkg, null, 2) + "\n"
+  );
+}
+
+module.exports = {
+  promotePeerDeps,
+  syncFederationWorkspace,
+  listFederationLibs,
+};

package/lib/purge-jar.js

@@ -2,22 +2,32 @@ const fs = require("fs");
 const path = require("path");
 const AdmZip = require("adm-zip");
 
-// Strip a federated remote contribution from a jar by dropping every entry
-// under META-INF/federation/<id>/. Inverse of packIntoJar. Returns
-// { jarPath, droppedEntries, hadContribution }.
+// Strip federated remote contributions from a jar by dropping entries under
+// META-INF/federation/.
+//
+// purgeJar({ jarPath, id }) — drops only META-INF/federation/<id>/.
+// purgeJar({ jarPath })     — drops every META-INF/federation/<*>/.
+//
+// Returns { jarPath, droppedEntries, droppedIds[], hadContribution }.
 function purgeJar({ jarPath, id }) {
   if (!fs.existsSync(jarPath)) {
     throw new Error(`Jar not found: ${jarPath}`);
   }
 
-  const contribRoot = `META-INF/federation/${id}/`;
+  const federationRoot = `META-INF/federation/`;
+  const targetPrefix = id ? `${federationRoot}${id}/` : federationRoot;
+
   const original = new AdmZip(jarPath);
   const out = new AdmZip();
 
   let dropped = 0;
+  const idsHit = new Set();
   for (const entry of original.getEntries()) {
-    if (entry.entryName.startsWith(contribRoot)) {
+    if (entry.entryName.startsWith(targetPrefix)) {
       dropped++;
+      const rest = entry.entryName.slice(federationRoot.length);
+      const slash = rest.indexOf("/");
+      if (slash > 0) idsHit.add(rest.slice(0, slash));
       continue;
     }
     if (entry.isDirectory) {
@@ -33,7 +43,12 @@ function purgeJar({ jarPath, id }) {
   }
 
   if (dropped === 0) {
-    return { jarPath, droppedEntries: 0, hadContribution: false };
+    return {
+      jarPath,
+      droppedEntries: 0,
+      droppedIds: [],
+      hadContribution: false,
+    };
   }
 
   const dir = path.dirname(jarPath);
@@ -44,7 +59,12 @@ function purgeJar({ jarPath, id }) {
   out.writeZip(tmp);
   fs.renameSync(tmp, jarPath);
 
-  return { jarPath, droppedEntries: dropped, hadContribution: true };
+  return {
+    jarPath,
+    droppedEntries: dropped,
+    droppedIds: [...idsHit].sort(),
+    hadContribution: true,
+  };
 }
 
 module.exports = { purgeJar };

package/lib/purge-remotes.js

@@ -3,118 +3,244 @@ const path = require("path");
 const { purgeJar } = require("./purge-jar");
 const { loadOrder, partitionByKind } = require("./build-modules");
 const { loadDeployContext, resolveTarget } = require("./target-resolution");
+const { syncFederationWorkspace } = require("./federation-peers");
 
-// Purge a single remote's deployed footprint:
-//   - jar target: drop META-INF/federation/<id>/ entries from the jar
-//   - ext target: remove <wpmRoot>/scripts/ext-admin-remotes/<id>/
-//   - always: remove host's <adminDir>/.federation/<id>/ types dir
-//
-// Uses the exact same target resolution as deploy — wsconfig override >
-// project package.json (target=ext | pom-derived artifactId). No part of the
-// jar location is implied from the project id; same abuse-resistance as deploy.
-function purgeOne({
-  workspaceDir,
-  id,
-  wpmRoot,
-  modulesFolder,
-  adminDir,
-  wsconfig,
-}) {
-  const hostFederationDir = path.join(adminDir, ".federation", id);
+// Per-remote purge action. Returns a structured action record.
+function purgeOne({ workspaceDir, id, ctx }) {
+  const hostFederationDir = path.join(ctx.adminDir, ".federation", id);
 
   const target = resolveTarget({
     workspaceDir,
     projectName: id,
-    wsconfig,
-    wpmRoot,
-    modulesFolder,
+    wsconfig: ctx.wsconfig,
+    wpmRoot: ctx.wpmRoot,
+    modulesFolder: ctx.modulesFolder,
   });
 
-  let artifactReport;
+  let artifact;
   if (target.kind === "jar") {
-    const result = purgeJar({ jarPath: target.jarPath, id });
-    artifactReport = {
+    const r = purgeJar({ jarPath: target.jarPath, id });
+    artifact = {
       kind: "jar",
       jarPath: target.jarPath,
       pomPath: target.pomPath,
       artifactId: target.artifactId,
-      ...result,
+      droppedEntries: r.droppedEntries,
+      hadContribution: r.hadContribution,
     };
   } else {
-    let removed = false;
-    if (fs.existsSync(target.extDir)) {
-      fs.rmSync(target.extDir, { recursive: true, force: true });
-      removed = true;
-    }
-    artifactReport = { kind: "ext", extDir: target.extDir, removedExtDir: removed };
+    const removed = fs.existsSync(target.extDir);
+    if (removed) fs.rmSync(target.extDir, { recursive: true, force: true });
+    artifact = { kind: "ext", extDir: target.extDir, removedExtDir: removed };
   }
 
-  let typesRemoved = false;
-  if (fs.existsSync(hostFederationDir)) {
+  const typesRemoved = fs.existsSync(hostFederationDir);
+  if (typesRemoved) {
     fs.rmSync(hostFederationDir, { recursive: true, force: true });
-    typesRemoved = true;
   }
 
-  return { ...artifactReport, hostFederationDir, typesRemoved };
+  return { id, kind: target.kind, ...artifact, hostFederationDir, typesRemoved };
 }
 
-function purgeRemotes({ workspaceDir, restrictTo = [], withDeps = false }) {
+// Purge across an admin-modules workspace.
+//
+// modeFilter: null | "jar" | "ext"
+//   null  → each remote is purged according to its own resolved target
+//   "jar" → only act on jar-targeted remotes (skip ext)
+//   "ext" → only act on ext-targeted remotes (skip jar)
+//
+// strict: when true and modeFilter is set with explicit restrictTo names,
+//   mismatches throw with an actionable error (suggests `ws-purge jar <path>`
+//   for jar-mismatch). When false (modeFilter without restrictTo), mismatches
+//   are silently filtered.
+function purgeRemotes({
+  workspaceDir,
+  restrictTo = [],
+  withDeps = false,
+  modeFilter = null,
+  strict = false,
+}) {
   const ctx = loadDeployContext(workspaceDir);
-
   const { order } = loadOrder({ workspaceDir, restrictTo, withDeps });
   const { remotes, libraries } = partitionByKind(workspaceDir, order);
 
-  console.log(`\n=== Purge order ===`);
-  remotes.forEach((n, i) => console.log(`  ${i + 1}. ${n}`));
+  console.log(`=== Purge ===`);
+  console.log(`  mode:    ${modeFilter || "auto (each by own target)"}`);
+  console.log(
+    `  scope:   ${restrictTo.length ? restrictTo.join(", ") : "all remotes"}`
+  );
   if (libraries.length) {
     console.log(
-      `  (skipping libraries: ${libraries.join(", ")} — wsmodules.kind=library)`
+      `  skipped libraries: ${libraries.join(", ")} (wsmodules.kind=library)`
     );
   }
+  console.log("");
+
+  const actions = [];
+  const skipped = [];
+  const errors = [];
 
-  const results = [];
   for (const id of remotes) {
-    console.log(`\n=== purge ${id} ===`);
+    let target;
     try {
-      const r = purgeOne({
+      target = resolveTarget({
         workspaceDir,
-        id,
+        projectName: id,
+        wsconfig: ctx.wsconfig,
         wpmRoot: ctx.wpmRoot,
         modulesFolder: ctx.modulesFolder,
-        adminDir: ctx.adminDir,
-        wsconfig: ctx.wsconfig,
       });
-      if (r.kind === "jar") {
-        console.log(`  target:         jar`);
-        console.log(`  jar:            ${r.jarPath}`);
-        if (r.artifactId) console.log(`  artifactId:     ${r.artifactId}`);
-        if (r.pomPath) console.log(`  pom:            ${r.pomPath}`);
-        if (r.hadContribution) {
-          console.log(`  dropped:        ${r.droppedEntries} entries`);
-        } else {
-          console.log(`  dropped:        (nothing to purge)`);
-        }
+    } catch (e) {
+      errors.push({ id, stage: "resolve", message: e.message });
+      continue;
+    }
+
+    if (modeFilter && target.kind !== modeFilter) {
+      if (strict) {
+        const hint =
+          modeFilter === "jar"
+            ? `Use \`ws-purge jar <pathtojar>\` to purge a specific jar by path.`
+            : `Use \`ws-purge\` (no mode) to purge by each module's own target.`;
+        errors.push({
+          id,
+          stage: "filter",
+          message: `${id} is ${target.kind}-targeted, not ${modeFilter}-targeted. ${hint}`,
+        });
+        continue;
+      }
+      skipped.push({ id, reason: `target is ${target.kind}, filter is ${modeFilter}` });
+      continue;
+    }
+
+    try {
+      const action = purgeOne({ workspaceDir, id, ctx });
+      actions.push(action);
+    } catch (e) {
+      errors.push({ id, stage: "purge", message: e.message });
+    }
+  }
+
+  reportActions({ actions, skipped, errors });
+
+  // Removed federation type dirs ⇒ workspaces list is stale; resync so
+  // the remaining libs stay correctly installed (and orphaned ones stop
+  // claiming workspace slots).
+  if (actions.some((a) => a.typesRemoved)) {
+    try {
+      syncFederationWorkspace(ctx.adminDir);
+    } catch (e) {
+      console.warn(
+        `\x1b[33mWarning:\x1b[0m federation peer resync failed: ${e.message}`
+      );
+    }
+  }
+
+  return { actions, skipped, errors };
+}
+
+// Escape hatch: purge a specific jar by path, dropping every
+// META-INF/federation/<*>/ entry regardless of which workspace owns it.
+function purgeJarPath(jarPath) {
+  console.log(`=== Purge ===`);
+  console.log(`  mode:    jar (specific path)`);
+  console.log(`  jar:     ${jarPath}`);
+  console.log("");
+
+  const actions = [];
+  const errors = [];
+  try {
+    const r = purgeJar({ jarPath });
+    actions.push({
+      id: null,
+      kind: "jar",
+      jarPath,
+      droppedEntries: r.droppedEntries,
+      droppedIds: r.droppedIds,
+      hadContribution: r.hadContribution,
+      hostFederationDir: null,
+      typesRemoved: false,
+    });
+  } catch (e) {
+    errors.push({ id: jarPath, stage: "purge", message: e.message });
+  }
+
+  reportActions({ actions, skipped: [], errors });
+  return { actions, skipped: [], errors };
+}
+
+function reportActions({ actions, skipped, errors }) {
+  console.log(`=== Actions ===`);
+  if (!actions.length) {
+    console.log(`  (nothing purged)`);
+  }
+  for (const a of actions) {
+    const label = a.id ? a.id : "(by path)";
+    if (a.kind === "jar") {
+      if (a.hadContribution) {
+        const ids = a.droppedIds && a.droppedIds.length
+          ? ` (ids: ${a.droppedIds.join(", ")})`
+          : "";
+        console.log(
+          `  ${label}  jar   purged ${a.droppedEntries} entries from ${a.jarPath}${ids}`
+        );
       } else {
-        console.log(`  target:         ext`);
-        console.log(`  ext dir:        ${r.extDir}`);
-        console.log(`  ext dir:        ${r.removedExtDir ? "removed" : "(absent)"}`);
+        console.log(
+          `  ${label}  jar   no contribution to purge in ${a.jarPath}`
+        );
       }
+    } else {
+      console.log(
+        `  ${label}  ext   ${a.removedExtDir ? "removed" : "(absent)"} ${a.extDir}`
+      );
+    }
+    if (a.hostFederationDir) {
       console.log(
-        `  host types:     ${r.typesRemoved ? "removed" : "(absent)"} (${r.hostFederationDir})`
+        `       host types ${a.typesRemoved ? "removed" : "(absent)"}: ${a.hostFederationDir}`
       );
-      results.push({ id, ok: true, ...r });
-    } catch (err) {
-      console.error(`  \x1b[31mfailed:\x1b[0m ${err.message}`);
-      results.push({ id, ok: false, error: err.message });
     }
   }
 
-  const ok = results.filter((r) => r.ok).length;
-  const failed = results.length - ok;
+  if (skipped.length) {
+    console.log(`\n=== Skipped ===`);
+    for (const s of skipped) console.log(`  ${s.id}: ${s.reason}`);
+  }
+
+  if (errors.length) {
+    console.log(`\n=== Errors ===`);
+    for (const e of errors)
+      console.log(`  \x1b[31m${e.id}\x1b[0m [${e.stage}] ${e.message}`);
+  }
+
+  const jars = actions.filter((a) => a.kind === "jar");
+  const exts = actions.filter((a) => a.kind === "ext");
+  const typesRemoved = actions.filter((a) => a.typesRemoved).length;
+  const noopJars = jars.filter((a) => !a.hadContribution).length;
+  const removedExt = exts.filter((a) => a.removedExtDir).length;
+
+  console.log(`\n=== Summary ===`);
   console.log(
-    `\nPurged ${ok} module(s)${failed ? `, ${failed} failed` : ""}.`
+    `  acted on ${actions.length} target(s): ${jars.length} jar, ${exts.length} ext`
   );
-  return { results };
+  if (jars.length) {
+    const totalEntries = jars.reduce((s, a) => s + (a.droppedEntries || 0), 0);
+    console.log(
+      `  jar:  ${totalEntries} entries dropped` +
+        (noopJars ? `; ${noopJars} jar(s) had no contribution` : "")
+    );
+  }
+  if (exts.length) {
+    console.log(
+      `  ext:  ${removedExt} dir(s) removed` +
+        (exts.length - removedExt
+          ? `; ${exts.length - removedExt} already absent`
+          : "")
+    );
+  }
+  if (typesRemoved) {
+    console.log(`  host: ${typesRemoved} .federation/<id>/ dir(s) removed`);
+  }
+  if (skipped.length) console.log(`  skipped: ${skipped.length}`);
+  if (errors.length) console.log(`  \x1b[31merrors: ${errors.length}\x1b[0m`);
 }
 
-module.exports = { purgeRemotes, purgeOne };
+module.exports = { purgeRemotes, purgeOne, purgeJarPath };

package/lib/webpack-factory.js

@@ -1,5 +1,7 @@
+const fs = require("fs");
 const path = require("path");
 const Module = require("module");
+const TsconfigPathsPlugin = require("tsconfig-paths-webpack-plugin");
 
 // Build the in-memory webpack config used to produce a federated remote
 // from a single synthetic entry that re-exports the lib's public API.
@@ -30,6 +32,19 @@ function buildWebpackConfig({
 
   const remoteOutDir = path.join(outDir, id, "remote");
 
+  // tsconfig.federation.json is the SSOT for cross-workspace paths
+  // (`@ws-remote/*` → `<adminDir>/.federation/*`, sibling lib aliases,
+  // etc.). Without this plugin webpack ignores tsconfig `paths` and
+  // walks node_modules — which fails for cross-workspace federation
+  // siblings that only live in the host's federation dir.
+  const federationTsconfig = path.join(workspaceDir, "tsconfig.federation.json");
+  const resolvePlugins = [];
+  if (fs.existsSync(federationTsconfig)) {
+    resolvePlugins.push(
+      new TsconfigPathsPlugin({ configFile: federationTsconfig })
+    );
+  }
+
   return {
     mode: "production",
     entry: syntheticEntry,
@@ -56,6 +71,7 @@ function buildWebpackConfig({
     },
     resolve: {
       alias: aliasMap,
+      plugins: resolvePlugins,
       extensions: [".ts", ".js", ".mjs", ".json"],
       // ngcc rewrites Angular packages in-place but leaves the
       // originals next to them, exposing both via package.json fields

package/lib/wire-host.js

@@ -53,6 +53,16 @@ function rebuildFederationTsconfig(workspaceDir) {
     federationTarget = path.join(hostDir, ".federation", "*");
     paths["@ws-remote/*"] = [federationTarget];
   }
+  // Catch-all fallback: any unresolved import resolves against this
+  // workspace's own node_modules. Required for cross-workspace federation
+  // siblings (e.g. @ws-remote/ws-framework) whose .d.ts files reference
+  // transitive deps (@angular/material/form-field, etc.) — TS walks up
+  // from the .d.ts file's location to find node_modules, but federation
+  // remotes live under <wpmRoot>/admin/.federation/ outside any consumer
+  // workspace's tree. This catch-all lets TS fall back to the consumer's
+  // node_modules regardless of where the .d.ts lives. Must come AFTER
+  // specific paths so they win on prefix match.
+  paths["*"] = ["./node_modules/*"];
   // tsconfig.federation.json is the leaf of the extends chain. Its single
   // responsibility now is to combine the workspace-local `paths` with the
   // canonical compiler options from @ws-test-realm/devkit/tsconfig.base.json.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ws-test-realm/admin-kit",
-  "version": "0.1.8",
+  "version": "0.1.11",
   "description": "Workflow CLI + scaffolding for Wiresphere admin-modules workspaces. Ships `ws-init-workspace` (init/merge into a project, stamps @wiresphere/shared's `getOverrides()` into the workspace's npm overrides block), `ws-modules` (build/pack/deploy driver), `ws-generate-module`/`ws-drop-module`, `ws-wire-host`, `ws-wire-pom`, `ws-sync-paths`, and `ws-pack-remote`. Depends on @wiresphere/devkit (toolchain BOM, peerDeps); pairs with @wiresphere/shared (runtime BOM + MF share map + overrides manifest). Requires npm 9+ for overrides + peerDep resolution to coexist cleanly.",
   "license": "Artistic-2.0",
   "publishConfig": {
@@ -14,6 +14,7 @@
     "ws-generate-module": "./bin/ws-generate-module.js",
     "ws-drop-module": "./bin/ws-drop-module.js",
     "ws-modules": "./bin/ws-modules.js",
+    "ws-purge": "./bin/ws-purge.js",
     "ws-sync-paths": "./bin/ws-sync-paths.js"
   },
   "main": "lib/index.js",
@@ -28,6 +29,7 @@
     "@ws-test-realm/devkit": "^0.3.0",
     "@ws-test-realm/shared": "^0.3.0",
     "adm-zip": "^0.5.10",
-    "fast-xml-parser": "^4.3.0"
+    "fast-xml-parser": "^4.3.0",
+    "tsconfig-paths-webpack-plugin": "^4.1.0"
   }
 }

package/template/package.json

@@ -12,7 +12,7 @@
 		"build": "ws-modules --build",
 		"pack": "ws-modules --pack",
 		"deploy": "ws-modules --deploy",
-		"purge": "ws-modules --purge",
+		"purge": "ws-purge",
 		"wire": "ws-modules --build --pack --deploy"
 	},
 	"prettier": "@ws-test-realm/devkit/prettier.config.js",