@xn-intenton-z2a/agentic-lib 7.2.12 → 7.2.13

package/bin/agentic-lib.js

@@ -720,6 +720,7 @@ function initPurge(seedsDir, missionName, initTimestamp) {
     "zero-main.js": "src/lib/main.js",
     "zero-main.test.js": "tests/unit/main.test.js",
     "zero-index.html": "src/web/index.html",
+    "zero-lib.js": "src/web/lib.js",
     "zero-web.test.js": "tests/unit/web.test.js",
     "zero-behaviour.test.js": "tests/behaviour/homepage.test.js",
     "zero-playwright.config.js": "playwright.config.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.2.12",
+  "version": "7.2.13",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {

package/src/actions/agentic-step/tasks/transform.js

@@ -120,7 +120,7 @@ export async function transform(context) {
           `## Website Files (${webFiles.length})`,
           "The website in `src/web/` uses the JS library.",
           "When transforming source code, also update the website to use the library's new/changed features.",
-          "The `lib-meta.js` file (generated by `npm run build:web` from `package.json`) provides `name`, `version`, and `description` exports to the browser.",
+          "`src/web/lib.js` re-exports from `../lib/main.js` so the page imports the real library directly. Keep `main.js` browser-safe (guard Node APIs behind `typeof process` checks). NEVER duplicate library functions inline in the web page.",
           ...webFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
           "",
         ]

package/src/agents/agent-apply-fix.md

@@ -18,9 +18,9 @@ A fix is never just one file. These layers form a single unit — if you change
 
 - **Library source** (`src/lib/main.js`) — the core implementation
 - **Unit tests** (`tests/unit/`) — test every function at the API level with exact values and edge cases
-- **Website** (`src/web/index.html` and related files) — imports and calls the library to demonstrate features.
-  **NEVER duplicate library functions inline in the web page** — use the build pipeline (`lib-meta.js`, or
-  a generated browser module) to share code. Inline copies cause behaviour tests to test a simulation, not the real library.
+- **Website** (`src/web/index.html` and `src/web/lib.js`) — `lib.js` re-exports from `../lib/main.js`, so the
+  page imports the **real library** directly. **NEVER duplicate library functions inline in the web page** —
+  add exports to `main.js` and they are automatically available via `lib.js`.
 - **Website unit tests** (`tests/unit/web.test.js`) — verify HTML structure and library wiring
 - **Behaviour tests** (`tests/behaviour/`) — Playwright tests that load the website in a real browser
   and verify features work at a high navigational level (demo output visible, interactive elements work).

package/src/agents/agent-issue-resolution.md

@@ -79,23 +79,26 @@ automatically (from `docs/` via `npm run build:web`).
 
 ### How the library connects to the website
 
-- `src/lib/main.js` is the JS library — it exports functions, `name`, `version`, `description`, and `getIdentity()`
-- `npm run build:web` copies `src/web/*` to `docs/` and generates `docs/lib-meta.js` from `package.json`
-- `src/web/index.html` imports `lib-meta.js` via `<script type="module">` to display the library's identity
-- The website should import and call library functions — not just describe them
+- `src/lib/main.js` is browser-safe — in Node it reads `package.json` via `createRequire`, in the browser via `fetch`
+- `src/web/lib.js` re-exports from `../lib/main.js` — the page imports the **real library**
+- `src/web/index.html` imports `./lib.js` via `<script type="module">` to access the library directly
+- The website works at rest (no build step needed for development)
+- `npm run build:web` generates `docs/lib.js` as a self-contained module for production (GitHub Pages)
 
 ### What to do with the website
 
-- **Use the library**: Import the library (or its browser-compatible parts) and call its functions on the page
+- **Use the library**: Import from `./lib.js` which re-exports from `../lib/main.js` — call library functions directly
 - **Show real results**: Display actual output from library functions, not placeholder text
 - When you add or change library functions, update the website to reflect them
 - **Demonstrate features**: Each significant library feature should be visible and usable on the website.
   Behaviour tests will verify these demonstrations work, so make them testable (use IDs, structured output).
+- **Keep main.js browser-safe**: Do not add Node-only top-level code (e.g. bare `require`, `process.argv` checks)
+  without guarding them behind `typeof process !== "undefined"` checks
 
 ### CRITICAL: Never duplicate library code in the web page
 
-**Do NOT copy or recreate library functions inline in `src/web/index.html`.** The web page must consume
-the library through the build pipeline — not by reimplementing functions in a `<script>` block.
+**Do NOT copy or recreate library functions inline in `src/web/index.html`.** The web page imports the
+library directly via `src/web/lib.js` → `src/lib/main.js`. There is no reason to duplicate.
 
 Why this matters:
 - Unit tests test `src/lib/main.js` directly
@@ -104,11 +107,11 @@ Why this matters:
 - The two copies can diverge silently, and tests pass even when the real library is broken
 
 How to share code between library and web:
-- Identity (name, version, description) flows via `lib-meta.js` (generated by `build:web` from `package.json`)
-- If the web page needs to call mission-specific functions, make them available through the build pipeline
-  (e.g. generate a browser-compatible module in `docs/` or add a build step that packages the pure functions)
+- `src/web/lib.js` re-exports everything from `../lib/main.js` — add exports to `main.js` and they are
+  automatically available to the web page
+- If adding a new exported function to `main.js`, make sure it is browser-safe (no bare Node API calls)
 - The behaviour test imports `getIdentity()` from `src/lib/main.js` and asserts the page displays the same
-  version — this coupling test proves the pipeline is wired up correctly
+  version — this coupling test proves the import chain is wired up correctly
 
 ### Guidelines
 

package/src/scripts/build-web.cjs

@@ -6,8 +6,10 @@
 //
 // Builds the docs/ directory for web serving:
 // 1. Creates docs/ and copies src/web/* into it
-// 2. Generates docs/lib-meta.js with package metadata exports
-// 3. Generates docs/lib-browser.js from src/lib/main.js (if it has named exports)
+// 2. Generates docs/lib.js — a self-contained browser module with:
+//    - Package identity (name, version, description) from package.json
+//    - Browser-safe exported functions extracted from src/lib/main.js
+//    This overwrites the src/web/lib.js re-export (which only works in dev).
 //
 // This file is part of the Example Suite for `agentic-lib` see: https://github.com/xn-intenton-z2a/agentic-lib
 // This file is licensed under the MIT License. For details, see LICENSE-MIT
@@ -34,64 +36,63 @@ if (fs.existsSync(webDir)) {
   }
 }
 
-// Step 2: Generate docs/lib-meta.js with package metadata
+// Step 2: Generate docs/lib.js — self-contained browser module
+// This overwrites the re-export copied from src/web/lib.js above,
+// replacing it with a standalone module that works on GitHub Pages
+// (where src/lib/main.js and package.json are not available).
 const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
-const metaLines = ["name", "version", "description"].map(
-  (k) => `export const ${k} = ${JSON.stringify(pkg[k])};`
+const sections = [];
+
+// Identity exports from package.json
+sections.push(
+  `export const name = ${JSON.stringify(pkg.name)};`,
+  `export const version = ${JSON.stringify(pkg.version)};`,
+  `export const description = ${JSON.stringify(pkg.description)};`,
+  "",
+  "export function getIdentity() {",
+  "  return { name, version, description };",
+  "}"
 );
-fs.writeFileSync(path.join(docsDir, "lib-meta.js"), metaLines.join("\n") + "\n");
-console.log("Wrote docs/lib-meta.js");
 
-// Step 3: Generate docs/lib-browser.js from src/lib/main.js named exports
-// Parse the main module for `export function` and `export async function` declarations
-// and re-emit them as a standalone browser-compatible module.
+// Extract browser-safe exported functions from src/lib/main.js
 const mainPath = path.resolve("src", "lib", "main.js");
 if (fs.existsSync(mainPath)) {
   const mainSrc = fs.readFileSync(mainPath, "utf8");
-  // Match named export functions: export function foo(...) { ... } or export async function foo(...)
-  const exportRegex = /^export\s+(async\s+)?function\s+(\w+)/gm;
-  const exportNames = [];
-  let match;
-  while ((match = exportRegex.exec(mainSrc)) !== null) {
-    exportNames.push(match[2]);
-  }
+  const lines = mainSrc.split("\n");
 
-  if (exportNames.length > 0) {
-    // Extract the function bodies by finding each export function and copying it verbatim
-    const lines = mainSrc.split("\n");
-    const functionBodies = [];
-    for (let i = 0; i < lines.length; i++) {
-      if (/^export\s+(async\s+)?function\s+\w+/.test(lines[i])) {
-        // Collect lines until we find the closing brace at column 0
-        const fnLines = [lines[i]];
-        let braceDepth = 0;
-        for (let j = i; j < lines.length; j++) {
-          for (const ch of lines[j]) {
-            if (ch === "{") braceDepth++;
-            if (ch === "}") braceDepth--;
-          }
-          if (j > i) fnLines.push(lines[j]);
-          if (braceDepth === 0 && j >= i) {
-            break;
-          }
+  // Skip identity-related exports and the main/CLI function — only extract
+  // mission-specific exported functions (e.g. hammingDistance, etc.)
+  const SKIP_FUNCTIONS = new Set(["getIdentity", "main"]);
+
+  for (let i = 0; i < lines.length; i++) {
+    const fnMatch = lines[i].match(/^export\s+(async\s+)?function\s+(\w+)/);
+    if (fnMatch && !SKIP_FUNCTIONS.has(fnMatch[2])) {
+      // Collect the full function body by tracking brace depth
+      const fnLines = [lines[i]];
+      let braceDepth = 0;
+      for (let j = i; j < lines.length; j++) {
+        for (const ch of lines[j]) {
+          if (ch === "{") braceDepth++;
+          if (ch === "}") braceDepth--;
+        }
+        if (j > i) fnLines.push(lines[j]);
+        if (braceDepth === 0 && j >= i) {
+          break;
         }
-        functionBodies.push(fnLines.join("\n"));
       }
+      sections.push("");
+      sections.push(fnLines.join("\n"));
     }
-
-    const header = [
-      "// docs/lib-browser.js",
-      "// Generated browser-compatible module exposing named exports from src/lib/main.js.",
-      "// Auto-generated by build-web.cjs — do not edit manually.",
-      "",
-    ].join("\n");
-
-    fs.writeFileSync(
-      path.join(docsDir, "lib-browser.js"),
-      header + functionBodies.join("\n\n") + "\n"
-    );
-    console.log(
-      `Wrote docs/lib-browser.js (${exportNames.length} exports: ${exportNames.join(", ")})`
-    );
   }
 }
+
+const header = [
+  "// docs/lib.js",
+  "// Self-contained browser module generated by build-web.cjs.",
+  "// Identity from package.json; functions extracted from src/lib/main.js.",
+  "// Do not edit — regenerate with: npm run build:web",
+  "",
+].join("\n");
+
+fs.writeFileSync(path.join(docsDir, "lib.js"), header + sections.join("\n") + "\n");
+console.log("Wrote docs/lib.js");

package/src/seeds/zero-README.md

@@ -49,33 +49,35 @@ The pipeline runs as GitHub Actions workflows. An LLM supervisor gathers reposit
 ## File Layout
 
 ```
-src/lib/main.js              ← library (Node entry point: identity + mission functions)
-src/web/index.html            ← web page (browser: imports lib-meta.js, demonstrates library)
+src/lib/main.js              ← library (browser-safe: identity + mission functions)
+src/web/index.html            ← web page (imports ./lib.js)
+src/web/lib.js                ← browser entry point (re-exports from ../lib/main.js)
 tests/unit/main.test.js       ← unit tests (import main.js directly, test API-level detail)
 tests/unit/web.test.js        ← web structure tests (read index.html as text, verify wiring)
-tests/behaviour/              ← Playwright E2E (run page in browser, import main.js for coupling)
+tests/behaviour/              ← Playwright E2E (serve from project root, import main.js for coupling)
 docs/                         ← build output (generated by npm run build:web)
-docs/lib-meta.js              ← generated: exports name, version, description from package.json
+docs/lib.js                   ← generated: self-contained module for GitHub Pages
 ```
 
-These files form a **coupled unit**. Changes to the library must flow through to the web page, and tests verify this coupling:
+These files form a **coupled unit**. The library works in both Node and the browser:
 
-- `src/lib/main.js` exports `getIdentity()` → returns `{ name, version, description }` from `package.json`
-- `npm run build:web` copies `src/web/*` to `docs/` and generates `docs/lib-meta.js` from `package.json`
-- `src/web/index.html` imports `lib-meta.js` at runtime → displays library identity on the page
+- `src/lib/main.js` is browser-safe — in Node it reads `package.json` via `createRequire`, in the browser via `fetch`
+- `src/web/lib.js` re-exports from `../lib/main.js` — the page imports the **real library**, not a generated copy
+- `src/web/index.html` imports `./lib.js` → displays library identity on the page
 - The behaviour test imports `getIdentity()` from `main.js` AND reads `#lib-version` from the rendered page → asserts they match
+- `npm run build:web` generates `docs/lib.js` as a self-contained module for production (GitHub Pages)
 
-This coupling test proves the web page is consuming the real library via the build pipeline. Mission-specific functions should follow the same path — never duplicate library logic inline in the web page.
+This coupling proves the web page consumes the real library. Mission-specific functions should follow the same path — never duplicate library logic inline in the web page.
 
 ## Test Strategy
 
 | Test layer | What it tests | How it binds |
 |------------|--------------|--------------|
 | **Unit tests** (`tests/unit/main.test.js`) | Library API: return values, error types, edge cases | Imports directly from `src/lib/main.js` |
-| **Web structure tests** (`tests/unit/web.test.js`) | HTML structure: expected elements, `lib-meta.js` import | Reads `src/web/index.html` as text |
-| **Behaviour tests** (`tests/behaviour/`) | End-to-end: page renders, interactive elements work | Playwright loads the built site; coupling test imports `getIdentity()` from `main.js` and asserts the page displays the same version |
+| **Web structure tests** (`tests/unit/web.test.js`) | HTML structure: expected elements, `lib.js` re-export | Reads `src/web/index.html` and `src/web/lib.js` as text |
+| **Behaviour tests** (`tests/behaviour/`) | End-to-end: page renders, displays real library values | Playwright serves from project root; coupling test imports `getIdentity()` from `main.js` and asserts the page displays the same version |
 
-The **coupling test** in the behaviour test is the key invariant: it proves the web page displays values from the actual library, not hardcoded or duplicated values. If the build pipeline breaks, this test fails.
+The **coupling test** in the behaviour test is the key invariant: it proves the web page displays values from the actual library, not hardcoded or duplicated values. The page imports `lib.js` which re-exports from `main.js` which reads `package.json` — the same chain the unit tests exercise.
 
 ## Configuration
 

package/src/seeds/zero-index.html

@@ -33,16 +33,16 @@
   <p>This website uses the library. See <a href="https://github.com/xn-intenton-z2a/repository0">the repository</a> for source code and mission details.</p>
   <script type="module">
     try {
-      const { name, version, description } = await import('./lib-meta.js');
+      const { name, version, description } = await import('./lib.js');
       document.getElementById('lib-name').textContent = name;
       document.getElementById('lib-version').textContent = version;
       document.getElementById('lib-description').textContent = description || '(no description)';
       document.getElementById('demo-output').textContent = JSON.stringify({ name, version, description }, null, 2);
       document.title = name + ' v' + version;
     } catch (e) {
-      document.getElementById('lib-version').textContent = '(build required)';
-      document.getElementById('lib-description').textContent = 'Run npm run build:web to generate library metadata';
-      document.getElementById('demo-output').textContent = 'Library not yet built. Run: npm run build:web';
+      document.getElementById('lib-version').textContent = '(error)';
+      document.getElementById('lib-description').textContent = e.message;
+      document.getElementById('demo-output').textContent = 'Failed to load library: ' + e.message;
     }
   </script>
 </body>

package/src/seeds/zero-lib.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2025-2026 Polycode Limited
+// src/web/lib.js — Browser entry point, re-exports from the library.
+export { name, version, description, getIdentity } from "../lib/main.js";

package/src/seeds/zero-main.js

@@ -3,11 +3,21 @@
 // Copyright (C) 2025-2026 Polycode Limited
 // src/lib/main.js
 
-import { createRequire } from "module";
-import { fileURLToPath } from "url";
+const isNode = typeof process !== "undefined" && !!process.versions?.node;
 
-const require = createRequire(import.meta.url);
-const pkg = require("../../package.json");
+let pkg;
+if (isNode) {
+  const { createRequire } = await import("module");
+  const requireFn = createRequire(import.meta.url);
+  pkg = requireFn("../../package.json");
+} else {
+  try {
+    const resp = await fetch(new URL("../../package.json", import.meta.url));
+    pkg = await resp.json();
+  } catch {
+    pkg = { name: document.title, version: "0.0.0", description: "" };
+  }
+}
 
 export const name = pkg.name;
 export const version = pkg.version;
@@ -29,7 +39,10 @@ export function main(args) {
   console.log(`${name}@${version}`);
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  const args = process.argv.slice(2);
-  main(args);
+if (isNode) {
+  const { fileURLToPath } = await import("url");
+  if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const args = process.argv.slice(2);
+    main(args);
+  }
 }

package/src/seeds/zero-package.json

@@ -9,7 +9,7 @@
     "build:web": "node .github/agentic-lib/scripts/build-web.cjs",
     "test": "vitest --run tests/unit/*.test.js",
     "test:unit": "vitest --run --coverage tests/unit/*.test.js",
-    "test:behaviour": "npm run build:web && npx playwright test --config playwright.config.js",
+    "test:behaviour": "npx playwright test --config playwright.config.js",
     "start": "npm run build:web && npx serve docs",
     "start:cli": "node src/lib/main.js"
   },
@@ -17,7 +17,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.2.12"
+    "@xn-intenton-z2a/agentic-lib": "^7.2.13"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",

package/src/seeds/zero-playwright.config.js

@@ -7,10 +7,10 @@ export default defineConfig({
   timeout: 30000,
   retries: 2,
   use: {
-    baseURL: "http://localhost:3000",
+    baseURL: "http://localhost:3000/src/web/",
   },
   webServer: {
-    command: "npx serve docs -l 3000",
+    command: "npx serve . -l 3000",
     port: 3000,
     reuseExistingServer: true,
   },

package/src/seeds/zero-web.test.js

@@ -15,9 +15,15 @@ describe("Website", () => {
     expect(html).toContain("</html>");
   });
 
-  test("index.html imports the library via lib-meta.js", () => {
+  test("index.html imports the library via lib.js", () => {
     const html = readFileSync("src/web/index.html", "utf8");
-    expect(html).toContain("lib-meta.js");
+    expect(html).toContain("lib.js");
+  });
+
+  test("src/web/lib.js re-exports from the library", () => {
+    expect(existsSync("src/web/lib.js")).toBe(true);
+    const lib = readFileSync("src/web/lib.js", "utf8");
+    expect(lib).toContain("../lib/main.js");
   });
 
   test("index.html displays library identity elements", () => {