@agilesyndrome/cf-genai-base 4.1.3 → 5.0.1

package/src/cli/users.js

@@ -0,0 +1,34 @@
+import { executeJson, parseJsonRows } from "./d1.js";
+
+function sql(value) { return "'" + String(value).replaceAll("'", "''") + "'"; }
+function query(database, target, command, options) { return parseJsonRows(executeJson(options.wranglerCommand, database, target, command, options)); }
+function csv(value) { return String(value).split(",").map((item) => item.trim()).filter(Boolean); }
+
+export function runUserCommand({ action, username, options }) {
+  const target = options.target || "local";
+  if (!["local", "staging", "production"].includes(target)) throw new Error("User target must be local, staging, or production.");
+  if (action === "list") {
+    const users = query(options.database, target, "SELECT id,email,display_name,provider,subject,is_admin,created_at,updated_at FROM auth_users ORDER BY email COLLATE NOCASE;", options);
+    return console.log(JSON.stringify(users.map((user) => ({ ...user, tenants: query(options.database, target, "SELECT t.id,t.name FROM auth_tenants t JOIN auth_user_tenants ut ON ut.tenant_id=t.id WHERE ut.user_id=" + sql(user.id) + " ORDER BY t.name COLLATE NOCASE;", options) })), null, 2));
+  }
+  if (!username) throw new Error("A username, email, subject, or user id is required.");
+  const where = `(id=${sql(username)} OR email=${sql(username)} OR subject=${sql(username)})`;
+  const rows = query(options.database, target, `SELECT id,email,display_name,provider,subject,is_admin,created_at,updated_at FROM auth_users WHERE ${where} LIMIT 1;`, options);
+  if (!rows[0]) throw new Error(`User not found: ${username}`);
+  if (action === "get") {
+    const user = rows[0];
+    const scopes = query(options.database, target, `SELECT scope_name,granted_at FROM auth_user_scopes WHERE user_id=${sql(user.id)} ORDER BY scope_name;`, options);
+    const groups = query(options.database, target, `SELECT group_name,granted_at FROM auth_user_groups WHERE user_id=${sql(user.id)} ORDER BY group_name;`, options);
+    const tenants = query(options.database, target, `SELECT t.id,t.name,ut.joined_at FROM auth_tenants t JOIN auth_user_tenants ut ON ut.tenant_id=t.id WHERE ut.user_id=${sql(user.id)} ORDER BY t.name COLLATE NOCASE;`, options);
+    return console.log(JSON.stringify({ ...user, scopes, groups, tenants }, null, 2));
+  }
+  if (action !== "update") throw new Error("Unknown user action.");
+  const assignments = [];
+  if (options.roles !== undefined) assignments.push(`is_admin=${csv(options.roles).includes("admin") ? 1 : 0}`);
+  if (!assignments.length && options.scopes === undefined && options.groups === undefined && options.tenants === undefined) throw new Error("user:update requires --roles, --scopes, --groups, or --tenants.");
+  if (assignments.length) query(options.database, target, `UPDATE auth_users SET ${assignments.join(",")},updated_at=CURRENT_TIMESTAMP WHERE id=${sql(rows[0].id)};`, options);
+  if (options.scopes !== undefined) { query(options.database, target, "DELETE FROM auth_user_scopes WHERE user_id=" + sql(rows[0].id) + ";", options); for (const scope of csv(options.scopes)) query(options.database, target, "INSERT OR IGNORE INTO auth_user_scopes (user_id,scope_name,granted_by) VALUES (" + sql(rows[0].id) + "," + sql(scope) + ",'human:cli');", options); }
+  if (options.groups !== undefined) { query(options.database, target, "DELETE FROM auth_user_groups WHERE user_id=" + sql(rows[0].id) + ";", options); for (const group of csv(options.groups)) query(options.database, target, "INSERT OR IGNORE INTO auth_user_groups (user_id,group_name,granted_by) VALUES (" + sql(rows[0].id) + "," + sql(group) + ",'human:cli');", options); }
+  if (options.tenants !== undefined) { const tenants = csv(options.tenants); if (tenants.length) { const available = query(options.database, target, "SELECT id FROM auth_tenants WHERE id IN (" + tenants.map(sql).join(",") + ");", options); const found = new Set(available.map((tenant) => tenant.id)); if (found.size !== tenants.length) throw new Error("One or more tenants do not exist."); } query(options.database, target, "DELETE FROM auth_user_tenants WHERE user_id=" + sql(rows[0].id) + ";", options); for (const tenant of tenants) query(options.database, target, "INSERT OR IGNORE INTO auth_user_tenants (user_id,tenant_id) VALUES (" + sql(rows[0].id) + "," + sql(tenant) + ");", options); }
+  return runUserCommand({ action: "get", username: rows[0].id, options });
+}

