@ws-test-realm/admin-kit 0.1.7

package/lib/pom.js

@@ -0,0 +1,84 @@
+const fs = require("fs");
+const path = require("path");
+
+// Pom parsing + module-scope path helpers.
+//
+// Scope rule: for a workspace at <workspace>, the module scope root is
+// path.dirname(workspace). All resolved pom paths must stay within that
+// directory. Validation runs at both wire time (ws-wire-pom) and deploy time.
+
+function getScopeRoot(workspaceDir) {
+  return path.dirname(path.resolve(workspaceDir));
+}
+
+function isWithinScope(workspaceDir, absPath) {
+  const scope = getScopeRoot(workspaceDir);
+  const rel = path.relative(scope, absPath);
+  return rel.length > 0 && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+function validatePomPath(workspaceDir, absPomPath) {
+  if (!fs.existsSync(absPomPath)) {
+    throw new Error(`Pom not found: ${absPomPath}`);
+  }
+  if (!fs.statSync(absPomPath).isFile()) {
+    throw new Error(`Pom path is not a file: ${absPomPath}`);
+  }
+  if (!isWithinScope(workspaceDir, absPomPath)) {
+    throw new Error(
+      `Pom path is outside module scope (${getScopeRoot(workspaceDir)}): ${absPomPath}`
+    );
+  }
+}
+
+// Resolve the absolute pom path for a project. If `pomField` is set in the
+// project's package.json (`wsmodules.pom`), it's a path relative to the
+// project dir — resolve + validate. Otherwise fall back to the scope-root
+// pom.xml. Throws if neither resolves to an existing pom.
+function resolveProjectPom(workspaceDir, projectName, pomField) {
+  if (pomField) {
+    const projectDir = path.join(workspaceDir, "projects", projectName);
+    const abs = path.resolve(projectDir, pomField);
+    validatePomPath(workspaceDir, abs);
+    return abs;
+  }
+  const fallback = path.join(getScopeRoot(workspaceDir), "pom.xml");
+  if (!fs.existsSync(fallback)) {
+    throw new Error(
+      `No pom found for ${projectName}: set wsmodules.pom in projects/${projectName}/package.json, place pom.xml at ${getScopeRoot(workspaceDir)}, or set wsmodules.target: "ext" to bypass jar deploy.`
+    );
+  }
+  return fallback;
+}
+
+// Read the project's own artifactId from a pom. fast-xml-parser yields a tree
+// where parent.artifactId is nested under `project.parent` and
+// dependency/plugin artifactIds are under their respective sections — so
+// `result.project.artifactId` is the project's own.
+function readArtifactId(absPomPath) {
+  const { XMLParser } = require("fast-xml-parser");
+  const xml = fs.readFileSync(absPomPath, "utf8");
+  const parser = new XMLParser({ ignoreAttributes: true });
+  const tree = parser.parse(xml);
+  const artifactId = tree && tree.project && tree.project.artifactId;
+  if (!artifactId || typeof artifactId !== "string") {
+    throw new Error(`Pom missing top-level <artifactId>: ${absPomPath}`);
+  }
+  return artifactId.trim();
+}
+
+// Compute the relative path to store in wsmodules.pom — relative from the
+// project dir, so it travels with the project on rename/move.
+function relativeFromProject(workspaceDir, projectName, absPomPath) {
+  const projectDir = path.join(workspaceDir, "projects", projectName);
+  return path.relative(projectDir, absPomPath);
+}
+
+module.exports = {
+  getScopeRoot,
+  isWithinScope,
+  validatePomPath,
+  resolveProjectPom,
+  readArtifactId,
+  relativeFromProject,
+};

package/lib/shared-deps.js

@@ -0,0 +1,90 @@
+// Build the `shared` map for ModuleFederationPlugin.
+//
+// Layers (later wins):
+//   1. sharedDescriptors() from @wiresphere/shared (host baseline:
+//      @angular/*, rxjs, etc.).
+//   2. Workspace-discovered libs (from alias map) as WORKSPACE_LIBS shape.
+//   3. Self-lib forced to import: false so the container does not load
+//      itself back through the shared scope.
+//   4. sharedExtras from pack.config.json (project overrides).
+//
+// Then for any entry left with `requiredVersion: 'auto'` we resolve the
+// version from <workspaceDir>/node_modules/<pkg>/package.json BEFORE handing
+// the map to share(). share()'s built-in auto-probe reads the workspace's
+// own package.json, which no longer lists Angular/rxjs/etc. directly — those
+// are pulled in transitively via @wiresphere/shared. Probing node_modules
+// closes that gap.
+const fs = require("fs");
+const path = require("path");
+
+function packageRootOf(key) {
+  if (key.startsWith("@")) {
+    const parts = key.split("/");
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : key;
+  }
+  return key.split("/")[0];
+}
+
+function tryReadVersion(workspaceDir, pkgRoot) {
+  const pkgJsonPath = path.join(
+    workspaceDir,
+    "node_modules",
+    pkgRoot,
+    "package.json"
+  );
+  try {
+    return JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")).version || null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveAutoVersions(map, workspaceDir) {
+  const out = {};
+  for (const [key, val] of Object.entries(map)) {
+    if (val && val.requiredVersion === "auto") {
+      const version = tryReadVersion(workspaceDir, packageRootOf(key));
+      out[key] = Object.assign({}, val, {
+        requiredVersion: version || false,
+      });
+    } else {
+      out[key] = val;
+    }
+  }
+  return out;
+}
+
+function buildSharedMap({ workspaceDir, aliasMap, selfId, sharedExtras }) {
+  const wsShared = require("@ws-test-realm/shared");
+  const { share } = require("@angular-architects/module-federation/webpack");
+
+  const WORKSPACE_LIBS = wsShared.WORKSPACE_LIBS || {
+    singleton: true,
+    strictVersion: false,
+    requiredVersion: false,
+  };
+
+  const map = Object.assign({}, wsShared.sharedDescriptors());
+
+  for (const libName of Object.keys(aliasMap)) {
+    if (libName.endsWith("-remote")) continue;
+    if (libName === selfId) {
+      if (!map[libName]) {
+        map[libName] = Object.assign({}, WORKSPACE_LIBS);
+      }
+    } else {
+      map[libName] = Object.assign({}, WORKSPACE_LIBS, {
+        import: false,
+      });
+    }
+  }
+
+  for (const [k, v] of Object.entries(sharedExtras || {})) {
+    map[k] = Object.assign({}, map[k] || {}, v);
+  }
+
+  const resolved = resolveAutoVersions(map, workspaceDir);
+  return share(resolved, workspaceDir);
+}
+
+module.exports = { buildSharedMap };

package/lib/synthetic-entry.js

@@ -0,0 +1,27 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+
+// Writes a temp directory containing a single `public-api.ts` that
+// re-exports everything from the lib's import path. Webpack's MF
+// `exposes['./Module']` points at this file; the import resolves
+// through the workspace alias for `<id>` (set up in webpack.resolve).
+function writeSyntheticEntry(id) {
+  const hash = crypto.randomBytes(4).toString("hex");
+  const dir = path.join(os.tmpdir(), "ws-pack-remote", `${id}-${hash}`);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, "public-api.ts");
+  fs.writeFileSync(file, `export * from '${id}';\n`, "utf8");
+  return { dir, file };
+}
+
+function cleanup(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch (e) {
+    // best-effort cleanup
+  }
+}
+
+module.exports = { writeSyntheticEntry, cleanup };

package/lib/template-copy.js

@@ -0,0 +1,136 @@
+const fs = require("fs");
+const path = require("path");
+
+// Copy non-package.json template files into destDir, skipping any path that
+// already exists. package.json gets a structured merge instead (see
+// mergePackageJson). Returns { copied: [...], skipped: [...] }.
+function copyTemplate(templateDir, destDir) {
+  if (!fs.existsSync(templateDir)) {
+    throw new Error(`Template not found: ${templateDir}`);
+  }
+  const copied = [];
+  const skipped = [];
+  for (const entry of fs.readdirSync(templateDir, { withFileTypes: true })) {
+    if (entry.name === "package.json") continue;
+    const src = path.join(templateDir, entry.name);
+    const dst = path.join(destDir, entry.name);
+    if (fs.existsSync(dst)) {
+      skipped.push(entry.name);
+      continue;
+    }
+    fs.cpSync(src, dst, { recursive: true });
+    copied.push(entry.name);
+  }
+  return { copied, skipped };
+}
+
+// Merge template package.json fields into existing package.json. On conflict
+// (key already present with a different shape/value), refuse and collect into
+// `conflicts`. Returns { conflicts: [{path, existing, incoming}], merged }
+// where `merged` is the resulting object (only valid if conflicts is empty).
+//
+// Merge rules per field:
+//   scripts            object: per-key add; conflict on different value
+//   dependencies       object: per-key add; conflict on different value
+//   devDependencies    same
+//   peerDependencies   same
+//   workspaces         array OR object: must equal incoming; conflict otherwise
+//   husky              object deep-merge; conflict on differing leaf values
+//   prettier           string or object: must equal incoming; conflict otherwise
+//   private            scalar: if missing or matches, set; conflict otherwise
+//   <anything else>    leave existing untouched (don't try to be clever)
+function mergePackageJson(existingPath, templatePath) {
+  const existing = JSON.parse(fs.readFileSync(existingPath, "utf8"));
+  const incoming = JSON.parse(fs.readFileSync(templatePath, "utf8"));
+  const conflicts = [];
+  const merged = { ...existing };
+
+  const mergeMap = (key) => {
+    if (!incoming[key]) return;
+    merged[key] = merged[key] || {};
+    for (const [k, v] of Object.entries(incoming[key])) {
+      if (k in merged[key]) {
+        if (JSON.stringify(merged[key][k]) !== JSON.stringify(v)) {
+          conflicts.push({
+            path: `${key}.${k}`,
+            existing: merged[key][k],
+            incoming: v,
+          });
+        }
+      } else {
+        merged[key][k] = v;
+      }
+    }
+  };
+
+  mergeMap("scripts");
+  mergeMap("dependencies");
+  mergeMap("devDependencies");
+  mergeMap("peerDependencies");
+
+  // husky deep-merge (object of objects)
+  if (incoming.husky) {
+    const eh = merged.husky || {};
+    const ih = incoming.husky;
+    const mh = { ...eh };
+    if (ih.hooks) {
+      mh.hooks = { ...(eh.hooks || {}) };
+      for (const [k, v] of Object.entries(ih.hooks)) {
+        if (k in mh.hooks && mh.hooks[k] !== v) {
+          conflicts.push({
+            path: `husky.hooks.${k}`,
+            existing: mh.hooks[k],
+            incoming: v,
+          });
+        } else {
+          mh.hooks[k] = v;
+        }
+      }
+    }
+    merged.husky = mh;
+  }
+
+  for (const scalar of ["prettier", "private"]) {
+    if (!(scalar in incoming)) continue;
+    if (scalar in existing) {
+      if (JSON.stringify(existing[scalar]) !== JSON.stringify(incoming[scalar])) {
+        conflicts.push({
+          path: scalar,
+          existing: existing[scalar],
+          incoming: incoming[scalar],
+        });
+      }
+    } else {
+      merged[scalar] = incoming[scalar];
+    }
+  }
+
+  // workspaces: equality check (don't try to merge arrays meaningfully)
+  if (incoming.workspaces) {
+    if ("workspaces" in existing) {
+      if (
+        JSON.stringify(existing.workspaces) !==
+        JSON.stringify(incoming.workspaces)
+      ) {
+        conflicts.push({
+          path: "workspaces",
+          existing: existing.workspaces,
+          incoming: incoming.workspaces,
+        });
+      }
+    } else {
+      merged.workspaces = incoming.workspaces;
+    }
+  }
+
+  return { conflicts, merged };
+}
+
+function writePackageJson(destPath, obj) {
+  // Match what npm writes: 2-space indent + trailing newline. Conservative;
+  // users with tabs/4-space style will see a one-time reformat but it's stable
+  // after the first prettier run.
+  fs.writeFileSync(destPath, JSON.stringify(obj, null, 2) + "\n");
+}
+
+module.exports = { copyTemplate, mergePackageJson, writePackageJson };

package/lib/topo-sort.js

@@ -0,0 +1,134 @@
+const fs = require("fs");
+const path = require("path");
+
+function getProjectDependencies(workspaceDir, projectName, allProjects, angularJson) {
+  const projectConfig = angularJson.projects[projectName];
+  if (!projectConfig) return [];
+  const projectRoot = projectConfig.root || `projects/${projectName}`;
+  const deps = new Set();
+
+  const considerName = (s) => {
+    if (!s) return;
+    for (const p of allProjects) {
+      if (p === projectName) continue;
+      if (s === p || s.startsWith(p + "/")) deps.add(p);
+    }
+  };
+
+  const tsConfigPath = projectConfig?.architect?.build?.options?.tsConfig;
+  if (tsConfigPath) {
+    const abs = path.join(workspaceDir, tsConfigPath);
+    if (fs.existsSync(abs)) {
+      try {
+        const tsc = JSON.parse(fs.readFileSync(abs, "utf8"));
+        const paths = tsc.compilerOptions?.paths || {};
+        for (const k of Object.keys(paths)) considerName(k);
+      } catch {}
+    }
+  }
+
+  const pkgPath = path.join(workspaceDir, projectRoot, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      for (const section of [
+        "dependencies",
+        "devDependencies",
+        "peerDependencies",
+      ]) {
+        for (const k of Object.keys(pkg[section] || {})) considerName(k);
+      }
+    } catch {}
+  }
+
+  const srcRoot = path.join(workspaceDir, projectRoot, "src");
+  if (fs.existsSync(srcRoot)) {
+    const importRe = /import\s.*from\s['"]([^'"]+)['"]/g;
+    const walk = (dir) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+        } else if (entry.name.endsWith(".ts")) {
+          try {
+            const content = fs.readFileSync(full, "utf8");
+            let m;
+            while ((m = importRe.exec(content))) considerName(m[1]);
+          } catch {}
+        }
+      }
+    };
+    walk(srcRoot);
+  }
+
+  return Array.from(deps);
+}
+
+function topologicalSort(graph) {
+  const sorted = [];
+  const visited = {};
+  const inStack = {};
+
+  const visit = (node, stack = []) => {
+    if (visited[node]) return;
+    if (inStack[node]) {
+      throw new Error(
+        `Circular dependency detected: ${[...stack, node].join(" → ")}`
+      );
+    }
+    inStack[node] = true;
+    for (const dep of graph[node] || []) {
+      visit(dep, [...stack, node]);
+    }
+    inStack[node] = false;
+    visited[node] = true;
+    sorted.push(node);
+  };
+
+  for (const node of Object.keys(graph)) visit(node);
+  return sorted;
+}
+
+// restrictTo: array of project names. Empty/undefined ⇒ keep full graph.
+// opts.withDeps: when true and restrictTo is non-empty, expand the set to
+// include every transitive workspace dep (legacy behavior). When false
+// (default), the set is exactly the names in restrictTo; the returned graph
+// keeps only edges within that set so the sort respects ordering among them.
+function buildDependencyGraph(workspaceDir, angularJson, restrictTo, opts = {}) {
+  const { withDeps = false } = opts;
+  const allProjects = Object.keys(angularJson.projects || {});
+  const graph = {};
+  for (const name of allProjects) {
+    graph[name] = getProjectDependencies(
+      workspaceDir,
+      name,
+      allProjects,
+      angularJson
+    );
+  }
+  if (!restrictTo || !restrictTo.length) return { graph, allProjects };
+
+  for (const n of restrictTo) {
+    if (!graph[n]) {
+      throw new Error(`Unknown project: ${n}`);
+    }
+  }
+
+  const allowed = new Set();
+  if (withDeps) {
+    const collect = (n) => {
+      if (allowed.has(n)) return;
+      allowed.add(n);
+      for (const d of graph[n] || []) collect(d);
+    };
+    for (const n of restrictTo) collect(n);
+  } else {
+    for (const n of restrictTo) allowed.add(n);
+  }
+
+  const restrictedGraph = {};
+  for (const n of allowed) restrictedGraph[n] = graph[n].filter((d) => allowed.has(d));
+  return { graph: restrictedGraph, allProjects: Array.from(allowed) };
+}
+
+module.exports = { getProjectDependencies, topologicalSort, buildDependencyGraph };

