@byline/core 4.4.0 → 4.4.1

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

@@ -58,7 +58,8 @@ export interface FieldHookContext {
      */
     data: Record<string, any>;
     /**
-     * Dot-path of the field inside the document, e.g. `"content.0.richText"`.
+     * Instance path of the field inside the document, e.g.
+     * `"content[id=block-id].richText"`.
      */
     path: string;
     /**
@@ -85,7 +86,7 @@ export interface FieldHookContext {
      * items (a checkbox that unchecks its siblings) or clearing a dependent
      * field when its driver changes. Paths use the same dot + bracket
      * notation as `FieldHookContext.path`, e.g.
-     * `files[1].filesGroup.generateThumbnail`.
+     * `files[id=file-id].filesGroup.generateThumbnail`.
      */
     setFieldValue: (path: string, value: any) => void;
 }

package/dist/config/attach-hooks.js

@@ -10,7 +10,7 @@ export function prepareHookAttachment(config) {
     const collections = new Map();
     const uploadFields = new Map();
     for (const collection of config.collections) {
-        assertDotFreeSegment(collection.path, `collection path "${collection.path}"`);
+        assertPathSafeSegment(collection.path, `collection path "${collection.path}"`);
         collections.set(collection.path, collection);
         indexUploadFields(collection, uploadFields);
     }
@@ -99,7 +99,7 @@ function assertOwnershipIntact(label, current, owned) {
 function indexUploadFields(collection, uploadFields) {
     const leafPaths = new Map();
     walkFieldDeclarations(collection.fields, (field, segments) => {
-        assertDotFreeSegment(field.name, `field name "${field.name}" in collection "${collection.path}"`);
+        assertPathSafeSegment(field.name, `field name "${field.name}" in collection "${collection.path}"`);
         if ((field.type !== 'file' && field.type !== 'image') || field.upload === undefined)
             return;
         const canonical = `${collection.path}.${formatDeclarationPath(segments)}`;
@@ -114,12 +114,27 @@ function indexUploadFields(collection, uploadFields) {
         // block never reaches the field visitor, so inferring block types from
         // field segments alone would silently stop validating them.
         onBlock: (block) => {
-            assertDotFreeSegment(block.blockType, `block type "${block.blockType}" in collection "${collection.path}"`);
+            assertPathSafeSegment(block.blockType, `block type "${block.blockType}" in collection "${collection.path}"`);
         },
     });
 }
-function assertDotFreeSegment(segment, label) {
-    if (segment.length === 0 || segment.includes('.')) {
-        throw new Error(`${label} must be a non-empty, dot-free hook registry path segment.`);
+/**
+ * A name that appears as a path segment must not contain the grammar's own
+ * punctuation.
+ *
+ * `.` separates segments in every notation. `[` and `]` delimit item selectors
+ * in instance paths, which field names already reach — a field named `a[0]`
+ * would not survive the round trip through `parseInstancePath`. Both are
+ * rejected where the name is declared rather than left to corrupt a path
+ * later.
+ */
+function assertPathSafeSegment(segment, label) {
+    if (segment.length === 0) {
+        throw new Error(`${label} must be a non-empty path segment.`);
+    }
+    for (const character of ['.', '[', ']']) {
+        if (segment.includes(character)) {
+            throw new Error(`${label} must not contain "${character}" — it is field path grammar punctuation.`);
+        }
     }
 }

package/dist/config/attach-hooks.test.node.js

@@ -149,11 +149,11 @@ describe('server hook attachment', () => {
         await expect(initBylineCore(invalid, {})).rejects.toThrow(/translations bundle/i);
         expect(definition.hooks).toBe(stable);
     });
-    it('rejects dotted registry segments and duplicate upload leaf names at boot', () => {
-        expect(() => prepareHookAttachment({ collections: [collection('docs.archive')] })).toThrow(/dot-free/);
+    it('rejects path-punctuation in registry segments and duplicate upload leaf names at boot', () => {
+        expect(() => prepareHookAttachment({ collections: [collection('docs.archive')] })).toThrow(/grammar punctuation/);
         const dottedField = collection();
         dottedField.fields = [{ name: 'meta.asset', type: 'file', upload: {} }];
-        expect(() => prepareHookAttachment({ collections: [dottedField] })).toThrow(/dot-free/);
+        expect(() => prepareHookAttachment({ collections: [dottedField] })).toThrow(/grammar punctuation/);
         const dottedBlock = collection();
         dottedBlock.fields = [
             {
@@ -162,7 +162,21 @@ describe('server hook attachment', () => {
                 blocks: [{ blockType: 'hero.large', fields: [] }],
             },
         ];
-        expect(() => prepareHookAttachment({ collections: [dottedBlock] })).toThrow(/dot-free/);
+        expect(() => prepareHookAttachment({ collections: [dottedBlock] })).toThrow(/grammar punctuation/);
+        // Brackets delimit item selectors in instance paths, which field names
+        // reach — so they are rejected for the same reason dots are.
+        const bracketField = collection();
+        bracketField.fields = [{ name: 'asset[0]', type: 'file', upload: {} }];
+        expect(() => prepareHookAttachment({ collections: [bracketField] })).toThrow(/grammar punctuation/);
+        const bracketBlock = collection();
+        bracketBlock.fields = [
+            {
+                name: 'content',
+                type: 'blocks',
+                blocks: [{ blockType: 'hero[large]', fields: [] }],
+            },
+        ];
+        expect(() => prepareHookAttachment({ collections: [bracketBlock] })).toThrow(/grammar punctuation/);
         const duplicate = collection();
         duplicate.fields = [
             { name: 'primary', type: 'group', fields: [{ name: 'asset', type: 'file', upload: {} }] },

package/dist/patches/patch.test.node.js

@@ -156,6 +156,32 @@ describe('applyPatches', () => {
         const moved = afterMove;
         expect(moved.reviews.map((r) => r._id)).toEqual(['c', 'a', 'b']);
     });
+    it('applies field patches against the array order at that point in the patch stream', () => {
+        const original = {
+            links: [
+                { _id: 'a', link: 'A' },
+                { _id: 'b', link: 'B' },
+            ],
+        };
+        const positional = applyPatches(DocsDefinition, original, [
+            { kind: 'array.move', path: 'links', itemId: 'b', toIndex: 0 },
+            { kind: 'field.set', path: 'links[0].link', value: 'moved B' },
+        ]);
+        expect(positional.errors).toHaveLength(0);
+        expect(positional.doc.links).toEqual([
+            { _id: 'b', link: 'moved B' },
+            { _id: 'a', link: 'A' },
+        ]);
+        const stable = applyPatches(DocsDefinition, original, [
+            { kind: 'array.move', path: 'links', itemId: 'b', toIndex: 0 },
+            { kind: 'field.set', path: 'links[id=b].link', value: 'same B' },
+        ]);
+        expect(stable.errors).toHaveLength(0);
+        expect(stable.doc.links).toEqual([
+            { _id: 'b', link: 'same B' },
+            { _id: 'a', link: 'A' },
+        ]);
+    });
     it('array.remove removes an item by stable _id', () => {
         const original = {
             reviews: [

package/dist/paths/parse-path.js

@@ -28,8 +28,13 @@ const ID_TOKEN = /^\[id=(.+)\]$/;
 export function parseDeclarationPath(path) {
     if (path.trim() === '')
         return { ok: false, reason: 'empty' };
-    if (path.includes('[') || path.includes(']'))
+    if (path.includes('['))
         return { ok: false, reason: 'index' };
+    // A closing bracket with no opener is not an item selector the caller wrote
+    // in the wrong dialect — it is a typo, and saying so beats advice about
+    // declaration paths not taking indices.
+    if (path.includes(']'))
+        return { ok: false, reason: 'malformed' };
     const segments = [];
     for (const part of path.split('.')) {
         if (part === '')

package/dist/paths/path-types.d.ts

@@ -80,7 +80,8 @@ export interface ResolveOptions {
      * - `'forbidden'` — stop and report `status: 'blocks'`. Used by the admin
      *   `fields{}` maps, where per-field overrides inside a block belong to the
      *   blockType-keyed `blockAdmin` registry so that one registration applies
-     *   wherever the block renders.
+     *   wherever the block renders. This bars *traversal* only: a path ending on
+     *   the blocks field resolves `ok`, since that field is itself overridable.
      */
     readonly blocks?: 'qualified' | 'forbidden';
 }

package/dist/paths/paths.test.node.js

@@ -68,6 +68,11 @@ describe('parseDeclarationPath', () => {
             reason: 'index',
         });
     });
+    it('distinguishes a stray bracket from a wrong-dialect index', () => {
+        // `index` steers the author from instance notation to declaration
+        // notation; that advice is misleading for what is only a typo.
+        expect(parseDeclarationPath('files].caption')).toEqual({ ok: false, reason: 'malformed' });
+    });
     it('rejects empty paths and empty segments', () => {
         expect(parseDeclarationPath('')).toEqual({ ok: false, reason: 'empty' });
         expect(parseDeclarationPath('   ')).toEqual({ ok: false, reason: 'empty' });
@@ -104,6 +109,13 @@ describe('parseInstancePath', () => {
             expect(parseInstancePath(bad).ok).toBe(false);
         }
     });
+    it('rejects an id containing a closing bracket rather than truncating it', () => {
+        // Ids are UUIDv7 today, so this is unreachable in practice. Pinned because
+        // the id token is scanned to the first `]`: the guarantee worth holding is
+        // that an id which somehow contains one is rejected outright, never
+        // silently shortened into a different — and possibly valid — id.
+        expect(parseInstancePath('gallery[id=a]b].alt').ok).toBe(false);
+    });
 });
 describe('formatting', () => {
     it('round-trips a declaration path', () => {
@@ -255,6 +267,15 @@ describe('resolveDeclarationPath', () => {
     it('reports `blocks` even for an unqualified path into a block', () => {
         expect(resolveDeclarationPath(fields, 'content.alt', { blocks: 'forbidden' }).status).toBe('blocks');
     });
+    it('resolves the blocks field itself under `forbidden`', () => {
+        // `forbidden` bars *traversal* into a block, not addressing the blocks
+        // field. A blocks field carries a label like any other, so an admin
+        // `fields{}` key naming it is a legitimate override target — what the
+        // narrowing rules out is reaching past it to the fields inside.
+        const result = resolveDeclarationPath(fields, 'content', { blocks: 'forbidden' });
+        expect(result.status).toBe('ok');
+        expect(result.status === 'ok' && result.field.type).toBe('blocks');
+    });
     it('rejects an unknown block type', () => {
         expect(resolveDeclarationPath(fields, 'content.audioBlock.alt').status).toBe('unresolved');
     });

package/dist/paths/resolve-path.js

@@ -80,6 +80,10 @@ export function resolveDeclarationPath(fields, path, options = {}) {
         if (field == null)
             return { status: 'unresolved', at: i };
         resolved.push({ kind: 'field', name: field.name });
+        // Deliberately ahead of the `blocks: 'forbidden'` check below: that policy
+        // bars *traversal* into a block, so a path ending on the blocks field
+        // resolves normally. The field carries a label like any other and is a
+        // legitimate admin override target.
         const isLast = i === input.length - 1;
         if (isLast)
             return { status: 'ok', field, segments: resolved };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.4.0",
+  "version": "4.4.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -81,7 +81,7 @@
     "pino": "^10.3.1",
     "sharp": "^0.35.3",
     "zod": "^4.4.3",
-    "@byline/auth": "4.4.0"
+    "@byline/auth": "4.4.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.4",