@byline/core 2.5.2 → 2.6.0

package/dist/@types/admin-types.d.ts

@@ -216,8 +216,11 @@ export interface CollectionAdminConfig<T = any> {
     /**
      * Preview URL configuration for the admin's live-preview affordance
      * (`<PreviewLink>` icon on the document edit page header). When omitted,
-     * the preview link defaults to `/${collectionPath}/${doc.path}` — fine
-     * for collections whose public URL mirrors the collection path.
+     * the preview link falls back through `CollectionDefinition.buildDocumentPath`
+     * (the same schema-side hook the richtext embed walker reads, so the
+     * public path and the Preview button agree by construction) and finally
+     * to the conventional `/${collectionPath}/${doc.path}` — fine for
+     * collections whose public URL mirrors the collection path.
      *
      * `url(doc, ctx)` — pure function returning the preview URL. Receives
      * the loaded document and a small request-scoped context object

package/dist/@types/site-config.d.ts

@@ -36,11 +36,42 @@ export interface BaseConfig {
         interface: {
             defaultLocale: string;
             locales: string[];
+            /**
+             * Optional display names for the admin language switcher. Each
+             * entry pairs a permitted locale code with the label users see
+             * in the menu — `Français` rather than the lowercase `français`
+             * that CLDR's `Intl.DisplayNames` returns for romance languages.
+             *
+             * Hosts that omit this fall back to `Intl.DisplayNames` per
+             * code; hosts that provide it for some codes still fall back
+             * for the rest. Entries for codes outside `locales` are silently
+             * ignored.
+             */
+            localeDefinitions?: ReadonlyArray<{
+                code: string;
+                nativeName: string;
+            }>;
         };
         content: {
             defaultLocale: string;
             locales: string[];
         };
+        /**
+         * Admin interface translation registry — a `TranslationBundle`
+         * produced by `@byline/i18n`'s `mergeTranslations(...)`. Locale →
+         * namespace → key → ICU MessageFormat-encoded string.
+         *
+         * Optional at the type level so `BaseConfig` stays loose for tests
+         * and seed scripts; required at runtime via `validateTranslations`
+         * whenever `interface.locales` is non-empty. See `docs/I18N.md` for
+         * the design.
+         *
+         * The shape is declared inline (rather than imported from
+         * `@byline/i18n`) so `@byline/core` stays a leaf-ish package. The
+         * `TranslationBundle` type from `@byline/i18n` is structurally
+         * assignable to this slot.
+         */
+        translations?: TranslationBundleShape;
     };
     collections: CollectionDefinition[];
     /**
@@ -51,6 +82,19 @@ export interface BaseConfig {
      */
     routes?: Partial<RoutesConfig>;
 }
