create-procode 0.0.0-stage → 1.1.0

package/src/cli.mjs

@@ -0,0 +1,514 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { parseArgs, helpText } from "./args.mjs";
+import { ask, confirm, closePrompt, isInteractive } from "./prompt.mjs";
+import { c, log, step, ok, warn, info } from "./log.mjs";
+import { buildDependencies, buildDevDependencies, PINNED_SET, resolveDependencySet } from "./deps.mjs";
+import {
+  BASE_DIR,
+  copyTree,
+  inspectTarget,
+  toPackageName,
+  toBasePath,
+  writeJson,
+  TEMPLATES_DIR,
+} from "./scaffold.mjs";
+import { applyMultiLanguage, applySampleTranslations, languagesProblem, parseLanguages } from "./multiLanguage.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG = JSON.parse(fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf8"));
+
+const DEFAULTS = {
+  name: "procode-app",
+  appCode: "MYAPP",
+  apiUrl: "https://qa.example.com/lowcodev2/api/{APP_CODE}/",
+  authUrl: "https://localhost:7016/token",
+  toolUrl: "https://lowcodeapi-399313.uc.r.appspot.com/",
+  env: "InDraft",
+  languages: "en,fr",
+};
+
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent ?? "";
+  for (const pm of ["pnpm", "yarn", "bun"]) if (ua.startsWith(pm)) return pm;
+  return "npm";
+}
+
+function runCommand(cmd, args, cwd) {
+  const res = spawnSync(cmd, args, {
+    cwd,
+    stdio: "inherit",
+    // On Windows npm/pnpm/yarn/git are .cmd shims, which spawn cannot exec directly.
+    shell: process.platform === "win32",
+  });
+  if (res.error) throw res.error;
+  return res.status === 0;
+}
+
+const VALID_APP_CODE = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+async function collectOptions(opts, positionals) {
+  const nonInteractive = opts.yes || !isInteractive();
+  const given = (key) => Object.prototype.hasOwnProperty.call(opts, key);
+
+  // Every question below is skippable: press Enter to take the shown default,
+  // or pass the matching flag and it is never asked at all.
+
+  // ---- project name -------------------------------------------------------
+  let name = opts.name ?? positionals[0];
+  if (!name) {
+    if (nonInteractive) {
+      name = DEFAULTS.name;
+    } else {
+      name = await ask("Project name?", DEFAULTS.name, (v) =>
+        v.includes("/") || v.includes("\\") ? "Use a plain directory name, not a path." : null,
+      );
+    }
+  }
+  const packageName = toPackageName(name);
+
+  // ---- application code ---------------------------------------------------
+  // The core resolves the adapter global by NAME as "getAdapter" +
+  // VITE_APPLICATION_CODE. If the two diverge every adapter silently falls back
+  // to a dummy and no screen ever has data - so this is validated, not free text.
+  const codeFromName = packageName.replace(/[^a-zA-Z0-9]/g, "").toUpperCase() || DEFAULTS.appCode;
+  let appCode = opts["app-code"];
+  if (!appCode) {
+    appCode = nonInteractive
+      ? codeFromName
+      : await ask("Application code (VITE_APPLICATION_CODE)?", codeFromName, (v) =>
+          VALID_APP_CODE.test(v)
+            ? null
+            : "Must start with a letter and hold only letters, digits and underscores - it becomes part of a JS identifier.",
+        );
+  }
+  if (!VALID_APP_CODE.test(appCode)) {
+    throw new Error(
+      "--app-code \"" +
+        appCode +
+        "\" is not usable: it becomes the global name getAdapter" +
+        appCode +
+        ", so it must start with a letter and hold only letters, digits and underscores.",
+    );
+  }
+
+  // ---- base path ----------------------------------------------------------
+  let basePath = opts.base;
+  if (!basePath) {
+    basePath = nonInteractive
+      ? "/" + packageName
+      : await ask("Base path (Vite base + VITE_HOMEPAGE)?", "/" + packageName);
+  }
+  basePath = toBasePath(basePath);
+
+  // ---- service URLs -------------------------------------------------------
+  const apiUrl = (opts["api-url"] ?? DEFAULTS.apiUrl).replace(/\{APP_CODE\}/g, appCode);
+  const authUrl = opts["auth-url"] ?? DEFAULTS.authUrl;
+  const toolUrl = opts["tool-url"] ?? DEFAULTS.toolUrl;
+  const projectEnv = opts.env ?? DEFAULTS.env;
+
+  // ---- booleans -----------------------------------------------------------
+  const pm = opts.pm ?? detectPackageManager();
+  const withSample = given("sample") ? opts.sample : true;
+  const withLint = given("lint") ? opts.lint : true;
+  const withTests = given("tests") ? opts.tests : true;
+  const latest = given("latest") ? opts.latest : true;
+
+  // ---- multi-language -----------------------------------------------------
+  // Off unless asked for: a root screen, a language switch and translation
+  // files are only worth carrying when the app is going to be translated.
+  // `--languages` alone implies it.
+  let multiLanguage = given("multi-language") ? opts["multi-language"] : given("languages") ? true : null;
+  if (multiLanguage === null) {
+    multiLanguage = nonInteractive ? false : await confirm("Enable multi-language (a language switch and translation files)?", false);
+  }
+  let languages = ["en"];
+  if (multiLanguage) {
+    let raw = opts.languages;
+    if (!raw) {
+      raw = nonInteractive
+        ? DEFAULTS.languages
+        : await ask("Languages (comma-separated codes, English is always included)?", DEFAULTS.languages, languagesProblem);
+    }
+    languages = parseLanguages(raw);
+  }
+
+  let install = given("install") ? opts.install : null;
+  if (install === null) {
+    install = nonInteractive ? true : await confirm("Run " + pm + " install now?", true);
+  }
+
+  let git = given("git") ? opts.git : null;
+  if (git === null) git = nonInteractive ? true : await confirm("Initialise a git repository?", true);
+
+  return {
+    name,
+    packageName,
+    appCode,
+    basePath,
+    apiUrl,
+    authUrl,
+    toolUrl,
+    projectEnv,
+    pm,
+    install,
+    git,
+    withSample,
+    withLint,
+    withTests,
+    latest,
+    multiLanguage,
+    languages,
+    force: Boolean(opts.force),
+  };
+}
+
+function buildTokens(o, set) {
+  return {
+    APP_NAME: o.name,
+    PKG_NAME: o.packageName,
+    APP_CODE: o.appCode,
+    BASE_PATH: o.basePath, // "/myapp"
+    BASE_PATH_SLASH: o.basePath.endsWith("/") ? o.basePath : o.basePath + "/", // "/myapp/"
+    API_BASE_URL: o.apiUrl,
+    AUTH_URL: o.authUrl,
+    TOOL_BASE_URL: o.toolUrl,
+    PROJECT_ENV: o.projectEnv,
+    GENERATOR_VERSION: PKG.version,
+    // README's Scripts table gains the test row only when tests are generated.
+    TEST_SCRIPT_ROW: o.withTests
+      ? "\n| `npm test` | vitest: every screen's slug is registered and its screenId unique" +
+        (o.multiLanguage ? "; every translation key exists in every language" : "") +
+        " (`src/**/*.test.ts`) |"
+      : "",
+    // Rendered from the same set package.json is written from, so the
+    // generated README cannot drift from the versions it pins.
+    REACT_RANGE: set.peers.react ?? "",
+    PROCODE_VERSIONS: Object.entries(set.procode)
+      .map(([name, range]) => "| `" + name + "` | " + range + " |")
+      .join("\n"),
+  };
+}
+
+/** Edit a generated file line by line, keeping its line endings. */
+function stripLines(file, drop, map = (line) => line) {
+  const raw = fs.readFileSync(file, "utf8");
+  const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+  const out = raw.split(/\r?\n/).filter((line) => !drop(line)).map(map);
+  fs.writeFileSync(file, out.join(eol), "utf8");
+}
+
+const TESTS_START = /\/\/ @tests-start\s*$/;
+const TESTS_END = /\/\/ @tests-end\s*$/;
+const TESTS_LINE = /\s*\/\/ @tests\s*$/;
+
+/** --no-tests: take vitest's block and its type reference out of vite.config.ts. */
+function stripTestBlock(file) {
+  let inBlock = false;
+  stripLines(file, (line) => {
+    if (TESTS_START.test(line)) return (inBlock = true);
+    if (TESTS_END.test(line)) {
+      inBlock = false;
+      return true;
+    }
+    return inBlock || TESTS_LINE.test(line);
+  });
+}
+
+/** With tests: keep the block, drop only the markers. */
+function keepTestBlock(file) {
+  stripLines(
+    file,
+    (line) => TESTS_START.test(line) || TESTS_END.test(line),
+    (line) => line.replace(TESTS_LINE, ""),
+  );
+}
+
+/** Remove the sample screen and unwire it, when --no-sample was passed. */
+function stripSample(root) {
+  fs.rmSync(path.join(root, "src", "Module", "Sample"), { recursive: true, force: true });
+  fs.rmSync(path.join(root, "src", "AdapterProvider", "SampleContacts.ts"), { force: true });
+  fs.rmSync(path.join(root, "src", "Factory", "Actions", "sampleContacts.ts"), { force: true });
+
+  // The registry keeps the two generic actions and the custom-widget pair;
+  // only the sample-screen stand-ins go.
+  fs.writeFileSync(
+    path.join(root, "src", "CustomAction.ts"),
+    [
+      'import { setField } from "./Factory/Actions/setField";',
+      'import { myAction, suggestReferenceCode } from "./Factory/Actions/myAction";',
+      "",
+      "/**",
+      " * Extension point 4 of 5: custom actions, resolved by a CUS_-prefixed key.",
+      " *",
+      " * Resolution is custom -> template -> standard. A key no tier knows is logged",
+      ' * and toasted as "This action is not available". A Map, not an object literal:',
+      ' * on a plain object, actionMap["constructor"] returns a function.',
+      " *",
+      " * Write a custom action only for logic none of the standard keys expresses,",
+      " * and NEVER to make an HTTP call.",
+      " */",
+      "class CustomActionFactory {",
+      "  private actionMap = new Map<string, (props: any, ...args: any[]) => any>([",
+      '    ["CUS_SET_FIELD", setField],',
+      '    ["CUS_MY_ACTION", myAction],',
+      '    ["CUS_SUGGEST_CODE", suggestReferenceCode],',
+      "  ]);",
+      "",
+      "  getAction(key: string) {",
+      "    return this.actionMap.get(key) ?? null; // never throw",
+      "  }",
+      "}",
+      "",
+      "export default CustomActionFactory;",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+
+  fs.writeFileSync(
+    path.join(root, "src", "Module", "index.ts"),
+    [
+      "/**",
+      " * slug -> schema. The slug is the URL segment after the Vite base; the schema",
+      " * is the JSON the core renders. A slug with no branch here is page-not-found.",
+      " */",
+      "export const getSchemaBySlugService = (_slug: string, _appCode: string): any => {",
+      "  return null;",
+      "};",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+
+  fs.writeFileSync(
+    path.join(root, "src", "AdapterProvider", "AdapterFactory.ts"),
+    [
+      "/**",
+      " * screenId -> adapter. Keyed by the `screenId` INSIDE the schema JSON, never by",
+      " * the slug. Read the id out of the file; never guess it.",
+      " *",
+      " * Registered onto window as `getAdapter<APPLICATION_CODE>` by main.tsx.",
+      " */",
+      "export const getAdapter = (_screenId: string): any => {",
+      "  return null;",
+      "};",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+}
+
+export async function run(argv) {
+  const { opts, positionals } = parseArgs(argv);
+
+  if (opts.help) {
+    log(helpText(PKG.version));
+    return;
+  }
+  if (opts.version) {
+    log(PKG.version);
+    return;
+  }
+
+  log("");
+  log("  " + c.bold(c.magenta("ProCode")) + " " + c.dim("project generator") + " " + c.dim("v" + PKG.version));
+  log("  " + c.dim("React + TypeScript + Vite, wired to the four ProCode libraries"));
+  log("");
+
+  let o;
+  try {
+    o = await collectOptions(opts, positionals);
+  } finally {
+    closePrompt();
+  }
+
+  const targetRoot = path.resolve(process.cwd(), o.name);
+
+  // ---- target directory ---------------------------------------------------
+  const target = inspectTarget(targetRoot);
+  if (target.notADirectory) throw new Error(targetRoot + " exists and is not a directory.");
+  if (!target.empty && !o.force) {
+    const shown = target.conflicts.slice(0, 5).join(", ") + (target.conflicts.length > 5 ? ", ..." : "");
+    throw new Error(
+      targetRoot +
+        " is not empty (" +
+        shown +
+        ").\n  Pick another name, empty the directory, or pass --force to scaffold into it anyway.",
+    );
+  }
+
+  log("");
+  step("Scaffolding into " + c.bold(targetRoot));
+  info("package   " + o.packageName);
+  info("app code  " + o.appCode + "   " + c.dim("(global: getAdapter" + o.appCode + ")"));
+  info("base path " + o.basePath);
+  info("api       " + o.apiUrl);
+  info("languages " + (o.multiLanguage ? o.languages.join(", ") : c.dim("English only (multi-language off)")));
+  log("");
+
+  // ---- library versions ---------------------------------------------------
+  // The newest published ProCode packages, with the peers and bundled packages
+  // those versions declare. Any failure (offline, a registry without the
+  // packages, a timeout) falls back to the set this generator was tested with.
+  let set = PINNED_SET;
+  if (o.latest) {
+    step("Resolving the latest ProCode library versions from the npm registry");
+    try {
+      set = await resolveDependencySet();
+      ok(
+        Object.entries(set.procode)
+          .map(([name, range]) => name.replace(/^procode-(lowcode-)?/, "") + " " + range.replace(/^\^/, ""))
+          .join(", "),
+      );
+    } catch (err) {
+      warn("Could not resolve the latest versions (" + (err?.message ?? err) + ").");
+      info("Using the versions this generator was tested with. Pass --no-latest to skip the lookup.");
+    }
+  } else {
+    info("using the tested library versions (--no-latest)");
+  }
+  log("");
+
+  // ---- files --------------------------------------------------------------
+  const tokens = buildTokens(o, set);
+  const created = copyTree(BASE_DIR, targetRoot, tokens);
+  ok(created.length + " project files written");
+
+  if (!o.withSample) {
+    stripSample(targetRoot);
+    info("sample module screen omitted (--no-sample)");
+  }
+
+  if (o.multiLanguage) {
+    const { translatedLibraries } = applyMultiLanguage(targetRoot, { languages: o.languages, withSample: o.withSample });
+    ok("multi-language: " + o.languages.join(", ") + " — root screen src/Module/Header.json, files in public/locales/");
+    const untranslated = o.languages.filter((l) => l !== "en" && !translatedLibraries.includes(l));
+    if (untranslated.length) {
+      info(
+        "the libraries' own text is included for " +
+          (translatedLibraries.join(", ") || "no language but English") +
+          "; for " + untranslated.join(", ") + " it shows in English until public/locales/<code>/{core,widget,kendo,template}.json are translated",
+      );
+    }
+  }
+
+  // ---- tests --------------------------------------------------------------
+  const viteConfig = path.join(targetRoot, "vite.config.ts");
+  if (o.withTests) {
+    copyTree(path.join(TEMPLATES_DIR, "tests"), targetRoot, tokens);
+    if (o.multiLanguage) copyTree(path.join(TEMPLATES_DIR, "tests-multi-language"), targetRoot, tokens);
+    // The markers only delimit the block for --no-tests; drop them.
+    keepTestBlock(viteConfig);
+  } else {
+    stripTestBlock(viteConfig);
+  }
+
+  if (!o.withLint) {
+    fs.rmSync(path.join(targetRoot, ".eslintrc.cjs"), { force: true });
+    // Its only recommendation is the ESLint extension.
+    fs.rmSync(path.join(targetRoot, ".vscode"), { recursive: true, force: true });
+  }
+
+  // ---- package.json -------------------------------------------------------
+  const pkgFile = path.join(targetRoot, "package.json");
+  const generated = JSON.parse(fs.readFileSync(pkgFile, "utf8"));
+  generated.dependencies = buildDependencies(set);
+  generated.devDependencies = buildDevDependencies({ lint: o.withLint, tests: o.withTests, set });
+  if (!o.withLint) delete generated.scripts.lint;
+  if (o.withTests) generated.scripts.test = "vitest run";
+  generated._procodeBundled = {
+    note:
+      "Bundled INSIDE the four ProCode packages. Do not add them here and do not bump them independently - react-redux in particular must stay on 8.x, or the core's store becomes invisible and every screen renders blank.",
+    ...set.bundled,
+  };
+  writeJson(pkgFile, generated);
+  ok(
+    "package.json written (" + (set.source === "latest" ? "latest" : "tested") + " versions): " +
+      Object.keys(generated.dependencies).length +
+      " dependencies, " +
+      Object.keys(generated.devDependencies).length +
+      " dev",
+  );
+
+  // ---- git ----------------------------------------------------------------
+  if (o.git) {
+    if (fs.existsSync(path.join(targetRoot, ".git"))) {
+      info("git repository already present, skipping init");
+    } else if (runCommand("git", ["init", "-q"], targetRoot)) {
+      ok("git repository initialised");
+    } else {
+      warn("git init failed - carrying on without it");
+    }
+  }
+
+  // ---- install ------------------------------------------------------------
+  let installed = false;
+  if (o.install) {
+    log("");
+    step("Installing dependencies with " + o.pm + " - this takes a few minutes");
+    log("");
+    installed = runCommand(o.pm, ["install"], targetRoot);
+    log("");
+    if (installed) ok("dependencies installed");
+    else warn(o.pm + " install failed - run it yourself in " + o.name + " and read the error");
+  }
+
+  // ---- multi-language: move the sample screen's text into the files ------
+  // The same versioned tool an app uses later (it ships with
+  // procode-lowcode-core), so it needs the install.
+  let sampleExtracted = false;
+  if (o.multiLanguage && o.withSample) {
+    if (installed) {
+      step("Moving the sample screen's text into public/locales/en/sample.json");
+      sampleExtracted = runCommand("npx", ["procode-extract-text", "sample", "src/Module/Sample/Contacts.json"], targetRoot);
+      if (sampleExtracted) {
+        const filled = applySampleTranslations(targetRoot, o.languages);
+        const rest = o.languages.filter((l) => l !== "en" && !filled.includes(l));
+        ok(
+          "sample screen text extracted" +
+            (filled.length ? " — translated into " + filled.join(", ") : "") +
+            (rest.length ? "; " + rest.join(", ") + " start in English — translate public/locales/{" + rest.join(",") + "}/sample.json" : ""),
+        );
+      } else {
+        warn("procode-extract-text failed - the sample screen stays in English; run it yourself (below)");
+      }
+    }
+  }
+
+  // ---- what to do next ----------------------------------------------------
+  const runCmd = o.pm === "npm" ? "npm run" : o.pm;
+  log("");
+  log("  " + c.green(c.bold("Done.")) + " Next:");
+  log("");
+  log("    " + c.cyan("cd") + " " + o.name);
+  if (!installed) log("    " + c.cyan(o.pm) + " install");
+  log("    " + c.cyan(runCmd) + " dev");
+  log("");
+  if (o.withSample) {
+    log("  The sample screen is at " + c.bold("http://localhost:5173" + o.basePath + "/sample"));
+    log("  " + c.dim(o.basePath + " is the Vite base, /sample is the slug in src/Module/index.ts"));
+    log("");
+  }
+  if (o.multiLanguage) {
+    log("  Multi-language: " + c.bold(o.languages.join(", ")) + " — switch in the header; " + c.dim("?lang=<code> picks the start language"));
+    if (o.withSample && !sampleExtracted) {
+      log("  Move the sample screen's text into the translation files once installed:");
+      log("    " + c.cyan("npx procode-extract-text sample src/Module/Sample/Contacts.json"));
+    }
+    log("");
+  }
+  log("  " + c.yellow("Before it will load real data:"));
+  log("    1. Point " + c.bold("VITE_CENTRAL_SERVICE_BASE_URL") + " in .env at your environment.");
+  log(
+    "    2. Put a dev token in " +
+      c.bold(".env.local") +
+      " as VITE_HARDCODED_TOKEN, or sign in for the AuthToken cookie.",
+  );
+  log("       " + c.dim(".env.local is gitignored. Never commit a token to .env."));
+  log("    3. " + c.bold("README.md") + " holds the rules - schema first, no axios under src/ outside main.tsx.");
+  log("");
+}