create-procode 1.0.0 → 1.1.0

package/README.md

@@ -42,6 +42,9 @@ npm create procode@latest myapp -- --app-code MYAPP --base /myapp --yes
 | `--no-git` | inits | Skip `git init` |
 | `--no-sample` | includes it | Skip the sample module screen (leaves the registries empty but wired) |
 | `--no-lint` | includes it | Skip ESLint config and its dev dependencies |
+| `--no-tests` | includes them | Skip vitest and the wiring tests (`npm test`): every screen's slug registered and screenId unique; with multi-language, every translation key present in every language (`enText.ts` included) |
+| `--multi-language` | asks; off with `--yes` | Switch on multi-language — a root screen with a language switch, translation files, the start-language hook ([below](#multi-language)) |
+| `--languages <codes>` | `en,fr` | With `--multi-language` (and implies it): the languages offered, e.g. `en,fr,hi`. English is always included — it is the libraries' default text |
 | `--no-latest` | resolves latest | Use the tested library versions in `src/deps.mjs` instead of the newest published ones |
 | `-y, --yes` | — | Take defaults for everything not passed as a flag |
 | `-f, --force` | — | Scaffold into a non-empty directory |
@@ -130,6 +133,28 @@ against the registries.
 
 Pass `--no-sample` for empty-but-wired registries instead.
 
+### Tests and the build guard
+
+By default the project gets **vitest** (`npm test`) with the one setting ProCode needs — `test.server.deps.inline: [/procode-/]` in `vite.config.ts`, without which a test importing a package fails to load — and `src/Module/schemas.test.ts`: every screen JSON under `src/Module` has a slug registered in `getSchemaBySlugService` (an unregistered one is a silent page-not-found) and a unique `screenId`. With multi-language it also gets `src/multiLanguage/enText.ts` (reads a reference's English back for assertions) and `translations.test.ts`: every `@t:` reference in a screen has English, every language has every key, no translation uses a `{placeholder}` its English lacks. `--no-tests` leaves all of it out.
+
+`vite build` **refuses to run while `VITE_HARDCODED_TOKEN` is set** — it reads `.env.local` like `vite dev`, so a personal dev token would otherwise be compiled into `dist/`. `ALLOW_TOKEN_IN_BUILD=1` overrides it for a throwaway local build.
+
+### Multi-language
+
+Asked as *Enable multi-language?* (default **no**), then *Languages?* (default `en,fr`); or `--multi-language --languages en,fr,hi`. ProCode multi-language (core 2.6.0+) is switched on by metadata, so "yes" writes:
+
+| File | What it is |
+|---|---|
+| `src/Module/Header.json` | The root screen (`VITE_HEADER_SLUG`, loaded before any page): its `multiLanguage` block — `enabled`, `defaultLocale: "en"`, the `locales`, the `resources` (`{base}locales/{locale}/{namespace}.json`) — and a `LANGUAGESELECTOR` (segmented up to 4 languages, a menu above). Registered as the `header` slug in `src/Module/index.ts` |
+| `public/locales/<code>/` | One folder per language: `core`, `widget`, `kendo`, `template` (the libraries' own text — empty for English, which is built in; **French and Hindi are included**, other languages show English until translated) and `header` (the language names) |
+| `src/multiLanguage/index.ts` | `initialLocale` — the start language when the user has not chosen one (a `?lang=fr` link; extend it with a company or profile setting) |
+| `src/main.tsx` | `multiLanguage: { initialLocale }` on the typed Core props |
+| `src/Factory/CustomWidgetFactory.tsx` | every custom widget wrapped with `withWidgetMultiLanguage`, so a Dropdown it draws from `/widgets` and Kendo's own text follow the language |
+| the sample screen | shows the header (`enableHeader: true`); after the install, `procode-extract-text` moves its text into `public/locales/en/sample.json`, and French and Hindi translations of it are written. With `--no-install` the command is printed instead |
+| `README.md` | a *Multi-language* section: where everything lives, how to convert a screen, add a language, translate in code |
+
+The generated README carries the rest. The smoke test scaffolds a multi-language app too and checks every file, key and wiring point above.
+
 ### What the generated project encodes
 
 These failure modes are prevented by construction rather than left to memory:
@@ -207,8 +232,9 @@ still need care:
 
 - **The tested fallback set**: used with `--no-latest` or when the registry is
   unreachable. Refresh it after a library release has been verified, then run the
-  smoke test with `--install`. Current pins: core `^2.5.0`, kendo-widget `^2.11.0`,
-  vs-template `^2.13.1`, vs-theme `^2.6.0` (the latest releases as of 2026-10-12).
+  smoke test with `--install`. Current pins: core `^2.7.0`, kendo-widget `^3.2.0`,
+  vs-template `^2.15.1`, vs-theme `^2.7.1` (the latest releases as of 2026-11-06), on KendoReact `^16.2.0` with
+  kendo-theme-default `^14.7.0`.
 - **`UNDECLARED_BUT_REQUIRED`**: packages the libraries need but do not declare
   as peers, so the lookup cannot find them. Add one here if a release starts
   needing a new one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-procode",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Scaffold a React + TypeScript + Vite app wired to the four ProCode low-code libraries (core, kendo-widget, vs-template, vs-theme).",
   "type": "module",
   "license": "UNLICENSED",

package/src/args.mjs

@@ -15,6 +15,9 @@ export const FLAGS = {
   git: { type: "boolean", value: true, desc: "Run git init (--no-git to skip)" },
   sample: { type: "boolean", value: true, desc: "Include the Sample module screen (--no-sample to skip)" },
   lint: { type: "boolean", value: true, desc: "Include ESLint config and dev dependencies" },
+  tests: { type: "boolean", value: true, desc: "Include vitest and the wiring tests — screen registration, and with multi-language, translation completeness (--no-tests to skip)" },
+  "multi-language": { type: "boolean", value: true, desc: "Switch on multi-language: root screen, language selector, translation files (--no-multi-language to skip)" },
+  languages: { type: "string", arg: "<codes>", desc: "With --multi-language: the languages offered, e.g. en,fr,hi (English is always included; default en,fr)" },
   latest: { type: "boolean", value: true, desc: "Use the newest published ProCode libraries and their peers (--no-latest: the tested versions)" },
   yes: { type: "boolean", value: true, short: "y", desc: "Accept defaults for everything not passed as a flag" },
   force: { type: "boolean", value: true, short: "f", desc: "Scaffold into a non-empty directory" },
@@ -125,6 +128,9 @@ EXAMPLES
   # everything on the command line, no prompts
   npx create-procode myapp --app-code MYAPP --base /myapp --yes
 
+  # with multi-language: English, French and Hindi, a language switch in the header
+  npx create-procode myapp --multi-language --languages en,fr,hi --yes
+
   # match an existing deployment, skip install
   npx create-procode vsbackoffice-next \
     --app-code LCBOV2 --base /lcbov2 \

package/src/cli.mjs

@@ -14,7 +14,9 @@ import {
   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"));
@@ -26,6 +28,7 @@ const DEFAULTS = {
   authUrl: "https://localhost:7016/token",
   toolUrl: "https://lowcodeapi-399313.uc.r.appspot.com/",
   env: "InDraft",
+  languages: "en,fr",
 };
 
 function detectPackageManager() {
@@ -111,8 +114,28 @@ async function collectOptions(opts, positionals) {
   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);
@@ -135,7 +158,10 @@ async function collectOptions(opts, positionals) {
     git,
     withSample,
     withLint,
+    withTests,
     latest,
+    multiLanguage,
+    languages,
     force: Boolean(opts.force),
   };
 }
@@ -152,6 +178,12 @@ function buildTokens(o, set) {
     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 ?? "",
@@ -161,6 +193,40 @@ function buildTokens(o, set) {
   };
 }
 
+/** 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 });
@@ -281,6 +347,7 @@ export async function run(argv) {
   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 ---------------------------------------------------
@@ -316,6 +383,30 @@ export async function run(argv) {
     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.
@@ -326,8 +417,9 @@ export async function run(argv) {
   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, 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.",
@@ -365,6 +457,28 @@ export async function run(argv) {
     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("");
@@ -379,6 +493,14 @@ export async function run(argv) {
     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(