@thebackstoryis/engineering-with-ai 0.2.9

package/src/runtime/team-hub-database.mjs

@@ -0,0 +1,288 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { TEAM_HUB_AUTHORITY_NOTICE, validateTeamHubEnvelope } from '../team-hub.mjs';
+import { projectTeamHubResourceRelease, validateTeamHubResourcePackage } from '../team-hub-resources.mjs';
+
+export function validateTeamHubDataRoot(dataRoot) {
+  const root = resolve(String(dataRoot ?? ''));
+  if (!String(dataRoot ?? '').trim()) throw new Error('Team Hub requires an explicit data root.');
+  if (/(?:^|[/\\])\.ewai-pipeline(?:[/\\]|$)/i.test(root)) throw new Error('Team Hub data must be separate from every project-local .ewai-pipeline runtime.');
+  if (/[/\\](?:CloudStorage|OneDrive|Dropbox|Google Drive)(?:[/\\]|$)/i.test(root) || root.startsWith('/Volumes/')) {
+    throw new Error('Team Hub SQLite data must not use a network, removable or cloud-synchronised folder.');
+  }
+  if (existsSync(root) && lstatSync(root).isSymbolicLink()) throw new Error('Team Hub data root must not be a symbolic link.');
+  return root;
+}
+
+export function teamHubDatabasePath(dataRoot) {
+  return resolve(validateTeamHubDataRoot(dataRoot), 'data/team-hub.sqlite');
+}
+
+export function openTeamHubDatabase(dataRoot) {
+  const path = teamHubDatabasePath(dataRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  const database = new DatabaseSync(path);
+  database.exec('PRAGMA foreign_keys = ON;');
+  database.exec('PRAGMA busy_timeout = 5000;');
+  database.exec('PRAGMA journal_mode = WAL;');
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS team_hub_projects (
+      project_id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      snapshot_json TEXT NOT NULL,
+      snapshot_digest TEXT NOT NULL,
+      generated_at TEXT NOT NULL,
+      accepted_at TEXT NOT NULL,
+      receipt_id TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS team_hub_receipts (
+      receipt_id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      snapshot_digest TEXT NOT NULL,
+      idempotency_key TEXT NOT NULL UNIQUE,
+      accepted_at TEXT NOT NULL,
+      receipt_json TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_team_hub_projects_accepted ON team_hub_projects(accepted_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_team_hub_receipts_project ON team_hub_receipts(project_id, accepted_at DESC);
+    CREATE TABLE IF NOT EXISTS team_hub_resource_releases (
+      resource_id TEXT NOT NULL,
+      version TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      name TEXT NOT NULL,
+      description TEXT NOT NULL,
+      publisher_id TEXT NOT NULL,
+      publisher_name TEXT NOT NULL,
+      compatibility_ewai TEXT NOT NULL,
+      package_digest TEXT NOT NULL,
+      package_json TEXT NOT NULL,
+      published_at TEXT NOT NULL,
+      receipt_id TEXT NOT NULL,
+      PRIMARY KEY(resource_id, version)
+    );
+    CREATE TABLE IF NOT EXISTS team_hub_resource_publication_receipts (
+      receipt_id TEXT PRIMARY KEY,
+      resource_id TEXT NOT NULL,
+      version TEXT NOT NULL,
+      package_digest TEXT NOT NULL,
+      idempotency_key TEXT NOT NULL UNIQUE,
+      published_at TEXT NOT NULL,
+      receipt_json TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_team_hub_resource_releases_published
+      ON team_hub_resource_releases(resource_id, published_at DESC, version DESC);
+  `);
+  return database;
+}
+
+function publicationReceiptFromRow(row, replayed) {
+  return { ...JSON.parse(row.receipt_json), replayed };
+}
+
+export function publishTeamHubResource(database, input, options = {}) {
+  const resourcePackage = validateTeamHubResourcePackage(input);
+  const resource = resourcePackage.resource;
+  const idempotencyKey = String(options.idempotencyKey ?? `${resource.id}@${resource.version}:${resourcePackage.digest}`);
+  if (!idempotencyKey || idempotencyKey.length > 500 || /[\u0000-\u001f\u007f]/.test(idempotencyKey)) {
+    throw Object.assign(new Error('Resource publication idempotency key is invalid.'), { status: 400, code: 'invalid-idempotency-key' });
+  }
+  const publishedAt = options.at ?? new Date().toISOString();
+  const receipt = {
+    schema: 'ewai.team-hub-resource-publication-receipt/v1',
+    receiptId: options.receiptId ?? `resource-publication-${randomUUID()}`,
+    resourceId: resource.id,
+    version: resource.version,
+    packageDigest: resourcePackage.digest,
+    idempotencyKey,
+    publishedAt,
+    replayed: false,
+    authority: 'Publication records immutable transport availability; it does not select or apply this resource.',
+  };
+  const release = projectTeamHubResourceRelease(resourcePackage);
+  database.exec('BEGIN IMMEDIATE;');
+  try {
+    const replay = database.prepare('SELECT receipt_json FROM team_hub_resource_publication_receipts WHERE idempotency_key = ?').get(idempotencyKey);
+    if (replay) {
+      database.exec('COMMIT;');
+      return publicationReceiptFromRow(replay, true);
+    }
+    const existing = database.prepare('SELECT package_digest FROM team_hub_resource_releases WHERE resource_id = ? AND version = ?').get(resource.id, resource.version);
+    if (existing) {
+      if (existing.package_digest !== resourcePackage.digest) {
+        throw Object.assign(new Error('A different immutable release already uses this resource ID and version.'), { status: 409, code: 'resource-release-conflict' });
+      }
+      const prior = database.prepare('SELECT receipt_json FROM team_hub_resource_publication_receipts WHERE resource_id = ? AND version = ? AND package_digest = ? ORDER BY published_at LIMIT 1').get(resource.id, resource.version, resourcePackage.digest);
+      if (prior) {
+        database.exec('COMMIT;');
+        return publicationReceiptFromRow(prior, true);
+      }
+    }
+    database.prepare(`
+      INSERT INTO team_hub_resource_releases
+        (resource_id, version, kind, name, description, publisher_id, publisher_name,
+         compatibility_ewai, package_digest, package_json, published_at, receipt_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      resource.id, resource.version, resource.kind, resource.name, resource.description,
+      resource.publisher.id, resource.publisher.name, resource.compatibility.ewai,
+      resourcePackage.digest, JSON.stringify(resourcePackage), publishedAt, receipt.receiptId,
+    );
+    database.prepare(`
+      INSERT INTO team_hub_resource_publication_receipts
+        (receipt_id, resource_id, version, package_digest, idempotency_key, published_at, receipt_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(receipt.receiptId, resource.id, resource.version, resourcePackage.digest, idempotencyKey, publishedAt, JSON.stringify(receipt));
+    database.exec('COMMIT;');
+  } catch (error) {
+    database.exec('ROLLBACK;');
+    throw error;
+  }
+  return { ...receipt, release: { ...release, publishedAt, receiptId: receipt.receiptId } };
+}
+
+function releaseFromRow(row) {
+  const resourcePackage = JSON.parse(row.package_json);
+  return {
+    schema: 'ewai.team-hub-resource-release/v1',
+    kind: row.kind,
+    id: row.resource_id,
+    name: row.name,
+    description: row.description,
+    version: row.version,
+    publisher: { id: row.publisher_id, name: row.publisher_name },
+    compatibility: { ewai: row.compatibility_ewai },
+    digest: row.package_digest,
+    fileCount: resourcePackage.files.length,
+    totalBytes: resourcePackage.files.reduce((sum, file) => sum + file.size, 0),
+    publishedAt: row.published_at,
+    receiptId: row.receipt_id,
+  };
+}
+
+export function readTeamHubResourceCatalogue(database) {
+  const releases = database.prepare(`
+    SELECT resource_id, version, kind, name, description, publisher_id, publisher_name,
+      compatibility_ewai, package_digest, package_json, published_at, receipt_id
+    FROM team_hub_resource_releases
+    ORDER BY resource_id COLLATE NOCASE, published_at DESC, version DESC
+  `).all().map(releaseFromRow);
+  return {
+    schema: 'ewai.team-hub-resource-catalogue/v1',
+    releases,
+    authority: 'Discovery does not install, select or apply a resource.',
+  };
+}
+
+export function readTeamHubResourcePackage(database, resourceId, version) {
+  const row = database.prepare('SELECT package_json FROM team_hub_resource_releases WHERE resource_id = ? AND version = ?').get(String(resourceId), String(version));
+  if (!row) throw Object.assign(new Error('Team Hub resource release was not found.'), { status: 404, code: 'resource-release-not-found' });
+  return validateTeamHubResourcePackage(JSON.parse(row.package_json));
+}
+
+function receiptFromRow(row, replayed) {
+  const receipt = JSON.parse(row.receipt_json);
+  return { ...receipt, replayed };
+}
+
+export function ingestTeamHubEnvelope(database, input, options = {}) {
+  const envelope = validateTeamHubEnvelope(input);
+  const acceptedAt = options.at ?? new Date().toISOString();
+  const receipt = {
+    schema: 'ewai.team-hub-receipt/v1',
+    receiptId: options.receiptId ?? `receipt-${randomUUID()}`,
+    projectId: envelope.snapshot.project.id,
+    snapshotDigest: envelope.snapshotDigest,
+    idempotencyKey: envelope.idempotencyKey,
+    acceptedAt,
+    replayed: false,
+  };
+  const receiptJson = JSON.stringify(receipt);
+  const snapshotJson = JSON.stringify(envelope.snapshot);
+
+  database.exec('BEGIN IMMEDIATE;');
+  try {
+    const existing = database.prepare('SELECT receipt_json FROM team_hub_receipts WHERE idempotency_key = ?').get(envelope.idempotencyKey);
+    if (existing) {
+      database.exec('COMMIT;');
+      return receiptFromRow(existing, true);
+    }
+    database.prepare(`
+      INSERT INTO team_hub_receipts (receipt_id, project_id, snapshot_digest, idempotency_key, accepted_at, receipt_json)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(receipt.receiptId, receipt.projectId, receipt.snapshotDigest, receipt.idempotencyKey, receipt.acceptedAt, receiptJson);
+    database.prepare(`
+      INSERT INTO team_hub_projects (project_id, name, snapshot_json, snapshot_digest, generated_at, accepted_at, receipt_id, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_id) DO UPDATE SET
+        name = excluded.name,
+        snapshot_json = excluded.snapshot_json,
+        snapshot_digest = excluded.snapshot_digest,
+        generated_at = excluded.generated_at,
+        accepted_at = excluded.accepted_at,
+        receipt_id = excluded.receipt_id,
+        updated_at = excluded.updated_at
+      WHERE excluded.generated_at >= team_hub_projects.generated_at
+    `).run(
+      receipt.projectId, envelope.snapshot.project.name, snapshotJson, envelope.snapshotDigest,
+      envelope.snapshot.generatedAt, receipt.acceptedAt, receipt.receiptId, acceptedAt,
+    );
+    database.exec('COMMIT;');
+  } catch (error) {
+    database.exec('ROLLBACK;');
+    throw error;
+  }
+  return receipt;
+}
+
+function freshness(acceptedAt, nowValue, staleAfterHours) {
+  const accepted = Date.parse(acceptedAt);
+  const now = Date.parse(nowValue);
+  if (!Number.isFinite(accepted) || !Number.isFinite(now)) return { state: 'unknown', acceptedAt, ageHours: null };
+  const ageHours = Math.max(0, Math.floor((now - accepted) / 3_600_000));
+  return { state: ageHours > staleAfterHours ? 'stale' : 'current', acceptedAt, ageHours };
+}
+
+export function readTeamHubPortfolio(database, options = {}) {
+  const now = options.now ?? new Date().toISOString();
+  const staleAfterHours = Math.max(1, Math.min(8_760, Number(options.staleAfterHours ?? 72)));
+  const rows = database.prepare('SELECT * FROM team_hub_projects ORDER BY name COLLATE NOCASE, project_id').all();
+  const projects = rows.map((row) => {
+    const snapshot = JSON.parse(row.snapshot_json);
+    const observed = freshness(row.accepted_at, now, staleAfterHours);
+    const attention = [...(snapshot.delivery?.attention ?? [])];
+    if (observed.state === 'stale') attention.unshift({ code: 'snapshot-stale', severity: 'warning', summary: 'The latest accepted snapshot is stale.' });
+    return {
+      id: row.project_id,
+      name: row.name,
+      freshness: observed,
+      evidence: {
+        submittedAt: snapshot.generatedAt,
+        acceptedAt: row.accepted_at,
+        snapshotDigest: row.snapshot_digest,
+        receiptId: row.receipt_id,
+      },
+      ewaiVersion: snapshot.ewaiVersion,
+      revisionDigest: snapshot.revision.digest,
+      intents: snapshot.intents,
+      delivery: snapshot.delivery,
+      resources: snapshot.resources,
+      attention: attention.slice(0, 20),
+    };
+  });
+  return {
+    schema: 'ewai.team-hub-portfolio/v1',
+    generatedAt: now,
+    staleAfterHours,
+    projects,
+    summary: {
+      total: projects.length,
+      current: projects.filter(({ freshness: item }) => item.state === 'current').length,
+      stale: projects.filter(({ freshness: item }) => item.state === 'stale').length,
+      attention: projects.filter(({ attention }) => attention.length > 0).length,
+    },
+    authority: { canApprove: false, notice: TEAM_HUB_AUTHORITY_NOTICE },
+  };
+}

package/src/runtime/team-hub-server.mjs

@@ -0,0 +1,191 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  ingestTeamHubEnvelope,
+  openTeamHubDatabase,
+  publishTeamHubResource,
+  readTeamHubPortfolio,
+  readTeamHubResourceCatalogue,
+  readTeamHubResourcePackage,
+  validateTeamHubDataRoot,
+} from './team-hub-database.mjs';
+import { TEAM_HUB_RESOURCE_LIMITS } from '../team-hub-resources.mjs';
+
+const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+const defaultStaticRoot = resolve(moduleDirectory, '../../public/team-hub');
+const DEFAULT_MAXIMUM_BODY_BYTES = 256 * 1024;
+
+function loopback(host) {
+  return ['127.0.0.1', 'localhost', '::1'].includes(String(host ?? '').toLowerCase());
+}
+
+function json(response, status, value) {
+  const body = `${JSON.stringify(value)}\n`;
+  response.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(body),
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff',
+  });
+  response.end(body);
+}
+
+function safeError(response, status, code, message) {
+  json(response, status, { error: { code, message } });
+}
+
+function authorised(request, token) {
+  if (!token) return false;
+  const supplied = String(request.headers.authorization ?? '');
+  const expected = `Bearer ${token}`;
+  const left = createHash('sha256').update(supplied).digest();
+  const right = createHash('sha256').update(expected).digest();
+  return timingSafeEqual(left, right);
+}
+
+async function readBody(request, maximumBytes) {
+  const declared = Number(request.headers['content-length'] ?? 0);
+  if (Number.isFinite(declared) && declared > maximumBytes) throw Object.assign(new Error('Request body exceeds the Team Hub limit.'), { status: 413, code: 'body-too-large' });
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > maximumBytes) throw Object.assign(new Error('Request body exceeds the Team Hub limit.'), { status: 413, code: 'body-too-large' });
+    chunks.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+  catch { throw Object.assign(new Error('Request body must be valid JSON.'), { status: 400, code: 'invalid-json' }); }
+}
+
+function staticAsset(response, staticRoot, pathname) {
+  const routes = new Map([
+    ['/', 'index.html'], ['/index.html', 'index.html'], ['/app.js', 'app.js'], ['/styles.css', 'styles.css'],
+  ]);
+  const name = routes.get(pathname);
+  if (!name) return false;
+  const path = resolve(staticRoot, name);
+  if (!existsSync(path) || !statSync(path).isFile()) return false;
+  const body = readFileSync(path);
+  const type = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8' }[extname(path)] ?? 'application/octet-stream';
+  response.writeHead(200, {
+    'content-type': type, 'content-length': body.length, 'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff', 'content-security-policy': "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'",
+  });
+  response.end(body);
+  return true;
+}
+
+export async function createTeamHubHttpServer(options = {}) {
+  const dataRoot = validateTeamHubDataRoot(options.dataRoot);
+  const host = String(options.host ?? '127.0.0.1');
+  if (!loopback(host) && options.allowNetwork !== true) throw new Error('A non-loopback Team Hub bind requires --allow-network.');
+  const token = String(options.token ?? '');
+  if (token.length < 16 || token.length > 1_024) throw new Error('Team Hub token must contain 16 to 1024 characters.');
+  const publisherToken = String(options.publisherToken ?? '');
+  if (publisherToken && (publisherToken.length < 16 || publisherToken.length > 1_024)) throw new Error('Team Hub publisher token must contain 16 to 1024 characters.');
+  if (publisherToken && publisherToken === token) throw new Error('Team Hub reader and publisher tokens must be different.');
+  const database = openTeamHubDatabase(dataRoot);
+  const startedAt = options.startedAt ?? new Date().toISOString();
+  const staticRoot = resolve(options.staticRoot ?? defaultStaticRoot);
+  const maximumBodyBytes = Number(options.maximumBodyBytes ?? DEFAULT_MAXIMUM_BODY_BYTES);
+  const maximumResourceBodyBytes = Number(options.maximumResourceBodyBytes ?? TEAM_HUB_RESOURCE_LIMITS.maximumPackageBytes);
+
+  const server = createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url ?? '/', `http://${request.headers.host ?? '127.0.0.1'}`);
+      if (url.search) return safeError(response, 400, 'unexpected-query', 'This Team Hub route does not accept query parameters.');
+      if (request.method === 'GET' && url.pathname === '/health') {
+        return json(response, 200, { schema: 'ewai.team-hub-health/v1', status: 'running', pid: process.pid, startedAt, bind: loopback(host) ? 'loopback' : 'network', tls: false, publisherConfigured: Boolean(publisherToken) });
+      }
+      if (request.method === 'GET' && ['/','/index.html','/app.js','/styles.css'].includes(url.pathname)) {
+        if (staticAsset(response, staticRoot, url.pathname)) return;
+      }
+      if (request.method === 'POST' && url.pathname === '/api/v1/resources') {
+        if (!publisherToken) return safeError(response, 503, 'publisher-not-configured', 'Resource publication is not configured on this Team Hub.');
+        if (!authorised(request, publisherToken)) return safeError(response, 401, 'unauthorised', 'Publisher authentication is required.');
+        if (!String(request.headers['content-type'] ?? '').toLowerCase().startsWith('application/json')) {
+          return safeError(response, 415, 'unsupported-media-type', 'Resource publication requires application/json.');
+        }
+        const input = await readBody(request, maximumResourceBodyBytes);
+        const receipt = publishTeamHubResource(database, input, { idempotencyKey: request.headers['idempotency-key'] });
+        return json(response, receipt.replayed ? 200 : 202, receipt);
+      }
+      if (request.method === 'GET' && url.pathname === '/api/v1/resources') {
+        if (!authorised(request, token) && !authorised(request, publisherToken)) return safeError(response, 401, 'unauthorised', 'Authentication is required.');
+        return json(response, 200, readTeamHubResourceCatalogue(database));
+      }
+      const resourceRelease = url.pathname.match(/^\/api\/v1\/resources\/([^/]+)\/releases\/([^/]+)$/);
+      if (request.method === 'GET' && resourceRelease) {
+        if (!authorised(request, token) && !authorised(request, publisherToken)) return safeError(response, 401, 'unauthorised', 'Authentication is required.');
+        let resourceId;
+        let version;
+        try { resourceId = decodeURIComponent(resourceRelease[1]); version = decodeURIComponent(resourceRelease[2]); }
+        catch { return safeError(response, 400, 'invalid-resource-identity', 'Resource identity is invalid.'); }
+        if (!/^org\.[a-z0-9]+(?:-[a-z0-9]+)*\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/.test(resourceId) || !/^\d+\.\d+\.\d+$/.test(version)) {
+          return safeError(response, 400, 'invalid-resource-identity', 'Resource identity is invalid.');
+        }
+        return json(response, 200, readTeamHubResourcePackage(database, resourceId, version));
+      }
+      if (url.pathname.startsWith('/api/v1/') && !authorised(request, token)) {
+        return safeError(response, 401, 'unauthorised', 'Authentication is required.');
+      }
+      if (request.method === 'POST' && url.pathname === '/api/v1/snapshots') {
+        if (!String(request.headers['content-type'] ?? '').toLowerCase().startsWith('application/json')) {
+          return safeError(response, 415, 'unsupported-media-type', 'Snapshots require application/json.');
+        }
+        const input = await readBody(request, maximumBodyBytes);
+        const receipt = ingestTeamHubEnvelope(database, input);
+        return json(response, receipt.replayed ? 200 : 202, receipt);
+      }
+      if (request.method === 'GET' && url.pathname === '/api/v1/portfolio') {
+        return json(response, 200, readTeamHubPortfolio(database));
+      }
+      return safeError(response, 404, 'not-found', 'Team Hub route not found.');
+    } catch (error) {
+      const status = Number(error.status ?? 400);
+      return safeError(response, status >= 400 && status < 600 ? status : 400, error.code ?? 'invalid-request', status >= 500 ? 'Team Hub could not complete the request.' : String(error.message ?? 'Invalid request.').slice(0, 240));
+    }
+  });
+
+  await new Promise((accept, reject) => {
+    server.once('error', reject);
+    server.listen(Number(options.port ?? 0), host, accept);
+  });
+  const address = server.address();
+  const displayHost = host === '::1' ? '[::1]' : host;
+  const url = `http://${displayHost}:${address.port}`;
+  return {
+    schema: 'ewai.team-hub-running-service/v1', url, host, port: address.port, startedAt,
+    close: async () => {
+      await new Promise((accept, reject) => server.close((error) => error ? reject(error) : accept()));
+      database.close();
+    },
+  };
+}
+
+function option(args, name, fallback = '') {
+  const index = args.indexOf(name);
+  return index === -1 ? fallback : args[index + 1];
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const tokenEnv = option(args, '--token-env');
+  const token = process.env[tokenEnv] ?? '';
+  const publisherTokenEnv = option(args, '--publisher-token-env');
+  const publisherToken = publisherTokenEnv ? process.env[publisherTokenEnv] ?? '' : '';
+  createTeamHubHttpServer({
+    dataRoot: option(args, '--data'), host: option(args, '--host', '127.0.0.1'),
+    port: Number(option(args, '--port', '0')), token, publisherToken, allowNetwork: args.includes('--allow-network'),
+  }).then((running) => {
+    const shutdown = async () => { await running.close(); process.exit(0); };
+    process.once('SIGTERM', shutdown);
+    process.once('SIGINT', shutdown);
+  }).catch((error) => {
+    process.stderr.write(`Team Hub failed to start: ${error.message}\n`);
+    process.exit(1);
+  });
+}

