@njeybe/nativ 2.4.0 → 2.4.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 2.4.1
+
+### Fixed & Improved
+
+- **Resilient Spec Slices Resolution.** Enhanced `resolveSpecSlices` in `src/core/spec-slices.ts` to gracefully resolve non-standard and shorthand contract/spec references across `.ai/` contracts:
+  - **Shorthand Markdown Section Anchors:** Supports numeric and prefix section references (e.g. `ui_specs.md#6`, `ui_specs.md#15`, `ui_specs.md#15.1`) by matching section prefixes when exact heading slug matches are not found.
+  - **JSON Root Keys without Leading Slash:** Automatically resolves JSON references missing a leading slash (e.g. `api_contracts.json#confirmationPageContracts`, `api_contracts.json#legalDocumentsContract`) by falling back to root property pointers and dot-path navigation.
+  - **Route Names Lookup:** Resolves named route references (e.g. `api_contracts.json#coaches.payment-qr`, `company.coaches.payment-qr`) across `routingPolicy.playerRoutes`, `venueScopedRoutes`, and other route collections.
+  - **Mail Events by Trigger:** Resolves mail event references by trigger name (e.g. `api_contracts.json#Coach Lesson Booked`, `Coach Payment Proof Uploaded`).
+  - **Database Schema Tables:** Resolves table references directly by name in `relevantTables` and `tables` collections (e.g. `db_schema.json#legal_documents`, `db_schema.json#coach_bookings`, `db_schema.json#sports`).
+
 ## 2.4.0
 
 ### Added

package/dist/core/spec-slices.js

@@ -16,9 +16,7 @@ function cap(text, max) {
         return { text, truncated: false };
     return { text: text.slice(0, Math.max(0, max)) + TRUNCATION_MARKER, truncated: true };
 }