package/src/cli/version.js

@@ -0,0 +1,54 @@
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+export const PACKAGE_NAME = "@agilesyndrome/cf-genai-base";
+
+export function localVersion() {
+  const packageUrl = new URL("../../package.json", import.meta.url);
+  return JSON.parse(readFileSync(packageUrl, "utf8")).version;
+}
+
+export function latestVersion(packageName = PACKAGE_NAME) {
+  const result = spawnSync("npm", ["view", packageName, "version"], {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+  });
+  if (result.error || result.status !== 0) return null;
+  const value = result.stdout.trim();
+  return value || null;
+}
+
+function parsedVersion(value) {
+  const match = String(value).trim().replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+  if (!match) return null;
+  return {
+    numbers: match.slice(1, 4).map(Number),
+    prerelease: match[4]?.split(".") ?? [],
+  };
+}
+
+export function compareVersions(left, right) {
+  const a = parsedVersion(left);
+  const b = parsedVersion(right);
+  if (!a || !b) return String(left).localeCompare(String(right));
+  for (let index = 0; index < 3; index += 1) {
+    if (a.numbers[index] !== b.numbers[index]) return a.numbers[index] - b.numbers[index];
+  }
+  if (a.prerelease.length === 0 && b.prerelease.length > 0) return 1;
+  if (a.prerelease.length > 0 && b.prerelease.length === 0) return -1;
+  return String(a.prerelease).localeCompare(String(b.prerelease), undefined, { numeric: true });
+}
+
+export function formatVersionOutput({ local, latest, packageName = PACKAGE_NAME }) {
+  const lines = [`${packageName} local: ${local}`, `${packageName} latest: ${latest ?? "unavailable"}`];
+  if (latest && compareVersions(latest, local) > 0) {
+    lines.push("Upgrade available:", `  npm i -g ${packageName}`);
+  }
+  return lines.join("\n");
+}
+
+export function runVersionCommand() {
+  const local = localVersion();
+  const latest = latestVersion();
+  console.log(formatVersionOutput({ local, latest }));
+}

package/src/{core.js → core/circuits.js}

