@ws-test-realm/admin-kit 0.1.7

package/README.md

@@ -0,0 +1,89 @@
+# @moodia/ws-schematics-remotes
+
+Provisional Node CLI for building federated admin remotes. Wraps an
+already-built lib dist into a `<id>/{federation.json, remote/*}` layout
+that drops directly into the admin federation controller's serving
+directory or into a jar for jar-served deployment.
+
+## Install (local, until published)
+
+```
+cd /Users/ph/projects/ws-admin/ws-schematics-remotes
+npm install
+npm link
+```
+
+`ws-pack-remote` is now available globally.
+
+## Use
+
+```
+# from the workspace root (e.g. runtime-admin-modules)
+npx ng build crm                                          # produce dist/crm
+ws-pack-remote --project projects/crm --workspace .       # produce dist/admin-remotes/crm/
+```
+
+Output:
+
+```
+dist/admin-remotes/crm/
+  federation.json
+  remote/
+    remoteEntry.js
+    *.js
+```
+
+Deploy with a single rsync:
+
+```
+rsync -a --delete dist/admin-remotes/crm/ \
+  /Users/ph/projects/wpm/ws-fiddle/scripts/ext-admin-remotes/crm/
+```
+
+## Identity defaults (no config required)
+
+| field         | default                    |
+| ------------- | -------------------------- |
+| `id`          | `path.basename(--project)` |
+| `hostId`      | `"admin"`                  |
+| `remoteName`  | `camelCase(id) + "Module"` |
+| `exposes`     | `"./Module"`               |
+| `displayName` | `id`                       |
+
+Override any of these via CLI flags. For rare cases where convention
+isn't enough, drop a `pack.config.json` in the project root — see below.
+
+## CLI
+
+```
+ws-pack-remote
+  --project <path>      required: lib project root
+  --workspace <path>    required: workspace root (resolves dist/<lib>)
+  [--out <dir>]         default: <workspace>/dist/admin-remotes
+  [--id <id>]
+  [--host <hostId>]
+  [--remote-name <s>]
+  [--exposes <key>]
+  [--display-name <s>]
+  [--config <file>]     alt path to pack.config.json
+```
+
+## `pack.config.json` (optional escape hatch)
+
+Used only when convention can't capture intent (id ≠ dir name, project-
+specific shared overrides, non-default hostId). Every field optional:
+
+```json
+{
+  "id": "crm",
+  "hostId": "admin",
+  "remoteName": "crmModule",
+  "exposes": "./Module",
+  "displayName": "crm",
+  "sharedExtras": {
+    "<package>": { "singleton": true, "requiredVersion": false }
+  }
+}
+```
+
+Identity precedence: CLI > pack.config.json > defaults.

