@mccaskie-labs/workbench-config 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.18
+
+### Patch Changes
+
+- The `strings` component: `capabilities/strings.json` (rules and probes for `@mccaskie-labs/workbench-strings`) joins the manifests, and `strings` joins the component list.
+
 ## 0.1.17
 
 ### Patch Changes

package/capabilities/schema.json

@@ -31,7 +31,8 @@
         "access",
         "r2",
         "kv",
-        "github"
+        "github",
+        "strings"
       ]
     },
     "title": {

package/capabilities/strings.json

@@ -0,0 +1,131 @@
+{
+  "$schema": "./schema.json",
+  "format": 1,
+  "component": "strings",
+  "title": "Words on screens and in emails",
+  "summary": "workbench-strings holds the words an app's own screens and emails say: one file per language in the app's repository, looked up on the server with named placeholders and plurals, one fallback chain to the base language, language detection with country before the browser's language, back-translation notes stripped at build, and a review gate so no unreviewed translation is inferred for anyone. The standard's tests ship as a kit.",
+  "status": "built",
+  "surfaces": {
+    "package": [
+      "defineStrings",
+      "resolveLocale",
+      "stripGlosses",
+      "WORKBENCH_LANGUAGES",
+      "WorkbenchStringsError"
+    ]
+  },
+  "rules": [
+    {
+      "id": "strings.server-only",
+      "kind": "must_not",
+      "text": "Import workbench-strings into browser code: the catalogue holds every language. Look words up on the server and pass the finished words to the page; the package's browser export throws.",
+      "enforced_by": "types",
+      "probe": "strings.lookup"
+    },
+    {
+      "id": "strings.no-literals",
+      "kind": "must_not",
+      "text": "Write user-visible words as literals in code, or keep a key nothing renders. Every word is a key in strings/strings.<base>.json, and the test kit's dead-key sweep fails on an unused one.",
+      "enforced_by": "review",
+      "probe": "strings.kit"
+    },
+    {
+      "id": "strings.one-chain",
+      "kind": "must",
+      "text": "Use strings.t and strings.email for every lookup, so screens and emails share one fallback chain: the locale, its parent, then the base. A word found further down the chain is logged.",
+      "enforced_by": "types",
+      "probe": "strings.lookup"
+    },
+    {
+      "id": "strings.country-before-header",
+      "kind": "must",
+      "text": "Detect the language in the order URL prefix, cookie, account, country, Accept-Language, default, with strings.detect. Country comes before the browser's language because phones report English whatever their owner reads.",
+      "enforced_by": "types",
+      "probe": "strings.detect"
+    },
+    {
+      "id": "strings.review-gate",
+      "kind": "must_not",
+      "text": "Serve a translated language to someone who did not choose it until its catalogue has _review.signed_off naming the reviewer and the date; country, header and default resolve to the base until then.",
+      "enforced_by": "types",
+      "probe": "strings.gate"
+    },
+    {
+      "id": "strings.named-reviewer",
+      "kind": "must_not",
+      "text": "Put a translated language live in production without _review.reviewer naming a native-speaker reviewer and their cadence; defineStrings refuses to start.",
+      "enforced_by": "types",
+      "probe": "strings.no-reviewer"
+    },
+    {
+      "id": "strings.email-missing-throws",
+      "kind": "must",
+      "text": "Treat an email word missing in the recipient's language and in the base as an error: strings.email throws missing_string rather than sending a key.",
+      "enforced_by": "types",
+      "probe": "strings.email-missing"
+    },
+    {
+      "id": "strings.glosses-stripped",
+      "kind": "must",
+      "text": "Keep a _gloss back-translation beside every translated string in the authored file, and ship only the generated file from npx workbench-strings build, which strips them; defineStrings refuses a catalogue with glosses.",
+      "enforced_by": "types",
+      "probe": "strings.kit"
+    }
+  ],
+  "examples": [
+    {
+      "id": "strings.example.lookup",
+      "title": "Detect the language and look words up",
+      "lang": "ts",
+      "probe": "strings.lookup",
+      "code": "// SERVER ONLY: the catalogue holds every language.\nimport { defineStrings } from '@mccaskie-labs/workbench-strings'\nimport enAU from '../strings/strings.en-AU.json'\nimport enPH from '../strings/runtime/strings.en-PH.json'\n\nconst strings = defineStrings({ env: workbenchEnv(env), base: { locale: 'en-AU', strings: enAU }, translations: { 'en-PH': enPH }, locales: ['en-PH', 'en-AU'], defaultLocale: 'en-PH' })\nconst { locale } = strings.detect(request, { account: user?.locale })\nconst title = strings.t(locale, 'ui.cart.count', { count: 3 })"
+    }
+  ],
+  "probes": [
+    {
+      "id": "strings.lookup",
+      "half": "runtime",
+      "expect": "pass",
+      "smoke": true,
+      "cost_hint_usd": 0,
+      "note": "Placeholders and a plural fill in each live locale, and a word missing in a translation comes from the base and is logged"
+    },
+    {
+      "id": "strings.detect",
+      "half": "runtime",
+      "expect": "pass",
+      "cost_hint_usd": 0,
+      "note": "Each step of the order wins over the next; a PH visitor whose browser says en-US gets the PH locale; XX falls through to the header"
+    },
+    {
+      "id": "strings.gate",
+      "half": "runtime",
+      "expect": "pass",
+      "cost_hint_usd": 0,
+      "note": "An unsigned translation is not inferred (gated: true, base served) but is served from the cookie or prefix"
+    },
+    {
+      "id": "strings.no-reviewer",
+      "half": "runtime",
+      "expect": "refused_as_expected",
+      "refusal": "no_reviewer",
+      "cost_hint_usd": 0,
+      "note": "defineStrings with env production and a translation with no _review.reviewer"
+    },
+    {
+      "id": "strings.email-missing",
+      "half": "runtime",
+      "expect": "refused_as_expected",
+      "refusal": "missing_string",
+      "cost_hint_usd": 0,
+      "note": "strings.email for a part no catalogue has"
+    },
+    {
+      "id": "strings.kit",
+      "half": "runtime",
+      "expect": "pass",
+      "cost_hint_usd": 0,
+      "note": "The app's own checkStrings run passes in its tests, and npx workbench-strings check passes in CI"
+    }
+  ]
+}

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "849b265d6d63";
+export declare const MANIFEST_VERSION: "d0231144218c";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -1518,6 +1518,113 @@ export declare const capabilities: {
             readonly note: "Prints the app's own HTML holding an image from a host not in allowOrigins; the PDF is made and the browser reports that image's request as blocked";
         }];
     };
