@ws-test-realm/admin-kit 0.1.7

package/lib/deploy-remotes.js

@@ -0,0 +1,249 @@
+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 };
+}
+
+function copyTypes(distLib, hostFederationDir) {
+  if (fs.existsSync(hostFederationDir)) {
+    fs.rmSync(hostFederationDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(hostFederationDir, { recursive: true });
+  fs.cpSync(distLib, hostFederationDir, { recursive: true });
+}
+
+// Copy the federation artifact (dist/admin-remotes/<id>/) to the ext target
+// 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(", ");
+    console.warn(
+      `\x1b[33mWarning:\x1b[0m a jar matching '${id}-*.jar' exists at ${list}; this project is targeting ext, but the name collision may indicate abuse.`
+    );
+  }
+  const srcDir = path.join(workspaceDir, "dist", "admin-remotes", id);
+  if (!fs.existsSync(srcDir)) {
+    throw new Error(
+      `Federation artifact missing: ${srcDir}. Run \`pack:remote\` first.`
+    );
+  }
+  if (fs.existsSync(extDir)) {
+    fs.rmSync(extDir, { recursive: true, force: true });
+  }
+  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 })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else fileCount += 1;
+    }
+  };
+  walk(extDir);
+  return { extDir, copiedFiles: fileCount };
+}
+
+function deployOne({
+  workspaceDir,
+  id,
+  wpmRoot,
+  modulesFolder,
+  adminBuildFolder,
+  wsconfig,
+}) {
+  const distRemoteDir = path.join(workspaceDir, "dist", "admin-remotes", id);
+  const distLibDir = path.join(workspaceDir, "dist", id);
+
+  if (!fs.existsSync(distRemoteDir)) {
+    throw new Error(
+      `Federation artifact missing: ${distRemoteDir}. Run \`pack:remote\` first.`
+    );
+  }
+  if (!fs.existsSync(distLibDir)) {
+    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({
+    workspaceDir,
+    projectName: id,
+    wsconfig,
+    wpmRoot,
+    modulesFolder,
+  });
+
+  // Perform the artifact deploy first; only on success do we touch host types.
+  let artifactReport;
+  if (target.kind === "jar") {
+    const packResult = packIntoJar({
+      jarPath: target.jarPath,
+      sourceDir: distRemoteDir,
+      id,
+    });
+    artifactReport = {
+      kind: "jar",
+      jarPath: target.jarPath,
+      pomPath: target.pomPath,
+      artifactId: target.artifactId,
+      ...packResult,
+    };
+  } else {
+    const extResult = deployExt({
+      workspaceDir,
+      id,
+      modulesDir,
+      extDir: target.extDir,
+    });
+    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 { order } = loadOrder({ workspaceDir, restrictTo, withDeps });
+  const { remotes, libraries } = partitionByKind(workspaceDir, order);
+
+  console.log(`\n=== Deploy 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=== deploy ${id} ===`);
+    const r = deployOne({
+      workspaceDir,
+      id,
+      wpmRoot: wsconfig.wpmRoot,
+      modulesFolder,
+      adminBuildFolder,
+      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.addedFiles !== undefined) {
+        console.log(`  packed files:  ${r.addedFiles}`);
+      }
+      if (r.droppedEntries) {
+        console.log(`  dropped stale: ${r.droppedEntries}`);
+      }
+    } else {
+      console.log(`  target:        ext`);
+      console.log(`  ext dir:       ${r.extDir}`);
+      console.log(`  copied files:  ${r.copiedFiles}`);
+    }
+    console.log(`  host types:    ${r.hostFederationDir}`);
+    results.push({ id, ...r });
+  }
+
+  console.log(`\nDeployed ${results.length} module(s).`);
+  return { results };
+}
+
+module.exports = { deployRemotes };

package/lib/drop-module.js

@@ -0,0 +1,71 @@
+const fs = require("fs");
+const path = require("path");
+const { rebuildFederationTsconfig } = require("./wire-host");
+
+function dropModule({ workspaceDir, name }) {
+  if (!fs.existsSync(path.join(workspaceDir, "angular.json"))) {
+    throw new Error(`No angular.json in ${workspaceDir} (not a workspace).`);
+  }
+
+  const projectDir = path.join(workspaceDir, "projects", name);
+  const distDir = path.join(workspaceDir, "dist", name);
+  const distRemoteDir = path.join(workspaceDir, "dist", "admin-remotes", name);
+
+  const projectExisted = fs.existsSync(projectDir);
+
+  if (projectExisted) {
+    fs.rmSync(projectDir, { recursive: true, force: true });
+  }
+
+  const angularJsonPath = path.join(workspaceDir, "angular.json");
+  const angular = JSON.parse(fs.readFileSync(angularJsonPath, "utf8"));
+  let angularChanged = false;
+  if (angular.projects && angular.projects[name]) {
+    delete angular.projects[name];
+    angularChanged = true;
+  }
+  if (angularChanged) {
+    fs.writeFileSync(
+      angularJsonPath,
+      JSON.stringify(angular, null, "\t") + "\n"
+    );
+  }
+
+  const fed = rebuildFederationTsconfig(workspaceDir);
+  const federationTsconfigUpdated = !(name in fed.paths);
+
+  let distCleaned = false;
+  if (fs.existsSync(distDir)) {
+    fs.rmSync(distDir, { recursive: true, force: true });
+    distCleaned = true;
+  }
+  let distRemoteCleaned = false;
+  if (fs.existsSync(distRemoteDir)) {
+    fs.rmSync(distRemoteDir, { recursive: true, force: true });
+    distRemoteCleaned = true;
+  }
+
+  // Hook point: when type publishing to the host lands, clean the host-side
+  // typings for this module here. See TODO.md.
+  const hostTypesCleaned = false;
+
+  if (
+    !projectExisted &&
+    !angularChanged &&
+    !distCleaned &&
+    !distRemoteCleaned
+  ) {
+    throw new Error(`No traces of '${name}' found to drop.`);
+  }
+
+  return {
+    projectExisted,
+    angularChanged,
+    federationTsconfigUpdated,
+    distCleaned,
+    distRemoteCleaned,
+    hostTypesCleaned,
+  };
+}
+
+module.exports = { dropModule };

package/lib/emit-descriptor.js

@@ -0,0 +1,31 @@
+const fs = require("fs");
+const path = require("path");
+
+// Write <out>/<id>/federation.json — the descriptor the admin federation
+// controller reads (both jar-side and ext-side).
+function emitDescriptor({
+  outDir,
+  id,
+  hostId,
+  remoteName,
+  exposes,
+  displayName,
+}) {
+  const dir = path.join(outDir, id);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, "federation.json");
+  const descriptor = {
+    hostId,
+    contributionId: id,
+    manifestEntry: {
+      id,
+      name: displayName,
+      remoteName,
+      exposedModule: exposes,
+    },
+  };
+  fs.writeFileSync(file, JSON.stringify(descriptor, null, 2) + "\n", "utf8");
+  return file;
+}
+
+module.exports = { emitDescriptor };

