@acorex/platform-generator 21.0.0-next.3 → 21.0.0-next.33

package/README.md

@@ -1,11 +1,72 @@
-# generator
+# @acorex/platform-generator
 
-This library was generated with [Nx](https://nx.dev).
+Nx schematics for ACoreX Platform **and** a standalone CLI that scaffolds a **new** Nx + Angular workspace using **published** `@acorex/*` packages from the npm registry (no local monorepo clone required).
 
-## Building
+## Building (this monorepo)
 
-Run `nx build generator` to build the library.
+```bash
+nx build generator
+```
 
-## Running unit tests
+## Published CLI (npm consumers)
 
-Run `nx test generator` to execute the unit tests via [Jest](https://jestjs.io).
+Install is optional; `npx` downloads the package on demand.
+
+### Standard commands
+
+```bash
+# Recommended: explicit binary from the published package
+npx @acorex/platform-generator@latest acorex-platform my-app "My App"
+
+# Same entry as above (direct script)
+npx @acorex/platform-generator@latest ./my-app "My App" --preset=minimal --connectivity=mock
+```
+
+The `acorex-platform` binary scaffolds a folder with `package.json`, `nx.json`, `apps/<folder-name>/…`, then runs `npm install` unless you pass `--skip-install`.
+
+### Router binary (`create-acorex-app`)
+
+`create-acorex-app` chooses the workflow automatically:
+
+| Situation | Behavior |
+|-----------|----------|
+| Current directory is **inside** an Nx workspace that contains `nx.json` | Delegates to `nx g @acorex-platform/generator:create-app` (adds `apps/<name>` in this repo). |
+| Not in such a workspace (e.g. empty folder) | Runs the **standalone** scaffold (registry dependencies). |
+| You want the Nx generator **explicitly** | Pass `--monorepo` (requires `--workspace` or `ACOREX_PLATFORM_ROOT` if not already inside the repo). |
+| You are inside a monorepo but want a **standalone** project elsewhere | Pass `--standalone` (ignores the detected workspace for routing). |
+
+### `npm create` / `npm init`
+
+The npm initializer for scoped packages expects a companion package named `@acorex/create-platform-generator`. Until that package exists, use `npx @acorex/platform-generator@latest acorex-platform …` as above.
+
+### Registry and versions
+
+Standalone projects resolve `@acorex/platform`, `@acorex/modules`, `@acorex/connectivity`, `@acorex/components`, etc. from npm. Version ranges are defined in `src/generators/standalone-workspace/versions.json` — **keep them aligned** with what you actually publish for each release.
+
+### Publish checklist (maintainers)
+
+- `@acorex/platform`, `@acorex/modules`, `@acorex/connectivity` (and other `@acorex/*` deps listed in `versions.json`) are published with compatible `exports` / secondary entry points for app imports.
+- Bump `versions.json` to match published semver.
+- Run `nx build generator` so templates and `src/bin/*.js` are copied into `dist/generator` before `npm publish` from the built artifact per your release process.
+
+## Internal development (this repo)
+
+From the repository root, creating an app **inside** `apps/` uses the Nx generator (workspace is detected automatically):
+
+```bash
+npm run create-app -- myapp "My App"
+# same as:
+npx nx g @acorex-platform/generator:create-app myapp "My App"
+```
+
+To force the **standalone** scaffold while your shell is inside this repo:
+
+```bash
+node generator/src/bin/create-acorex-app.js ../path/to/new-folder "My App" --standalone
+```
+
+## Unit tests
+
+```bash
+nx test generator
+```

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@acorex/platform-generator",
-  "version": "21.0.0-next.3",
+  "version": "21.0.0-next.33",
   "peerDependencies": {
-    "@acorex/modules": "21.0.0-next.3"
+    "@acorex/modules": "21.0.0-next.33"
+  },
+  "dependencies": {
+    "ejs": "^3.1.10"
   },
   "type": "commonjs",
   "main": "./src/index.js",
@@ -10,7 +13,10 @@
   "private": false,
   "generators": "./generators.json",
   "bin": {
-    "acx-create-entity": "./src/bin/interactive-entity-creator.js"
+    "acorex-platform": "./src/bin/standalone-scaffold.js",
+    "acx-create-entity": "./src/bin/interactive-entity-creator.js",
+    "create-acorex-app": "./src/bin/create-acorex-app.js",
+    "acx-create-app": "./src/bin/create-acorex-app.js"
   },
   "sideEffects": false,
   "types": "./src/index.d.ts"

package/src/bin/create-acorex-app.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Creates an ACoreX Platform app either:
+ * - Inside this monorepo (Nx generator) when a workspace with nx.json is resolved, unless --standalone
+ * - As a standalone npm workspace (registry deps) when no workspace is found, or with --standalone
+ *
+ * Usage:
+ *   create-acorex-app <appName> "<appTitle>" [options]
+ *   create-acorex-app <project-dir> "<title>" --standalone [standalone options]
+ *
+ * Monorepo (Nx):
+ *   create-acorex-app myapp "My App" --workspace=C:\path\to\acorex-platform
+ *   create-acorex-app myapp "My App"   # from a directory inside the cloned repo
+ *   create-acorex-app myapp "My App" --monorepo
+ *
+ * Standalone (no local clone):
+ *   create-acorex-app my-app "My App" --standalone
+ *   # or from a directory that is not inside an Nx workspace:
+ *   create-acorex-app my-app "My App"
+ */
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const { runStandalone } = require('./standalone-scaffold');
+
+function findWorkspaceRoot(startDir) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, 'nx.json'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+
+/**
+ * Strips workspace flags and returns { workspaceRoot, nxArgs }.
+ */
+function parseCli(argv) {
+  let workspaceRoot = process.env.ACOREX_PLATFORM_ROOT ? path.resolve(process.env.ACOREX_PLATFORM_ROOT) : null;
+  const nxArgs = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--workspace' && argv[i + 1]) {
+      workspaceRoot = path.resolve(argv[i + 1]);
+      i++;
+      continue;
+    }
+    if (a.startsWith('--workspace=')) {
+      workspaceRoot = path.resolve(a.slice('--workspace='.length));
+      continue;
+    }
+    nxArgs.push(a);
+  }
+
+  if (!workspaceRoot) {
+    workspaceRoot = findWorkspaceRoot(process.cwd());
+  }
+
+  return { workspaceRoot, nxArgs };
+}
+
+function stripRoutingFlags(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--standalone' || a === '--monorepo') {
+      continue;
+    }
+    out.push(a);
+  }
+  return out;
+}
+
+const rawArgv = process.argv.slice(2);
+const forceStandalone = rawArgv.includes('--standalone');
+const forceMonorepo = rawArgv.includes('--monorepo');
+const argv = stripRoutingFlags(rawArgv);
+
+const { workspaceRoot, nxArgs } = parseCli(argv);
+
+const hasValidWorkspace = Boolean(workspaceRoot && fs.existsSync(path.join(workspaceRoot, 'nx.json')));
+
+if (forceMonorepo && !hasValidWorkspace) {
+  console.error(
+    [
+      '[create-acorex-app] --monorepo requires an Nx workspace (nx.json).',
+      '  Pass --workspace=<path-to-acorex-platform> or set ACOREX_PLATFORM_ROOT.',
+    ].join('\n'),
+  );
+  process.exit(1);
+}
+
+const useNxGenerator = forceMonorepo || (!forceStandalone && hasValidWorkspace);
+
+if (!useNxGenerator) {
+  runStandalone(argv);
+  return;
+}
+
+const nxForward = ['nx', 'g', '@acorex-platform/generator:create-app', ...nxArgs];
+const isWindows = process.platform === 'win32';
+const cmd = isWindows ? 'npx.cmd' : 'npx';
+const result = spawnSync(cmd, nxForward, {
+  cwd: workspaceRoot,
+  stdio: 'inherit',
+  shell: isWindows,
+});
+
+process.exit(result.status === null ? 1 : result.status);