npm - @ofidj/generator-fidj - Versions diffs - 1.0.1 → 1.0.4 - Mend

@ofidj/generator-fidj 1.0.1 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md CHANGED Viewed

@@ -2,10 +2,12 @@
 Generate a Fidj-integrated TypeScript app with a short command. Public identity and content are generator inputs; authentication and per-app privacy are reusable template behavior. Node 22 or 24 is the validation matrix.
+Registry examples require published compatible versions. For current workspace development, supply a built local SDK with `--sdk-path`.
 ## Content app — static hosting
 ```sh
-create-fidj my-app --app-id YOUR_FIDJ_ID --title "My App" --welcome "Welcome" --content "<p>About my app</p>" --domain example.com
+npx -y -p @ofidj/generator-fidj -p yo yo @ofidj/fidj my-app --app-id YOUR_FIDJ_ID --title "My App" --welcome "Welcome" --content "<p>About my app</p>" --domain example.com
 cd my-app
 npm install && npm run build-prod
 ```
@@ -18,27 +20,55 @@ Serve `www/` on a static host. It contains your public content, SDK sign-in/acco
 Omit `--content` to generate Studio Notes: a browser client plus Node backend with private persisted notes. The backend revalidates the session and live app roles for every protected request. Owner/Editor may write; other members may read their own notes. This mode requires Node hosting and is separate from the static content app scenario.
+Departure uses an in-app confirmation that states the membership, consent and notes being removed and preserves the membership when cancelled.
 Configure the generated privacy adapter so departure from either Studio Notes or Fidj erases the same app data. Notes persist outside disposable output. Failed cleanup stays pending in Fidj and can be retried; completed receipts remain visible. See the generated README for server-side configuration and persistence limits.
 ## CLI and local development
-The package exposes `create-fidj`; from its checkout use `node bin/create-fidj.cjs`. Yeoman `yo @ofidj/fidj my-app --app-id YOUR_FIDJ_ID` invokes the same scaffolder and accepts the content/title/welcome/domain options. The old `app2021` positional command is a historical reference, not the maintained interface.
+The public entry is `yo @ofidj/fidj`; output goes to `<cwd>/<appname>`. Use the `npx` form above or install once:
+```sh
+npm install --no-save @ofidj/generator-fidj yo
+npx --no-install yo @ofidj/fidj my-app --app-id YOUR_FIDJ_ID
+```
+Repeat a flag for `--highlight` and `--badge`; the values are read from the
+command line, so a comma inside one is safe. The old `app2021` positional command
+and its Ionic/Cordova templates are gone; the `typescript` template is the only
+one.
+> Maintainers: `bin/create-fidj.cjs` is the same scaffolder without Yeoman, for
+> tooling that runs from a checkout and cannot install `yo` —
+> `scripts/local-stack.py` and `fidj-app`'s `create:local` use it.
+> `test/parity.test.cjs` fails if either door ever gains an input the other
+> lacks. It is not an entry point to hand to anyone building an app.
 - `--anonymous true|false`: show or hide anonymous entry in content apps (default: `true`). Set `--anonymous false` for a sign-in-only entry flow, as mleweb does.
+- `--highlight "<heading>|<body>"`: add a numbered cell to the sign-in panel, repeatable up to six. These are the app's own selling points, so an app that passes none simply shows its identity — mleweb passes none, Fidj passes four.
+- `--badge <text>`: add a trust badge under the sign-in form, repeatable up to four, 40 characters each. None are supplied by default — "EU-hosted" or "GDPR art. 17 · 20" are claims about a particular app, not about every app the generator makes.
+- `--logo <image>` and `--favicon <image>`: the app's own marks, copied into `public/brand/`. The logo sits beside the app name at the top of the sign-in panel; the favicon goes in the browser tab. Both fall back to the Fidj mark, so neither is ever blank. Accepts `.png`, `.svg`, `.gif`, `.jpg`, `.webp` or `.ico` under 512KB — an animated GIF works as a logo, and as a favicon in the browsers that animate one.
 - `--api-endpoint`: select the API (default: hosted sandbox).
 - `--sdk-path` or `FIDJ_SDK_DIR`: use a built local SDK during coordinated development.
 - `--local` or `FIDJ_LOCAL=true`: use the loopback API/console. Test credentials stay in the validation guide, outside the content app UI. Supply the matching local app ID; `FIDJ_APP_ID` can override it.
 - `--replace`: regenerate only a destination containing `.fidj-generated`; unmarked projects are protected.