package/src/runtime/team-hub.mjs

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateTeamHubDataRoot } from './team-hub-database.mjs';
+
+const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+const serverEntry = resolve(moduleDirectory, 'team-hub-server.mjs');
+
+function servicePaths(dataRoot) {
+  const root = validateTeamHubDataRoot(dataRoot);
+  return { root, state: resolve(root, 'runtime/team-hub.json'), log: resolve(root, 'logs/team-hub.log') };
+}
+
+function readState(path) {
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}
+
+function writeState(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+
+async function health(url, timeout = 800) {
+  try {
+    const response = await fetch(`${url}/health`, { signal: AbortSignal.timeout(timeout) });
+    if (!response.ok) return null;
+    const value = await response.json();
+    return value.schema === 'ewai.team-hub-health/v1' ? value : null;
+  } catch { return null; }
+}
+
+function basePort(dataRoot) {
+  const digest = createHash('sha256').update(resolve(dataRoot)).digest();
+  return 48000 + digest.readUInt16BE(0) % 1000;
+}
+
+function ports(dataRoot, configured) {
+  if (Number(configured) > 0) return [Number(configured)];
+  const first = basePort(dataRoot);
+  return Array.from({ length: 20 }, (_, index) => 48000 + ((first - 48000 + index) % 1000));
+}
+
+export async function teamHubStatus(options = {}) {
+  const paths = servicePaths(options.dataRoot);
+  const state = readState(paths.state);
+  if (!state?.url) return { schema: 'ewai.team-hub-service-status/v1', status: 'stopped', state: null };
+  const observed = await health(state.url);
+  if (!observed || Number(observed.pid) !== Number(state.pid)) return { schema: 'ewai.team-hub-service-status/v1', status: 'stale', state };
+  return { schema: 'ewai.team-hub-service-status/v1', status: 'running', state: { ...state, bind: observed.bind, tls: observed.tls, publisherConfigured: observed.publisherConfigured === true } };
+}
+
+export async function ensureTeamHub(options = {}) {
+  const paths = servicePaths(options.dataRoot);
+  const tokenEnv = String(options.tokenEnv ?? '');
+  if (!/^[A-Z][A-Z0-9_]{2,100}$/.test(tokenEnv)) throw new Error('Team Hub requires a safe --token-env name.');
+  if (!String((options.env ?? process.env)[tokenEnv] ?? '')) throw new Error(`Team Hub token environment variable is unavailable: ${tokenEnv}`);
+  const publisherTokenEnv = String(options.publisherTokenEnv ?? '');
+  if (publisherTokenEnv && !/^[A-Z][A-Z0-9_]{2,100}$/.test(publisherTokenEnv)) throw new Error('Team Hub requires a safe --publisher-token-env name.');
+  if (publisherTokenEnv && !String((options.env ?? process.env)[publisherTokenEnv] ?? '')) throw new Error(`Team Hub publisher token environment variable is unavailable: ${publisherTokenEnv}`);
+  if (publisherTokenEnv && publisherTokenEnv === tokenEnv) throw new Error('Team Hub reader and publisher token environment variables must be different.');
+  const host = String(options.host ?? '127.0.0.1');
+  if (!['127.0.0.1', 'localhost', '::1'].includes(host) && options.allowNetwork !== true) throw new Error('A non-loopback Team Hub bind requires --allow-network.');
+  const current = await teamHubStatus({ dataRoot: paths.root });
+  if (current.status === 'running') return { status: 'running', started: false, ...current.state };
+  rmSync(paths.state, { force: true });
+  mkdirSync(dirname(paths.log), { recursive: true });
+  const log = openSync(paths.log, 'a');
+  try {
+    for (const port of ports(paths.root, options.port)) {
+      const displayHost = host === '::1' ? '[::1]' : host;
+      const url = `http://${displayHost}:${port}`;
+      if (await health(url, 250)) continue;
+      const args = [serverEntry, '--data', paths.root, '--host', host, '--port', String(port), '--token-env', tokenEnv];
+      if (publisherTokenEnv) args.push('--publisher-token-env', publisherTokenEnv);
+      if (options.allowNetwork) args.push('--allow-network');
+      const child = spawn(process.execPath, args, { detached: true, stdio: ['ignore', log, log], env: options.env ?? process.env });
+      child.unref();
+      const deadline = Date.now() + Number(options.timeoutMs ?? 5_000);
+      while (Date.now() < deadline) {
+        await new Promise((accept) => setTimeout(accept, 100));
+        const observed = await health(url, 400);
+        if (observed && Number(observed.pid) === Number(child.pid)) {
+          const state = { schema: 'ewai.team-hub-service-state/v1', pid: child.pid, host, port, url, tokenEnv, publisherTokenEnv: publisherTokenEnv || null, startedAt: observed.startedAt };
+          writeState(paths.state, state);
+          return { status: 'running', started: true, ...state };
+        }
+        if (child.exitCode !== null) break;
+      }
+    }
+  } finally { closeSync(log); }
+  throw new Error(`Unable to start Team Hub. Review the service log under the configured data root.`);
+}
+
+export async function stopTeamHub(options = {}) {
+  const paths = servicePaths(options.dataRoot);
+  const current = await teamHubStatus({ dataRoot: paths.root });
+  if (current.status !== 'running') {
+    rmSync(paths.state, { force: true });
+    return { schema: 'ewai.team-hub-service-status/v1', status: 'stopped', stopped: false };
+  }
+  try { process.kill(Number(current.state.pid), 'SIGTERM'); }
+  catch (error) { if (error.code !== 'ESRCH') throw error; }
+  const deadline = Date.now() + 3_000;
+  while (Date.now() < deadline && await health(current.state.url, 250)) await new Promise((accept) => setTimeout(accept, 100));
+  rmSync(paths.state, { force: true });
+  return { schema: 'ewai.team-hub-service-status/v1', status: 'stopped', stopped: true };
+}