+/**
+ * Inline structural shape for the admin translation registry. Kept here
+ * (rather than imported from `@byline/i18n`) so `@byline/core` doesn't
+ * take a runtime dep on the i18n package. `@byline/i18n`'s
+ * `TranslationBundle` is structurally identical and assignable.
+ */
+export type TranslationBundleShape = Readonly<{
+    [locale: string]: Readonly<{
+        [namespace: string]: Readonly<{
+            [key: string]: string;
+        }>;
+    }>;
+}>;
 /**
  * Client-side configuration. Extends BaseConfig with admin UI presentation
  * config (React components, formatters, column definitions, etc.).

package/dist/core.js

@@ -12,6 +12,7 @@ import { createBylineLogger, defineLogger } from './lib/logger.js';
 import { Registry } from './lib/registry.js';
 import { ensureCollections } from './services/collection-bootstrap.js';
 import { discoverCounterGroups } from './services/discover-counter-groups.js';
+import { validateTranslations } from './services/i18n-validator.js';
 import { validateRichTextFieldFlags } from './services/richtext-populate.js';
 /**
  * Initialize Byline CMS core services via the typed registry.
@@ -45,6 +46,26 @@ export const initBylineCore = async (config, pinoLogger) => {
         populate: config.fields?.richText?.populate != null,
         embed: config.fields?.richText?.embed != null,
     });
+    // Validate the admin i18n translation registry against the configured
+    // interface locale set. Throws on structural errors (missing bundle for
+    // a declared locale, defaultLocale outside the permitted set, …); soft
+    // warnings (key-set drift between locales) are logged so contributors
+    // see translation gaps without it blocking boot. The bundle lives at
+    // `i18n.translations` (one axis, not nested under `interface`) — the
+    // validator takes the assembled shape so locale config and bundle
+    // travel together.
+    const i18nValidation = validateTranslations({
+        defaultLocale: config.i18n.interface.defaultLocale,
+        locales: config.i18n.interface.locales,
+        translations: config.i18n.translations,
+    });
+    for (const warning of i18nValidation.warnings) {
+        composed.logger.warn({
+            locale: warning.locale,
+            namespace: warning.namespace,
+            missingKeys: warning.missingKeys,
+        }, `[i18n] '${warning.locale}.${warning.namespace}' is missing ${warning.missingKeys.length} key(s) relative to the other locales`);
+    }
     // Backward compat: populate globalThis singletons
     defineServerConfig(config);
     defineLogger(composed.logger);

package/dist/services/i18n-validator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Boot-time validator for the admin translation registry. Mirrors the
+ * fail-fast posture of `validateRichTextFieldFlags` — surfacing wiring
+ * mistakes at `initBylineCore()` rather than at first request.
+ *
+ * Rules enforced:
+ *   1. `defaultLocale` must be in the permitted `locales` set.
+ *   2. When `locales` is non-empty, `translations` must be present.
+ *   3. Every locale in `locales` must have at least one namespace +
+ *      one key in `translations`. A locale with zero translations is
+ *      almost always a missing-bundle bug — at minimum the consumer
+ *      should opt out of the locale set entirely.
+ *
+ * Soft warning (returned, not thrown):
+ *   - Key set drift across locales. A namespace that carries `{ a, b }`
+ *     in `en` and `{ a }` in `fr` reports `fr` as missing `b`. Surfaces
+ *     translation gaps without blocking boot — partial translations are
+ *     normal during community-contributor flow.
+ */
+import type { TranslationBundleShape } from '../@types/site-config.js';
+export interface InterfaceI18nConfig {
+    defaultLocale: string;
+    locales: string[];
+    translations?: TranslationBundleShape;
+}
+export interface TranslationDriftWarning {
+    locale: string;
+    namespace: string;
+    /** Keys present in some other locale's same namespace but absent here. */
+    missingKeys: string[];
+}
+export interface ValidateTranslationsResult {
+    /** Soft warnings — caller decides whether to log or ignore. */
+    warnings: TranslationDriftWarning[];
+}
+/**
+ * Validate the admin translation slot against the configured interface
+ * locale set. Throws on any structural error; returns soft warnings for
+ * key-set drift between locales.
+ */
+export declare function validateTranslations(i18n: InterfaceI18nConfig): ValidateTranslationsResult;

package/dist/services/i18n-validator.js

