create-procode 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,267 @@
-# Temporary Holding Version
+# create-procode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scaffold a React 18 + TypeScript + Vite application wired to the four ProCode
+low-code libraries — with `main.tsx`, all five extension points, a working sample
+screen and the import-boundary ESLint config already in place.
+
+```bash
+npm create procode@latest myapp
+# or
+npx create-procode myapp
+```
+
+## Usage
+
+```bash
+# interactive — every question has a default; press Enter to accept it
+npm create procode@latest
+
+# name positionally, everything else prompted
+npx create-procode myapp
+
+# fully specified, no prompts
+npx create-procode myapp --app-code MYAPP --base /myapp --yes
+
+# the same through npm create — options go after `--`
+npm create procode@latest myapp -- --app-code MYAPP --base /myapp --yes
+```
+
+### Options
+
+| Option | Default | What it sets |
+|---|---|---|
+| `<name>` / `--name <name>` | `procode-app` | Project directory and package name |
+| `--app-code <code>` | derived from the name | `VITE_APPLICATION_CODE`, and therefore the `getAdapter<CODE>` global |
+| `--base <path>` | `/<name>` | Vite `base` **and** `VITE_HOMEPAGE` — kept equal by construction |
+| `--api-url <url>` | QA placeholder | `VITE_CENTRAL_SERVICE_BASE_URL`; a `{APP_CODE}` placeholder is filled in |
+| `--auth-url <url>` | `https://localhost:7016/token` | `VITE_AUTH_URL` |
+| `--tool-url <url>` | the low-code tool host | `VITE_TOOL_BASE_URL` |
+| `--env <name>` | `InDraft` | `VITE_PROJECT_ENVIROMENT` — `InDraft` or `Published` |
+| `--pm <pm>` | auto-detected | `npm` \| `pnpm` \| `yarn` \| `bun` |
+| `--no-install` | installs | Skip the dependency install |
+| `--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 |
+| `-h, --help` / `-v, --version` | — | |
+
+Anything not passed as a flag is asked interactively, with a default already
+filled in — so you can drive this entirely from flags, entirely from prompts, or
+any mix. With `--yes`, or when stdin is not a TTY (CI), nothing is asked.
+
+## What you get
+
+```
+myapp/
+├── README.md                     quick start, layout, the rules, pinned versions
+├── package.json                  the newest ProCode releases + the peers they declare
+├── index.html                    root element + favicon link
+├── vite.config.ts                base, es2020 target, optimizeDeps
+├── tsconfig.json / tsconfig.node.json
+├── .env / .env.local.example     every var the core reads, documented
+├── .nvmrc                        Node 24
+├── .eslintrc.cjs                 the framework's import boundary, at lint time
+├── .vscode/extensions.json       recommends the ESLint extension
+├── .gitignore
+├── public/favicon.svg            served from the base path
+└── src/
+    ├── main.tsx                  the single integration point — every <Core> prop, typed
+    ├── vite-env.d.ts             typed import.meta.env
+    ├── constant.ts               APPLICATION_CODE, AuthToken, the three registry enums
+    ├── localizationResolver.ts   answers vs-template's date / currency lookups
+    ├── icons.ts                  registerIcons map
+    ├── routes.ts                 customRoute
+    ├── Screens/                  LoaderElement, ErrorElement, PageNotFoundElement
+    ├── Utils/                    responseFormatter, fieldErrorMapper, errorMessageMapper,
+    │                             customStorages, the shared log sink
+    ├── Module/                   (1) slug -> schema      + Sample/Contacts.json
+    ├── AdapterProvider/          (2) screenId -> adapter + SampleContacts.ts (seeds the rows)
+    ├── Factory/
+    │   ├── CustomWidgetFactory.tsx      (3) custom widgets
+    │   ├── CustomValidationFactory.tsx  (5) custom validations
+    │   ├── CustomRuleEffectFactory.ts   custom rule effects (customRuleEffectProvider)
+    │   ├── RuleEffects/readOnlyEffect.ts  CUS_READONLY, used by the sample
+    │   ├── Widgets/MyWidget/            a presentation-only widget, composed from library widgets
+    │   ├── Widgets/SectionNav/          the "Sections" rail for long forms
+    │   ├── Widgets/Notification/        the app's one toast host
+    │   ├── Actions/setField.ts          CUS_SET_FIELD — a button reaching MODIFY_MODEL
+    │   ├── Actions/myAction.ts          the custom widget's two actions
+    │   ├── Actions/sampleContacts.ts    stand-ins for the API-backed standard actions
+    │   └── Validations/myValidation.ts
+    ├── CustomAction.ts           (4) custom actions, keyed CUS_*
+    ├── CustomAuthorizationProvider.ts
+    └── assets/styles/index.scss  the five-layer SCSS cascade, in order
+```
+
+### The sample screen
+
+One JSON document with no backend, built to show what the stack does declaratively:
+
+| Coordinate | Value |
+|---|---|
+| slug | `sample` → `src/Module/index.ts` |
+| schema | `src/Module/Sample/Contacts.json` |
+| screenId | `sample-contacts` |
+| adapter | `SampleContacts` → `src/AdapterProvider/AdapterFactory.ts` |
+
+- `H1` heading and a permission-gated **Add contact** button (`CustomAuthorizationProvider`).
+- Three vs-template `BLOCK` summary tiles bound to the view model.
+- A `GRID` with sorting, column search, checkbox selection and three bulk actions
+  that open `CONFOMATIONALERTBOX` with the selection count spliced into the text;
+  the name column is a `NAVIGATIONCELL` that opens the inline editor. Sort and
+  search travel through the grid's `onScreenDataLoad` event, the same path
+  `LOAD_SCREEN_DATA` takes against a server (paging is server-side by design).
+- An editor shown by a `ruleInterpreter` entry, with `TEXTBOX`, `DROPDOWN` (inline
+  options), `DATE`, `SWITCH`, `TEXTAREA`, the custom `MY_WIDGET` (composed from the
+  library's `TextBox` and `Button`), standard validators, `MY_VALIDATION`, and a
+  conditional *Sales region* field driven by a second rule.
+- **Save** validates every editor field through the core's `executeValidation` seam,
+  upserts the row, refreshes the tiles and opens `INFOMATIONALERTBOX`.
+
+The rows are seeded by the adapter's `defaultViewModel`. Five small actions in
+`sampleContacts.ts` stand in for `DELETE_ASYNC` / `UPDATE_ASYNC` /
+`FORMSUBMIT_CREATE_ASYNC`; each header names the standard key that replaces it,
+and the schema's `_readme` lists the three swaps. The smoke test derives its
+registry checks from the schema itself: every `widgetType`, action key, validation
+name, rule target, bulk-action target and permission key in the sample is verified
+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:
+
+- **The newest ProCode libraries, with matching peers.** At scaffold time the CLI
+  asks the npm registry for the latest version of each of the four packages, and
+  writes the React, Kendo, router and axios ranges *those* versions declare as
+  peers. `@progress/kendo-theme-default` and `kendo-react-labels` follow the
+  kendo-react range, and `@types/react` follows the React major. A library
+  release reaches new apps with no generator update. It uses the registry npx
+  was run with, so a mirror works. If the lookup fails (offline, a timeout), the
+  CLI warns and uses the tested set in `src/deps.mjs`; `--no-latest` chooses
+  that set on purpose.
+- **React stays on the major the libraries declare.** Today that is
+  `react ^18.2.0`; 19 installs cleanly then fails at runtime.
+- **`react-redux` is never declared.** It is bundled inside the core. Declaring it
+  and floating to 9.x gives two Provider contexts, and every screen renders blank
+  with nothing in the console.
+- **`@progress/kendo-theme-default` is included.** It is a missing peer
+  declaration, not an optional extra — the widget library's SCSS imports it by
+  name, so omitting it is a hard build failure on the first `npm run dev`.
+- **`build.target: es2020`.** At `es2015` the downlevel transform miscompiles a
+  `const` declaring two rest patterns at once, and Kendo's date picker throws
+  *"Cannot destructure 'null' as it is null"* in built bundles only.
+- **`base` and `VITE_HOMEPAGE` are written from one value**, so they cannot drift.
+- **`VITE_APPLICATION_CODE` is validated** as a JS identifier fragment, because it
+  becomes the `getAdapter<CODE>` global the core resolves by name.
+- **The SCSS import order** is fixed and annotated — it is the cascade, and
+  reordering gives "Undefined variable" or silently wrong spacing.
+- **`main.tsx` ordering** is annotated as load-bearing, with `validateStatus`
+  first, and the smoke test asserts it.
+- **Every `<Core>` seam is wired, and type-checked.** `<Core>` accepts `any`, so a
+  misspelled prop compiles and is silently dropped. `main.tsx` builds a typed
+  `CoreProps` object instead, and the smoke test asserts every seam is in it:
+  widget, action, validation and rule-effect providers, authorization, routes,
+  storages, response formatting, 422 field errors, error-message text, the 401
+  handler, the loader / error / 404 screens and the notification host. The core
+  and widget loggers, `registerIcons` and `registerLocalization` are registered
+  before render. Deprecated props are never emitted.
+- **Rule effects are injectable.** `CustomRuleEffectFactory` is resolved before the
+  standard effects, so it can add effects or override `SHOW` / `HIDE`. The sample
+  uses its `CUS_READONLY`, and the smoke test checks every effect a schema names is
+  standard or registered.
+- **Factories use `Map` lookups.** On a plain object, a key like `"constructor"`
+  returns an `Object.prototype` function the core would invoke.
+- **The core stylesheet builds on Linux.** procode-lowcode-core exports `./styles`
+  as `src/Assets/…`, but ships `src/assets/…`. A Vite alias points the import at the
+  real path, so CI and Docker builds stop failing with "Can't find stylesheet to import".
+- **The localization seam is registered.** `main.tsx` calls vs-template's
+  `registerLocalization()` with `src/localizationResolver.ts` before render. It
+  answers every `LocalizationKey` from one date pattern, including
+  `dateFormatSections`. Without that key, a date box's placeholder changes to
+  Kendo's long form on focus.
+- **The framework's import boundary is enforced at lint time.** Custom code is still
+  built from library parts: a control
+  inside a custom widget is the library's `TextBox` / `Dropdown` / `Button` from
+  `procode-lowcode-kendo-widget/widgets`, never `@progress/kendo-react-*`; icons go
+  through `loadIcon` / `registerIcons`, never a second icon set; navigation is
+  `NAVIGATE` / `MENUNAVIGATE`, never `window.location`; toasts are `responseConfig`
+  or the one Notification host, never `react-toastify` elsewhere; `react-redux`,
+  `react-router-dom` and `procode-*/src/…` deep paths are library internals.
+  `.eslintrc.cjs` refuses any of those. It honours one escape hatch — a
+  `// procode-escalation: <key> — L<n> cannot compose this because <limitation>` comment — for a control
+  the library genuinely does not wrap, so every exception is greppable. The sample
+  `MyWidget` is itself composed from library widgets, so the first custom widget a
+  developer copies is a correct one.
+
+## Maintenance
+
+### Library versions
+
+New apps get the latest ProCode releases automatically, so a library release
+needs no generator change. [`src/deps.mjs`](./src/deps.mjs) holds two things that
+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.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.
+
+The generated README's version table is rendered from whichever set was used.
+
+### Test
+
+```bash
+npm run smoke                 # scaffold + structural assertions, seconds
+node scripts/smoke-test.mjs --install   # also npm install + npm run build
+node scripts/smoke-test.mjs --keep      # leave the generated app for inspection
+```
+
+The `--install` run is the only one that catches a dependency set that resolves on
+paper but not in practice.
+
+## Publishing
+
+```bash
+npm version patch
+npm publish
+```
+
+`files` in `package.json` ships `bin/`, `src/` and `templates/` — about 50 KB packed.
+
+## Requirements
+
+Node 18+ to run the generator. Node 24 recommended for the generated app.
+Zero runtime dependencies — the CLI uses only Node builtins.

