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

package/bin/ws-modules.js

@@ -3,58 +3,76 @@
 // workspace.
 //
 // Usage:
-//   ws-modules <names...|all> [--build] [--pack] [--deploy] [--with-deps]
+//   ws-modules <names...|all> [--build] [--pack] [--deploy] [--purge] [--with-deps]
 //
 //   <names...>      one or more project names from angular.json
 //   all             expand to every project in angular.json
 //   --build         ng build each lib (topo-ordered)
 //   --pack          federation-pack each lib into dist/admin-remotes/<id>/
 //   --deploy        push jar + types into <wpmRoot>/<modulesFolder>/<id>-*.jar
+//   --purge         strip prior federation contribution from the jar (or ext
+//                   dir) and host's .federation/<id>/ types dir. Resolves the
+//                   target the same way --deploy does (wsconfig override >
+//                   project package.json's wsmodules.target / pom).
 //   --with-deps     expand selection to include each name's in-workspace deps
 //
 // Behaviour:
 //   - No args at all                 → print usage, exit 1
 //   - Positional + step flag(s)      → run exactly those steps, non-interactive
 //   - Positional, no step flags      → prompt y/n for each of build/pack/deploy
-//                                       (and --with-deps); run the selected set
+//                                       (and --with-deps); run the selected set.
+//                                       Purge is NOT prompted (destructive +
+//                                       not part of the normal wire cycle).
 //   - Step flag(s) but no positional → error (need to know what to operate on)
 //
+// Step ordering when multiple are passed: purge → build → pack → deploy.
+//
 // Examples:
 //   ws-modules all                              # interactive
 //   ws-modules db-login                         # interactive, just this project
 //   ws-modules all --build --pack --deploy      # wire the whole stack
 //   ws-modules db-login --build --with-deps     # build db-login + its deps
 //   ws-modules crm shop-common --pack           # pack two specific projects
+//   ws-modules all --purge                      # strip stale contributions
+//   ws-modules all --purge --build --pack --deploy   # nuke + rewire
 
 const readline = require("readline");
 const { buildLibs, packRemotes } = require("../lib/build-modules");
 const { deployRemotes } = require("../lib/deploy-remotes");
+const { purgeRemotes } = require("../lib/purge-remotes");
 
-const STEP_FLAGS = ["build", "pack", "deploy"];
+const STEP_FLAGS = ["purge", "build", "pack", "deploy"];
 const PASSIVE_FLAGS = ["with-deps"];
 const KNOWN_FLAGS = new Set([...STEP_FLAGS, ...PASSIVE_FLAGS]);
 
-const USAGE = `ws-modules <names...|all> [--build] [--pack] [--deploy] [--with-deps]
+const USAGE = `ws-modules <names...|all> [--build] [--pack] [--deploy] [--purge] [--with-deps]
 
-Drive build / pack / deploy across an admin-modules workspace.
+Drive build / pack / deploy / purge across an admin-modules workspace.
 
 Positional:
   <names...>      one or more project names from angular.json
   all             expand to every project in angular.json
 
