@mpfrontend/ftg-cli 0.0.0-stage → 0.1.0

package/DESIGN-SYNC.md

@@ -0,0 +1,159 @@
+# Reviewed export synchronization
+
+CLI 0.1.0 implements explicit source onboarding plus a **finite normalized local export** profile. It does not call Figma, infer
+missing behavior, run an LLM, execute test commands, publish or monitor for updates. The caller must
+have implementation authority for the named consumer and separate human review for promotion.
+The baseline covers only the declared export, never an assertion that the entire Figma DLS is implemented.
+
+## Select and attach the source
+
+Initialize a new workspace with exactly one mode:
+
+```sh
+mpfrontend init --name product --directory ./product --design-source none --json
+mpfrontend init --name product --directory ./product --design-source existing --json
+```
+
+`none` is code-first and reports `disabled`; it can attach later. `existing` means the product/team owns
+its own private or public DLS, its binding, exports and distribution rights. The design-backed mode
+starts `pending`; initialization does not inspect, copy, publish or change any Figma file. The MVP does
+not ship or depend on a Figma Community design system.
+
+After creating the binding described below, attach and verify it:
+
+```sh
+mpfrontend design attach --directory . --source existing --binding design.binding.json --dry-run --json
+mpfrontend design attach --directory . --source existing --binding design.binding.json --json
+mpfrontend design status --directory . --json
+```
+
+Attachment verifies the full canonical binding hash. The attached contract is immutable: selecting
+another source or binding requires an explicitly reviewed new workspace/migration, not a force flag.
+Paths and symlinks fail closed, writers use an exclusive lock, and dry-run writes nothing. `status`
+revalidates current files but never imports or accepts a baseline.
+
+The attachment records the binding path/hash but does not duplicate the private source
+identity into `.mpfrontend/design-source.json`; the consumer binding remains authoritative. This reduces
+metadata duplication but is not publication sanitization: a private binding/export still stays private.
+
+## Inputs
+
+Place `design.binding.json` at the consumer root. All paths are relative to that root. Snapshot input
+can be an explicitly supplied local file; source identity must match. Unknown revision/capture time stay null.
+Preserve the original export and its provenance outside core; record any deliberate normalization,
+collection/mode projection or omitted scope. Do not invent a capture/revision or distribution rights.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "product-theme",
+  "source": {"fileKey": "supplied-file-key", "nodeId": "1:2"},
+  "brandId": "product-brand",
+  "modeAttribute": "data-mode",
+  "stateDirectory": ".mpfrontend/design/product-theme",
+  "outputDirectory": "themes/product-theme/generated",
+  "tokens": [{"sourceId": "color:surface", "cssName": "--mp-surface-canvas"}],
+  "components": [{"sourceId": "button:1", "adapter": "src/button.tsx", "tests": ["tests/button.test.ts"]}],
+  "ignoredTokens": [],
+  "ignoredComponents": []
+}
+```
+
+`modeAttribute` is data-mode or data-theme. State directory must be `.mpfrontend/design/<id>` and
+output a themes/packages subdirectory ending in `/generated`. Stable source IDs may contain letters,
+digits, dots, colons, underscores and hyphens; prototype keys are refused. CSS names and brand IDs
+have constrained syntax. Ignore entries are `{sourceId, reason}` and cannot overlap mapped entries.
+Ignored scope is an explicit reviewed exclusion, not full-DLS acceptance.
+
+```json
+{
+  "schemaVersion": 1,
+  "source": {
+    "fileKey": "supplied-file-key", "nodeId": "1:2", "revision": null,
+    "capturedAt": "2026-10-07T07:00:00.000Z", "extractorVersion": "reviewed-export-v1"
+  },
+  "modes": ["light", "dark"],
+  "tokens": [{
+    "id": "color:surface", "name": "Canvas", "type": "color",
+    "values": {"light": "#ffffff", "dark": "#101010"}
+  }],
+  "components": [{
+    "id": "button:1", "name": "Button", "variants": {"tone": ["primary", "ghost"]},
+    "properties": {"disabled": "boolean"},
+    "behavior": {"status": "known", "description": "Disabled prevents pointer and keyboard activation"},
+    "assets": []
+  }],
+  "assets": []
+}
+```
+
+Token types: color (3/4/6/8-digit hex), dimension (`{value, unit}` with px/rem/em/%), finite number,
+or a constrained plain string. A value can instead be `{alias: "stable-token-id"}` in either mode;
+cycles, absent targets and incompatible types fail. This is not arbitrary CSS/gradient/expression,
+font-asset or multi-collection compilation. The profile explicitly requires light/dark normalized modes;
+additional modes/unknown schema fields are rejected rather than discarded. Component variants are
+named string lists; properties describe an authored API, not a TypeScript code generator. Behavior
+can be unknown for import/diff, but an unknown mapped behavior blocks application/promotion.
+
+Assets are `{id, sha256, mimeType, license}`; component asset IDs must resolve. Unknown license blocks
+application. Only metadata is generated: binary assets/fonts and their rights remain consumer-owned.
+Do not interpret a declared license string as independent legal clearance.
+
+## Commands and ownership
+
+```sh
+mpfrontend design import --binding design.binding.json --snapshot reviewed-export.json --dry-run --json
+mpfrontend design import --binding design.binding.json --snapshot reviewed-export.json --json
+mpfrontend design validate --binding design.binding.json --candidate <hash> --json
+mpfrontend design diff --binding design.binding.json --candidate <hash> --json
+mpfrontend design plan --binding design.binding.json --candidate <hash> --dry-run --json
+mpfrontend design plan --binding design.binding.json --candidate <hash> --json
+mpfrontend design apply --plan <returned-plan-path> --dry-run --json
+mpfrontend design apply --plan <reviewed-plan-path> --json
+mpfrontend design accept --plan <reviewed-plan-path> --evidence evidence/acceptance.json --dry-run --json
+mpfrontend design check --binding design.binding.json --json
+```
+
+Import creates a hash-addressed immutable candidate, never a baseline. Plan is bound to the candidate,
+CLI version, canonical binding, prior baseline/ownership and current output hashes. Review it before
+apply. Apply writes only two owned outputs (`tokens.gen.css`, `components.gen.json`) and an ownership
+receipt. CSS is brand-scoped with light/dark and system-dark selectors. Component metadata is not
+React implementation. Initial/changed/removed components, asset changes and token rename/removal
+produce authored tasks; unchanged mapped components still require adapter/test evidence.
+
+Unknown mappings, unresolved behavior/rights, stale plans and an unowned output collision fail closed.
+Paths cannot traverse or enter protected/private configuration; every consumer symlink is refused.
+Writers acquire an exclusive `.design-write.lock`, stage files and compare before replacement. Rollback
+preserves a concurrent edit and reports conflicts. This is not a crash-atomic filesystem transaction:
+after interruption inspect the marker, staged/owned files, hashes and exact plan before operator recovery.
+No age-based marker removal, force overwrite or authored-source deletion is implemented. Cooperative
+writer locks do not turn an adversarial local filesystem into a sandbox/security boundary.
+
+Exit codes: 0 success, 2 invalid/unsupported inputs or unresolved mapping, 3 stale/drift/failed acceptance,
+4 path/ownership/concurrency violation. Dry-run performs no writes. Check before a baseline is accepted
+fails with code 3; applying tokens alone is not an accepted synchronization.
+
+## Evidence and acceptance
+
+`accept` consumes a reviewed attestation, **not a test execution engine**. The responsible developer/CI
+must actually run each named check and supply its artifact. A digest validates artifact identity and
+current files; it cannot prove that a human's claimed result is truthful or that a screenshot is good.
+Never use the synthetic unit attestations as real reference/production acceptance.
+
+Evidence JSON has exact schemaVersion, planId, candidateHash, bindingHash and cliVersion; review is
+`{approved: true, reviewer: "review identity"}`. Required checks are unit, typecheck, visual-light,
+visual-dark, rtl, keyboard and contrast; asset-rights is additionally required when assets exist.
+Each check is `{name, passed: true, command, artifact: {path, sha256}}`. Artifacts and the report are
+consumer-local under evidence/; hashes use raw bytes. Do not put credentials or private data in reports.
+
+Each task is `{id, status: "implemented", files: [{path, sha256}]}` and must include all required
+authored adapter/test paths. Migration/asset tasks require at least one reviewed authored file.
+Unknown/duplicate check/task IDs, failed checks, missing tasks/files and changed artifacts refuse
+promotion. Re-running checks/code review is the caller's responsibility after any relevant change.
+Successful acceptance records the exact candidate/plan/binding/evidence identity. Later check verifies
+the accepted outputs, report and referenced current artifacts/authored files; altered evidence fails.
+Publication and owner visual approval remain separate gates.
+
+The source regression suite executes all seven commands, semantic behavior/removal/alias scenarios,
+safety refusals and isolated acceptance-guard removals. Independent packed-command verification and
+real consumer DLS adoption are tracked in the workspace implementation status, not inferred here.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @mpfrontend/ftg-cli
 
-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.
+Local development package. Runtime: tooling. Public API is exported from src/index.ts and compiled
+into dist. Nx owns build, typecheck, lint and test targets. Consumer applications install packed artifacts.
+See ../../docs/IMPLEMENTATION-STATUS.md for observed evidence and remaining work.
+
+## Repository commands
+
+```sh
+mpfrontend init --name my-product --directory ./my-product --design-source none --dry-run --json
+mpfrontend init --name my-product --directory ./my-product --design-source existing --json
+mpfrontend design attach --directory ./my-product --source existing --binding design.binding.json --json
+mpfrontend design status --directory ./my-product --json
+mpfrontend create app --name customer --directory ./my-product/apps/customer --dry-run
+mpfrontend create feature --app apps/customer --name order-review --dry-run --json
+mpfrontend create route --app apps/customer --path order-review --feature order-review --json
+mpfrontend create package --name formatting --runtime universal --json
+mpfrontend skills list --json
+mpfrontend skills install --directory ./my-product --for both --profile base --dry-run --json
+mpfrontend skills check --directory ./my-product --json
+ftg generate --config ./my-product/apps/customer/ftg.config.json --dry-run --json
+ftg check --config ./my-product/apps/customer/ftg.config.json --json
+```
+
+The [CLI guide](../../docs/CLI-GUIDE.md) describes every command: what it does, when to run it, what it
+writes and what it refuses.
+
+`init` creates a neutral pinned Nx/pnpm shell in a **new** directory; an existing directory or symlink
+is refused. It does not install dependencies, run Git, access/modify Figma, deploy, publish or configure
+protected runtime authority. The catalog template requires an explicitly supplied approved OpenAPI
+contract. The generated README describes the sequence; a scaffold/build is not production acceptance.
+Development packages are not published: local validation supplies verified tarball overrides.
+
+Design-source selection is an explicit workspace contract:
+
+- `none` is a fully usable code-first workspace and may attach a source later.
+- `existing` is a consumer-owned private or product DLS. Attachment validates only the local binding;
+  the source, normalized exports, mappings, assets and distribution rights remain in the consumer.
+
+The MVP does not publish, require or offer a Figma Community DLS. A product without a DLS can remain
+code-first with `none`; a product with any approved existing Figma/DLS uses `existing`.
+
+Initialization records `disabled` or `pending` state in `.mpfrontend/design-source.json`; it never
+captures or writes Figma. `design attach` changes only that root contract, is dry-run capable,
+exclusive and idempotent for the exact same attachment, and refuses source changes once attached.
+`design status` revalidates an attached consumer binding. It does not import or accept a design
+baseline. See [the design contract](./DESIGN-SYNC.md).
+
+All eighteen approved finite source procedures are available. Actual agent behavioral acceptance remains
+separate. Skill ownership
+and repository concurrency rules are described in @mpfrontend/ai-skills, not hidden by placeholders.
+
+FTG refuses generation/check/dry-run while an output `.ftg-write.lock` marker exists. Writers acquire
+it exclusively and compare planned files before replacement; rollback preserves a concurrent change
+instead of silently overwriting it. A crashed writer can leave its marker/partial output: inspect the
+files and reconcile their manifest before an operator removes the stale marker. There is no force
+option or automatic age-based deletion. Multi-file output is not a crash-atomic filesystem transaction.
+
+FTG generator dev.6 emits selected full 200/201/202 JSON-response or explicit empty-204
+`ReadModels`/`parseRead`, standalone CJS validators and
+declarations in the same owned output/manifest as resource field metadata. `responsePath` selects
+table fields only; it does not truncate the response reader. Validators are compiled during generation
+using Ajv 8.20.0 and ajv-formats 3.0.1; consumers need those exact runtime-helper dependencies.
+Runtime does not compile schemas or require unsafe-eval. Invalid data throws a generic error without
+logging payloads; values are never coerced, defaulted or stripped. Required write-only properties are
+omitted from read types/requirements and explicitly rejected in a response, even in an open object.
+
+Read generation currently requires OpenAPI 3.1 finite object/array shapes. Unsupported recursive,
+composed or mixed fixed/dictionary models and meaningful reference siblings are rejected rather than
+guessed. This is not complete form/write/permission generation. See the
+[OpenAPI schema specification](https://spec.openapis.org/oas/v3.1.0.html#schema-object) and
+[Ajv standalone design](https://ajv.js.org/standalone.html) for the underlying contracts.
+
+Explicit `requests` selections independently generate `RequestModels`, `requests` field metadata and
+`parseRequest` standalone validators. The JSON profile requires a required JSON object mutation body,
+closed objects at every level and supported non-recursive schemas. It preserves validation constraints,
+includes write-only inputs and forbids read-only/unknown fields. An explicit request selection with
+`body: "none"` requires an absent OpenAPI requestBody and emits an undefined-only type/validator and
+empty field metadata. Any supplied payload is refused, including null and an empty object. This is a
+consumer restriction, not an inference that every server with absent metadata forbids all bodies.
+An explicit request selection with `body: "optional-json"` instead requires a present OpenAPI
+requestBody whose `required` flag is not true. It emits `undefined` plus the declared finite closed
+object shape; an exact null/object union also includes null. Its validator accepts absence and valid
+declared values while still rejecting malformed, unknown or incomplete objects.
+An explicit response selection with `responseStatus: "204"` and `body: "none"` requires a declared
+204 response with no `content`, forbids `responsePath`, and emits an undefined-only read type/validator.
+JSON profiles never silently become empty. Other empty statuses, multipart, guarded PATCH, business
+rules and inferred widgets remain unsupported. See
+[request integration](../../docs/R4-GENERATED-REQUESTS.md) for its tested scope.
+
+The executable reports its own packaged version, not the generator's version. Fresh packed-consumer
+validation checks this equality, thirty-six installed Codex/Claude procedure files, required-boolean false,
+real client bundling, frozen installation and preservation controls. Advisory upload is separate:
+`tools/distribution/consumer.mjs` does not run online audit unless explicitly given `--online-audit`.
+Without it the report says `dependencyAudit: not-run`, never passed. Get authorization for metadata
+upload to the registry's advisory service before selecting that option.
+
+CLI dev.18 provides source `attach`/`status` plus the seven lifecycle `design` commands against a
+finite normalized local export:
+[reviewed export lifecycle and evidence contract](./DESIGN-SYNC.md). Base skills install twenty-eight
+files; the combined design profile installs thirty-six. An import never changes baseline, a generated
+component registry is not React implementation, and acceptance verifies reviewed artifact identities
+rather than executing or judging the reported tests. Actual reference design/visual acceptance remains
+separate. No Figma write, automatic watcher, deployment or registry action is performed.

package/dist/catalog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Checks every catalog set of an app against its locale registry: each registry locale has a catalog, each
+ * catalog has exactly the base keys, every message parses and takes the base parameters, and code uses
+ * every key. The registry is `localeRegistry` of `src/config/app.ts`; catalogs are the default exports of
+ * `messages/<locale>.ts` files, read with Node's TypeScript type stripping.
+ */
+export declare function catalogCheck(appDirectory: string): Promise<{
+    ok: boolean;
+    locales: any[];
+    defaultLocale: string;
+    catalogs: string[];
+    keys: number;
+    problems: (Readonly<{
+        code: "MISSING_LOCALE" | "UNKNOWN_LOCALE" | "MISSING_KEY" | "EXTRA_KEY" | "UNUSED_KEY" | "UNDEFINED_KEY" | "PARAMETER_MISMATCH" | "INVALID_MESSAGE";
+        locale?: string;
+        key?: string;
+    }> & {
+        catalog: string;
+    })[];
+}>;

package/dist/catalog.js

@@ -0,0 +1,134 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join, resolve, relative, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { checkCatalogs } from '@mpfrontend/i18n';
+import { InputError } from './index.js';
+const sourceFile = /\.(?:ts|tsx|mts|cts|js|jsx|mjs)$/;
+const testFile = /\.test\.[a-z]+$/;
+const literal = /(['"`])((?:\\.|(?!\1)[^\\\n])*)\1/g;
+const translatorVariable = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*([A-Za-z_$][\w$]*)\.translator\(/g;
+const namedImports = /import\s*(?:type\s+)?\{([^}]*)\}\s*from\s*(['"])(\.{1,2}\/[^'"]*)\2/g;
+const escape = (value) => value.replace(/[$]/g, '\\$&');
+/**
+ * The keys a source file asks each catalog set for: the literal first argument of a call of a translator
+ * variable (`const t = messages.translator(...)`) whose messages object is imported from a set's module
+ * (`<dir>/messages`, or a folder whose `messages/` holds the set).
+ */
+function translatorKeys(file, source, sets) {
+    const imported = new Map();
+    for (const match of source.matchAll(namedImports))
+        for (const part of match[1].split(',')) {
+            const [name, alias] = part.trim().split(/\s+as\s+/);
+            if (name)
+                imported.set((alias ?? name).trim(), resolve(dirname(file), match[3]));
+        }
+    const keys = new Map();
+    for (const match of source.matchAll(translatorVariable)) {
+        const module = imported.get(match[2]);
+        if (!module)
+            continue;
+        const set = sets.has(module) ? module : sets.has(join(module, 'messages')) ? join(module, 'messages') : undefined;
+        if (!set)
+            continue;
+        const calls = new RegExp('(?<![\\w$.])' + escape(match[1]) + '\\(\\s*([\'"`])((?:\\\\.|(?!\\1)[^\\\\\\n$])*)\\1', 'g');
+        for (const call of source.matchAll(calls)) {
+            const found = keys.get(set) ?? new Set();
+            found.add(call[2]);
+            keys.set(set, found);
+        }
+    }
+    return keys;
+}
+/** Every directory named `messages` under `src`, and every source file outside them; links are not followed. */
+async function walk(root, directory, sets, sources) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory()) {
+            if (entry.name === 'generated' || entry.name === 'node_modules')
+                continue;
+            if (entry.name === 'messages') {
+                const locales = {};
+                for (const file of await readdir(path, { withFileTypes: true }))
+                    if (file.isFile() && /^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*\.ts$/.test(file.name))
+                        locales[file.name.slice(0, -3)] = join(path, file.name);
+                // A feature's or an entity's catalog is used within that unit; the app catalog anywhere in src.
+                const parts = relative(root, path).split(sep);
+                const unit = parts[0] === 'features' || parts[0] === 'entities' ? join(root, parts[0], parts[1]) : root;
+                sets.push({ path, scope: unit, locales });
+            }
+            else
+                await walk(root, path, sets, sources);
+        }
+        else if (entry.isFile() && sourceFile.test(entry.name) && !testFile.test(entry.name))
+            sources.push(path);
+    }
+}
+/**
+ * Checks every catalog set of an app against its locale registry: each registry locale has a catalog, each
+ * catalog has exactly the base keys, every message parses and takes the base parameters, and code uses
+ * every key. The registry is `localeRegistry` of `src/config/app.ts`; catalogs are the default exports of
+ * `messages/<locale>.ts` files, read with Node's TypeScript type stripping.
+ */
+export async function catalogCheck(appDirectory) {
+    const app = resolve(appDirectory), src = join(app, 'src');
+    let registry;
+    try {
+        registry = (await import(pathToFileURL(join(src, 'config/app.ts')).href)).localeRegistry;
+    }
+    catch {
+        registry = undefined;
+    }
+    if (!registry || !Array.isArray(registry.locales) || typeof registry.defaultLocale !== 'string')
+        throw new InputError('LOCALE_REGISTRY_UNREADABLE');
+    const sets = [], sources = [];
+    await walk(src, src, sets, sources);
+    const literals = new Map(), requested = new Map();
+    const setPaths = new Set(sets.map(set => set.path));
+    for (const file of sources) {
+        const values = new Set(), source = await readFile(file, 'utf8');
+        for (const match of source.matchAll(literal))
+            if (!match[2].includes('${'))
+                values.add(match[2]);
+        literals.set(file, values);
+        for (const [set, keys] of translatorKeys(file, source, setPaths)) {
+            const all = requested.get(set) ?? new Set();
+            for (const key of keys)
+                all.add(key);
+            requested.set(set, all);
+        }
+    }
+    const problems = [];
+    let keys = 0;
+    for (const set of sets) {
+        const catalogs = {};
+        for (const [code, file] of Object.entries(set.locales)) {
+            if (!registry.locales.includes(code)) {
+                problems.push({ catalog: relative(app, set.path), code: 'UNKNOWN_LOCALE', locale: code });
+                continue;
+            }
+            try {
+                const value = (await import(pathToFileURL(file).href)).default;
+                if (!value || typeof value !== 'object' || Object.values(value).some(message => typeof message !== 'string'))
+                    throw new Error();
+                catalogs[code] = value;
+            }
+            catch {
+                problems.push({ catalog: relative(app, set.path), code: 'INVALID_MESSAGE', locale: code });
+            }
+        }
+        const used = new Set();
+        for (const [file, values] of literals)
+            if (file.startsWith(set.scope + sep))
+                for (const value of values)
+                    used.add(value);
+        keys += Object.keys(catalogs[registry.defaultLocale] ?? {}).length;
+        // A key that code asks for and the base lacks is reported only once the base itself is readable.
+        const usedKeys = catalogs[registry.defaultLocale] ? requested.get(set.path) ?? [] : [];
+        for (const problem of checkCatalogs({ defaultLocale: registry.defaultLocale, locales: registry.locales, catalogs, isUsed: key => used.has(key), usedKeys }))
+            problems.push({ catalog: relative(app, set.path), ...problem });
+    }
+    return { ok: problems.length === 0, locales: registry.locales, defaultLocale: registry.defaultLocale, catalogs: sets.map(set => relative(app, set.path)).sort(), keys, problems };
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};