@thebackstoryis/engineering-with-ai 0.2.9

package/src/persona-website-provider.mjs

@@ -0,0 +1,134 @@
+import { hostname, homedir } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { readPersonaLicence, personaLicencePath, personaInstallationSecret, writePrivatePersonaJson } from './persona-licence-config.mjs';
+import { MAX_PERSONA_ZIP_BYTES } from './persona-zip.mjs';
+
+export const DEFAULT_PERSONA_SERVER = 'https://www.conversationalcoding.dev';
+const api = '/wp-json/conversational-coding/v1/persona-pack';
+const semanticVersion = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const safeId = v => typeof v === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(v);
+const messages = {
+  invalid_licence_key: 'That licence key could not be verified. Check the key in My Account and try again.',
+  invalid_licence: 'That licence key could not be verified. Check the key in My Account and try again.',
+  installation_limit_reached: 'This licence is already active on three machines. Deactivate a machine in My Account, then try again.',
+  subscription_expired: 'This subscription has expired. Installed individual personas remain usable, but updates have ended.',
+  subscription_inactive: 'This subscription is not currently available. Check My Account.',
+  invalid_activation: 'This machine activation could not be verified. Configure the licence again.',
+};
+export function personaServer(value = DEFAULT_PERSONA_SERVER) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error('Persona server must be a safe HTTPS origin'); }
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('Persona server must be a safe HTTPS origin');
+  // Explicit alternative origins are for independently approved self-hosted deployments.
+  return url.origin;
+}
+export function parsePersonaRelease(release) {
+  if (!release || release.schema !== 'ewai.persona-pack/v1' || release.id !== 'ewai.personas.professional'
+    || !semanticVersion.test(release.version) || !/^[a-f0-9]{64}$/.test(release.artefact?.sha256)
+    || !Number.isSafeInteger(release.artefact.size) || release.artefact.size < 22 || release.artefact.size > MAX_PERSONA_ZIP_BYTES) throw new Error('The persona release contract could not be verified');
+  return { version: release.version, sha256: release.artefact.sha256, size: release.artefact.size };
+}
+export function parsePersonaSubscription(data) {
+  if (!data || !safeId(data.id) || !['individual', 'team'].includes(data.plan_type)
+    || !['active', 'grace', 'cancelled', 'expired', 'pending', 'revoked', 'refunded'].includes(data.status)
+    || typeof data.ends_at !== 'string' || !Number.isFinite(Date.parse(data.ends_at))) throw new Error('The persona subscription contract could not be verified');
+  return { id: data.id, planType: data.plan_type, status: data.status, endsAt: new Date(data.ends_at).toISOString() };
+}
+
+async function request(url, options, limit, context) {
+  const signal = AbortSignal.timeout(context.timeout ?? 8000);
+  let rejectAbort;
+  const aborted = new Promise((_, reject) => {
+    rejectAbort = () => reject(new Error('timeout'));
+    signal.addEventListener('abort', rejectAbort, { once: true });
+  });
+  // Keep a deadline alive even for a test/custom transport with no socket.
+  const deadline = setTimeout(rejectAbort, context.timeout ?? 8000);
+  try {
+    const response = await Promise.race([(context.fetchImpl ?? fetch)(url, { ...options, redirect: 'error', signal }), aborted]);
+    if (response.redirected) throw new Error('redirect');
+    const length = response.headers.get('content-length');
+    if (length && (!/^\d+$/.test(length) || Number(length) > limit)) throw new Error('size');
+    const reader = response.body?.getReader(); if (!reader) throw new Error('empty');
+    const chunks = []; let size = 0;
+    try {
+      for (;;) {
+        const part = await Promise.race([reader.read(), aborted]);
+        if (part.done) break;
+        size += part.value.byteLength; if (size > limit) throw new Error('size');
+        chunks.push(Buffer.from(part.value));
+      }
+    } finally { void reader.cancel().catch(() => {}); }
+    return { response, bytes: Buffer.concat(chunks, size) };
+  } catch { throw new Error('Persona access could not be checked safely. Check your connection and try again; installed content has not been removed.'); }
+  finally { clearTimeout(deadline); signal.removeEventListener('abort', rejectAbort); }
+}
+async function jsonRequest(url, options, context) {
+  const { response, bytes } = await request(url, options, 64 * 1024, context);
+  let body;
+  try { body = JSON.parse(bytes.toString('utf8')); } catch { throw new Error('The persona service returned an unsupported response. Installed content has not been removed.'); }
+  if (!response.ok) {
+    const code = Object.hasOwn(messages, body?.code) ? body.code : 'provider-access-unknown';
+    const error = new Error(messages[code] || 'Persona access could not be verified. Installed content has not been removed.');
+    error.code = code; throw error;
+  }
+  return body;
+}
+const packageVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const version = options => options.clientVersion || packageVersion;
+const headers = token => ({ Accept: 'application/json', ...(token ? { Authorization: 'Bearer ' + token } : {}) });
+
+export async function configurePersonaLicence(options = {}) {
+  const home = options.home ?? homedir(), server = personaServer(options.server);
+  const prior = readPersonaLicence(home);
+  const licenceKey = String(options.licenceKey ?? '').trim();
+  if (!licenceKey || licenceKey.length > 512 || /[\x00-\x1f\x7f]/.test(licenceKey)) throw new Error('Enter a valid licence key using the private terminal prompt');
+  const installationSecret = personaInstallationSecret(home);
+  const machineName = String(options.machineName ?? hostname()).trim();
+  if (!machineName || machineName.length > 120 || /[\x00-\x1f\x7f]/.test(machineName)) throw new Error('Machine name must be a short readable label');
+  const data = await jsonRequest(server + api + '/activations', {
+    method: 'POST', headers: { ...headers(), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ licence_key: licenceKey, installation_secret: installationSecret, machine_name: machineName, product: 'engineering-with-ai', client_version: version(options) }),
+  }, options);
+  if (data.schema !== 'cce.activation/v1' || !safeId(data.activation_id) || typeof data.activation_token !== 'string'
+    || data.activation_token.length < 16 || data.activation_token.length > 512 || /[\x00-\x20\x7f]/.test(data.activation_token)) throw new Error('Machine activation returned an unsupported contract; existing credentials were kept');
+  // Older server activations can be stored, but cannot prove plan-specific expiry.
+  const subscription = data.subscription ? parsePersonaSubscription(data.subscription) : null;
+  const seatId = safeId(data.seat_id) ? data.seat_id : null;
+  writePrivatePersonaJson(home, personaLicencePath(home), {
+    schema: 'ewai.persona-licence/v1', server, licenceKey, installationSecret,
+    activationId: data.activation_id, activationToken: data.activation_token, seatId, subscription, machineName,
+  });
+  return { schema: 'ewai.persona-licence-setup/v1', status: 'configured', provider: 'wordpress-edd', replaced: Boolean(prior), machineLimit: 3 };
+}
+
+export async function websitePersonaStatus(credentials, options = {}) {
+  const server = personaServer(credentials.server);
+  const data = await jsonRequest(server + api + '/status?product=engineering-with-ai&client_version=' + encodeURIComponent(version(options)), { headers: headers(credentials.activationToken) }, options);
+  if (data.schema !== 'cce.entitlement-status/v1' || !['available', 'unavailable'].includes(data.access)
+    || !safeId(data.seat?.id) || data.activation?.id !== credentials.activationId) throw new Error('The persona status contract could not be verified; installed content has not been removed');
+  const subscription = parsePersonaSubscription(data.subscription);
+  if (credentials.seatId && credentials.seatId !== data.seat.id) throw new Error('The licensed seat changed unexpectedly; configure the licence again');
+  if (data.access === 'available' && (!['active', 'grace', 'cancelled'].includes(subscription.status) || Date.parse(subscription.endsAt) <= Date.now())) throw new Error('The persona status contract is inconsistent');
+  if (subscription.status === 'expired' && (data.access !== 'unavailable' || Date.parse(subscription.endsAt) > Date.now())) throw new Error('The persona expiry contract is inconsistent');
+  return { access: data.access, subscription, seatId: data.seat.id, server, release: data.access === 'available' ? parsePersonaRelease(data.release) : null };
+}
+
+export async function acquireWebsitePersonaArchive(credentials, status, options = {}) {
+  if (status.access !== 'available') throw new Error('Persona updates are unavailable for this subscription');
+  const server = personaServer(credentials.server);
+  const grant = await jsonRequest(server + api + '/download-grants', {
+    method: 'POST', headers: { ...headers(credentials.activationToken), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ product: 'engineering-with-ai', client_version: version(options) }),
+  }, options);
+  let url; try { url = new URL(grant.download_url); } catch { throw new Error('The persona download grant is invalid'); }
+  const release = parsePersonaRelease(grant.release);
+  if (grant.schema !== 'cce.download-grant/v1' || url.origin !== server || url.username || url.password || url.hash
+    || url.pathname !== '/' || [...url.searchParams.keys()].some(k => k !== 'cce-download')
+    || !url.searchParams.get('cce-download') || url.searchParams.getAll('cce-download').length !== 1
+    || !Number.isFinite(Date.parse(grant.expires_at)) || Date.parse(grant.expires_at) <= Date.now()
+    || release.sha256 !== status.release.sha256 || release.version !== status.release.version || release.size !== status.release.size) throw new Error('The persona download grant could not be verified; check for updates and retry');
+  const { response, bytes } = await request(url.href, { headers: { Accept: 'application/zip' } }, MAX_PERSONA_ZIP_BYTES, options);
+  if (!response.ok) throw new Error('The short-lived persona download could not be completed; request a fresh download');
+  return bytes;
+}