package/lib/webpack-factory.js

@@ -0,0 +1,104 @@
+const path = require("path");
+const Module = require("module");
+
+// 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.
+//
+// We resolve the workspace's webpack + ModuleFederationPlugin so the
+// build runs against the same versions used by the workspace's own
+// dependency graph (avoids shared-scope ABI surprises).
+function buildWebpackConfig({
+  workspaceDir,
+  syntheticEntry,
+  outDir,
+  id,
+  remoteName,
+  exposes,
+  aliasMap,
+  sharedMap,
+}) {
+  const requireFromWorkspace = Module.createRequire(
+    path.join(workspaceDir, "package.json")
+  );
+  const ModuleFederationPlugin = requireFromWorkspace(
+    "webpack/lib/container/ModuleFederationPlugin"
+  );
+  const babelLoader = requireFromWorkspace.resolve("babel-loader");
+  const linkerPlugin = requireFromWorkspace.resolve(
+    "@angular/compiler-cli/linker/babel"
+  );
+
+  const remoteOutDir = path.join(outDir, id, "remote");
+
+  return {
+    mode: "production",
+    entry: syntheticEntry,
+    context: workspaceDir,
+    // Terser's default class-name mangling strips identifying info
+    // Angular's runtime relies on (you get `'_' is neither
+    // ComponentType nor DirectiveType` errors). Angular CLI's builder
+    // configures Terser with Angular-aware options; we don't, so keep
+    // minimization off until that config is ported. Output is larger
+    // but functionally correct.
+    optimization: {
+      minimize: false,
+    },
+    output: {
+      path: remoteOutDir,
+      publicPath: "auto",
+      uniqueName: remoteName,
+      // Content-hash all chunks so the controller can serve them
+      // with immutable caching. The MF plugin overrides this to
+      // "remoteEntry.js" for the entry only — that one stays at a
+      // stable URL and is revalidated each load.
+      filename: "[name].[contenthash:10].js",
+      chunkFilename: "[name].[contenthash:10].js",
+    },
+    resolve: {
+      alias: aliasMap,
+      extensions: [".ts", ".js", ".mjs", ".json"],
+      // ngcc rewrites Angular packages in-place but leaves the
+      // originals next to them, exposing both via package.json fields
+      // (`module` for the partial-Ivy original, `module_ivy_ngcc` for
+      // the full-Ivy processed copy). Webpack's default mainFields
+      // doesn't know about the latter — it resolves to the partial
+      // version and components show up as `'MatInput' is neither
+      // ComponentType nor DirectiveType` because their `ɵdir` static
+      // is missing. Angular CLI's builder injects this same ordering.
+      mainFields: ["module_ivy_ngcc", "browser", "module", "main"],
+    },
+    module: {
+      rules: [
+        // Run the Angular partial-Ivy linker over every JS module.
+        // ng-packagr emits libs in compilationMode "partial" by
+        // default since v12; the runtime can't always process
+        // partial declarations directly (we hit
+        // `meta.deps.map is not a function` in ɵɵngDeclareFactory).
+        // Babel-with-linker rewrites the partial declarations to
+        // full Ivy at bundle time — same step that Angular CLI's
+        // custom-webpack:browser builder does implicitly.
+        {
+          test: /\.m?js$/,
+          loader: babelLoader,
+          options: {
+            compact: false,
+            cacheDirectory: true,
+            plugins: [linkerPlugin],
+          },
+          resolve: { fullySpecified: false },
+        },
+      ],
+    },
+    plugins: [
+      new ModuleFederationPlugin({
+        name: remoteName,
+        library: { type: "window", name: remoteName },
+        filename: "remoteEntry.js",
+        exposes: { [exposes]: syntheticEntry },
+        shared: sharedMap,
+      }),
+    ],
+  };
+}
+
+module.exports = { buildWebpackConfig };