+    readonly strings: {
+        readonly $schema: "./schema.json";
+        readonly format: 1;
+        readonly component: "strings";
+        readonly title: "Words on screens and in emails";
+        readonly summary: "workbench-strings holds the words an app's own screens and emails say: one file per language in the app's repository, looked up on the server with named placeholders and plurals, one fallback chain to the base language, language detection with country before the browser's language, back-translation notes stripped at build, and a review gate so no unreviewed translation is inferred for anyone. The standard's tests ship as a kit.";
+        readonly status: "built";
+        readonly surfaces: {
+            readonly package: readonly ["defineStrings", "resolveLocale", "stripGlosses", "WORKBENCH_LANGUAGES", "WorkbenchStringsError"];
+        };
+        readonly rules: readonly [{
+            readonly id: "strings.server-only";
+            readonly kind: "must_not";
+            readonly text: "Import workbench-strings into browser code: the catalogue holds every language. Look words up on the server and pass the finished words to the page; the package's browser export throws.";
+            readonly enforced_by: "types";
+            readonly probe: "strings.lookup";
+        }, {
+            readonly id: "strings.no-literals";
+            readonly kind: "must_not";
+            readonly text: "Write user-visible words as literals in code, or keep a key nothing renders. Every word is a key in strings/strings.<base>.json, and the test kit's dead-key sweep fails on an unused one.";
+            readonly enforced_by: "review";
+            readonly probe: "strings.kit";
+        }, {
+            readonly id: "strings.one-chain";
+            readonly kind: "must";
+            readonly text: "Use strings.t and strings.email for every lookup, so screens and emails share one fallback chain: the locale, its parent, then the base. A word found further down the chain is logged.";
+            readonly enforced_by: "types";
+            readonly probe: "strings.lookup";
+        }, {
+            readonly id: "strings.country-before-header";
+            readonly kind: "must";
+            readonly text: "Detect the language in the order URL prefix, cookie, account, country, Accept-Language, default, with strings.detect. Country comes before the browser's language because phones report English whatever their owner reads.";
+            readonly enforced_by: "types";
+            readonly probe: "strings.detect";
+        }, {
+            readonly id: "strings.review-gate";
+            readonly kind: "must_not";
+            readonly text: "Serve a translated language to someone who did not choose it until its catalogue has _review.signed_off naming the reviewer and the date; country, header and default resolve to the base until then.";
+            readonly enforced_by: "types";
+            readonly probe: "strings.gate";
+        }, {
+            readonly id: "strings.named-reviewer";
+            readonly kind: "must_not";
+            readonly text: "Put a translated language live in production without _review.reviewer naming a native-speaker reviewer and their cadence; defineStrings refuses to start.";
+            readonly enforced_by: "types";
+            readonly probe: "strings.no-reviewer";
+        }, {
+            readonly id: "strings.email-missing-throws";
+            readonly kind: "must";
+            readonly text: "Treat an email word missing in the recipient's language and in the base as an error: strings.email throws missing_string rather than sending a key.";
+            readonly enforced_by: "types";
+            readonly probe: "strings.email-missing";
+        }, {
+            readonly id: "strings.glosses-stripped";
+            readonly kind: "must";
+            readonly text: "Keep a _gloss back-translation beside every translated string in the authored file, and ship only the generated file from npx workbench-strings build, which strips them; defineStrings refuses a catalogue with glosses.";
+            readonly enforced_by: "types";
+            readonly probe: "strings.kit";
+        }];
+        readonly examples: readonly [{
+            readonly id: "strings.example.lookup";
+            readonly title: "Detect the language and look words up";
+            readonly lang: "ts";
+            readonly code: "// SERVER ONLY: the catalogue holds every language.\nimport { defineStrings } from '@mccaskie-labs/workbench-strings'\nimport enAU from '../strings/strings.en-AU.json'\nimport enPH from '../strings/runtime/strings.en-PH.json'\n\nconst strings = defineStrings({ env: workbenchEnv(env), base: { locale: 'en-AU', strings: enAU }, translations: { 'en-PH': enPH }, locales: ['en-PH', 'en-AU'], defaultLocale: 'en-PH' })\nconst { locale } = strings.detect(request, { account: user?.locale })\nconst title = strings.t(locale, 'ui.cart.count', { count: 3 })";
+            readonly probe: "strings.lookup";
+        }];
+        readonly probes: readonly [{
+            readonly id: "strings.lookup";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0;
+            readonly note: "Placeholders and a plural fill in each live locale, and a word missing in a translation comes from the base and is logged";
+        }, {
+            readonly id: "strings.detect";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+            readonly note: "Each step of the order wins over the next; a PH visitor whose browser says en-US gets the PH locale; XX falls through to the header";
+        }, {
+            readonly id: "strings.gate";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+            readonly note: "An unsigned translation is not inferred (gated: true, base served) but is served from the cookie or prefix";
+        }, {
+            readonly id: "strings.no-reviewer";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "no_reviewer";
+            readonly cost_hint_usd: 0;
+            readonly note: "defineStrings with env production and a translation with no _review.reviewer";
+        }, {
+            readonly id: "strings.email-missing";
+            readonly half: "runtime";
+            readonly expect: "refused_as_expected";
+            readonly refusal: "missing_string";
+            readonly cost_hint_usd: 0;
+            readonly note: "strings.email for a part no catalogue has";
+        }, {
+            readonly id: "strings.kit";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly cost_hint_usd: 0;
+            readonly note: "The app's own checkStrings run passes in its tests, and npx workbench-strings check passes in CI";
+        }];
+    };
 };
 export type Alias = (typeof capabilities)["ai"]["allowed"]["aliases"][number]["alias"];
 export type GatewayScope = (typeof capabilities)["gateway"]["allowed"]["scopes"][number];