package/src/persona-zip.mjs

@@ -0,0 +1,87 @@
+import { inflateRawSync } from 'node:zlib';
+import { existsSync, lstatSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+const MAX_FILES = 1000, MAX_FILE = 1024 * 1024, MAX_TOTAL = 16 * 1024 * 1024;
+export const MAX_PERSONA_ZIP_BYTES = 20 * 1024 * 1024;
+const crcTable = Array.from({ length: 256 }, (_, i) => {
+  let c = i; for (let j = 0; j < 8; j++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+export function crc32(bytes) {
+  let c = 0xffffffff; for (const b of bytes) c = crcTable[(c ^ b) & 255] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+function range(bytes, start, size) {
+  if (!Number.isSafeInteger(start) || start < 0 || size < 0 || start + size > bytes.length) throw new Error('Malformed persona ZIP bounds');
+  return bytes.subarray(start, start + size);
+}
+function safeName(raw) {
+  let name;
+  try { name = new TextDecoder('utf-8', { fatal: true }).decode(raw); }
+  catch { throw new Error('Persona ZIP path is not UTF-8'); }
+  if (!name || name.length > 512 || /[\\:\x00-\x1f\x7f]/.test(name) || name.startsWith('/')) throw new Error('Unsafe persona ZIP path');
+  const directory = name.endsWith('/'), parts = (directory ? name.slice(0, -1) : name).split('/');
+  if (parts.some(p => !p || p === '.' || p === '..' || p.startsWith('.') || /[. ]$/.test(p)
+    || /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/i.test(p))) throw new Error('Unsafe persona ZIP path');
+  if (!directory && !/\.(md|markdown|txt|yaml|yml|json|csv)$/i.test(name)
+    && !/^(license|notice|readme)$/i.test(parts.at(-1))) throw new Error('Persona ZIP file type is not allowed');
+  return { name, directory };
+}
+
+// Deliberately supports the small release format, not arbitrary ZIP/ZIP64 files.
+export function extractPersonaZip(input, destination) {
+  const bytes = Buffer.from(input);
+  if (bytes.length < 22 || bytes.length > MAX_PERSONA_ZIP_BYTES) throw new Error('Persona ZIP exceeds archive bounds');
+  if (!existsSync(destination) || !lstatSync(destination).isDirectory() || lstatSync(destination).isSymbolicLink() || readdirSync(destination).length) throw new Error('Persona ZIP requires an empty private staging directory');
+  let end = -1;
+  for (let i = bytes.length - 22; i >= Math.max(0, bytes.length - 65557); i--) {
+    if (bytes.readUInt32LE(i) === 0x06054b50 && i + 22 + bytes.readUInt16LE(i + 20) === bytes.length) { end = i; break; }
+  }
+  if (end < 0) throw new Error('Malformed persona ZIP directory');
+  const count = bytes.readUInt16LE(end + 10), size = bytes.readUInt32LE(end + 12), start = bytes.readUInt32LE(end + 16);
+  if (bytes.readUInt16LE(end + 4) || bytes.readUInt16LE(end + 6) || count !== bytes.readUInt16LE(end + 8)
+    || count === 0 || count > MAX_FILES || count === 65535 || start + size !== end) throw new Error('Unsupported persona ZIP directory');
+  const entries = [], names = new Map(); let position = start, total = 0, lastEnd = 0;
+  for (let i = 0; i < count; i++) {
+    const c = range(bytes, position, 46);
+    if (c.readUInt32LE(0) !== 0x02014b50) throw new Error('Malformed persona ZIP entry');
+    const flags = c.readUInt16LE(8), method = c.readUInt16LE(10), compressed = c.readUInt32LE(20), uncompressed = c.readUInt32LE(24);
+    const n = c.readUInt16LE(28), extra = c.readUInt16LE(30), comment = c.readUInt16LE(32), offset = c.readUInt32LE(42);
+    const raw = range(bytes, position + 46, n), path = safeName(raw), mode = c.readUInt32LE(38) >>> 16, type = mode & 0xf000;
+    range(bytes, position, 46 + n + extra + comment);
+    if ((flags & ~0x80e) || method !== 8 && (flags & 6) || ![0, 8].includes(method) || c.readUInt16LE(34)
+      || uncompressed > MAX_FILE || compressed > MAX_PERSONA_ZIP_BYTES || (type && type !== (path.directory ? 0x4000 : 0x8000))
+      || (mode & 0o111) && !path.directory) throw new Error('Unsupported or unsafe persona ZIP entry');
+    total += uncompressed; if (total > MAX_TOTAL) throw new Error('Persona ZIP exceeds total content size');
+    const normalized = path.name.replace(/\/$/, '').toLowerCase();
+    if (names.has(normalized)) throw new Error('Duplicate persona ZIP path');
+    names.set(normalized, path.directory);
+    const h = range(bytes, offset, 30);
+    if (offset < lastEnd || h.readUInt32LE(0) !== 0x04034b50 || h.readUInt16LE(6) !== flags || h.readUInt16LE(8) !== method
+      || h.readUInt16LE(26) !== n || !range(bytes, offset + 30, n).equals(raw)) throw new Error('Malformed persona ZIP local entry');
+    const dataStart = offset + 30 + n + h.readUInt16LE(28), dataEnd = dataStart + compressed;
+    if (dataEnd > start || dataStart < offset + 30) throw new Error('Malformed persona ZIP data bounds');
+    const data = range(bytes, dataStart, compressed);
+    let body;
+    try { body = method === 0 ? Buffer.from(data) : inflateRawSync(data, { maxOutputLength: MAX_FILE }); }
+    catch { throw new Error('Persona ZIP inflation failed or exceeded bounds'); }
+    if (body.length !== uncompressed || crc32(body) !== c.readUInt32LE(16)) throw new Error('Persona ZIP CRC or size mismatch');
+    if (path.directory && body.length) throw new Error('Persona ZIP directory contains data');
+    if (!(flags & 8) && (h.readUInt32LE(14) !== c.readUInt32LE(16) || h.readUInt32LE(18) !== compressed || h.readUInt32LE(22) !== uncompressed)) throw new Error('Malformed persona ZIP header');
+    lastEnd = dataEnd;
+    entries.push({ ...path, body }); position += 46 + n + extra + comment;
+  }
+  if (position !== end) throw new Error('Malformed persona ZIP directory length');
+  for (const e of entries) {
+    const parts = e.name.replace(/\/$/, '').toLowerCase().split('/');
+    for (let i = 1; i < parts.length; i++) if (names.get(parts.slice(0, i).join('/')) === false) throw new Error('Conflicting persona ZIP paths');
+  }
+  // Validate every entry before writing any content.
+  for (const e of entries) {
+    const path = resolve(destination, e.name);
+    if (e.directory) mkdirSync(path, { recursive: true, mode: 0o700 });
+    else { mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); writeFileSync(path, e.body, { flag: 'wx', mode: 0o600 }); }
+  }
+  return { fileCount: entries.filter(e => !e.directory).length, totalBytes: total };
+}

package/src/personas.mjs

@@ -0,0 +1,159 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, extname, resolve } from 'node:path';
+import YAML from 'yaml';
+import { projectPaths } from './paths.mjs';
+
+const personaSlugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const personaRefPattern = /^[a-z0-9][a-z0-9._-]*$/;
+
+export function validatePersonaRef(value) {
+  const reference = String(value ?? '').trim();
+  if (!personaRefPattern.test(reference)) throw new Error(`Invalid persona reference: ${reference}`);
+  return reference;
+}
+
+function findMarkdown(root) {
+  if (!existsSync(root)) return [];
+  const found = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const path = resolve(root, entry.name);
+    if (entry.isDirectory()) found.push(...findMarkdown(path));
+    if (entry.isFile() && extname(entry.name).toLowerCase() === '.md') found.push(path);
+  }
+  return found;
+}
+
+export function readPersona(path) {
+  const content = readFileSync(path, 'utf8');
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  let metadata = {};
+  let parseStatus = 'none';
+  if (match) {
+    try {
+      metadata = YAML.parse(match[1]) ?? {};
+      parseStatus = 'parsed';
+    } catch {
+      const legacyName = match[1].match(/^name:\s*(.+)$/m)?.[1]?.trim();
+      metadata = legacyName ? { name: legacyName } : {};
+      parseStatus = 'legacy-fallback';
+    }
+  }
+  const name = metadata?.name || basename(path, extname(path));
+  const id = validatePersonaRef(metadata?.id || name);
+  const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').replace(/^#\s+.+\r?\n+/, '');
+  const summary = body.split(/\r?\n\s*\r?\n/).find((paragraph) => paragraph.trim() && !paragraph.trim().startsWith('#')) ?? '';
+  return {
+    id,
+    name,
+    description: metadata?.description || summary.replace(/[`*_>#\[\]]/g, '').replace(/\s+/g, ' ').trim().slice(0, 240),
+    category: metadata?.category || '',
+    pack: metadata?.pack || '',
+    tier: metadata?.tier || '',
+    version: metadata?.version || '',
+    tags: metadata?.tags || [],
+    capabilities: metadata?.capabilities || [],
+    parseStatus,
+    path
+  };
+}
+
+export function listPersonas(roots, query = '') {
+  const normalizedQuery = query.trim().toLowerCase();
+  const unique = new Map();
+
+  for (const root of roots) {
+    for (const path of findMarkdown(root)) {
+      let persona;
+      try {
+        persona = readPersona(path);
+      } catch {
+        continue;
+      }
+      const key = `${persona.id}:${path}`;
+      if (!normalizedQuery || JSON.stringify(persona).toLowerCase().includes(normalizedQuery)) {
+        unique.set(key, persona);
+      }
+    }
+  }
+
+  return [...unique.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export function indexPersonas(roots, query = '') {
+  return listPersonas(roots, query).map((persona) => ({
+    id: persona.id,
+    name: persona.name,
+    description: persona.description,
+    category: persona.category,
+    tier: persona.tier,
+    tags: persona.tags,
+    capabilities: persona.capabilities,
+    path: persona.path
+  }));
+}
+
+export function personalPersonaRoot(home = homedir()) {
+  return resolve(home, '.ewai/personas');
+}
+
+export function projectPersonaRoot(projectRoot) {
+  if (!projectRoot) throw new Error('A project root is required for project personas');
+  return resolve(projectPaths(projectRoot).personaRoot, 'project');
+}
+
+export function personaLibraryRoot(scope, options = {}) {
+  if (scope === 'personal') return personalPersonaRoot(options.home);
+  if (scope === 'project') return projectPersonaRoot(options.projectRoot);
+  throw new Error(`Unsupported persona scope: ${scope}`);
+}
+
+function personaName(slug) {
+  return slug
+    .split('-')
+    .map((part) => `${part[0].toUpperCase()}${part.slice(1)}`)
+    .join(' ');
+}
+
+function personaTemplate({ scope, slug, name, category }) {
+  const metadata = {
+    schema: 'ewai.persona/v1',
+    id: `${scope}.${slug}`,
+    name,
+    version: '0.1.0',
+    description: `A ${scope} persona for ${name}.`,
+    category,
+    pack: `ewai.personas.${scope}`,
+    tier: scope,
+    tags: [],
+    capabilities: []
+  };
+
+  return `---\n${YAML.stringify(metadata, { lineWidth: 0 }).trim()}\n---\n\n# ${name}\n\n## Mission\n\nDescribe the outcome this persona cares about and the perspective it brings.\n\n## Operating stance\n\n- Describe how this persona approaches decisions.\n- Record the standards, evidence, or experience it should use.\n- Make uncertainty and assumptions explicit.\n\n## Questions to keep asking\n\n- What would this persona need to know?\n- What risks or opportunities would it notice?\n- What evidence would satisfy it?\n\n## Boundaries\n\n- This persona advises; it does not replace real stakeholders or grant authority.\n- Evidence from real people takes priority over simulated feedback.\n`;
+}
+
+export function createPersona(options = {}) {
+  const scope = options.scope || 'personal';
+  const slug = options.slug?.trim() || '';
+  if (!personaSlugPattern.test(slug)) {
+    throw new Error('Persona slug must use lowercase letters, numbers, and single hyphens');
+  }
+
+  const root = personaLibraryRoot(scope, options);
+  const path = resolve(root, `${slug}.md`);
+  if (existsSync(path) && !options.force) {
+    throw new Error(`Persona already exists: ${path}`);
+  }
+
+  const name = options.name?.trim() || personaName(slug);
+  const category = options.category?.trim() || 'general';
+  mkdirSync(root, { recursive: true });
+  writeFileSync(path, personaTemplate({ scope, slug, name, category }), 'utf8');
+
+  return {
+    schema: 'ewai.persona-create-result/v1',
+    id: `${scope}.${slug}`,
+    scope,
+    path
+  };
+}