package/lib/generate-module.js

@@ -0,0 +1,105 @@
+const fs = require("fs");
+const path = require("path");
+const { rebuildFederationTsconfig } = require("./wire-host");
+
+function pascalCase(s) {
+  return s
+    .split(/[-_]/g)
+    .map((p) => (p ? p.charAt(0).toUpperCase() + p.slice(1) : p))
+    .join("");
+}
+
+function camelCase(s) {
+  return s
+    .split(/[-_]/g)
+    .map((p, i) => {
+      if (!p) return p;
+      return i === 0 ? p : p.charAt(0).toUpperCase() + p.slice(1);
+    })
+    .join("");
+}
+
+function buildTokens(name) {
+  return {
+    name,
+    className: pascalCase(name),
+    camelName: camelCase(name),
+    selector: `ws-${name}`,
+  };
+}
+
+function substitute(s, tokens) {
+  return s
+    .replace(/__className__/g, tokens.className)
+    .replace(/__camelName__/g, tokens.camelName)
+    .replace(/__selector__/g, tokens.selector)
+    .replace(/__name__/g, tokens.name);
+}
+
+function copyAndSubstitute(src, dest, tokens) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const newName = substitute(entry.name, tokens);
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, newName);
+    if (entry.isDirectory()) {
+      copyAndSubstitute(srcPath, destPath, tokens);
+    } else {
+      const content = fs.readFileSync(srcPath, "utf8");
+      fs.writeFileSync(destPath, substitute(content, tokens));
+    }
+  }
+}
+
+function registerInAngularJson(workspaceDir, name) {
+  const angularJsonPath = path.join(workspaceDir, "angular.json");
+  const angular = JSON.parse(fs.readFileSync(angularJsonPath, "utf8"));
+  angular.projects = angular.projects || {};
+  angular.projects[name] = {
+    projectType: "library",
+    root: `projects/${name}`,
+    sourceRoot: `projects/${name}/src`,
+    prefix: "ws",
+    architect: {
+      build: {
+        builder: "@angular-devkit/build-angular:ng-packagr",
+        options: { project: `projects/${name}/ng-package.json` },
+        configurations: {
+          production: {
+            tsConfig: `projects/${name}/tsconfig.lib.prod.json`,
+          },
+          development: { tsConfig: `projects/${name}/tsconfig.lib.json` },
+        },
+        defaultConfiguration: "production",
+      },
+    },
+  };
+  fs.writeFileSync(
+    angularJsonPath,
+    JSON.stringify(angular, null, "\t") + "\n"
+  );
+}
+
+function generateModule({ workspaceDir, name, templateModuleDir }) {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new Error(
+      `Invalid module name: ${name}. Use lowercase, hyphen-separated (e.g. db-login).`
+    );
+  }
+  if (!fs.existsSync(path.join(workspaceDir, "angular.json"))) {
+    throw new Error(`No angular.json in ${workspaceDir} (not a workspace).`);
+  }
+  const projectDir = path.join(workspaceDir, "projects", name);
+  if (fs.existsSync(projectDir)) {
+    throw new Error(`projects/${name}/ already exists.`);
+  }
+
+  const tokens = buildTokens(name);
+  copyAndSubstitute(templateModuleDir, projectDir, tokens);
+  registerInAngularJson(workspaceDir, name);
+  rebuildFederationTsconfig(workspaceDir);
+
+  return { projectDir, tokens };
+}
+
+module.exports = { generateModule, buildTokens };