package/lib/wire-host.js

@@ -0,0 +1,96 @@
+const fs = require("fs");
+const path = require("path");
+
+function wsconfigPath(workspaceDir) {
+  return path.join(workspaceDir, "wsconfig.json");
+}
+
+function readWsconfig(workspaceDir) {
+  const file = wsconfigPath(workspaceDir);
+  if (!fs.existsSync(file)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    throw new Error(`Failed to parse ${file}: ${e.message}`);
+  }
+}
+
+function writeWsconfig(workspaceDir, config) {
+  fs.writeFileSync(
+    wsconfigPath(workspaceDir),
+    JSON.stringify(config, null, 2) + "\n"
+  );
+}
+
+function readModulesJson(wpmRoot) {
+  const file = path.join(wpmRoot, "modules.json");
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function resolveHostDir(wpmRoot) {
+  const modulesJson = readModulesJson(wpmRoot);
+  const adminBuildFolder = modulesJson.adminBuildFolder || "./admin";
+  return path.resolve(wpmRoot, adminBuildFolder);
+}
+
+function collectSiblingPaths(workspaceDir) {
+  const angularJsonPath = path.join(workspaceDir, "angular.json");
+  if (!fs.existsSync(angularJsonPath)) return {};
+  const angular = JSON.parse(fs.readFileSync(angularJsonPath, "utf8"));
+  const out = {};
+  for (const name of Object.keys(angular.projects || {})) {
+    out[name] = [`dist/${name}/${name}`, `dist/${name}`];
+  }
+  return out;
+}
+
+function rebuildFederationTsconfig(workspaceDir) {
+  const paths = collectSiblingPaths(workspaceDir);
+  const wsconfig = readWsconfig(workspaceDir);
+  let federationTarget = null;
+  if (wsconfig.wpmRoot) {
+    const hostDir = resolveHostDir(wsconfig.wpmRoot);
+    federationTarget = path.join(hostDir, ".federation", "*");
+    paths["@ws-remote/*"] = [federationTarget];
+  }
+  // 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.
+  // Workspace tsconfig.json sits on top and extends THIS file.
+  const config = {
+    extends: "@ws-test-realm/devkit/tsconfig.base.json",
+    compilerOptions: { paths },
+  };
+  const file = path.join(workspaceDir, "tsconfig.federation.json");
+  fs.writeFileSync(file, JSON.stringify(config, null, "\t") + "\n");
+  return { file, paths, federationTarget };
+}
+
+function applyWpmRoot(workspaceDir, wpmRoot, hostId) {
+  if (!wpmRoot) {
+    throw new Error("wpmRoot is required");
+  }
+  const abs = path.resolve(wpmRoot);
+  if (!fs.existsSync(path.join(abs, "modules.json"))) {
+    throw new Error(`Not a wpm project root (no modules.json): ${abs}`);
+  }
+  const config = readWsconfig(workspaceDir);
+  config.wpmRoot = abs;
+  config.hostId = hostId || "admin";
+  writeWsconfig(workspaceDir, config);
+
+  const fed = rebuildFederationTsconfig(workspaceDir);
+  return {
+    wpmRoot: abs,
+    hostId: config.hostId,
+    federationTsconfig: fed.file,
+    federationTarget: fed.federationTarget,
+  };
+}
+
+module.exports = {
+  readWsconfig,
+  writeWsconfig,
+  applyWpmRoot,
+  rebuildFederationTsconfig,
+};