+The generated shell paints from one design system: `src/tokens.css` holds every
+colour, family and radius, and `src/style.css` may not introduce a literal of
+its own. Fonts are self-hosted under `public/fonts` and served from the build
+manifest, so a generated site stays statically hostable and makes no
+third-party request on sign-in. fidj-app consumes the same tokens, which is why
+a style change lands here first.
 Generation writes `.env.example`, `.env` and public `app.config.json`. Static configuration is embedded at build time: regenerate/rebuild when changing endpoints. Notes server configuration is read at runtime. Do not place secrets in any public configuration or content input.
-During this unreleased milestone, build `../fidj-node` and pass `--sdk-path ../fidj-node/dist`. Committed templates use registry dependency `@ofidj/node ^3.6.24`; a registry-only install is not validated until coordinated versions are published.
+For unpublished coordinated changes, build the sibling SDK and pass `--sdk-path` with its absolute `dist` path. Committed templates use registry dependency `@ofidj/node ^3.6.24`; a registry-only install is not validated until coordinated versions are published.
 ## Real validation repository
 [mleweb](https://github.com/mlefree/mleweb) is the thin command-line validation fixture whose generated website is mlefree.com. Its `package.json` passes the original Mario GIF, welcome text and About/CV/contact links directly into this generator. No custom downstream renderer is required. GitHub CI runs the same generation/build path on Node 22/24 and uploads artifacts. Publishing the site to gh-pages, which is what mlefree.com serves, is a separate deliberate job: it runs on mleweb's `master` or on an explicit workflow dispatch, never from a version branch.
-Run `npm test` for scaffolding/CLI safety tests. Generated projects include TypeScript checking and HTTP integration tests for live authorization and privacy isolation. Local acceptance steps are in the workspace's `product-plan/09-generated-app-validation.md`.
+Run `npm test` for scaffolding/CLI safety tests. Generated projects include TypeScript checking and HTTP integration tests for live authorization and privacy isolation. See the [local acceptance walkthrough](../LOCAL-DEVELOPMENT.md). Follow TDD: add/run a failing generator or generated-app test before implementation, make it green, then refactor and rerun regression checks.
 ## Releasing to npm
@@ -49,8 +79,8 @@ with `NPM_TOKEN`; this package publishes from the repository root rather than
 from a `dist` directory, because it ships its sources.
 The package contains `bin/`, `lib/` and the `typescript` template only. The
-`app2018` and `app2021` Yeoman templates are excluded: nothing reads them, and
-they accounted for 11.8MB of the 11.9MB published. `main` points at
+`app2018` and `app2021` Yeoman templates were deleted: nothing read them, and
+they accounted for 11.8MB of the repository. `main` points at
 `lib/scaffold.cjs`, so `require('@ofidj/generator-fidj')` returns `{ scaffold }`
 alongside the `create-fidj` binary.
@@ -67,7 +97,7 @@ The generated content app opens on `/#/signin`. Sign in, or choose **Enter anony
 Build your application for the `/module/` base URL, then pass its public output to the same generator:
 ```sh
-create-fidj my-app --app-id YOUR_FIDJ_ID --title "My App" --welcome "Welcome back" --description "Your app description" --anonymous false --module ./built-console --module-entry 'index.html#/my'
+npx -y -p @ofidj/generator-fidj -p yo yo @ofidj/fidj my-app --app-id YOUR_FIDJ_ID --title "My App" --welcome "Welcome back" --description "Your app description" --anonymous false --module ./built-console --module-entry 'index.html#/my'
 cd my-app && npm install && npm run build-prod
 ```
@@ -96,14 +126,28 @@ Generated starters include `npm run privacy:check`: configure the server-only `F
 Readiness confirms this handler only. Register its trusted URL and independent secret with the Fidj API operator; the app owner console can then check the same connection. Group roles granted in Fidj are enforced by the generated backend on each protected operation.
-## Generate an OIDC app
+## Beta OIDC input
-`--oidc-issuer` switches the shared content/module entry to “Continue with Fidj”. The issuer owns password entry; the generator preserves your title, welcome message, logo/content inputs and anonymous-entry choice.
+`--oidc-issuer` selects the OIDC entry for content/module apps while preserving branding and anonymous-entry configuration. This is beta: the API ships an integrated provider from 3.6.26, but it serves no `/oidc` routes until an operator configures an issuer and signing keys, so confirm the issuer you pass actually answers discovery before offering it.
-```sh
-create-fidj my-app --app-id YOUR_APP_ID --api-endpoint https://api.sandbox.fidj.ovh/v3 --oidc-issuer https://api.sandbox.fidj.ovh/oidc --anonymous false --content '<h1>My app</h1>'
-```
+A compatible issuer, REST API and registered callback without a fragment are prerequisites. Validate that integration and coordinated SDK publication before offering it to app builders. Notes retains its existing authentication flow; no subject migration is implied.
+## Required service agreement
+All generated sign-in and account-creation forms (content, composed Fidj and
+Notes) share an unchecked required agreement checkbox. Both submit buttons stay
+disabled until it is checked. Reading the agreement opens an in-app dialog;
+failed agreement loading keeps sign-in blocked. Anonymous entry, when enabled,
+is not a login and does not record agreement acceptance.
-An operator must enable that issuer before this command can authenticate. Register the exact deployed entry URL as the callback; it must not contain a fragment. Local loopback HTTP is supported. During the unreleased beta, use the coordinated SDK checkout through `--sdk-path`; registry-only publication is still pending.
+The text and version come from the app's public API metadata, not copied generator
+settings. The API records acceptance before issuing the app token, preserves
+optional choices, and rejects a missing choice or stale version. Repeated login
+with the same version does not duplicate the history. Administrative membership
+creation does not fabricate a user's acceptance.
-OIDC currently supports static content and application-module assemblies. The Notes storage fixture retains its existing auth flow; no migration of stored Notes subjects is implied. Static HTML/assets remain public regardless of the login screen. Confidential data needs server authorization, preferably with an HttpOnly backend session. mleweb remains the command-line generator fixture: retain the original Mario and About/CV content, and activate OIDC only after its target issuer and callback are configured.
+Before release, the owner sets `configurationAsJSON.serviceAgreement` to
+`{"version":"2026-09-11","text":"Your complete app service agreement"}` through
+`PUT /apps/:appId`, preserving its other configuration fields. Changing the text
+requires a new version. Until configured, the API exposes the explicitly labelled
+`starter-demo-1` demo agreement. No generated-source edit is necessary.

package/bin/create-fidj.cjs CHANGED Viewed

@@ -13,6 +13,10 @@ try {
       welcome: { type: "string" },
       description: { type: "string" },
       content: { type: "string" },
+      highlight: { type: "string", multiple: true },
+      badge: { type: "string", multiple: true },
+      logo: { type: "string" },
+      favicon: { type: "string" },
       anonymous: { type: "string" },
       domain: { type: "string" },
       module: { type: "string" },
@@ -24,7 +28,7 @@ try {
   });
   if (values.help || positionals.length !== 1) {
     console.log(
-      "Usage: create-fidj <directory> --app-id <fidjId> [--api-endpoint <url>] [--title <text> --welcome <text> --description <text> --content <html> --domain <hostname>] [--module <built-directory> --module-entry <index.html#/route>] [--oidc-issuer https://api.example/oidc] [--anonymous true|false] [--local] [--replace]",
+      "Usage: create-fidj <directory> --app-id <fidjId> [--api-endpoint <url>] [--title <text> --welcome <text> --description <text> --content <html> --domain <hostname>] [--highlight '<heading>|<body>' ...] [--badge <text> ...] [--logo <image>] [--favicon <image>] [--module <built-directory> --module-entry <index.html#/route>] [--oidc-issuer https://api.example/oidc] [--anonymous true|false] [--local] [--replace]",
     );
     process.exitCode = values.help ? 0 : 1;
   } else {
@@ -37,6 +41,10 @@ try {
       welcome: values.welcome,
       description: values.description,
       content: values.content,
+      highlights: values.highlight,
+      badges: values.badge,
+      logo: values.logo,
+      favicon: values.favicon,
       anonymous: values.anonymous,
       domain: values.domain,
       module: values.module,

package/generators/app/index.js CHANGED Viewed

@@ -1,23 +1,55 @@
 const Generator = require("yeoman-generator");
 const { scaffold } = require("../../lib/scaffold.cjs");
+// Yeoman and bin/create-fidj.cjs are two doors into the same scaffolder, and
+// they must stay at parity: an input added to one and not the other silently
+// disappears for half the users. test/parity.test.cjs fails when they drift.
+const TEXT_OPTIONS = [
+  "app-id",
+  "api-endpoint",
+  "oidc-issuer",
+  "sdk-path",
+  "title",
+  "welcome",
+  "description",
+  "content",
+  "anonymous",
+  "domain",
+  "module",
+  "module-entry",
+  "logo",
+  "favicon",
+];
+// Repeatable: --highlight twice yields two cells.
+const LIST_OPTIONS = ["highlight", "badge"];
+const FLAG_OPTIONS = ["local", "replace"];
+// Yeoman joins a repeated flag into one comma-separated string before any type
+// coercion, and splitting that back is wrong: a highlight body legitimately
+// contains commas ("An install, a fidjId, a few lines"). Read the occurrences
+// from argv, which is exactly what was typed, and fall back to Yeoman's value
+// when the generator is composed programmatically rather than from a command
+// line.
+function repeated(name, fallback, argv = process.argv) {
+  const found = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === "--" + name && index + 1 < argv.length)
+      found.push(argv[index + 1]);
+    else if (argv[index].startsWith("--" + name + "="))
+      found.push(argv[index].slice(name.length + 3));
+  }
+  if (found.length) return found;
+  if (fallback === undefined) return undefined;
+  return Array.isArray(fallback) ? fallback : [fallback];
+}
 module.exports = class extends Generator {
   constructor(args, opts) {
     super(args, opts);
     this.argument("appname", { type: String, required: false });
-    this.option("app-id", { type: String });
-    for (const key of [
-      "title",
-      "welcome",
-      "description",
-      "content",
-      "domain",
-      "sdk-path",
-      "anonymous",
-      "module",
-      "module-entry",
-    ])
-      this.option(key, { type: String });
+    for (const key of TEXT_OPTIONS) this.option(key, { type: String });
+    for (const key of LIST_OPTIONS) this.option(key, { type: String });
+    for (const key of FLAG_OPTIONS) this.option(key, { type: Boolean });
     this.option("api-endpoint", {
       type: String,
       default: "https://api.sandbox.fidj.ovh/v3",
@@ -55,11 +87,19 @@ module.exports = class extends Generator {
       description: this.options.description,
       content: this.options.content,
       anonymous: this.options.anonymous,
+      highlights: repeated("highlight", this.options.highlight),
+      badges: repeated("badge", this.options.badge),
+      logo: this.options.logo,
+      favicon: this.options.favicon,
       module: this.options.module,
       moduleEntry: this.options["module-entry"],
       domain: this.options.domain,
-      sdkPath: this.options["sdk-path"],
-      appId: this.options["app-id"] || this.answers.appId,
+      sdkPath: this.options["sdk-path"] || process.env.FIDJ_SDK_DIR,
+      oidcIssuer: this.options["oidc-issuer"],
+      local: this.options.local || process.env.FIDJ_LOCAL === "true",
+      replace: this.options.replace,
+      appId:
+        process.env.FIDJ_APP_ID || this.options["app-id"] || this.answers.appId,
       apiEndpoint: this.options["api-endpoint"],
     });
     this.log(
@@ -67,3 +107,5 @@ module.exports = class extends Generator {
     );
   }
 };
+module.exports.repeatedOption = repeated;

package/generators/app/templates/typescript/README.md CHANGED Viewed

@@ -29,7 +29,7 @@ The current unreleased generator requires the matching `@ofidj/node` 3.6.24 SDK.
 - `test/server.test.mjs`: fresh HTTP servers verify role changes, revoked/foreign sessions, outage failure, per-user notes and privacy scope.
 - `scripts/build.mjs`: browser and Node builds using [esbuild](https://esbuild.github.io/getting-started/), with a separate TypeScript typecheck.
-Run `npm test` before changing the template. Every fresh generated app includes the same tests.
+Use TDD: add and run a failing behavior test before implementation (red), make it pass (green), then refactor and run `npm test`. Change maintained template source and regenerate to verify that every fresh app receives the fix.
 ## Privacy scope
@@ -41,7 +41,7 @@ The browser SDK stores the app’s session in this origin’s local storage. Use
 ## Local scenario
-Only when using the loopback API, set `LOCAL_DEMO=true` to show synthetic Alex/Maya/Sam sign-in shortcuts. These accounts must be seeded by your local Fidj API; the starter does not create accounts or seed data remotely. Alex is the owner, and the owner console can grant Maya Editor access.
+For the Notes fixture only, `LOCAL_DEMO=true` with the loopback API enables synthetic Alex/Maya/Sam sign-in shortcuts. Content/module entries keep test accounts in developer documentation. These accounts must be seeded by your local Fidj API; the starter does not create accounts or seed data remotely. Alex is the owner, and the owner console can grant Maya Editor access.
 ## Entry flow
@@ -71,3 +71,13 @@ Keep `FIDJ_DATA_DIR` outside public assets and generated output. Use one writer
 After starting the Notes backend with its server-only adapter secret, run `npm run privacy:check`. The signed check confirms export/erase capabilities and writable storage without accessing user records. Override `FIDJ_APP_URL` for a deployed HTTPS backend. Keep this secret out of browser configuration.
 Run `npm run privacy:rehearse` for an isolated temporary-store HTTP scenario covering live roles, scoped export, persistence, failure and idempotent erasure. It never points at your running data directory. Groups are managed in the Fidj owner console; direct and group roles are checked live by the backend.
+## Agreement at sign-in
+Sign-in and account creation require the unchecked service-agreement checkbox.
+Read the app's current text/version from the dialog before accepting. If the
+agreement is not accepted, submitting explains the requirement while preserving
+the form; if the agreement cannot load, the form stays blocked. The API records the accepted
+version per app; optional privacy choices are separate. The app owner must replace
+the default demo agreement using the Fidj app's `configurationAsJSON.serviceAgreement`
+(`version` and `text`) before release. No generated-source edit is needed.

package/generators/app/templates/typescript/app.config.json CHANGED Viewed

@@ -6,5 +6,9 @@
   "localDemo": false,
   "allowAnonymous": true,
   "moduleEntry": "",
-  "description": "A space to explore, with an account that puts you in control."
+  "description": "A space to explore, with an account that puts you in control.",
+  "highlights": [],
+  "badges": [],
+  "logo": "./fidj-logo.png",
+  "favicon": "./fidj-logo.png"
 }

package/generators/app/templates/typescript/package.json CHANGED Viewed

@@ -15,7 +15,7 @@
     "privacy:rehearse": "npm run build && node --test test/server.test.mjs"
   },
   "dependencies": {
-    "@ofidj/node": "^3.6.24"
+    "@ofidj/node": "^3.6.26"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/generators/app/templates/typescript/public/fidj-logo.png CHANGED Viewed

Binary file

package/generators/app/templates/typescript/public/fonts/IBMPlexMono-400-latin-ext.woff2 ADDED Viewed

Binary file

package/generators/app/templates/typescript/public/fonts/IBMPlexMono-400-latin.woff2 ADDED Viewed

Binary file

package/generators/app/templates/typescript/public/fonts/IBMPlexMono-500-latin-ext.woff2 ADDED Viewed

Binary file

package/generators/app/templates/typescript/public/fonts/IBMPlexMono-500-latin.woff2 ADDED Viewed

Binary file

package/generators/app/templates/typescript/public/fonts/IBMPlexSans-400_600-latin-ext.woff2 ADDED Viewed

Binary file

package/generators/app/templates/typescript/public/fonts/IBMPlexSans-400_600-latin.woff2 ADDED Viewed

Binary file

package/generators/app/templates/typescript/public/fonts/InstrumentSerif-400-latin-ext.woff2 ADDED Viewed

Binary file

package/generators/app/templates/typescript/public/fonts/InstrumentSerif-400-latin.woff2 ADDED Viewed

Binary file

package/generators/app/templates/typescript/scripts/build.mjs CHANGED Viewed

@@ -13,6 +13,9 @@ await Promise.all([
     target: "es2022",
     outfile: "dist/public/main.js",
     sourcemap: true,
+    // The design system's fonts are copied with public/; esbuild must leave
+    // their url()s alone rather than try to resolve them at build time.
+    external: ["*.woff2"],
   }),
   build({
     entryPoints: ["server/index.ts"],

package/generators/app/templates/typescript/scripts/render-content.mjs CHANGED Viewed

@@ -8,7 +8,7 @@ const escape = (value) =>
   );
 export function renderContent(config) {
   // HTML is supplied by the developer at generation time, never by an app visitor.
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="referrer" content="no-referrer"><title>${escape(config.title)}</title><link rel="icon" href="./fidj-logo.png"><link rel="stylesheet" href="./main.css"></head><body>
-  <header class="topbar"><a class="brand" href="#/content">${escape(config.title)}</a><a class="fidj-brand" href="${escape(config.moduleEntry || config.dashboardUrl + "/#/my")}"><img src="./fidj-logo.png" alt="Fidj">My privacy ↗</a></header>
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="referrer" content="no-referrer"><title>${escape(config.title)}</title><link rel="icon" href="${escape(config.favicon)}"><link rel="stylesheet" href="./main.css"></head><body>
+  <header class="topbar"><a class="brand" href="#/content"><img src="${escape(config.logo)}" alt="">${escape(config.title)}</a></header>
   <main><template id="public-content"><section class="card public-content"><h1>${escape(config.welcome)}</h1><div>${config.content}</div></section></template><div id="app" aria-live="polite"></div><footer>Built with Fidj · Your choices belong to this app.</footer></main><script type="module" src="./main.js"></script></body></html>`;
 }

package/generators/app/templates/typescript/server/index.ts CHANGED Viewed

@@ -241,7 +241,16 @@ export function createApp(
         "/main.css": ["main.css", "text/css"],
         "/fidj-logo.png": ["fidj-logo.png", "image/png"],
       };
-      if (!files[pathname] && pathname.startsWith("/module/")) {
+      // Beyond the named files above, three directories are served from the
+      // build manifest: the assembled application module, the design system's
+      // self-hosted fonts, and any logo or favicon the app supplied. The
+      // manifest only resolves paths the build actually produced.
+      if (
+        !files[pathname] &&
+        (pathname.startsWith("/module/") ||
+          pathname.startsWith("/fonts/") ||
+          pathname.startsWith("/brand/"))
+      ) {
         const manifest = JSON.parse(
           await readFile(join(__dirname, "public-files.json"), "utf8"),
         );