package/lib/identity.js

@@ -0,0 +1,49 @@
+const fs = require("fs");
+const path = require("path");
+
+function camelCase(s) {
+  return s
+    .split(/[-_]/g)
+    .map((part, i) =>
+      i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)
+    )
+    .join("");
+}
+
+function loadPackConfig(projectDir, explicitPath) {
+  const file = explicitPath
+    ? path.resolve(explicitPath)
+    : path.join(projectDir, "pack.config.json");
+  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 resolveIdentity(args) {
+  const projectDir = path.resolve(args.project);
+  const dirName = path.basename(projectDir);
+  const fromConfig = loadPackConfig(projectDir, args.config);
+
+  const id = args.id || fromConfig.id || dirName;
+  const hostId = args.host || fromConfig.hostId || "admin";
+  const remoteName =
+    args.remoteName || fromConfig.remoteName || `${camelCase(id)}Module`;
+  const exposes = args.exposes || fromConfig.exposes || "./Module";
+  const displayName = args.displayName || fromConfig.displayName || id;
+  const sharedExtras = fromConfig.sharedExtras || {};
+
+  return {
+    id,
+    hostId,
+    remoteName,
+    exposes,
+    displayName,
+    sharedExtras,
+    projectDir,
+  };
+}
+
+module.exports = { resolveIdentity, camelCase };

package/lib/jar-glob.js

@@ -0,0 +1,55 @@
+const fs = require("fs");
+const path = require("path");
+
+// Constrained glob matcher for jar lookups.
+//
+// Pattern syntax: literal characters + optional `*`. Each `*` expands to the
+// regex character class `[0-9.]+` — i.e. only digits and dots, the legitimate
+// character set of maven version strings. Non-version `*` matches are rejected
+// to prevent name-collision attacks (e.g. `wiresphere-crm-malicious.jar`
+// satisfying a `wiresphere-crm-*.jar` glob).
+//
+// `findMatches(modulesDir, pattern)` returns an alpha-sorted array of matching
+// filenames in `modulesDir`. Throws if modulesDir is missing.
+
+const VERSION_CHAR_CLASS = "[0-9.]+";
+
+function patternToRegex(pattern) {
+  // Escape regex metacharacters, then replace the placeholder `\*` (from
+  // escaping the user's literal `*`) with the version char class.
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  const expanded = escaped.replace(/\*/g, VERSION_CHAR_CLASS);
+  return new RegExp(`^${expanded}$`);
+}
+
+function findMatches(modulesDir, pattern) {
+  if (!fs.existsSync(modulesDir)) {
+    throw new Error(`Modules dir not found: ${modulesDir}`);
+  }
+  const re = patternToRegex(pattern);
+  return fs
+    .readdirSync(modulesDir)
+    .filter((f) => re.test(f))
+    .sort();
+}
+
+// Resolve a single match given a pattern. Errors on no match. Warns + returns
+// first on multiple matches. Returns the absolute jar path.
+function resolveOne(modulesDir, pattern, label) {
+  const matches = findMatches(modulesDir, pattern);
+  if (!matches.length) {
+    throw new Error(
+      `No jar matching '${pattern}' in ${modulesDir}` +
+        (label ? ` (for ${label})` : "")
+    );
+  }
+  if (matches.length > 1) {
+    console.warn(
+      `Multiple jars match '${pattern}' in ${modulesDir}; using ${matches[0]}` +
+        (label ? ` (for ${label})` : "")
+    );
+  }
+  return path.join(modulesDir, matches[0]);
+}
+
+module.exports = { findMatches, resolveOne, patternToRegex };

package/lib/pack-into-jar.js

@@ -0,0 +1,74 @@
+const fs = require("fs");
+const path = require("path");
+const AdmZip = require("adm-zip");
+
+function walk(dir, base = dir) {
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    const full = path.join(dir, name);
+    const stat = fs.statSync(full);
+    if (stat.isDirectory()) {
+      out.push(...walk(full, base));
+    } else if (stat.isFile()) {
+      out.push({
+        abs: full,
+        rel: path.relative(base, full).split(path.sep).join("/"),
+      });
+    }
+  }
+  return out;
+}
+
+// Repack a jar to carry a federated remote contribution under
+// META-INF/federation/<id>/. Drops any pre-existing entries under that
+// prefix (so re-deploys are clean), then adds every file under sourceDir
+// at <prefix>/<relpath>. sourceDir is expected to be the
+// dist/admin-remotes/<id>/ tree (which already contains both
+// federation.json and remote/* per ws-pack-remote's emit).
+function packIntoJar({ jarPath, sourceDir, id }) {
+  if (!fs.existsSync(jarPath)) {
+    throw new Error(`Jar not found: ${jarPath}`);
+  }
+  if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory()) {
+    throw new Error(`Source dir not found or not a directory: ${sourceDir}`);
+  }
+
+  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
+      );
+    }
+  }
+
+  const files = walk(sourceDir);
+  for (const f of files) {
+    out.addFile(contribRoot + f.rel, fs.readFileSync(f.abs));
+  }
+
+  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, addedFiles: files.length };
+}
+
+module.exports = { packIntoJar };