-Step flags (run exactly the steps you list — if none, you'll be prompted):
+Step flags (run exactly the steps you list — if none, you'll be prompted for
+build/pack/deploy; purge is never prompted):
   --build         ng build each lib (topo-ordered)
   --pack          federation-pack each lib into dist/admin-remotes/<id>/
   --deploy        push jar + types into <wpmRoot>/<modulesFolder>/<id>-*.jar
+  --purge         strip prior federation contribution from the jar (or ext
+                  dir) and host's .federation/<id>/ types dir
 
 Other:
   --with-deps     expand selection to include each name's in-workspace deps
 
+Order when multiple steps are passed: purge → build → pack → deploy.
+
 Examples:
   ws-modules all
   ws-modules db-login --build
   ws-modules all --build --pack --deploy
   ws-modules crm shop-common --pack
+  ws-modules all --purge
+  ws-modules all --purge --build --pack --deploy
 `;
 
 function parseArgv(argv) {
@@ -143,6 +161,7 @@ async function main() {
   let withDeps;
   if (stepFlagsPresent) {
     steps = {
+      purge: !!argv.flags.purge,
       build: !!argv.flags.build,
       pack: !!argv.flags.pack,
       deploy: !!argv.flags.deploy,
@@ -150,11 +169,11 @@ async function main() {
     withDeps = !!argv.flags["with-deps"];
   } else {
     const ans = await promptForSteps(!!argv.flags["with-deps"]);
-    steps = { build: ans.build, pack: ans.pack, deploy: ans.deploy };
+    steps = { purge: false, build: ans.build, pack: ans.pack, deploy: ans.deploy };
     withDeps = ans.withDeps;
   }
 
-  if (!steps.build && !steps.pack && !steps.deploy) {
+  if (!steps.purge && !steps.build && !steps.pack && !steps.deploy) {
     console.log("No steps selected. Nothing to do.");
     return;
   }
@@ -164,10 +183,11 @@ async function main() {
 
   console.log(
     `\nws-modules: ${argv.positional.join(" ")} →` +
-      ` build=${steps.build} pack=${steps.pack} deploy=${steps.deploy}` +
+      ` purge=${steps.purge} build=${steps.build} pack=${steps.pack} deploy=${steps.deploy}` +
       ` with-deps=${withDeps}`
   );
 
+  if (steps.purge) purgeRemotes(common);
   if (steps.build) buildLibs(common);
   if (steps.pack) packRemotes(common);
   if (steps.deploy) deployRemotes(common);

package/lib/deploy-remotes.js

@@ -2,85 +2,8 @@ const fs = require("fs");
 const path = require("path");
 const { packIntoJar } = require("./pack-into-jar");
 const { loadOrder, partitionByKind } = require("./build-modules");
-const { resolveProjectPom, readArtifactId } = require("./pom");
-const { resolveOne, findMatches } = require("./jar-glob");
-
-function readWsconfig(workspaceDir) {
-  const file = path.join(workspaceDir, "wsconfig.json");
-  if (!fs.existsSync(file)) {
-    throw new Error(
-      `No wsconfig.json in ${workspaceDir}. Run \`ws-wire-host <wpm-root>\` first.`
-    );
-  }
-  return JSON.parse(fs.readFileSync(file, "utf8"));
-}
-
-function readModulesJson(wpmRoot) {
-  const file = path.join(wpmRoot, "modules.json");
-  if (!fs.existsSync(file)) {
-    throw new Error(`No modules.json at ${wpmRoot}.`);
-  }
-  return JSON.parse(fs.readFileSync(file, "utf8"));
-}
-
-function readProjectPkg(workspaceDir, name) {
-  const pkgPath = path.join(workspaceDir, "projects", name, "package.json");
-  if (!fs.existsSync(pkgPath)) return {};
-  try {
-    return JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-  } catch {
-    return {};
-  }
-}
-
-// Decide jar vs ext for a project, honouring wsconfig override > package.json.
-// Returns { kind: "jar", jarPath } or { kind: "ext", extDir }.
-function resolveTarget({ workspaceDir, projectName, wsconfig, wpmRoot, modulesFolder }) {
-  const modulesDir = path.resolve(wpmRoot, modulesFolder);
-  const extDir = path.join(
-    wpmRoot,
-    "scripts",
-    "ext-admin-remotes",
-    projectName
-  );
-
-  // 1. wsconfig override
-  const override =
-    wsconfig.deployOverrides && wsconfig.deployOverrides[projectName];
-  if (override) {
-    if (override.jar && override.ext) {
-      throw new Error(
-        `wsconfig.deployOverrides.${projectName}: set exactly one of 'jar' or 'ext', not both`
-      );
-    }
-    if (override.ext === true) {
-      return { kind: "ext", extDir };
-    }
-    if (override.jar) {
-      const jarPath = resolveOne(modulesDir, override.jar, projectName);
-      return { kind: "jar", jarPath };
-    }
-  }
-
-  // 2. project package.json
-  const pkg = readProjectPkg(workspaceDir, projectName);
-  const target = (pkg.wsmodules && pkg.wsmodules.target) || "jar";
-  if (target === "ext") {
-    return { kind: "ext", extDir };
-  }
-  if (target !== "jar") {
-    throw new Error(
-      `Invalid wsmodules.target for ${projectName}: ${JSON.stringify(target)} (expected 'jar' or 'ext')`
-    );
-  }
-
-  // 3. pom-derived artifactId
-  const pomField = pkg.wsmodules && pkg.wsmodules.pom;
-  const pomPath = resolveProjectPom(workspaceDir, projectName, pomField);
-  const artifactId = readArtifactId(pomPath);
-  const jarPath = resolveOne(modulesDir, `${artifactId}-*.jar`, projectName);
-  return { kind: "jar", jarPath, pomPath, artifactId };
-}
+const { findMatches } = require("./jar-glob");
+const { loadDeployContext, resolveTarget } = require("./target-resolution");
 
 function copyTypes(distLib, hostFederationDir) {
   if (fs.existsSync(hostFederationDir)) {
@@ -94,7 +17,6 @@ function copyTypes(distLib, hostFederationDir) {
 // dir (replace-existing semantics). Also warn if a same-id-named jar exists
 // in the modules folder — possible name-collision abuse signal.
 function deployExt({ workspaceDir, id, modulesDir, extDir }) {
-  // Collision check: same constrained-glob rules as everywhere else.
   const collisions = findMatches(modulesDir, `${id}-*.jar`);
   if (collisions.length) {
     const list = collisions.map((c) => path.join(modulesDir, c)).join(", ");
@@ -113,7 +35,6 @@ function deployExt({ workspaceDir, id, modulesDir, extDir }) {
   }
   fs.mkdirSync(extDir, { recursive: true });
   fs.cpSync(srcDir, extDir, { recursive: true });
-  // Count files for the report.
   let fileCount = 0;
   const walk = (d) => {
     for (const e of fs.readdirSync(d, { withFileTypes: true })) {
@@ -131,7 +52,8 @@ function deployOne({
   id,
   wpmRoot,
   modulesFolder,
-  adminBuildFolder,
+  adminDir,
+  modulesDir,
   wsconfig,
 }) {
   const distRemoteDir = path.join(workspaceDir, "dist", "admin-remotes", id);
@@ -146,8 +68,6 @@ function deployOne({
     throw new Error(`Lib dist missing: ${distLibDir}. Run \`build\` first.`);
   }
 
-  const modulesDir = path.resolve(wpmRoot, modulesFolder);
-  const adminDir = path.resolve(wpmRoot, adminBuildFolder);
   const hostFederationDir = path.join(adminDir, ".federation", id);
 
   const target = resolveTarget({
@@ -158,7 +78,6 @@ function deployOne({
     modulesFolder,
   });
 
-  // Perform the artifact deploy first; only on success do we touch host types.
   let artifactReport;
   if (target.kind === "jar") {
     const packResult = packIntoJar({
@@ -183,22 +102,13 @@ function deployOne({
     artifactReport = { kind: "ext", ...extResult };
   }
 
-  // Artifact deploy succeeded — now publish types.
   copyTypes(distLibDir, hostFederationDir);
 
   return { ...artifactReport, hostFederationDir };
 }
 
 function deployRemotes({ workspaceDir, restrictTo = [], withDeps = false }) {
-  const wsconfig = readWsconfig(workspaceDir);
-  if (!wsconfig.wpmRoot) {
-    throw new Error(
-      "wsconfig.json missing wpmRoot. Run `ws-wire-host <wpm-root>`."
-    );
-  }
-  const modulesJson = readModulesJson(wsconfig.wpmRoot);
-  const modulesFolder = modulesJson.modulesFolder || "./modules";
-  const adminBuildFolder = modulesJson.adminBuildFolder || "./admin";
+  const ctx = loadDeployContext(workspaceDir);
 
   const { order } = loadOrder({ workspaceDir, restrictTo, withDeps });
   const { remotes, libraries } = partitionByKind(workspaceDir, order);
@@ -217,10 +127,11 @@ function deployRemotes({ workspaceDir, restrictTo = [], withDeps = false }) {
     const r = deployOne({
       workspaceDir,
       id,
-      wpmRoot: wsconfig.wpmRoot,
-      modulesFolder,
-      adminBuildFolder,
-      wsconfig,
+      wpmRoot: ctx.wpmRoot,
+      modulesFolder: ctx.modulesFolder,
+      adminDir: ctx.adminDir,
+      modulesDir: ctx.modulesDir,
+      wsconfig: ctx.wsconfig,
     });
     if (r.kind === "jar") {
       console.log(`  target:        jar`);

package/lib/purge-jar.js

@@ -0,0 +1,50 @@
+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 }.
+function purgeJar({ jarPath, id }) {
+  if (!fs.existsSync(jarPath)) {
+    throw new Error(`Jar not found: ${jarPath}`);
+  }
+
+  const contribRoot = `META-INF/federation/${id}/`;
+  const original = new AdmZip(jarPath);
+  const out = new AdmZip();
+
+  let dropped = 0;
+  for (const entry of original.getEntries()) {
+    if (entry.entryName.startsWith(contribRoot)) {
+      dropped++;
+      continue;
+    }
+    if (entry.isDirectory) {
+      out.addFile(entry.entryName, Buffer.alloc(0), "", entry.attr);
+    } else {
+      out.addFile(
+        entry.entryName,
+        entry.getData(),
+        entry.comment,
+        entry.attr
+      );
+    }
+  }
+
+  if (dropped === 0) {
+    return { jarPath, droppedEntries: 0, hadContribution: false };
+  }
+
+  const dir = path.dirname(jarPath);
+  const tmp = path.join(
+    dir,
+    `.${path.basename(jarPath)}.repack.${process.pid}.tmp`
+  );
+  out.writeZip(tmp);
+  fs.renameSync(tmp, jarPath);
+
+  return { jarPath, droppedEntries: dropped, hadContribution: true };
+}
+
+module.exports = { purgeJar };

package/lib/purge-remotes.js

@@ -0,0 +1,120 @@
+const fs = require("fs");
+const path = require("path");
+const { purgeJar } = require("./purge-jar");
+const { loadOrder, partitionByKind } = require("./build-modules");
+const { loadDeployContext, resolveTarget } = require("./target-resolution");
+
+// 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);
+
+  const target = resolveTarget({
+    workspaceDir,
+    projectName: id,
+    wsconfig,
+    wpmRoot,
+    modulesFolder,
+  });
+
+  let artifactReport;
+  if (target.kind === "jar") {
+    const result = purgeJar({ jarPath: target.jarPath, id });
+    artifactReport = {
+      kind: "jar",
+      jarPath: target.jarPath,
+      pomPath: target.pomPath,
+      artifactId: target.artifactId,
+      ...result,
+    };
+  } 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 };
+  }
+
+  let typesRemoved = false;
+  if (fs.existsSync(hostFederationDir)) {
+    fs.rmSync(hostFederationDir, { recursive: true, force: true });
+    typesRemoved = true;
+  }
+
+  return { ...artifactReport, hostFederationDir, typesRemoved };
+}
+
+function purgeRemotes({ workspaceDir, restrictTo = [], withDeps = 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}`));
+  if (libraries.length) {
+    console.log(
+      `  (skipping libraries: ${libraries.join(", ")} — wsmodules.kind=library)`
+    );
+  }
+
+  const results = [];
+  for (const id of remotes) {
+    console.log(`\n=== purge ${id} ===`);
+    try {
+      const r = purgeOne({
+        workspaceDir,
+        id,
+        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)`);
+        }
+      } else {
+        console.log(`  target:         ext`);
+        console.log(`  ext dir:        ${r.extDir}`);
+        console.log(`  ext dir:        ${r.removedExtDir ? "removed" : "(absent)"}`);
+      }
+      console.log(
+        `  host types:     ${r.typesRemoved ? "removed" : "(absent)"} (${r.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;
+  console.log(
+    `\nPurged ${ok} module(s)${failed ? `, ${failed} failed` : ""}.`
+  );
+  return { results };
+}
+
+module.exports = { purgeRemotes, purgeOne };

package/lib/target-resolution.js

@@ -0,0 +1,121 @@
+const fs = require("fs");
+const path = require("path");
+const { resolveProjectPom, readArtifactId } = require("./pom");
+const { resolveOne } = require("./jar-glob");
+
+function readWsconfig(workspaceDir) {
+  const file = path.join(workspaceDir, "wsconfig.json");
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `No wsconfig.json in ${workspaceDir}. Run \`ws-wire-host <wpm-root>\` first.`
+    );
+  }
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function readModulesJson(wpmRoot) {
+  const file = path.join(wpmRoot, "modules.json");
+  if (!fs.existsSync(file)) {
+    throw new Error(`No modules.json at ${wpmRoot}.`);
+  }
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function readProjectPkg(workspaceDir, name) {
+  const pkgPath = path.join(workspaceDir, "projects", name, "package.json");
+  if (!fs.existsSync(pkgPath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// Load the deployment context once and reuse across step runners (deploy,
+// purge, ...). Returns { wsconfig, wpmRoot, modulesFolder, modulesDir,
+// adminBuildFolder, adminDir }.
+function loadDeployContext(workspaceDir) {
+  const wsconfig = readWsconfig(workspaceDir);
+  if (!wsconfig.wpmRoot) {
+    throw new Error(
+      "wsconfig.json missing wpmRoot. Run `ws-wire-host <wpm-root>`."
+    );
+  }
+  const modulesJson = readModulesJson(wsconfig.wpmRoot);
+  const modulesFolder = modulesJson.modulesFolder || "./modules";
+  const adminBuildFolder = modulesJson.adminBuildFolder || "./admin";
+  const modulesDir = path.resolve(wsconfig.wpmRoot, modulesFolder);
+  const adminDir = path.resolve(wsconfig.wpmRoot, adminBuildFolder);
+  return {
+    wsconfig,
+    wpmRoot: wsconfig.wpmRoot,
+    modulesFolder,
+    adminBuildFolder,
+    modulesDir,
+    adminDir,
+  };
+}
+
+// Decide jar vs ext for a project, honouring wsconfig override > package.json.
+// Returns { kind: "jar", jarPath, pomPath?, artifactId? } or
+// { kind: "ext", extDir }.
+function resolveTarget({
+  workspaceDir,
+  projectName,
+  wsconfig,
+  wpmRoot,
+  modulesFolder,
+}) {
+  const modulesDir = path.resolve(wpmRoot, modulesFolder);
+  const extDir = path.join(
+    wpmRoot,
+    "scripts",
+    "ext-admin-remotes",
+    projectName
+  );
+
+  // 1. wsconfig override
+  const override =
+    wsconfig.deployOverrides && wsconfig.deployOverrides[projectName];
+  if (override) {
+    if (override.jar && override.ext) {
+      throw new Error(
+        `wsconfig.deployOverrides.${projectName}: set exactly one of 'jar' or 'ext', not both`
+      );
+    }
+    if (override.ext === true) {
+      return { kind: "ext", extDir };
+    }
+    if (override.jar) {
+      const jarPath = resolveOne(modulesDir, override.jar, projectName);
+      return { kind: "jar", jarPath };
+    }
+  }
+
+  // 2. project package.json
+  const pkg = readProjectPkg(workspaceDir, projectName);
+  const target = (pkg.wsmodules && pkg.wsmodules.target) || "jar";
+  if (target === "ext") {
+    return { kind: "ext", extDir };
+  }
+  if (target !== "jar") {
+    throw new Error(
+      `Invalid wsmodules.target for ${projectName}: ${JSON.stringify(target)} (expected 'jar' or 'ext')`
+    );
+  }
+
+  // 3. pom-derived artifactId
+  const pomField = pkg.wsmodules && pkg.wsmodules.pom;
+  const pomPath = resolveProjectPom(workspaceDir, projectName, pomField);
+  const artifactId = readArtifactId(pomPath);
+  const jarPath = resolveOne(modulesDir, `${artifactId}-*.jar`, projectName);
+  return { kind: "jar", jarPath, pomPath, artifactId };
+}
+
+module.exports = {
+  readWsconfig,
+  readModulesJson,
+  readProjectPkg,
+  loadDeployContext,
+  resolveTarget,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ws-test-realm/admin-kit",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "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": {

package/template/package.json

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