package/bin/ws-drop-module.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// ws-drop-module — remove a federated admin module from the current
+// workspace. Deletes projects/<name>/, the angular.json entry, rebuilds
+// tsconfig.federation.json without it, plus any dist/<name> and
+// dist/admin-remotes/<name> build artifacts.
+//
+// Usage:
+//   ws-drop-module <name>
+
+const { dropModule } = require("../lib/drop-module");
+
+function main() {
+  const positional = process.argv
+    .slice(2)
+    .filter((a) => !a.startsWith("--"));
+  const name = positional[0];
+  if (!name) {
+    console.error("Usage: ws-drop-module <name>");
+    process.exit(1);
+  }
+  try {
+    const r = dropModule({ workspaceDir: process.cwd(), name });
+    console.log(`Dropped module ${name}.`);
+    if (r.projectExisted) console.log(`  - removed projects/${name}/`);
+    if (r.angularChanged)
+      console.log(`  - removed projects.${name} from angular.json`);
+    if (r.federationTsconfigUpdated)
+      console.log(
+        `  - rebuilt tsconfig.federation.json without ${name}`
+      );
+    if (r.distCleaned) console.log(`  - removed dist/${name}/`);
+    if (r.distRemoteCleaned)
+      console.log(`  - removed dist/admin-remotes/${name}/`);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/ws-generate-module.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// ws-generate-module — scaffold a federated admin module project under
+// projects/<name>/ in the current workspace. Updates angular.json and
+// tsconfig.json paths.
+//
+// Usage:
+//   ws-generate-module <name>
+
+const path = require("path");
+const { generateModule } = require("../lib/generate-module");
+
+function main() {
+  const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const name = positional[0];
+  if (!name) {
+    console.error("Usage: ws-generate-module <name>");
+    process.exit(1);
+  }
+
+  const workspaceDir = process.cwd();
+  const templateModuleDir = path.join(__dirname, "..", "template-module");
+
+  try {
+    const { projectDir } = generateModule({
+      workspaceDir,
+      name,
+      templateModuleDir,
+    });
+    console.log(`Generated ${path.relative(workspaceDir, projectDir)}/`);
+    console.log(`Updated angular.json + tsconfig.json with the new project.`);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/ws-init-workspace.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// ws-init-workspace — initialize an admin-modules workspace in PWD.
+//
+// Steps:
+//   1. Refuse if PWD already has angular.json (don't clobber an existing workspace).
+//   2. If no package.json, run `npm init -y` to create a minimal one.
+//   3. Merge template/package.json fields into PWD's package.json. Conflicts
+//      (existing scripts/deps/etc. with different values than the template's)
+//      cause the script to abort with a report — user resolves and re-runs.
+//   4. Copy the rest of template/ (angular.json, tsconfig.json, etc.) — skip
+//      any file that already exists.
+//   5. Run `npm install` to materialize the merged deps.
+//   6. If --wpm-root was passed, wire wsconfig.json + tsconfig.federation.json.
+//
+// Usage:
+//   ws-init-workspace [--wpm-root <path>] [--host-id <id>]
+//
+// Designed to be invoked as `npx ws-init-workspace` from inside a project that
+// has already `npm install --save-dev @wiresphere/admin-kit`'d (or one that
+// hasn't — step 2 covers that case).
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const {
+  copyTemplate,
+  mergePackageJson,
+  writePackageJson,
+} = require("../lib/template-copy");
+const { applyWpmRoot } = require("../lib/wire-host");
+
+function parseArgs(argv) {
+  const aliases = { "wpm-root": "wpmRoot", "host-id": "hostId" };
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const key = a.slice(2);
+    const mapped = aliases[key];
+    if (!mapped) {
+      console.error(`Unknown flag: --${key}`);
+      process.exit(1);
+    }
+    const val = argv[i + 1];
+    if (val === undefined || val.startsWith("--")) {
+      args[mapped] = true;
+    } else {
+      args[mapped] = val;
+      i++;
+    }
+  }
+  return args;
+}
+
+function ensurePackageJson(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (fs.existsSync(pkgPath)) return { created: false };
+  console.log("No package.json found — running `npm init -y`...");
+  execSync("npm init -y", { cwd, stdio: "inherit" });
+  return { created: true };
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const wpmRoot = args.wpmRoot && args.wpmRoot !== true ? args.wpmRoot : null;
+  const hostId = args.hostId && args.hostId !== true ? args.hostId : "admin";
+  const cwd = process.cwd();
+
+  if (fs.existsSync(path.join(cwd, "angular.json"))) {
+    console.error(
+      `angular.json already exists in ${cwd}; refusing to clobber an existing workspace.`
+    );
+    process.exit(1);
+  }
+
+  ensurePackageJson(cwd);
+
+  const templateDir = path.join(__dirname, "..", "template");
+  const templatePkg = path.join(templateDir, "package.json");
+  const destPkg = path.join(cwd, "package.json");
+
+  console.log(`\nMerging template package.json into ${destPkg}`);
+  const { conflicts, merged } = mergePackageJson(destPkg, templatePkg);
+  if (conflicts.length) {
+    console.error("Refusing to merge — conflicts:");
+    for (const c of conflicts) {
+      console.error(
+        `  - ${c.path}: existing=${JSON.stringify(c.existing)} incoming=${JSON.stringify(c.incoming)}`
+      );
+    }
+    console.error(
+      "Resolve these in your package.json (or remove the conflicting keys) and re-run."
+    );
+    process.exit(1);
+  }
+
+  // Self-inject admin-kit into devDependencies so the workspace's bins resolve
+  // via `node_modules/.bin/` after the post-merge `npm install`. We read our
+  // own version rather than hard-coding it.
+  const ownPkg = JSON.parse(
+    fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")
+  );
+  merged.devDependencies = merged.devDependencies || {};
+  if (!merged.devDependencies[ownPkg.name]) {
+    merged.devDependencies[ownPkg.name] = `^${ownPkg.version}`;
+  }
+
+  // Stamp @wiresphere/shared's `getOverrides()` into the workspace's
+  // `overrides` block. npm's overrides field is the only mechanism that
+  // forces a single version across the whole dep tree (peerDeps just trigger
+  // conflicts, regular deps nest). Shared exports the canonical pin set so
+  // every workspace ends up with the same values. Re-running is idempotent —
+  // existing override entries are overwritten with shared's current values.
+  try {
+    const { getOverrides } = require("@ws-test-realm/shared");
+    const overrides = getOverrides();
+    merged.overrides = Object.assign({}, merged.overrides || {}, overrides);
+    console.log(
+      `\nStamped ${Object.keys(overrides).length} overrides from @wiresphere/shared`
+    );
+  } catch (e) {
+    console.error(
+      `Warning: could not stamp overrides from @wiresphere/shared (${e.message}). Workspace may have version-drift issues at install time.`
+    );
+  }
+
+  // Stamp @wiresphere/devkit's `engines` into the workspace so npm warns on
+  // Node/npm version drift. devkit is the toolchain BOM — it owns the answer
+  // to "which Node/npm does this stack work with". Also drops a .nvmrc so
+  // nvm users get auto-switched on cd.
+  try {
+    const devkitPkg = require("@ws-test-realm/devkit/package.json");
+    if (devkitPkg.engines) {
+      merged.engines = Object.assign({}, merged.engines || {}, devkitPkg.engines);
+      console.log(
+        `Stamped engines from @wiresphere/devkit: node=${devkitPkg.engines.node}, npm=${devkitPkg.engines.npm}`
+      );
+      if (devkitPkg.engines.node) {
+        const nvmrcPath = path.join(cwd, ".nvmrc");
+        fs.writeFileSync(nvmrcPath, `${devkitPkg.engines.node}\n`);
+        console.log(`Wrote ${nvmrcPath}`);
+      }
+    }
+  } catch (e) {
+    console.error(
+      `Warning: could not stamp engines from @wiresphere/devkit (${e.message}).`
+    );
+  }
+
+  writePackageJson(destPkg, merged);
+
+  console.log(`\nCopying other template files into ${cwd}`);
+  const { copied, skipped } = copyTemplate(templateDir, cwd);
+  if (copied.length) console.log(`  copied:  ${copied.join(", ")}`);
+  if (skipped.length) console.log(`  skipped: ${skipped.join(", ")} (already exist)`);
+
+  console.log("\nRunning npm install...");
+  try {
+    execSync("npm install", { cwd, stdio: "inherit" });
+  } catch (e) {
+    console.error(`npm install failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (wpmRoot) {
+    console.log("\nWiring wpm-root pointer...");
+    try {
+      const result = applyWpmRoot(cwd, wpmRoot, hostId);
+      console.log(
+        `wsconfig.json:\n  wpmRoot = ${result.wpmRoot}\n  hostId  = ${result.hostId}`
+      );
+      console.log(
+        `tsconfig.federation.json:\n  @ws-remote/* -> ${result.federationTarget}`
+      );
+    } catch (e) {
+      console.error(e.message);
+      process.exit(1);
+    }
+  } else {
+    console.log(
+      "\nSkipping wpm-root wire (none provided). Run `ws-wire-host <path>` later."
+    );
+  }
+
+  console.log(
+    `\nWorkspace ready at ${cwd}.\nTry: npm run generate-module <name>`
+  );
+}
+
+main();

package/bin/ws-modules.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// ws-modules — unified driver for build / pack / deploy across an admin-modules
+// workspace.
+//
+// Usage:
+//   ws-modules <names...|all> [--build] [--pack] [--deploy] [--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
+//   --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
+//   - Step flag(s) but no positional → error (need to know what to operate on)
+//
+// 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
+
+const readline = require("readline");
+const { buildLibs, packRemotes } = require("../lib/build-modules");
+const { deployRemotes } = require("../lib/deploy-remotes");
+
+const STEP_FLAGS = ["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]
+
+Drive build / pack / deploy 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):
+  --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
+
+Other:
+  --with-deps     expand selection to include each name's in-workspace deps
+
+Examples:
+  ws-modules all
+  ws-modules db-login --build
+  ws-modules all --build --pack --deploy
+  ws-modules crm shop-common --pack
+`;
+
+function parseArgv(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const name = a.slice(2);
+      if (!KNOWN_FLAGS.has(name)) {
+        console.error(`Unknown flag: --${name}`);
+        console.error(USAGE);
+        process.exit(1);
+      }
+      flags[name] = true;
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+function resolveSelection(positional) {
+  if (positional.includes("all")) {
+    if (positional.length > 1) {
+      throw new Error("`all` cannot be combined with project names");
+    }
+    return [];
+  }
+  return positional;
+}
+
+function prompt(rl, question, defaultYes = true) {
+  const hint = defaultYes ? "Y/n" : "y/N";
+  return new Promise((resolve) => {
+    rl.question(`${question} (${hint}) `, (raw) => {
+      const s = (raw || "").trim().toLowerCase();
+      if (!s) return resolve(defaultYes);
+      resolve(s === "y" || s === "yes");
+    });
+  });
+}
+
+async function promptForSteps(prefillWithDeps) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    const build = await prompt(rl, "Build?", true);
+    const pack = await prompt(rl, "Pack?", true);
+    const deploy = await prompt(rl, "Deploy?", false);
+    const withDeps = prefillWithDeps
+      ? true
+      : await prompt(rl, "Include workspace deps?", false);
+    return { build, pack, deploy, withDeps };
+  } finally {
+    rl.close();
+  }
+}
+
+async function main() {
+  const argv = parseArgv(process.argv);
+
+  if (!argv.positional.length && !Object.keys(argv.flags).length) {
+    process.stdout.write(USAGE);
+    process.exit(1);
+  }
+
+  if (!argv.positional.length) {
+    console.error("ws-modules: need module names or `all`.");
+    console.error(USAGE);
+    process.exit(1);
+  }
+
+  let restrictTo;
+  try {
+    restrictTo = resolveSelection(argv.positional);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+
+  const stepFlagsPresent = STEP_FLAGS.some((s) => argv.flags[s]);
+  let steps;
+  let withDeps;
+  if (stepFlagsPresent) {
+    steps = {
+      build: !!argv.flags.build,
+      pack: !!argv.flags.pack,
+      deploy: !!argv.flags.deploy,
+    };
+    withDeps = !!argv.flags["with-deps"];
+  } else {
+    const ans = await promptForSteps(!!argv.flags["with-deps"]);
+    steps = { build: ans.build, pack: ans.pack, deploy: ans.deploy };
+    withDeps = ans.withDeps;
+  }
+
+  if (!steps.build && !steps.pack && !steps.deploy) {
+    console.log("No steps selected. Nothing to do.");
+    return;
+  }
+
+  const workspaceDir = process.cwd();
+  const common = { workspaceDir, restrictTo, withDeps };
+
+  console.log(
+    `\nws-modules: ${argv.positional.join(" ")} →` +
+      ` build=${steps.build} pack=${steps.pack} deploy=${steps.deploy}` +
+      ` with-deps=${withDeps}`
+  );
+
+  if (steps.build) buildLibs(common);
+  if (steps.pack) packRemotes(common);
+  if (steps.deploy) deployRemotes(common);
+}
+
+main().catch((e) => {
+  console.error(e.stack || e.message);
+  process.exit(1);
+});