@@ -1,54 +1,46 @@
-export const HEALTHCHECK_STATES = ["red", "yellow", "green"];
-export const CIRCUIT_BREAKER_STATES = ["off", "tripped", "on"];
-export const HEALTHCHECK_MODES = ["any", "all"];
-export const BASE_PACKAGE_NAME = "@agilesyndrome/cf-genai-base";
-export const BASE_VERSION = "4.1.1";
-
-export function eventLog(level, event, details = {}) {
-  const method = ["debug", "info", "warn", "error"].includes(level) ? level : "info";
-  console[method](`[EventLog] ${event}`, details);
+import { auditLog, eventLog } from "./events.js";
+import { createD1 } from "./d1.js";
+import { secureJson } from "./security.js";
+import { BASE_PACKAGE_NAME, BASE_VERSION, CIRCUIT_BREAKER_STATES, HEALTHCHECK_MODES, HEALTHCHECK_STATES } from "./constants.js";
+
+export async function featureCircuit(env, id, who = "system:read") {
+  return getCircuitBreaker(env, id, { who }).catch((error) => {
+    eventLog("error", "feature.circuit.read.failed", { breaker: id, errorName: error?.name || "Error", errorMessage: String(error?.message || "Unknown circuit breaker error").slice(0, 300) });
+    void env?.event?.("feature.circuit.read.failed", "feature", { breaker: id, who, errorName: error?.name || "Error" });
+    return null;
+  });
 }
 
-export function auditLog({ who = "system", operation, resource, details = {} }) {
-  console.info(`[AuditLog] ${who}:${operation} ${resource}`, details);
-}
+export async function featureAvailable(env, id, who = "system:read") { return (await featureCircuit(env, id, who))?.state === "on"; }
 
-export function requestActor(state = {}) {
-  if (state.requestedBy) return String(state.requestedBy);
-  if (state.authUser?.id) return `user:${state.authUser.id}`;
-  if (state.user?.auth_strategy === "http_basic") return "user:admin";
-  if (state.user?.sub) return `user:${state.user.sub}`;
-  return "system:read";
+export async function requireFeatureCircuit(env, { feature, breakerId, operation, requestId, who, message = "The requested feature is unavailable." }) {
+  const breaker = await featureCircuit(env, breakerId, who || "system:read");
+  if (breaker?.state === "on") return breaker;
+  const details = { feature, breaker: breakerId, state: breaker?.state || "missing", operation, requestId: requestId || null };
+  eventLog("warn", "feature.request.blocked", details);
+  auditLog({ who: who || "system:read", operation: "blocked", resource: `feature:${feature}`, details });
+  await env?.event?.("feature.request.blocked", "feature", { ...details, who: who || "system:read" });
+  throw Object.assign(new Error(message), { status: 503, code: "feature_circuit_unavailable", feature, breakerId, circuitState: breaker?.state || "missing" });
 }
 
-export function createD1(env, { who = "system:read" } = {}) {
-  if (!env?.DB) throw new Error("A DB binding is required");
-  const db = env.DB;
+export function createAvailabilityFeature({ name = "base", breakerId = `${name}:site-available`, displayName = "Site availability", publicPaths = ["/health", "/api/health"] } = {}) {
   return {
-    prepare(sql) {
-      const statement = db.prepare(sql);
-      return new Proxy(statement, { get(target, property) {
-        const value = target[property];
-        if (typeof value !== "function" || !["run", "first", "all", "raw"].includes(property)) return typeof value === "function" ? value.bind(target) : value;
-        return async (...args) => {
-          auditD1(who, sql);
-          return value.apply(target, args);
-        };
-      }});
-    },
-    async batch(statements) {
-      auditD1(who, "BATCH");
-      return typeof db.batch === "function" ? db.batch(statements) : Promise.all(statements.map((statement) => statement.run()));
+    name,
+    packageName: BASE_PACKAGE_NAME,
+    version: BASE_VERSION,
+    healthcheck: async () => ({ feature: name, component: "site-available", displayName, state: "green", metadata: { endpoint: "/health", expectedStatus: 200 } }),
+    circuitBreakers: [{ id: breakerId, name: "site-available", displayName, state: "on", allowSelfHealing: false, healthchecks: [`${name}:site-available`] }],
+    async middleware(request, env, ctx, next) {
+      const pathname = new URL(request.url).pathname;
+      if (publicPaths.some((path) => pathname === path || pathname.startsWith(`${path}/`))) return next(request);
+      const breaker = await featureCircuit(env, breakerId, "system:read");
+      if (breaker?.state === "on") return next(request);
+      await env.event?.("feature.maintenance", "availability", { feature: name, breaker: breakerId, state: breaker?.state || "missing", pathname, method: request.method });
+      return secureJson({ error: "The site is temporarily unavailable." }, 503);
     },
   };
 }
 
-function auditD1(who, sql) {
-  const operation = String(sql).trim().match(/^(SELECT|INSERT|UPDATE|DELETE|REPLACE|WITH)/i)?.[1]?.toLowerCase() || "execute";
-  eventLog("debug", "d1.operation", { who, operation });
-  auditLog({ who, operation, resource: "d1" });
-}
-
 export function normalizeHealthcheck(input = {}) {
   const state = String(input.state || "yellow").toLowerCase();
   if (!HEALTHCHECK_STATES.includes(state)) throw new Error("Healthcheck state must be red, yellow, or green");
@@ -66,19 +58,15 @@ export function normalizeCircuitBreaker(input = {}) {
 }
 
 export async function registerHealthcheck(env, input, { who = "system:read" } = {}) {
-  const item = normalizeHealthcheck(input);
-  const db = createD1(env, { who });
-  const id = String(input.id || `${item.feature}:${item.component}`);
+  const item = normalizeHealthcheck(input); const db = createD1(env, { who }); const id = String(input.id || `${item.feature}:${item.component}`);
   await db.prepare(`INSERT INTO core_healthchecks (id,feature,component,display_name,state,metadata_json) VALUES (?,?,?,?,?,?) ON CONFLICT(feature,component) DO UPDATE SET display_name=excluded.display_name,metadata_json=excluded.metadata_json,updated_at=CURRENT_TIMESTAMP`).bind(id, item.feature, item.component, item.displayName, item.state, JSON.stringify(item.metadata)).run();
   return getHealthcheck(env, id, { who });
 }
 
 export async function updateHealthcheck(env, id, state, { who = "system:read" } = {}) {
   if (!HEALTHCHECK_STATES.includes(String(state).toLowerCase())) throw new Error("Healthcheck state must be red, yellow, or green");
-  const item = await getHealthcheck(env, id, { who });
-  if (!item) return null;
-  const db = createD1(env, { who });
-  await db.prepare("UPDATE core_healthchecks SET state=?,updated_at=CURRENT_TIMESTAMP WHERE id=?").bind(String(state).toLowerCase(), id).run();
+  const item = await getHealthcheck(env, id, { who }); if (!item) return null;
+  await createD1(env, { who }).prepare("UPDATE core_healthchecks SET state=?,updated_at=CURRENT_TIMESTAMP WHERE id=?").bind(String(state).toLowerCase(), id).run();
   auditLog({ who, operation: "update", resource: `feature:${item.feature} component:${item.component} ${String(state).toLowerCase()}` });
   return getHealthcheck(env, id, { who });
 }
@@ -87,22 +75,18 @@ export async function getHealthcheck(env, id, { who = "system:read" } = {}) { re
 export async function listHealthchecks(env, { who = "system:read" } = {}) { return (await createD1(env, { who }).prepare("SELECT * FROM core_healthchecks ORDER BY feature,component").bind().all()).results || []; }
 
 export async function registerCircuitBreaker(env, input, { who = "system:read" } = {}) {
-  const item = normalizeCircuitBreaker(input);
-  const db = createD1(env, { who });
-  const id = String(input.id || `${item.feature}:${item.name}`);
+  const item = normalizeCircuitBreaker(input); const db = createD1(env, { who }); const id = String(input.id || `${item.feature}:${item.name}`);
   await db.prepare(`INSERT INTO core_circuit_breakers (id,feature,name,display_name,state,healthcheck_mode,allow_self_healing,metadata_json) VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(feature,name) DO UPDATE SET display_name=excluded.display_name,healthcheck_mode=excluded.healthcheck_mode,allow_self_healing=excluded.allow_self_healing,metadata_json=excluded.metadata_json,updated_at=CURRENT_TIMESTAMP`).bind(id, item.feature, item.name, item.displayName, item.state, item.healthcheckMode, item.allowSelfHealing ? 1 : 0, JSON.stringify(item.metadata)).run();
   await db.batch([db.prepare("DELETE FROM core_circuit_breaker_healthchecks WHERE circuit_breaker_id=?").bind(id), db.prepare("DELETE FROM core_circuit_breaker_dependencies WHERE circuit_breaker_id=?").bind(id), ...item.healthchecks.map((healthcheckId) => db.prepare("INSERT OR IGNORE INTO core_circuit_breaker_healthchecks (circuit_breaker_id,healthcheck_id) VALUES (?,?)").bind(id, healthcheckId)), ...item.dependsOnCircuitBreakers.map((dependencyId) => db.prepare("INSERT OR IGNORE INTO core_circuit_breaker_dependencies (circuit_breaker_id,dependency_id) VALUES (?,?)").bind(id, dependencyId))]);
   return getCircuitBreaker(env, id, { who });
 }
 
-export async function getCircuitBreaker(env, id, { who = "system:read" } = {}) { const db = createD1(env, { who }); const breaker = await db.prepare("SELECT * FROM core_circuit_breakers WHERE id=?").bind(id).first(); if (!breaker) return null; breaker.healthchecks = (await db.prepare("SELECT healthcheck_id FROM core_circuit_breaker_healthchecks WHERE circuit_breaker_id=?").bind(id).all()).results.map((row) => row.healthcheck_id) ; breaker.depends_on_circuit_breakers = (await db.prepare("SELECT dependency_id FROM core_circuit_breaker_dependencies WHERE circuit_breaker_id=?").bind(id).all()).results.map((row) => row.dependency_id); return breaker; }
+export async function getCircuitBreaker(env, id, { who = "system:read" } = {}) { const db = createD1(env, { who }); const breaker = await db.prepare("SELECT * FROM core_circuit_breakers WHERE id=?").bind(id).first(); if (!breaker) return null; breaker.healthchecks = (await db.prepare("SELECT healthcheck_id FROM core_circuit_breaker_healthchecks WHERE circuit_breaker_id=?").bind(id).all()).results.map((row) => row.healthcheck_id); breaker.depends_on_circuit_breakers = (await db.prepare("SELECT dependency_id FROM core_circuit_breaker_dependencies WHERE circuit_breaker_id=?").bind(id).all()).results.map((row) => row.dependency_id); return breaker; }
 export async function listCircuitBreakers(env, { who = "system:read" } = {}) { const rows = (await createD1(env, { who }).prepare("SELECT * FROM core_circuit_breakers ORDER BY feature,name").bind().all()).results || []; return Promise.all(rows.map((row) => getCircuitBreaker(env, row.id, { who }))); }
 
 export async function setCircuitBreaker(env, id, state, { who = "system:read", automated = false } = {}) {
-  const next = String(state).toLowerCase();
-  if (!CIRCUIT_BREAKER_STATES.includes(next)) throw new Error("Circuit breaker state must be off, tripped, or on");
-  const current = await getCircuitBreaker(env, id, { who });
-  if (!current) return null;
+  const next = String(state).toLowerCase(); if (!CIRCUIT_BREAKER_STATES.includes(next)) throw new Error("Circuit breaker state must be off, tripped, or on");
+  const current = await getCircuitBreaker(env, id, { who }); if (!current) return null;
   if (automated && !((current.state === "on" && next === "tripped") || (current.state === "tripped" && next === "on" && Boolean(current.allow_self_healing)))) return current;
   if (automated && next === "off") return current;
   await createD1(env, { who }).prepare("UPDATE core_circuit_breakers SET state=?,updated_at=CURRENT_TIMESTAMP WHERE id=?").bind(next, id).run();
@@ -111,27 +95,18 @@ export async function setCircuitBreaker(env, id, state, { who = "system:read", a
 }
 
 export async function evaluateCircuitBreaker(env, id, { who = "system:read" } = {}) {
-  const breaker = await getCircuitBreaker(env, id, { who });
-  if (!breaker) return null;
-  const db = createD1(env, { who });
+  const breaker = await getCircuitBreaker(env, id, { who }); if (!breaker) return null; const db = createD1(env, { who });
   const rows = (await db.prepare("SELECT h.state FROM core_healthchecks h JOIN core_circuit_breaker_healthchecks b ON b.healthcheck_id=h.id WHERE b.circuit_breaker_id=?").bind(id).all()).results || [];
-  const failing = rows.map((row) => row.state === "red");
-  const dependencies = (await db.prepare("SELECT b.state FROM core_circuit_breakers b JOIN core_circuit_breaker_dependencies d ON d.dependency_id=b.id WHERE d.circuit_breaker_id=?").bind(id).all()).results || [];
-  const dependencyFailed = dependencies.some((row) => row.state === "tripped");
-  const shouldTrip = dependencyFailed || (failing.length > 0 &&  (breaker.healthcheck_mode === "all" ? failing.every(Boolean) : failing.some(Boolean)));
+  const failing = rows.map((row) => row.state === "red"); const dependencies = (await db.prepare("SELECT b.state FROM core_circuit_breakers b JOIN core_circuit_breaker_dependencies d ON d.dependency_id=b.id WHERE d.circuit_breaker_id=?").bind(id).all()).results || [];
+  const dependencyFailed = dependencies.some((row) => row.state === "tripped"); const shouldTrip = dependencyFailed || (failing.length > 0 && (breaker.healthcheck_mode === "all" ? failing.every(Boolean) : failing.some(Boolean)));
   if (breaker.state === "on" && shouldTrip) return setCircuitBreaker(env, id, "tripped", { who, automated: true });
   if (breaker.state === "tripped" && !shouldTrip && breaker.allow_self_healing) return setCircuitBreaker(env, id, "on", { who, automated: true });
   return breaker;
 }
 
-
 export async function registerFeatureManifests(env, features = [], { who = "system:read" } = {}) {
   for (const feature of features) {
-    const name = String(feature?.name || feature?.id || "feature");
-    const declaredResult = typeof feature?.healthcheck === "function" ? await feature.healthcheck(env, { who }) : (feature?.healthchecks || feature?.healthChecks || []);
-    const declaredHealthchecks = Array.isArray(declaredResult) ? declaredResult : [declaredResult];
-    const healthchecks = [];
-    const breakers = [];
+    const name = String(feature?.name || feature?.id || "feature"); const declaredResult = typeof feature?.healthcheck === "function" ? await feature.healthcheck(env, { who }) : (feature?.healthchecks || feature?.healthChecks || []); const declaredHealthchecks = Array.isArray(declaredResult) ? declaredResult : [declaredResult]; const healthchecks = []; const breakers = [];
     for (const healthcheck of declaredHealthchecks) healthchecks.push(await registerHealthcheck(env, { ...healthcheck, feature: healthcheck.feature || name }, { who }));
     for (const breaker of feature?.circuitBreakers || feature?.circuit_breakers || []) breakers.push(await registerCircuitBreaker(env, { ...breaker, feature: breaker.feature || name }, { who }));
     await registerCircuitBreaker(env, { id: `${name}:rollup`, feature: name, name: "rollup", displayName: `${name} feature`, state: "on", allowSelfHealing: true, healthchecks: healthchecks.filter(Boolean).map((item) => item.id), dependsOnCircuitBreakers: breakers.filter(Boolean).map((item) => item.id) }, { who });
@@ -139,43 +114,21 @@ export async function registerFeatureManifests(env, features = [], { who = "syst
 }
 
 export async function listFeatureHealth(env, { who = "system:read" } = {}) {
-  const checks = await listHealthchecks(env, { who });
-  const severity = { green: 0, yellow: 1, red: 2 };
-  const features = {};
+  const checks = await listHealthchecks(env, { who }); const severity = { green: 0, yellow: 1, red: 2 }; const features = {};
   for (const check of checks) { const name = check.feature; if (!features[name] || severity[check.state] > severity[features[name].state]) features[name] = { feature: name, state: check.state, healthchecks: 0 }; features[name].healthchecks += 1; }
   return Object.values(features).sort((a, b) => a.feature.localeCompare(b.feature));
 }
 
-
 export function normalizeFeatureManifest(feature = {}) {
-  const source = feature && typeof feature === "object" ? feature : {};
-  const manifest = source.manifest && typeof source.manifest === "object" ? source.manifest : source;
-  const name = String(source.name || source.id || manifest.name || "feature");
-  const packageName = source.packageName || source.package_name || source.package || manifest.packageName || manifest.package_name || manifest.package;
-  const version = source.version || source.packageVersion || source.package_version || manifest.version;
-  return {
-    feature: name,
-    display_name: String(source.displayName || source.display_name || manifest.displayName || manifest.display_name || name),
-    package_name: packageName ? String(packageName) : null,
-    version: version ? String(version) : null,
-  };
+  const source = feature && typeof feature === "object" ? feature : {}; const manifest = source.manifest && typeof source.manifest === "object" ? source.manifest : source; const name = String(source.name || source.id || manifest.name || "feature"); const packageName = source.packageName || source.package_name || source.package || manifest.packageName || manifest.package_name || manifest.package; const version = source.version || source.packageVersion || source.package_version || manifest.version;
+  return { feature: name, display_name: String(source.displayName || source.display_name || manifest.displayName || manifest.display_name || name), package_name: packageName ? String(packageName) : null, version: version ? String(version) : null };
 }
 
 export async function listFeatureCatalog(env, features = [], { who = "system:read" } = {}) {
-  const [healthchecks, circuitBreakers] = await Promise.all([listHealthchecks(env, { who }), listCircuitBreakers(env, { who })]);
-  const manifests = new Map([["base", { feature: "base", display_name: "Base platform", package_name: BASE_PACKAGE_NAME, version: BASE_VERSION }]]);
-  for (const feature of features) {
-    const manifest = normalizeFeatureManifest(feature);
-    manifests.set(manifest.feature, manifest);
-  }
+  const [healthchecks, circuitBreakers] = await Promise.all([listHealthchecks(env, { who }), listCircuitBreakers(env, { who })]); const manifests = new Map([["base", { feature: "base", display_name: "Base platform", package_name: BASE_PACKAGE_NAME, version: BASE_VERSION }]]);
+  for (const feature of features) { const manifest = normalizeFeatureManifest(feature); manifests.set(manifest.feature, manifest); }
   for (const item of healthchecks) if (!manifests.has(item.feature)) manifests.set(item.feature, normalizeFeatureManifest({ name: item.feature }));
   for (const item of circuitBreakers) if (!manifests.has(item.feature)) manifests.set(item.feature, normalizeFeatureManifest({ name: item.feature }));
-  const severity = { green: 0, yellow: 1, red: 2 };
-  const state = (items) => items.reduce((current, item) => severity[item.state] > severity[current] ? item.state : current, "green");
-  return [...manifests.values()].sort((a, b) => a.feature.localeCompare(b.feature)).map((manifest) => {
-    const featureHealthchecks = healthchecks.filter((item) => item.feature === manifest.feature);
-    const featureBreakers = circuitBreakers.filter((item) => item.feature === manifest.feature);
-    const rollup = featureBreakers.find((item) => item.name === "rollup") || null;
-    return { ...manifest, health: featureHealthchecks.length ? state(featureHealthchecks) : "yellow", healthchecks: featureHealthchecks, circuit_breakers: featureBreakers, circuit_breaker: rollup };
-  });
+  const severity = { green: 0, yellow: 1, red: 2 }; const state = (items) => items.reduce((current, item) => severity[item.state] > severity[current] ? item.state : current, "green");
+  return [...manifests.values()].sort((a, b) => a.feature.localeCompare(b.feature)).map((manifest) => { const featureHealthchecks = healthchecks.filter((item) => item.feature === manifest.feature); const featureBreakers = circuitBreakers.filter((item) => item.feature === manifest.feature); const rollup = featureBreakers.find((item) => item.name === "rollup") || null; return { ...manifest, health: featureHealthchecks.length ? state(featureHealthchecks) : "yellow", healthchecks: featureHealthchecks, circuit_breakers: featureBreakers, circuit_breaker: rollup }; });
 }

package/src/core/constants.js

@@ -0,0 +1,5 @@
+export const HEALTHCHECK_STATES = ["red", "yellow", "green"];
+export const CIRCUIT_BREAKER_STATES = ["off", "tripped", "on"];
+export const HEALTHCHECK_MODES = ["any", "all"];
+export const BASE_PACKAGE_NAME = "@agilesyndrome/cf-genai-base";
+export const BASE_VERSION = "4.1.3";

package/src/core/d1.js

@@ -0,0 +1,54 @@
+import { auditLog, eventLog } from "./events.js";
+
+export function createD1(env, { who = "system:read" } = {}) {
+  if (!env?.DB) throw new Error("A DB binding is required");
+  const db = env.DB;
+  return {
+    prepare(sql) {
+      const statement = db.prepare(sql);
+      return new Proxy(statement, { get(target, property) {
+        const value = target[property];
+        if (typeof value !== "function" || !["run", "first", "all", "raw"].includes(property)) return typeof value === "function" ? value.bind(target) : value;
+        return async (...args) => { auditD1(who, sql); return value.apply(target, args); };
+      }});
+    },
+    async batch(statements) {
+      auditD1(who, "BATCH");
+      return typeof db.batch === "function" ? db.batch(statements) : Promise.all(statements.map((statement) => statement.run()));
+    },
+  };
+}
+
+export function auditedD1(db, who = "system:read") {
+  if (!db) return db;
+  return new Proxy(db, {
+    get(target, property) {
+      const value = target[property];
+      if (property === "prepare") return (sql) => {
+        const statement = value.call(target, sql);
+        return new Proxy(statement, {
+          get(statementTarget, statementProperty) {
+            const method = statementTarget[statementProperty];
+            if (!["run", "first", "all", "raw"].includes(statementProperty) || typeof method !== "function") return typeof method === "function" ? method.bind(statementTarget) : method;
+            return async (...args) => { auditD1(who, sql); return method.apply(statementTarget, args); };
+          },
+        });
+      };
+      if (property === "batch") return (statements) => { auditD1(who, "BATCH"); return typeof value === "function" ? value.call(target, statements) : Promise.all(statements.map((statement) => statement.run())); };
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+export function auditedEnv(env, who = "system:read") {
+  if (!env?.DB) return env;
+  const result = Object.create(env);
+  result.DB = auditedD1(env.DB, who);
+  return result;
+}
+
+function auditD1(who, sql) {
+  const operation = String(sql).trim().match(/^(SELECT|INSERT|UPDATE|DELETE|REPLACE|WITH)/i)?.[1]?.toLowerCase() || "execute";
+  eventLog("debug", "d1.operation", { who, operation });
+  auditLog({ who, operation, resource: "d1" });
+}

package/src/core/event-hub.js

@@ -0,0 +1,29 @@
+import { DurableObject } from "cloudflare:workers";
+
+export class EventHub extends DurableObject {
+  async fetch(request) {
+    const url = new URL(request.url);
+    if (request.method === "POST" && url.pathname === "/publish") {
+      if (request.headers.get("X-CF-GenAI-Event") !== "1") return new Response("Not found", { status: 404 });
+      const event = await request.json().catch(() => null);
+      if (!event?.id || !event?.what) return Response.json({ error: "Invalid event" }, { status: 400 });
+      const message = JSON.stringify({ type: "event", event });
+      for (const socket of this.ctx.getWebSockets()) {
+        try { socket.send(message); } catch { socket.close(1011, "Event delivery failed"); }
+      }
+      return Response.json({ ok: true });
+    }
+    if (request.method !== "GET" || request.headers.get("Upgrade")?.toLowerCase() !== "websocket") return new Response("WebSocket upgrade required", { status: 426 });
+    const pair = new WebSocketPair();
+    const [client, server] = Object.values(pair);
+    this.ctx.acceptWebSocket(server);
+    return new Response(null, { status: 101, webSocket: client });
+  }
+
+  webSocketMessage(socket, message) {
+    if (message === "ping") socket.send(JSON.stringify({ type: "pong" }));
+  }
+
+  webSocketClose() {}
+  webSocketError() {}
+}

package/src/core/events.js

@@ -0,0 +1,63 @@
+export function Event(who, what, where, when = new Date(), details = {}) {
+  return {
+    id: crypto.randomUUID(),
+    who: String(who || "system"),
+    what: String(what || "event"),
+    where: String(where || "application"),
+    when: when instanceof Date ? when.toISOString() : new Date(when || Date.now()).toISOString(),
+    details: details && typeof details === "object" ? details : { value: details },
+  };
+}
+
+export function createEventHandler(features = [], { eventHubBinding = "EVENT_HUB" } = {}) {
+  const handlers = features.flatMap((feature) => {
+    const handler = feature?.eventHandler || feature?.event_handler;
+    return typeof handler === "function" ? [handler.bind(feature)] : [];
+  });
+  return async (event, env, ctx) => {
+    if (!event) return null;
+    eventLog("info", event.what, { who: event.who, where: event.where, when: event.when, ...event.details });
+    await Promise.all([
+      ...handlers.map((handler) => Promise.resolve(handler(event, { env, ctx }))),
+      publishLiveEvent(env, event, eventHubBinding),
+    ]);
+    return event;
+  };
+}
+
+export function eventRooms(event) {
+  const audience = event?.details?.audience || {};
+  const rooms = [];
+  if (audience.userId) rooms.push(`user:${audience.userId}`);
+  if (audience.tenantId) rooms.push(`tenant:${audience.tenantId}`);
+  if (!rooms.length && String(event?.who || "").startsWith("user:")) rooms.push(String(event.who));
+  return [...new Set(rooms)];
+}
+
+async function publishLiveEvent(env, event, bindingName) {
+  const namespace = bindingName && env?.[bindingName];
+  if (!namespace || typeof namespace.idFromName !== "function") return;
+  for (const room of eventRooms(event)) {
+    try {
+      const stub = namespace.get(namespace.idFromName(room));
+      await stub.fetch("https://cf-genai-event-hub/publish", { method: "POST", headers: { "X-CF-GenAI-Event": "1", "Content-Type": "application/json" }, body: JSON.stringify(event) });
+    } catch (error) {
+      eventLog("warn", "live.event.publish.failed", { room, error: error?.message || String(error) });
+    }
+  }
+}
+
+export async function emitEvent(env, event, ctx) {
+  if (typeof env?.eventHandler === "function") return env.eventHandler(event, env, ctx);
+  if (event) eventLog("info", event.what, { who: event.who, where: event.where, when: event.when, ...event.details });
+  return event;
+}
+
+export function eventLog(level, event, details = {}) {
+  const method = ["debug", "info", "warn", "error"].includes(level) ? level : "info";
+  console[method](`[EventLog] ${event}`, details);
+}
+
+export function auditLog({ who = "system", operation, resource, details = {} }) {
+  console.info(`[AuditLog] ${who}:${operation} ${resource}`, details);
+}

package/src/core/identity.js

@@ -0,0 +1,39 @@
+import { Event, emitEvent } from "./events.js";
+
+export function requestActor(state = {}) {
+  if (state.requestedBy) return String(state.requestedBy);
+  const canonical = authUser(state);
+  if (canonical?.id) return `user:${canonical.id}`;
+  if (state.user?.auth_strategy === "http_basic") return "user:admin";
+  if (state.user?.sub) return `user:${state.user.sub}`;
+  return "system:read";
+}
+
+export function authUser(value) {
+  return value?.authUser || value?.user?.authUser || value?.state?.authUser || value?.state?.user?.authUser || (value?.id && value?.provider && value?.subject ? value : null) || null;
+}
+
+export function userId(value) {
+  return authUser(value)?.id || value?.userId || value?.sub || value?.email || null;
+}
+
+export function requestIdentity(state = {}) {
+  const canonical = authUser(state);
+  return {
+    user: state.user || null,
+    authUser: canonical,
+    userId: canonical?.id || null,
+    who: requestActor(state),
+    isAuthenticated: Boolean(canonical || state.user),
+    isAdmin: Boolean(state.user?.auth_strategy === "http_basic" || canonical?.is_admin),
+  };
+}
+
+export function requestContext({ request, env, ctx, state, data } = {}) {
+  const identity = requestIdentity(state);
+  return {
+    request, env, ctx, state, data: data || state?.data,
+    ...identity,
+    event: (what, where = "application", details = {}, when = new Date()) => emitEvent(env, Event(identity.who, what, where, when, details), ctx),
+  };
+}

package/src/core/index.js

@@ -0,0 +1,7 @@
+export * from "./constants.js";
+export * from "./events.js";
+export * from "./identity.js";
+export * from "./security.js";
+export * from "./d1.js";
+export * from "./circuits.js";
+export * from "./jobs.js";