@krizaka/org 0.5.0 → 0.7.0

package/README.md

@@ -19,6 +19,10 @@ Without a build step, read it from the CDN: [krizaka-assets.b-cdn.net/org/v1/org
   (`defaults/v1/<kind>/<id>-<size>.<ext>`, written by krizaka-ui `tools/export-defaults.mjs`). An app never hard-codes or bundles one:
   `listDefaults(kind)` lists them, `defaultFor(kind, seed)` picks one deterministically (FNV-1a of the seed, modulo the list), `defaultUrl(item, size)` gives the URL,
   `fetchDefaults(ORG_URL)` reads the section from the published JSON. A folder is never given a person.
+- **One name per entry of the family.** `org.family` (and `familyName(id)`) is the only place a name is written: the company
+  is « Krizaka », a product goes by its own name (Orazaka, Yomizaka, Akinaza — never « Krizaka Yomizaka »), a library or a tool
+  is « Krizaka <X> » (Krizaka UI, Krizaka Java, Krizaka TypeScript, Krizaka Lab; the short name only under a
+  heading « Open source »). The bar, the switcher and every footer read it; a test holds the rule.
 - **Public facts only.** Never an address, a phone number, figures, a secret, an IP address or an internal host: the test
   scans for them and the schema refuses any field it does not list.
 - **Validated.** `orgSchema` (JSON Schema 2020-12) and the types `Org`, `AppConfig`…; a test validates the data and requests every
@@ -29,3 +33,31 @@ Without a build step, read it from the CDN: [krizaka-assets.b-cdn.net/org/v1/org
   `MEDIA_STORAGE_API_KEY` and `MEDIA_STORAGE_ZONE`; without them it warns and publishes nothing.
 
 Apache-2.0 · [Krizaka TypeScript](https://github.com/krizaka/krizaka-ts)
+
+## What `org.json` is, and what it is not
+
+**Service discovery only** (founder, 2026-11-01): the addresses and versions clients resolve (API URLs, minimum and latest app
+versions, the default media, the family's names and addresses). It is read at start by the apps and published at each release.
+Names, status, store availability, social links and the footer contents are **not** in it: they are admin configuration of each
+app in its database, through `@krizaka/settings` (audit trail), read at runtime and at build where needed (a save redeploys).
+The shared validation (no code name as a display name, FR/EN labels, valid URLs) lives in the settings package.
+
+A rename is therefore: the administrator edits the value in the app's settings, saves, and the build-time pages redeploy.
+The seed below is only the default of that setting.
+
+## Commercial names (`brands`, a seed)
+
+The code names (`yomizaka`, `akinaza`, `orazaka`, `kachizaka`) stay internal: repositories, packages, coordinates, CLI. A customer
+reads the commercial name, endorsed by the company — **« Verikora by Krizaka »** / **« Verikora par Krizaka »**.
+
+```ts
+import { brandOf, displayName, lockup } from "@krizaka/org";
+brandOf("akinaza").domains.shop; // "https://folioviv.shop"
+displayName("yomizaka", settingValue); // the admin's choice (`brand.displayName`), else « Verikora »
+lockup("orazaka", "fr"); // « Sovkora par Krizaka »
+```
+
+**The guard.** `npx krizaka-code-names [--report] [--allow <path-part>] <built-html-dir> messages/ stores/` fails when a
+public surface shows a code name (or « Krizaka ECM ») where the commercial name is required. Allowed, declared once: URLs
+and hosts, `@krizaka/*` and `com.krizaka.*` coordinates, `krizaka/<repo>`, code (backticks, `<pre>`, `<code>`), class names
+and attributes other than `alt` / `title` / `aria-label`, catalogue keys, and each brand's one « formerly » line.

package/bin/krizaka-code-names.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// krizaka-code-names — a public surface never shows a code name where the commercial name is required (krizaka-internal#2036).
+//   krizaka-code-names [--report] [--allow <path-part>]... <file-or-dir>...
+// Reads built HTML (visible text, title, description, social metadata, alt/title/aria-label), message catalogues (values only),
+// and any other text file (emails, receipts, stores/*.json, llms.txt). `--allow` skips the files whose path contains the part
+// (internal pages, developer pages). Exit 1 on a hit; `--report` prints and exits 0 (a repo starts as a report, then requires it).
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+
+import { catalogueValues, findCodeNames, visibleText } from "../dist/index.js";
+
+const args = process.argv.slice(2);
+const report = args.includes("--report");
+const allow = [];
+const roots = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--report") continue;
+  if (args[i] === "--allow") allow.push(args[++i]);
+  else roots.push(args[i]);
+}
+if (roots.length === 0) {
+  console.error("usage: krizaka-code-names [--report] [--allow <path-part>]... <file-or-dir>...");
+  process.exit(2);
+}
+const TEXT = new Set([".html", ".htm", ".json", ".txt", ".md", ".mjml", ".hbs", ".xml", ".vtt"]);
+const files = [];
+const walk = (p) => {
+  if (allow.some((a) => p.includes(a))) return;
+  if (statSync(p).isDirectory()) {
+    for (const e of readdirSync(p)) if (e !== "node_modules" && !e.startsWith(".")) walk(join(p, e));
+  } else if (TEXT.has(extname(p).toLowerCase())) files.push(p);
+};
+roots.forEach(walk);
+
+let count = 0;
+for (const file of files) {
+  const raw = readFileSync(file, "utf8");
+  const ext = extname(file).toLowerCase();
+  let pieces;
+  if (ext === ".html" || ext === ".htm") pieces = [["", visibleText(raw)]];
+  else if (ext === ".json") {
+    try {
+      pieces = catalogueValues(JSON.parse(raw));
+    } catch {
+      pieces = [["", raw]];
+    }
+  } else pieces = [["", raw]];
+  for (const [key, text] of pieces) {
+    for (const hit of findCodeNames(text)) {
+      count++;
+      const where = key ? `${file} ${key}` : file;
+      console.log(`${where}: « ${hit.word} » → « ${hit.use} »  …${hit.context}…`);
+    }
+  }
+}
+console.log(`${count} code name(s) on public surfaces in ${files.length} file(s)${report ? " (report only)" : ""}.`);
+process.exit(count > 0 && !report ? 1 : 0);

package/dist/index.d.ts

@@ -18,6 +18,30 @@ interface OrgSite {
     name: string;
     url: string;
 }
+/** Where an entry of the family sits: the company's own pages, the products, the open-source libraries and tools, GitHub. */
+type FamilyGroup = "krizaka" | "products" | "open-source" | "github";
+/** `released`: open to use. `development`: built in the open, said « In development ». */
+type FamilyStatus = "released" | "development";
+/**
+ * One name of the family, the only place it is written. The naming rule (founder, 2026-10-30): the company is
+ * « Krizaka »; a product goes by its own name (« Yomizaka », never « Krizaka Yomizaka »); a library or a tool is always
+ * « Krizaka <X> » (« Krizaka UI », never « UI » alone outside a group headed « Open source »).
+ */
+interface FamilyEntry {
+    id: string;
+    /** The display name, never translated (« Krizaka TypeScript »). */
+    name: string;
+    /** The short name, only inside its group's heading (« TypeScript » under « Open source »). */
+    short: string;
+    group: FamilyGroup;
+    status: FamilyStatus;
+    /** The day it was released (`YYYY-MM-DD`): `released` on a product or an open-source entry needs it, data not words. */
+    releasedAt?: string;
+    /** Its home: the site, or the repository while it has no site. */
+    url: string;
+    /** Its public source repository (`null` for GitHub itself). */
+    repo: string | null;
+}
 interface OrgAvatar {
     id: string;
     /** `person` is a silhouette, `plain` a plain disc. */
@@ -112,6 +136,8 @@ interface Org {
     /** Only the products that are live. */
     products: OrgProduct[];
     sites: OrgSite[];
+    /** Every name of the family, in reading order (group, then order inside it): the bar, the switcher and every footer read it. */
+    family: FamilyEntry[];
     contact: {
         page: Localized;
         /** The public support address; `null` while none is public. */
@@ -147,6 +173,73 @@ declare const APP_SCHEMA_URL = "https://krizaka-assets.b-cdn.net/org/v1/app.sche
 /** The runtime config a mobile app may know, per live product. The app reads it at start, with a copy built into the binary as fallback. */
 declare const apps: Record<string, AppConfig>;
 
+/**
+ * The commercial names (krizaka-internal#2033, #2035, #2036): the code name stays internal, the customer reads the
+ * commercial name, « Verikora by Krizaka ». Every app, site and template reads them from here — never a literal.
+ *
+ * These are NOT in `org.json`: the org JSON is service discovery only (the addresses and versions clients resolve). Names,
+ * status, stores and the footer are admin configuration of each app (`@krizaka/settings`, audit trail); this module is the
+ * seed and the validation vocabulary, not a published file.
+ */
+/** `product`: sold on its own. `service`: a part the products carry (Kridoc, the managed storage). */
+type BrandKind = "product" | "service";
+interface OrgBrand {
+    /** The internal name: the repository, the packages, the CLI (`yomizaka`). Never on a public page. */
+    codeName: string;
+    /** The name the customer reads (`Verikora`). One capital; capitals only in the wordmark. */
+    commercialName: string;
+    kind: BrandKind;
+    /** The endorsement after the name: « by Krizaka » / « par Krizaka ». */
+    endorsement: Localized;
+    /** The hosts of the brand (https URLs); `null` where it has none. */
+    domains: {
+        site: string;
+        app: string | null;
+        shop: string | null;
+        dev: string | null;
+    };
+    /** The one dated « formerly » line of the transition; `null` when the code name was never public. */
+    formerly: Localized | null;
+}
+/** The seed: one commercial name per code name. Nothing flips to it until the readiness checklist (krizaka-internal#2092). */
+declare const brands: readonly OrgBrand[];
+/** The brand of a code name (`brandOf("yomizaka").commercialName` → « Verikora »). */
+declare const brandOf: (codeName: string) => OrgBrand;
+/** The longest name an administrator may set (a bar, a store listing and an email subject must hold it). */
+declare const DISPLAY_NAME_MAX = 30;
+/**
+ * The name an app shows: the administrator's choice (`brand.displayName` in its settings) when one is set, else the
+ * commercial name. Never the code name: a setting equal to a code name falls back to the commercial name.
+ */
+declare const displayName: (codeName: string, chosen?: string | null) => string;
+/** The lockup in words: « Verikora by Krizaka » / « Verikora par Krizaka ». `fr` reads French, anything else English. */
+declare const lockup: (codeName: string, locale: string, chosen?: string | null) => string;
+/** The words a public surface never shows: every code name, and « Krizaka ECM » (it is Kridoc). */
+declare const CODE_NAMES: readonly string[];
+/** The code name → commercial name map the guard prints in its hints. */
+declare const codeNameMap: () => Record<string, string>;
+interface CodeNameHit {
+    /** The word found, as written. */
+    word: string;
+    /** What to write instead. */
+    use: string;
+    /** Up to 40 characters around it. */
+    context: string;
+}
+/** The code names a piece of customer-facing text shows (case-insensitive, whole words), minus the allowed spans. */
+declare const findCodeNames: (text: string) => CodeNameHit[];
+/**
+ * The text a visitor reads in a built HTML page: the body text, the title, the description and social metadata, and the
+ * `alt`, `title` and `aria-label` attributes. Scripts, styles, `<pre>` and `<code>` (developer pages' commands) and
+ * comments are left out, and so are class names and links (a `brand-yomizaka` class or a GitHub href is not shown).
+ */
+declare const visibleText: (html: string) => string;
+/**
+ * The values of a message catalogue (EN/FR JSON), keyed by their path. A key path may name a code name
+ * (`site.yomizaka.title`): keys are structure; only the values are read by a customer.
+ */
+declare const catalogueValues: (catalogue: unknown, path?: string) => [string, string][];
+
 /** The products that have a demo cast. */
 type CastProduct = "orazaka" | "yomizaka" | "akinaza";
 /** What a persona does in the app: a member, a shop owner or a customer of one, an administrator. */
@@ -207,7 +300,6 @@ declare function fetchDefaults(url: string, fetchImpl?: typeof fetch): Promise<O
 declare const CDN = "https://krizaka-assets.b-cdn.net";
 declare const ORG_URL = "https://krizaka-assets.b-cdn.net/org/v1/org.json";
 declare const ORG_SCHEMA_URL = "https://krizaka-assets.b-cdn.net/org/v1/org.schema.json";
-/** The public facts about Krizaka. Reviewed by pull request; changing a fact is one PR here and a release. */
 declare const org: Org;
 
 /** The JSON Schema of `org/v1/org.json`. Nothing outside it is allowed (`additionalProperties: false` everywhere): a new fact is a new line here first. */
@@ -217,7 +309,7 @@ declare const orgSchema: {
     readonly title: "Krizaka organisation — public facts";
     readonly type: "object";
     readonly additionalProperties: false;
-    readonly required: readonly ["$schema", "schemaVersion", "version", "updatedAt", "company", "brand", "people", "defaults", "products", "sites", "contact", "footer"];
+    readonly required: readonly ["$schema", "schemaVersion", "version", "updatedAt", "company", "brand", "people", "defaults", "products", "sites", "family", "contact", "footer"];
     readonly properties: {
         readonly $schema: {
             readonly type: "string";
@@ -695,6 +787,53 @@ declare const orgSchema: {
                 };
             };
         };
+        readonly family: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "name", "short", "group", "status", "url", "repo"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-z0-9]+(-[a-z0-9]+)*$";
+                    };
+                    readonly name: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly short: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly group: {
+                        readonly enum: readonly ["krizaka", "products", "open-source", "github"];
+                    };
+                    readonly status: {
+                        readonly enum: readonly ["released", "development"];
+                    };
+                    readonly releasedAt: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                    };
+                    readonly url: {
+                        readonly type: "string";
+                        readonly format: "uri";
+                        readonly pattern: "^https://";
+                    };
+                    readonly repo: {
+                        readonly anyOf: readonly [{
+                            readonly type: "string";
+                            readonly format: "uri";
+                            readonly pattern: "^https://";
+                        }, {
+                            readonly type: "null";
+                        }];
+                    };
+                };
+            };
+        };
         readonly contact: {
             readonly type: "object";
             readonly additionalProperties: false;
@@ -858,5 +997,8 @@ declare const appSchema: {
 declare const localized: (text: Localized, locale: string) => string;
 /** The footer line of the family, « Une entreprise de Technologies Krizaka · Fait à Montréal ». */
 declare const footerLine: (locale: string) => string;
+/** A name of the family by id (`familyName("ts")` → « Krizaka TypeScript »): the only way a site writes one. */
+declare const familyEntry: (id: string) => FamilyEntry;
+declare const familyName: (id: string) => string;
 
-export { APP_SCHEMA_URL, type AppConfig, type AppEnvironment, CAST, CAST_VERSION, CDN, type CastPersona, type CastProduct, type CastRole, DEFAULT_KINDS, type Localized, ORG_SCHEMA_URL, ORG_URL, type Org, type OrgAvatar, type OrgBanner, type OrgDefaultItem, type OrgDefaultKind, type OrgDefaults, type OrgMark, type OrgProduct, type OrgSite, type ProductStatus, appSchema, apps, castMedia, castOf, defaultFor, defaultUrl, defaults, fetchDefaults, footerLine, listDefaults, localized, org, orgSchema, persona, personaByRole, seedFingerprint, seedHash };
+export { APP_SCHEMA_URL, type AppConfig, type AppEnvironment, type BrandKind, CAST, CAST_VERSION, CDN, CODE_NAMES, type CastPersona, type CastProduct, type CastRole, type CodeNameHit, DEFAULT_KINDS, DISPLAY_NAME_MAX, type FamilyEntry, type FamilyGroup, type FamilyStatus, type Localized, ORG_SCHEMA_URL, ORG_URL, type Org, type OrgAvatar, type OrgBanner, type OrgBrand, type OrgDefaultItem, type OrgDefaultKind, type OrgDefaults, type OrgMark, type OrgProduct, type OrgSite, type ProductStatus, appSchema, apps, brandOf, brands, castMedia, castOf, catalogueValues, codeNameMap, defaultFor, defaultUrl, defaults, displayName, familyEntry, familyName, fetchDefaults, findCodeNames, footerLine, listDefaults, localized, lockup, org, orgSchema, persona, personaByRole, seedFingerprint, seedHash, visibleText };