@@ -0,0 +1,99 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Validate the admin translation slot against the configured interface
+ * locale set. Throws on any structural error; returns soft warnings for
+ * key-set drift between locales.
+ */
+export function validateTranslations(i18n) {
+    const { defaultLocale, locales, translations } = i18n;
+    const errors = [];
+    // (1) Default must be in the permitted set.
+    if (locales.length > 0 && !locales.includes(defaultLocale)) {
+        errors.push(`defaultLocale '${defaultLocale}' is not in i18n.interface.locales [${locales.join(', ')}]. ` +
+            `Add it to locales, or change defaultLocale to one of the existing entries.`);
+    }
+    // No locales declared → skip the remaining checks. Hosts that don't
+    // mount the admin UI (seeds, migrations, headless tooling) can omit
+    // translations entirely.
+    if (locales.length === 0) {
+        return { warnings: [] };
+    }
+    // (2) Non-empty locale set requires a translations bundle.
+    if (translations == null) {
+        errors.push(`i18n.interface.locales declares [${locales.join(', ')}] but no translations bundle is registered. ` +
+            `Pass one to defineClientConfig via i18n.translations — see @byline/i18n's adminTranslations() ` +
+            `and mergeTranslations() helpers.`);
+        if (errors.length > 0) {
+            throw new Error(formatErrors(errors));
+        }
+        return { warnings: [] };
+    }
+    // (3) Every declared locale must have at least one (namespace, key).
+    for (const locale of locales) {
+        const localeBundle = translations[locale];
+        if (localeBundle == null || namespaceKeyCount(localeBundle) === 0) {
+            errors.push(`i18n.interface.locales includes '${locale}' but no translations are registered for it. ` +
+                `Either drop '${locale}' from locales or wire a community bundle (e.g. @byline/i18n-${locale}).`);
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(formatErrors(errors));
+    }
+    // Soft warnings — key-set drift.
+    return { warnings: collectDriftWarnings(translations, locales) };
+}
+function namespaceKeyCount(localeBundle) {
+    let count = 0;
+    for (const namespace of Object.keys(localeBundle)) {
+        count += Object.keys(localeBundle[namespace] ?? {}).length;
+    }
+    return count;
+}
+function collectDriftWarnings(translations, locales) {
+    // For each namespace, take the union of keys across all locales,
+    // then report per-locale which keys are missing relative to that
+    // union.
+    const namespaceKeyUnion = new Map();
+    for (const locale of locales) {
+        const localeBundle = translations[locale];
+        if (localeBundle == null)
+            continue;
+        for (const namespace of Object.keys(localeBundle)) {
+            let union = namespaceKeyUnion.get(namespace);
+            if (union == null) {
+                union = new Set();
+                namespaceKeyUnion.set(namespace, union);
+            }
+            for (const key of Object.keys(localeBundle[namespace] ?? {})) {
+                union.add(key);
+            }
+        }
+    }
+    const warnings = [];
+    for (const locale of locales) {
+        const localeBundle = translations[locale];
+        if (localeBundle == null)
+            continue;
+        for (const [namespace, union] of namespaceKeyUnion) {
+            const present = new Set(Object.keys(localeBundle[namespace] ?? {}));
+            const missing = [];
+            for (const key of union) {
+                if (!present.has(key))
+                    missing.push(key);
+            }
+            if (missing.length > 0) {
+                warnings.push({ locale, namespace, missingKeys: missing });
+            }
+        }
+    }
+    return warnings;
+}
+function formatErrors(errors) {
+    return `initBylineCore: i18n translation configuration errors:\n  - ${errors.join('\n  - ')}`;
+}

package/dist/services/i18n-validator.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/services/i18n-validator.test.node.js

@@ -0,0 +1,133 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { validateTranslations } from './i18n-validator.js';
+describe('validateTranslations — happy paths', () => {
+    it('passes when every declared locale has at least one (namespace, key)', () => {
+        expect(() => validateTranslations({
+            defaultLocale: 'en',
+            locales: ['en', 'fr'],
+            translations: {
+                en: { 'byline-admin': { foo: 'Foo' } },
+                fr: { 'byline-admin': { foo: 'Foo (FR)' } },
+            },
+        })).not.toThrow();
+    });
+    it('skips validation entirely when locales is empty (seed scripts, headless tooling)', () => {
+        const result = validateTranslations({
+            defaultLocale: 'en',
+            locales: [],
+        });
+        expect(result.warnings).toEqual([]);
+    });
+    it('returns no warnings when key sets are aligned across locales', () => {
+        const result = validateTranslations({
+            defaultLocale: 'en',
+            locales: ['en', 'fr'],
+            translations: {
+                en: { 'byline-admin': { a: 'A', b: 'B' } },
+                fr: { 'byline-admin': { a: 'A-fr', b: 'B-fr' } },
+            },
+        });
+        expect(result.warnings).toEqual([]);
+    });
+});
+describe('validateTranslations — structural errors', () => {
+    it('throws when defaultLocale is not in the permitted locales set', () => {
+        expect(() => validateTranslations({
+            defaultLocale: 'de',
+            locales: ['en', 'fr'],
+            translations: {
+                en: { 'byline-admin': { a: 'A' } },
+                fr: { 'byline-admin': { a: 'A' } },
+            },
+        })).toThrow(/defaultLocale 'de' is not in i18n\.interface\.locales/);
+    });
+    it('throws when locales is non-empty but no translations bundle is registered', () => {
+        expect(() => validateTranslations({
+            defaultLocale: 'en',
+            locales: ['en'],
+        })).toThrow(/no translations bundle is registered/);
+    });
+    it('throws when a declared locale has no namespaces in the bundle', () => {
+        expect(() => validateTranslations({
+            defaultLocale: 'en',
+            locales: ['en', 'fr'],
+            translations: {
+                en: { 'byline-admin': { a: 'A' } },
+                // fr declared but no entry in the bundle
+            },
+        })).toThrow(/'fr' but no translations are registered for it/);
+    });
+    it('throws when a declared locale has a namespace but zero keys', () => {
+        expect(() => validateTranslations({
+            defaultLocale: 'en',
+            locales: ['en', 'fr'],
+            translations: {
+                en: { 'byline-admin': { a: 'A' } },
+                fr: { 'byline-admin': {} },
+            },
+        })).toThrow(/'fr' but no translations are registered/);
+    });
+    it('reports every locale failure in one combined error', () => {
+        expect(() => validateTranslations({
+            defaultLocale: 'en',
+            locales: ['en', 'fr', 'de'],
+            translations: {
+                en: { 'byline-admin': { a: 'A' } },
+            },
+        })).toThrow(/'fr' but no translations.*\n.*'de' but no translations/s);
+    });
+});
+describe('validateTranslations — soft drift warnings', () => {
+    it('flags keys missing in one locale but present in another (same namespace)', () => {
+        const result = validateTranslations({
+            defaultLocale: 'en',
+            locales: ['en', 'fr'],
+            translations: {
+                en: { 'byline-admin': { a: 'A', b: 'B' } },
+                fr: { 'byline-admin': { a: 'A-fr' } },
+            },
+        });
+        expect(result.warnings).toEqual([
+            { locale: 'fr', namespace: 'byline-admin', missingKeys: ['b'] },
+        ]);
+    });
+    it('flags drift across multiple namespaces independently', () => {
+        const result = validateTranslations({
+            defaultLocale: 'en',
+            locales: ['en', 'fr'],
+            translations: {
+                en: {
+                    'byline-admin': { a: 'A' },
+                    'plugin-x': { foo: 'Foo', bar: 'Bar' },
+                },
+                fr: {
+                    'byline-admin': { a: 'A-fr' },
+                    'plugin-x': { foo: 'Foo-fr' },
+                },
+            },
+        });
+        expect(result.warnings).toEqual([{ locale: 'fr', namespace: 'plugin-x', missingKeys: ['bar'] }]);
+    });
+    it('reports drift in both directions when neither locale is a superset', () => {
+        const result = validateTranslations({
+            defaultLocale: 'en',
+            locales: ['en', 'fr'],
+            translations: {
+                en: { 'byline-admin': { a: 'A', b: 'B' } },
+                fr: { 'byline-admin': { a: 'A-fr', c: 'C-fr' } },
+            },
+        });
+        // en is missing 'c' (present in fr); fr is missing 'b' (present in en).
+        expect(result.warnings).toEqual(expect.arrayContaining([
+            { locale: 'en', namespace: 'byline-admin', missingKeys: ['c'] },
+            { locale: 'fr', namespace: 'byline-admin', missingKeys: ['b'] },
+        ]));
+    });
+});

package/dist/services/index.d.ts

@@ -6,6 +6,7 @@ export { type DiscoverCounterGroupsInput, discoverCounterGroups, } from './disco
 export * from './document-lifecycle.js';
 export * from './document-read.js';
 export * from './field-upload.js';
+export { type InterfaceI18nConfig, type TranslationDriftWarning, type ValidateTranslationsResult, validateTranslations, } from './i18n-validator.js';
 export { type CycleRelationValue, createReadContext, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateOptions, type PopulateSpec, populateDocuments, type ReadContext, type UnresolvedRelationValue, } from './populate.js';
 export { buildRelationSummaryPopulateMap, type RelationTargetResolver, resolveRelationProjection, } from './relation-projection.js';
 export { type EmbedRichTextFieldsOptions, embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';

package/dist/services/index.js

@@ -7,6 +7,7 @@ export { discoverCounterGroups, } from './discover-counter-groups.js';
 export * from './document-lifecycle.js';
 export * from './document-read.js';
 export * from './field-upload.js';
+export { validateTranslations, } from './i18n-validator.js';
 export { createReadContext, populateDocuments, } from './populate.js';
 export { buildRelationSummaryPopulateMap, resolveRelationProjection, } from './relation-projection.js';
 export { embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';

package/dist/services/richtext-embed.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/services/richtext-embed.test.node.js

@@ -0,0 +1,149 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Tests for the per-leaf embed walker (`embedRichTextFields`). Focus on
+ * the surface owned by core — leaf gating via `embedRelationsOnSave` and
+ * branch C (per-leaf error swallow). The visitor-side branches (A / B /
+ * found) live in `@byline/richtext-lexical` and have their own suite.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { embedRichTextFields } from './richtext-embed.js';
+const noopLogger = {
+    log: vi.fn(),
+    fatal: vi.fn(),
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+    trace: vi.fn(),
+    silent: vi.fn(),
+};
+const fakeReadContext = {};
+const richTextValue = (label) => ({
+    root: { type: 'root', children: [], _label: label },
+});
+describe('embedRichTextFields', () => {
+    it('invokes the embed adapter once per richText leaf, including nested ones', async () => {
+        const fields = [
+            { name: 'body', type: 'richText', label: 'Body' },
+            {
+                name: 'meta',
+                type: 'group',
+                label: 'Meta',
+                fields: [{ name: 'summary', type: 'richText', label: 'Summary' }],
+            },
+            {
+                name: 'faq',
+                type: 'array',
+                label: 'FAQ',
+                fields: [{ name: 'answer', type: 'richText', label: 'Answer' }],
+            },
+        ];
+        const data = {
+            body: richTextValue('body'),
+            meta: { summary: richTextValue('summary') },
+            faq: [{ answer: richTextValue('answer-0') }],
+        };
+        const embed = vi.fn(async () => { });
+        await embedRichTextFields({
+            fields,
+            collectionPath: 'pages',
+            data,
+            embed,
+            readContext: fakeReadContext,
+            logger: noopLogger,
+        });
+        expect(embed).toHaveBeenCalledTimes(3);
+        const paths = embed.mock.calls.map((call) => call[0].fieldPath);
+        expect(paths.sort()).toEqual(['body', 'faq.0.answer', 'meta.summary']);
+    });
+    it('skips leaves whose embedRelationsOnSave is explicitly false', async () => {
+        const fields = [
+            { name: 'snapshot', type: 'richText', label: 'Snapshot' },
+            {
+                name: 'thin',
+                type: 'richText',
+                label: 'Thin',
+                embedRelationsOnSave: false,
+            },
+        ];
+        const data = {
+            snapshot: richTextValue('snapshot'),
+            thin: richTextValue('thin'),
+        };
+        const embed = vi.fn(async () => { });
+        await embedRichTextFields({
+            fields,
+            collectionPath: 'pages',
+            data,
+            embed,
+            readContext: fakeReadContext,
+            logger: noopLogger,
+        });
+        expect(embed).toHaveBeenCalledTimes(1);
+        expect(embed.mock.calls[0]?.[0]).toMatchObject({
+            fieldPath: 'snapshot',
+        });
+    });
+    it('swallows per-leaf errors, logs at error level, and keeps walking subsequent leaves (branch C)', async () => {
+        const fields = [
+            { name: 'first', type: 'richText', label: 'First' },
+            { name: 'second', type: 'richText', label: 'Second' },
+            { name: 'third', type: 'richText', label: 'Third' },
+        ];
+        const data = {
+            first: richTextValue('first'),
+            second: richTextValue('second'),
+            third: richTextValue('third'),
+        };
+        const failingErr = new Error('transport down');
+        const embed = vi.fn(async (ctx) => {
+            if (ctx.fieldPath === 'second')
+                throw failingErr;
+        });
+        const logger = {
+            ...noopLogger,
+            error: vi.fn(),
+        };
+        await expect(embedRichTextFields({
+            fields,
+            collectionPath: 'pages',
+            data,
+            embed,
+            readContext: fakeReadContext,
+            logger,
+        })).resolves.toBeUndefined();
+        // All three leaves were attempted — the failure in 'second' did not
+        // short-circuit the walk.
+        expect(embed).toHaveBeenCalledTimes(3);
+        expect(logger.error).toHaveBeenCalledTimes(1);
+        expect(logger.error).toHaveBeenCalledWith(expect.objectContaining({
+            err: failingErr,
+            collectionPath: 'pages',
+            fieldPath: 'second',
+        }), expect.stringMatching(/branch C/i));
+        // The persisted state for the failing leaf is untouched (the data
+        // object the caller passed in is mutated only by the adapter — and
+        // here the adapter threw before doing anything).
+        expect(data.second).toEqual(richTextValue('second'));
+    });
+    it('is a no-op when the document carries no richText fields', async () => {
+        const fields = [{ name: 'title', type: 'text', label: 'Title' }];
+        const data = { title: 'Hello' };
+        const embed = vi.fn(async () => { });
+        await embedRichTextFields({
+            fields,
+            collectionPath: 'pages',
+            data,
+            embed,
+            readContext: fakeReadContext,
+            logger: noopLogger,
+        });
+        expect(embed).not.toHaveBeenCalled();
+    });
+});

package/dist/validation/shared.d.ts

@@ -17,6 +17,26 @@
  * Pure Zod — no runtime side effects, client-safe.
  */
 import { z } from 'zod';
+/**
+ * Stable error codes emitted by `passwordSchema`. The schema yields
+ * these as the Zod issue message rather than free-form English so
+ * client callers can translate them at render time. Server-side
+ * consumers that don't translate (the defensive request-shape
+ * validation in admin command handlers) will see the code itself —
+ * acceptable because the form-level validation catches the same
+ * case first, so the server message is only surfaced when a
+ * malformed payload reaches the API outside the normal flow.
+ *
+ * Adding a new code: extend the union and add a matching key in the
+ * admin-side translator map (`@byline/admin/lib/translate-validation-error`).
+ * The same map shape is the recommended pattern for future schemas in
+ * this file — emit codes here, translate in `@byline/admin`.
+ */
+export declare const PASSWORD_ERROR_CODES: {
+    readonly TOO_SHORT: "password.tooShort";
+    readonly TOO_LONG: "password.tooLong";
+    readonly COMPLEXITY: "password.complexity";
+};
 /**
  * Standard password policy — 8 to 128 characters, must contain at least
  * one uppercase, one lowercase, one digit, and one character from the

package/dist/validation/shared.js

@@ -17,6 +17,26 @@
  * Pure Zod — no runtime side effects, client-safe.
  */
 import { z } from 'zod';
+/**
+ * Stable error codes emitted by `passwordSchema`. The schema yields
+ * these as the Zod issue message rather than free-form English so
+ * client callers can translate them at render time. Server-side
+ * consumers that don't translate (the defensive request-shape
+ * validation in admin command handlers) will see the code itself —
+ * acceptable because the form-level validation catches the same
+ * case first, so the server message is only surfaced when a
+ * malformed payload reaches the API outside the normal flow.
+ *
+ * Adding a new code: extend the union and add a matching key in the
+ * admin-side translator map (`@byline/admin/lib/translate-validation-error`).
+ * The same map shape is the recommended pattern for future schemas in
+ * this file — emit codes here, translate in `@byline/admin`.
+ */
+export const PASSWORD_ERROR_CODES = {
+    TOO_SHORT: 'password.tooShort',
+    TOO_LONG: 'password.tooLong',
+    COMPLEXITY: 'password.complexity',
+};
 /**
  * Standard password policy — 8 to 128 characters, must contain at least
  * one uppercase, one lowercase, one digit, and one character from the
@@ -28,9 +48,9 @@ import { z } from 'zod';
  */
 export const passwordSchema = z
     .string()
-    .min(8, 'Password must be at least 8 characters long.')
-    .max(128, 'Password must not exceed 128 characters.')
-    .regex(/^(?=.*?[A-Z])(?=.*?[a-z])(?=.*?[0-9])(?=.*?[#?!@$%^&*-]).{8,}$/, 'Password must contain at least one uppercase letter, one lowercase letter, one number, and one character from the following: #?!@$%^&*-');
+    .min(8, PASSWORD_ERROR_CODES.TOO_SHORT)
+    .max(128, PASSWORD_ERROR_CODES.TOO_LONG)
+    .regex(/^(?=.*?[A-Z])(?=.*?[a-z])(?=.*?[0-9])(?=.*?[#?!@$%^&*-]).{8,}$/, PASSWORD_ERROR_CODES.COMPLEXITY);
 /**
  * UUID with a descriptive error message. Equivalent to `z.uuid()` but
  * the message is caller-friendly for forms that surface field errors

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "2.5.2",
+  "version": "2.6.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "2.5.2"
+    "@byline/auth": "2.6.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",