package/dist/capabilities.gen.js

@@ -1,6 +1,6 @@
 // Generated by `npm run capabilities:build` from capabilities/*.json. Do not edit.
 // check:capabilities fails in Checks when this file is stale.
-export const MANIFEST_VERSION = "849b265d6d63";
+export const MANIFEST_VERSION = "d0231144218c";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -2052,5 +2052,136 @@ export const capabilities = {
                 "note": "Prints the app's own HTML holding an image from a host not in allowOrigins; the PDF is made and the browser reports that image's request as blocked"
             }
         ]
+    },
+    "strings": {
+        "$schema": "./schema.json",
+        "format": 1,
+        "component": "strings",
+        "title": "Words on screens and in emails",
+        "summary": "workbench-strings holds the words an app's own screens and emails say: one file per language in the app's repository, looked up on the server with named placeholders and plurals, one fallback chain to the base language, language detection with country before the browser's language, back-translation notes stripped at build, and a review gate so no unreviewed translation is inferred for anyone. The standard's tests ship as a kit.",
+        "status": "built",
+        "surfaces": {
+            "package": [
+                "defineStrings",
+                "resolveLocale",
+                "stripGlosses",
+                "WORKBENCH_LANGUAGES",
+                "WorkbenchStringsError"
+            ]
+        },
+        "rules": [
+            {
+                "id": "strings.server-only",
+                "kind": "must_not",
+                "text": "Import workbench-strings into browser code: the catalogue holds every language. Look words up on the server and pass the finished words to the page; the package's browser export throws.",
+                "enforced_by": "types",
+                "probe": "strings.lookup"
+            },
+            {
+                "id": "strings.no-literals",
+                "kind": "must_not",
+                "text": "Write user-visible words as literals in code, or keep a key nothing renders. Every word is a key in strings/strings.<base>.json, and the test kit's dead-key sweep fails on an unused one.",
+                "enforced_by": "review",
+                "probe": "strings.kit"
+            },
+            {
+                "id": "strings.one-chain",
+                "kind": "must",
+                "text": "Use strings.t and strings.email for every lookup, so screens and emails share one fallback chain: the locale, its parent, then the base. A word found further down the chain is logged.",
+                "enforced_by": "types",
+                "probe": "strings.lookup"
+            },
+            {
+                "id": "strings.country-before-header",
+                "kind": "must",
+                "text": "Detect the language in the order URL prefix, cookie, account, country, Accept-Language, default, with strings.detect. Country comes before the browser's language because phones report English whatever their owner reads.",
+                "enforced_by": "types",
+                "probe": "strings.detect"
+            },
+            {
+                "id": "strings.review-gate",
+                "kind": "must_not",
+                "text": "Serve a translated language to someone who did not choose it until its catalogue has _review.signed_off naming the reviewer and the date; country, header and default resolve to the base until then.",
+                "enforced_by": "types",
+                "probe": "strings.gate"
+            },
+            {
+                "id": "strings.named-reviewer",
+                "kind": "must_not",
+                "text": "Put a translated language live in production without _review.reviewer naming a native-speaker reviewer and their cadence; defineStrings refuses to start.",
+                "enforced_by": "types",
+                "probe": "strings.no-reviewer"
+            },
+            {
+                "id": "strings.email-missing-throws",
+                "kind": "must",
+                "text": "Treat an email word missing in the recipient's language and in the base as an error: strings.email throws missing_string rather than sending a key.",
+                "enforced_by": "types",
+                "probe": "strings.email-missing"
+            },
+            {
+                "id": "strings.glosses-stripped",
+                "kind": "must",
+                "text": "Keep a _gloss back-translation beside every translated string in the authored file, and ship only the generated file from npx workbench-strings build, which strips them; defineStrings refuses a catalogue with glosses.",
+                "enforced_by": "types",
+                "probe": "strings.kit"
+            }
+        ],
+        "examples": [
+            {
+                "id": "strings.example.lookup",
+                "title": "Detect the language and look words up",
+                "lang": "ts",
+                "code": "// SERVER ONLY: the catalogue holds every language.\nimport { defineStrings } from '@mccaskie-labs/workbench-strings'\nimport enAU from '../strings/strings.en-AU.json'\nimport enPH from '../strings/runtime/strings.en-PH.json'\n\nconst strings = defineStrings({ env: workbenchEnv(env), base: { locale: 'en-AU', strings: enAU }, translations: { 'en-PH': enPH }, locales: ['en-PH', 'en-AU'], defaultLocale: 'en-PH' })\nconst { locale } = strings.detect(request, { account: user?.locale })\nconst title = strings.t(locale, 'ui.cart.count', { count: 3 })",
+                "probe": "strings.lookup"
+            }
+        ],
+        "probes": [
+            {
+                "id": "strings.lookup",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0,
+                "note": "Placeholders and a plural fill in each live locale, and a word missing in a translation comes from the base and is logged"
+            },
+            {
+                "id": "strings.detect",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0,
+                "note": "Each step of the order wins over the next; a PH visitor whose browser says en-US gets the PH locale; XX falls through to the header"
+            },
+            {
+                "id": "strings.gate",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0,
+                "note": "An unsigned translation is not inferred (gated: true, base served) but is served from the cookie or prefix"
+            },
+            {
+                "id": "strings.no-reviewer",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "no_reviewer",
+                "cost_hint_usd": 0,
+                "note": "defineStrings with env production and a translation with no _review.reviewer"
+            },
+            {
+                "id": "strings.email-missing",
+                "half": "runtime",
+                "expect": "refused_as_expected",
+                "refusal": "missing_string",
+                "cost_hint_usd": 0,
+                "note": "strings.email for a part no catalogue has"
+            },
+            {
+                "id": "strings.kit",
+                "half": "runtime",
+                "expect": "pass",
+                "cost_hint_usd": 0,
+                "note": "The app's own checkStrings run passes in its tests, and npx workbench-strings check passes in CI"
+            }
+        ]
     }
 };