-function markdownSection(content, anchor) {
-    const wanted = decodeURIComponent(anchor).toLowerCase();
-    const lines = content.split(/\r?\n/);
+function findSection(lines, predicate) {
     const seen = new Map();
     let inFence = false;
     let start = -1;
@@ -40,17 +38,41 @@ function markdownSection(content, anchor) {
                 return lines.slice(start, i).join('\n').trimEnd();
             continue;
         }
-        const base = slugifyHeading(m[2]);
+        const headingText = m[2];
+        const base = slugifyHeading(headingText);
         const count = seen.get(base) ?? 0;
         seen.set(base, count + 1);
         const slug = count === 0 ? base : `${base}-${count}`;
-        if (slug === wanted) {
+        if (predicate(slug, headingText)) {
             start = i;
             level = hLevel;
         }
     }
     return start >= 0 ? lines.slice(start).join('\n').trimEnd() : null;
 }
+function markdownSection(content, anchor) {
+    const wanted = decodeURIComponent(anchor).trim().toLowerCase();
+    const lines = content.split(/\r?\n/);
+    // 1. Exact slug match (standard markdown anchor)
+    const exact = findSection(lines, (slug) => slug === wanted);
+    if (exact !== null)
+        return exact;
+    // 2. Prefix / section number match (e.g. "6" or "15.1" matching "## 6. Coach..." or "### 15.1 Shared Pieces")
+    const prefixMatch = findSection(lines, (_slug, headingText) => {
+        const raw = headingText.trim().toLowerCase();
+        if (raw === wanted)
+            return true;
+        if (raw.startsWith(`${wanted}.`) || raw.startsWith(`${wanted} `) || raw.startsWith(`${wanted}:`))
+            return true;
+        const base = slugifyHeading(headingText);
+        if (base.startsWith(`${wanted}-`) || base === wanted)
+            return true;
+        return false;
+    });
+    if (prefixMatch !== null)
+        return prefixMatch;
+    return null;
+}
 function jsonPointerValue(doc, pointer) {
     if (pointer === '')
         return { found: true, value: doc };
@@ -80,6 +102,73 @@ function jsonPointerValue(doc, pointer) {
     }
     return { found: true, value: current };
 }
+function getByDotPath(obj, pathStr) {
+    const parts = pathStr.split('.');
+    let cur = obj;
+    for (const p of parts) {
+        if (cur && typeof cur === 'object' && Object.prototype.hasOwnProperty.call(cur, p)) {
+            cur = cur[p];
+        }
+        else {
+            return { found: false };
+        }
+    }
+    return { found: true, value: cur };
+}
+function findEntityInDoc(doc, ref) {
+    if (!doc || typeof doc !== 'object')
+        return { found: false };
+    // 1. Direct table match in relevantTables or tables
+    const tables = Array.isArray(doc.relevantTables) ? doc.relevantTables : (Array.isArray(doc.tables) ? doc.tables : null);
+    if (tables) {
+        const table = tables.find((t) => t && (t.name === ref || t.tableName === ref || t.id === ref));
+        if (table)
+            return { found: true, value: table };
+    }
+    if (doc.tables && typeof doc.tables === 'object' && !Array.isArray(doc.tables) && Object.prototype.hasOwnProperty.call(doc.tables, ref)) {
+        return { found: true, value: doc.tables[ref] };
+    }
+    // 2. Mail events trigger match
+    if (Array.isArray(doc.mailEvents)) {
+        const event = doc.mailEvents.find((m) => m && (m.trigger === ref || m.endpoint === ref || m.id === ref));
+        if (event)
+            return { found: true, value: event };
+    }
+    // 3. Routes match in routingPolicy or routes
+    const routeLists = [];
+    if (doc.routingPolicy && typeof doc.routingPolicy === 'object') {
+        if (Array.isArray(doc.routingPolicy.playerRoutes))
+            routeLists.push(doc.routingPolicy.playerRoutes);
+        if (Array.isArray(doc.routingPolicy.venueScopedRoutes))
+            routeLists.push(doc.routingPolicy.venueScopedRoutes);
+        if (Array.isArray(doc.routingPolicy.adminRoutes))
+            routeLists.push(doc.routingPolicy.adminRoutes);
+        if (Array.isArray(doc.routingPolicy.routes))
+            routeLists.push(doc.routingPolicy.routes);
+    }
+    if (Array.isArray(doc.routes))
+        routeLists.push(doc.routes);
+    for (const list of routeLists) {
+        const route = list.find((r) => r && (r.name === ref ||
+            r.id === ref ||
+            (Array.isArray(r.routeNames) && r.routeNames.includes(ref))));
+        if (route)
+            return { found: true, value: route };
+    }
+    // 4. Contract list items (e.g. confirmationPageContracts array)
+    for (const key of Object.keys(doc)) {
+        const val = doc[key];
+        if (Array.isArray(val)) {
+            const match = val.find((item) => item && typeof item === 'object' && (item.name === ref ||
+                item.id === ref ||
+                item.trigger === ref ||
+                (Array.isArray(item.routeNames) && item.routeNames.includes(ref))));
+            if (match)
+                return { found: true, value: match };
+        }
+    }
+    return { found: false };
+}
 function joinUrl(base, p) {
     return typeof base === 'string' ? base.replace(/\/+$/, '') + p : p;
 }
@@ -115,9 +204,32 @@ function endpointValue(doc, fragment) {
     return byId ? { found: true, value: byId } : { found: false };
 }
 function jsonRefValue(doc, fragment) {
-    if (fragment === '' || fragment.startsWith('/'))
+    if (fragment === '')
         return jsonPointerValue(doc, fragment);
-    return endpointValue(doc, fragment);
+    // 1. Direct JSON pointer starting with /
+    if (fragment.startsWith('/')) {
+        const ptr = jsonPointerValue(doc, fragment);
+        if (ptr.found)
+            return ptr;
+    }
+    else {
+        // 2. JSON pointer or top-level property without leading slash (e.g. #confirmationPageContracts)
+        const ptr = jsonPointerValue(doc, `/${fragment}`);
+        if (ptr.found)
+            return ptr;
+        // 3. Dot-path property navigation (e.g. #contract.section)
+        if (fragment.includes('.')) {
+            const dot = getByDotPath(doc, fragment);
+            if (dot.found)
+                return dot;
+        }
+    }
+    // 4. Endpoint lookup by method + path or id
+    const endpoint = endpointValue(doc, fragment);
+    if (endpoint.found)
+        return endpoint;
+    // 5. Named entity lookup: route names, mail event triggers, DB schema tables
+    return findEntityInDoc(doc, fragment);
 }
 /**
  * Resolves specRefs ("ui_specs.md#anchor", "api_contracts.json#/paths/~1x",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@njeybe/nativ",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Role-based multi-agent workflow harness: Claude Code by default, other AI agents pluggable",
   "type": "module",
   "main": "dist/index.js",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "nativ",
   "displayName": "nativ",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Role-based multi-agent workflow for Claude Code: architect, worker, verifier and explorer agents, task-scope enforcement, and the nativ MCP server.",
   "author": {
     "name": "JB Natividad"