package/bin/create-procode.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.mjs";
+
+run(process.argv.slice(2)).catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error("\n\x1b[31m✖\x1b[0m " + (err?.message ?? err));
+  if (process.env.PROCODE_DEBUG) console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "create-procode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "private": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "create-procode": "bin/create-procode.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "smoke": "node scripts/smoke-test.mjs"
+  },
+  "keywords": [
+    "procode",
+    "lowcode",
+    "varstreet",
+    "vite",
+    "react",
+    "scaffold",
+    "create-app"
+  ]
+}

package/src/args.mjs

@@ -0,0 +1,145 @@
+/**
+ * Flag table. `type` drives parsing; `value` on a boolean flag is what the
+ * long form sets, so `--install` and `--no-install` share one key.
+ */
+export const FLAGS = {
+  name: { type: "string", arg: "<name>", desc: "Project directory and package name (or pass it positionally)" },
+  "app-code": { type: "string", arg: "<code>", desc: "VITE_APPLICATION_CODE — must match the getAdapter<CODE> global" },
+  base: { type: "string", arg: "<path>", desc: "Vite base / VITE_HOMEPAGE, e.g. /myapp" },
+  "api-url": { type: "string", arg: "<url>", desc: "VITE_CENTRAL_SERVICE_BASE_URL (the {APP_CODE} placeholder is filled in)" },
+  "auth-url": { type: "string", arg: "<url>", desc: "VITE_AUTH_URL" },
+  "tool-url": { type: "string", arg: "<url>", desc: "VITE_TOOL_BASE_URL" },
+  env: { type: "string", arg: "<name>", desc: "VITE_PROJECT_ENVIROMENT (InDraft | Published)", choices: ["InDraft", "Published"] },
+  pm: { type: "string", arg: "<pm>", desc: "Package manager: npm | pnpm | yarn | bun", choices: ["npm", "pnpm", "yarn", "bun"] },
+  install: { type: "boolean", value: true, desc: "Run the package manager install (--no-install to skip)" },
+  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" },
+  help: { type: "boolean", value: true, short: "h", desc: "Show this help" },
+  version: { type: "boolean", value: true, short: "v", desc: "Print the version" },
+};
+
+const ALIASES = Object.fromEntries(
+  Object.entries(FLAGS)
+    .filter(([, f]) => f.short)
+    .map(([k, f]) => [f.short, k]),
+);
+
+export function parseArgs(argv) {
+  const opts = {};
+  const positionals = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+
+    if (token === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+
+    if (token.startsWith("--")) {
+      let body = token.slice(2);
+      let inlineValue;
+      const eq = body.indexOf("=");
+      if (eq !== -1) {
+        inlineValue = body.slice(eq + 1);
+        body = body.slice(0, eq);
+      }
+
+      let negated = false;
+      let key = body;
+      if (body.startsWith("no-") && FLAGS[body.slice(3)]?.type === "boolean") {
+        negated = true;
+        key = body.slice(3);
+      }
+
+      const flag = FLAGS[key];
+      if (!flag) throw new Error(`Unknown option --${body}. Run with --help to see the supported options.`);
+
+      if (flag.type === "boolean") {
+        if (inlineValue !== undefined) {
+          opts[key] = !["false", "0", "no"].includes(inlineValue.toLowerCase());
+        } else {
+          opts[key] = negated ? !flag.value : flag.value;
+        }
+        continue;
+      }
+
+      const value = inlineValue !== undefined ? inlineValue : argv[++i];
+      if (value === undefined || value.startsWith("--")) {
+        throw new Error(`Option --${key} needs a value, e.g. --${key} ${flag.arg}`);
+      }
+      if (flag.choices && !flag.choices.includes(value)) {
+        throw new Error(`--${key} must be one of: ${flag.choices.join(", ")} (got "${value}")`);
+      }
+      opts[key] = value;
+      continue;
+    }
+
+    if (token.startsWith("-") && token.length > 1) {
+      for (const ch of token.slice(1)) {
+        const key = ALIASES[ch];
+        if (!key) throw new Error(`Unknown option -${ch}. Run with --help to see the supported options.`);
+        opts[key] = FLAGS[key].value ?? true;
+      }
+      continue;
+    }
+
+    positionals.push(token);
+  }
+
+  return { opts, positionals };
+}
+
+export function helpText(version) {
+  const rows = Object.entries(FLAGS).map(([key, f]) => {
+    const short = f.short ? `-${f.short}, ` : "    ";
+    const left = `  ${short}--${key}${f.arg ? " " + f.arg : ""}`;
+    return { left, desc: f.desc, choices: f.choices };
+  });
+  const width = Math.max(...rows.map((r) => r.left.length)) + 2;
+
+  return `
+create-procode v${version}
+
+  Scaffold a React + TypeScript + Vite app wired to the four ProCode libraries:
+  procode-lowcode-core, procode-lowcode-kendo-widget, procode-vs-template and
+  procode-vs-theme — with main.tsx, the five extension points, a sample module
+  screen and the import-boundary ESLint config already in place.
+
+USAGE
+  npm create procode@latest <project-name> -- [options]
+  npx create-procode <project-name> [options]
+  npx create-procode --name <project-name> [options]
+
+OPTIONS
+${rows.map((r) => r.left.padEnd(width) + r.desc + (r.choices ? ` [${r.choices.join("|")}]` : "")).join("\n")}
+
+EXAMPLES
+  # interactive
+  npx create-procode
+
+  # 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 \
+    --api-url https://qa.example.com/lowcodev2/api/{APP_CODE}/ \
+    --no-install --yes
+
+AFTER SCAFFOLDING
+  cd <project-name>
+  npm install          # if you passed --no-install
+  npm run dev          # http://localhost:5173<base>/sample
+`;
+}