package/dist/capability-schema.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const COMPONENTS: readonly ["gateway", "ai", "images", "image-search", "config", "email", "email-inbound", "email-sending", "database", "workers", "domains", "dns", "analytics", "country", "pdf", "access", "r2", "kv", "github"];
+export declare const COMPONENTS: readonly ["gateway", "ai", "images", "image-search", "config", "email", "email-inbound", "email-sending", "database", "workers", "domains", "dns", "analytics", "country", "pdf", "access", "r2", "kv", "github", "strings"];
 export type Component = (typeof COMPONENTS)[number];
 export declare const allowedSchemas: {
     gateway: z.ZodObject<{
@@ -110,6 +110,7 @@ export declare const capabilitySchema: z.ZodObject<{
         kv: "kv";
         pdf: "pdf";
         r2: "r2";
+        strings: "strings";
         workers: "workers";
     }>;
     title: z.ZodString;

package/dist/capability-schema.js

@@ -22,6 +22,7 @@ export const COMPONENTS = [
     "r2",
     "kv",
     "github",
+    "strings",
 ];
 const id = z.string().regex(/^[a-z0-9][a-z0-9.-]*$/, "lower case, digits, dots and hyphens");
 const code = z.string().regex(/^[a-z][a-z0-9_]*$/, "a snake_case error code");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
   "license": "UNLICENSED",
   "type": "module",