@adaas/a-frame 0.1.1 → 0.1.2

package/examples/structure/main.ts

@@ -0,0 +1,195 @@
+/**
+ * Interactive Architecture Planner
+ *
+ * Translates natural-language requirements into a typed software architecture.
+ *
+ * Flow:
+ *   1. [generate] — the AI reads your requirements and guesses which containers,
+ *                   components, fragments and entities are needed, with a "role"
+ *                   explaining why each element was included.
+ *   2. [map]      — each guess is matched to the closest registered class via
+ *                   cosine similarity.  Unmatched elements go to the AI with the
+ *                   top-K candidates; the AI selects the best fit or suggests an
+ *                   alternative description that is then re-searched locally.
+ *   3. [patch]    — interactive refinement loop: type instructions to evolve the
+ *                   architecture, each patch re-runs the mapping step.
+ *
+ * Usage:
+ *   npx ts-node examples/structure/main.ts
+ *   npx ts-node examples/structure/main.ts "build a multi-tenant SaaS API"
+ *
+ * All diagnostic details go to .logs/<timestamp>_<goal>.log
+ */
+
+import { A_Concept, A_Container, A_Error } from '@adaas/a-concept';
+import { A_Frame } from '@adaas/a-frame/core';
+import { A_FrameIndex } from '@adaas/a-frame/index';
+import { A_FrameDynamicStructure } from '@adaas/a-frame/dynamic-structure';
+import { config } from 'dotenv';
+import { createInterface } from 'readline';
+import { FileLogger } from '../logger';
+import { SERVER_APP_COMPONENTS } from './server-app.components';
+import { S, c, renderWelcome, renderGuesses, renderStructure, renderRaw, renderHelp } from './renderer';
+
+config();
+
+const MIN_SCORE      = 0.6;
+const CANDIDATE_COUNT = 5;   // top-K candidates sent to AI on each unmatched-element retry
+
+async function main(): Promise<void> {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q: string): Promise<string> => new Promise(res => rl.question(q, res));
+
+    renderWelcome(SERVER_APP_COMPONENTS.length);
+
+    const presetGoal = process.argv[2]?.trim();
+    const goal = presetGoal
+        ? (console.log(c(`  Goal: ${presetGoal}`, S.bcyan)), presetGoal)
+        : (await ask(c('  Describe the server application you want to build:\n  ▸ ', S.bcyan))).trim();
+    if (!goal) { console.log('  No goal given.'); rl.close(); return; }
+
+    const log = new FileLogger(goal);
+
+    // ── Framework setup ───────────────────────────────────────────────────────
+    console.log(c('\n  Setting up framework…', S.dim));
+    const container = new A_Container({ name: 'ServerAppWorkspace', components: SERVER_APP_COMPONENTS });
+    const concept = new A_Concept({
+        name: 'ArchitecturePlanner',
+        components: [A_Frame],
+        containers: [container],
+    });
+    await concept.load();
+
+    const index = concept.scope.resolve(A_FrameIndex)!;
+    const defs = index.listDefinitions({});
+    const unembedded = defs.filter(d => !d.isEmbed);
+
+    console.log(c(`  Embedding ${unembedded.length} definitions…`, S.dim));
+    await Promise.all(unembedded.map(d => d.embed()));
+
+    log.info('Setup complete', {
+        components: SERVER_APP_COMPONENTS.length,
+        indexed: defs.length,
+        embedded: index.listDefinitions({}).filter(d => d.isEmbed).length,
+    });
+
+    // ── Create & register DynamicStructure ────────────────────────────────────
+    const structure = new A_FrameDynamicStructure({
+        prompt: goal,
+        options: {
+            minScore:       MIN_SCORE,
+            candidateCount: CANDIDATE_COUNT,
+        },
+    });
+    container.scope.register(structure);
+
+    // ── Generate ──────────────────────────────────────────────────────────────
+    console.log(c('  Generating architecture guesses…', S.dim));
+    const t0 = Date.now();
+    await structure.generate();
+    const def0 = structure.definition;
+    log.info('Generated', {
+        containers: def0?.containers.length ?? 0,
+        components: def0?.components.length ?? 0,
+        fragments:  def0?.fragments.length  ?? 0,
+        entities:   def0?.entities.length   ?? 0,
+        ms: Date.now() - t0,
+    });
+    if (def0) {
+        const total = def0.containers.length + def0.components.length
+            + def0.fragments.length + def0.entities.length;
+        console.log(c(`  ✓ ${total} elements guessed — ${def0.containers.length} containers, ${def0.components.length} components, ${def0.fragments.length} fragments, ${def0.entities.length} entities`, S.dim));        renderGuesses(def0);    }
+
+    // ── Map ───────────────────────────────────────────────────────────────────
+    console.log(c('  Mapping guesses to registered classes…', S.dim));
+    const t1 = Date.now();
+    await structure.map();
+    const res = structure.mapResult;
+    const allMapped = res
+        ? [...res.containers, ...res.containers.flatMap(ct => [...ct.components, ...ct.fragments, ...ct.entities]),
+           ...res.components, ...res.fragments, ...res.entities]
+        : [];
+    const matchedCount = allMapped.filter(e => e.matchedClass !== null).length;
+    log.info('Mapped', { total: allMapped.length, matched: matchedCount, ms: Date.now() - t1 });
+    console.log(c(`  ✓ ${matchedCount}/${allMapped.length} elements matched`, S.dim));
+
+    let revision = 0;
+    renderStructure(structure, revision);
+    renderHelp();
+
+    // ── Interactive patch loop ────────────────────────────────────────────────
+    while (true) {
+        const input = (await ask(c('  ▸ ', S.yellow))).trim();
+        if (!input) continue;
+
+        const cmd = input.toLowerCase();
+
+        if (cmd === 'done' || cmd === 'exit' || cmd === 'quit') {
+            const def = structure.definition;
+            const total = (def?.containers.length ?? 0) + (def?.components.length ?? 0)
+                + (def?.fragments.length ?? 0) + (def?.entities.length ?? 0);
+            console.log(c(`\n  ✓ Final architecture: "${goal}"`, S.green));
+            console.log(c(`    ${def?.containers.length ?? 0} containers  ·  ${total} elements total  ·  ${revision} revision(s)`, S.dim));
+            console.log(c(`  ✓ Log: ${log.path}\n`, S.dim));
+            break;
+        }
+
+        if (cmd === 'redraw') { renderStructure(structure, revision); continue; }
+
+        if (cmd === 'raw') { renderRaw(structure); continue; }
+
+        if (cmd === 'remap') {
+            console.log(c('  Re-mapping guesses to classes…', S.dim));
+            const rt = Date.now();
+            await structure.map();
+            const remapRes = structure.mapResult;
+            const remapAll = remapRes
+                ? [...remapRes.containers, ...remapRes.containers.flatMap(ct => [...ct.components, ...ct.fragments, ...ct.entities]),
+                   ...remapRes.components, ...remapRes.fragments, ...remapRes.entities]
+                : [];
+            const remapMatched = remapAll.filter(e => e.matchedClass !== null).length;
+            log.info('Remapped', { total: remapAll.length, matched: remapMatched, ms: Date.now() - rt });
+            renderStructure(structure, revision);
+            console.log(c(`  ✓ Re-mapped: ${remapMatched}/${remapAll.length} matched\n`, S.dim));
+            continue;
+        }
+
+        // ── Patch ─────────────────────────────────────────────────────────────
+        log.header('PATCH REQUEST', { input, revision: revision + 1 });
+        console.log(c('  Applying patch…', S.dim));
+
+        try {
+            const pt = Date.now();
+            await structure.patch(input);
+            log.info('Patched', {
+                version: structure.version,
+                containers: structure.definition?.containers.length ?? 0,
+                components: structure.definition?.components.length ?? 0,
+                ms: Date.now() - pt,
+            });
+
+            console.log(c('  Re-mapping after patch…', S.dim));
+            const mt = Date.now();
+            await structure.map();
+            log.info('Mapped after patch', { ms: Date.now() - mt });
+
+            revision++;
+            renderStructure(structure, revision);
+            console.log(c(`  ✓ Revision ${revision} applied\n`, S.green));
+        } catch (err) {
+            const msg = err instanceof A_Error ? err.description : (err as Error).message;
+            console.log(c(`\n  ✗ Patch failed: ${msg}\n`, S.red));
+            log.error('Patch failed', { message: msg });
+        }
+    }
+
+    rl.close();
+}
+
+main().catch(err => {
+    console.error(
+        c('\n  Fatal error\n', S.red, S.bold),
+        err instanceof A_Error ? err.description : (err as Error).message,
+    );
+    process.exit(1);
+});

package/examples/structure/renderer.ts

@@ -0,0 +1,296 @@
+/**
+ * Terminal renderer for the Architecture Planner example.
+ *
+ * Owns all ANSI colours, layout constants, text-wrapping, and every
+ * console.log call that draws the architecture on screen.  Nothing here
+ * knows about the A-Frame workflow — it only knows how to display it.
+ */
+
+import type {
+    A_FrameDynamicStructureDefinition,
+    A_FrameDynamicStructureDefinitionEntity,
+} from '@adaas/a-frame/dynamic-structure';
+import { A_FrameDynamicStructure } from '@adaas/a-frame/dynamic-structure';
+
+// ─── ANSI colour palette ──────────────────────────────────────────────────────
+
+const ESC = '\x1b[';
+export const S = {
+    reset:   `${ESC}0m`,
+    bold:    `${ESC}1m`,
+    dim:     `${ESC}2m`,
+    italic:  `${ESC}3m`,
+    cyan:    `${ESC}36m`,
+    bcyan:   `${ESC}96m`,
+    green:   `${ESC}32m`,
+    bgreen:  `${ESC}92m`,
+    yellow:  `${ESC}33m`,
+    byellow: `${ESC}93m`,
+    blue:    `${ESC}34m`,
+    bblue:   `${ESC}94m`,
+    magenta: `${ESC}35m`,
+    red:     `${ESC}31m`,
+    gray:    `${ESC}90m`,
+    white:   `${ESC}37m`,
+};
+
+/** Apply one or more ANSI style codes to a string, then reset. */
+export const c = (s: string, ...st: string[]): string => st.join('') + s + S.reset;
+
+export const CLEAR = '\x1b[2J\x1b[H';
+
+// ─── Text layout ──────────────────────────────────────────────────────────────
+
+export function wrap(text: string, w = 68): string[] {
+    const words = text.split(/\s+/);
+    const lines: string[] = [];
+    let line = '';
+    for (const word of words) {
+        const next = line ? `${line} ${word}` : word;
+        if (next.length > w) { if (line) lines.push(line); line = word; } else line = next;
+    }
+    if (line) lines.push(line);
+    return lines;
+}
+
+// ─── Element model ────────────────────────────────────────────────────────────
+
+export type ElementWithMatch = {
+    prompt: string;
+    /** Why this element was guessed — the requirement or concern it satisfies. */
+    role?: string;
+    class?: string;
+    matchedClass: string | null;
+    matchScore: number;
+    matchError?: { title: string; description: string } | null;
+};
+
+export function asMatchEntry(el: A_FrameDynamicStructureDefinitionEntity): ElementWithMatch {
+    return { ...el, matchedClass: null, matchScore: 0 };
+}
+
+// ─── Element / section renderers ─────────────────────────────────────────────
+
+export function renderElement(el: ElementWithMatch, indent = '    '): void {
+    const matched  = el.matchedClass !== null;
+    const errored  = !matched && el.matchError;
+    const scoreStr = matched
+        ? c(`[${el.matchScore.toFixed(3)}]`, el.matchScore >= 0.75 ? S.bgreen : S.yellow)
+        : errored
+            ? c('[✗]', S.red)
+            : c('[?]', S.gray);
+    const nameStr  = matched
+        ? c(el.matchedClass!, S.bgreen, S.bold)
+        : errored
+            ? c(el.class ?? '(unmatched)', S.red)
+            : c(el.class ?? '(unmapped)', S.gray);
+
+    console.log(`${indent}${scoreStr} ${nameStr}`);
+    for (const line of wrap(el.prompt, 62)) {
+        console.log(c(`${indent}  ${line}`, S.dim));
+    }
+    if (el.role) {
+        console.log(c(`${indent}  ↳ ${el.role}`, S.blue));
+    }
+    if (errored) {
+        console.log(c(`${indent}  ✗ ${el.matchError!.description.slice(0, 72)}`, S.red));
+    }
+}
+
+export function renderSection(label: string, items: ElementWithMatch[], indent = '  '): void {
+    if (!items.length) return;
+    console.log(c(`\n${indent}${label}`, S.bold, S.yellow));
+    console.log(c(`${indent}${'─'.repeat(64)}`, S.gray));
+    for (const el of items) renderElement(el, indent + '  ');
+}
+
+// ─── Guess view (pre-map) ─────────────────────────────────────────────────────
+
+/** Print a single raw guess element (no match score yet, just prompt + role). */
+function renderGuessElement(
+    el: A_FrameDynamicStructureDefinitionEntity,
+    indent = '    ',
+): void {
+    console.log(c(`${indent}▸ ${el.class ?? '?'}`, S.bcyan));
+    for (const line of wrap(el.prompt, 62)) {
+        console.log(c(`${indent}  ${line}`, S.dim));
+    }
+    if ((el as any).role) {
+        console.log(c(`${indent}  ↳ ${(el as any).role}`, S.blue));
+    }
+}
+
+/**
+ * Print the raw guesses returned by `generate()` — before any mapping.
+ * Shows containers (+ their nested elements) then cross-cutting groups.
+ */
+export function renderGuesses(def: A_FrameDynamicStructureDefinition): void {
+    const total = def.containers.length + def.components.length
+        + def.fragments.length + def.entities.length;
+
+    console.log(c('\n' + '━'.repeat(72), S.gray));
+    console.log(c(`  ╸ AI guesses  ·  ${total} top-level elements`, S.dim));
+    console.log(c('━'.repeat(72), S.gray));
+
+    if (def.containers.length) {
+        console.log(c('\n  CONTAINERS', S.bold, S.yellow));
+        console.log(c('  ' + '─'.repeat(68), S.gray));
+        for (const ct of def.containers) {
+            console.log();
+            renderGuessElement(ct, '  ');
+            if (ct.components?.length) {
+                console.log(c('    components', S.bold, S.yellow));
+                for (const el of ct.components) renderGuessElement(el, '      ');
+            }
+            if (ct.fragments?.length) {
+                console.log(c('    fragments', S.bold, S.yellow));
+                for (const el of ct.fragments) renderGuessElement(el, '      ');
+            }
+            if (ct.entities?.length) {
+                console.log(c('    entities', S.bold, S.yellow));
+                for (const el of ct.entities) renderGuessElement(el, '      ');
+            }
+        }
+    }
+
+    if (def.components.length) {
+        console.log(c('\n  COMPONENTS', S.bold, S.yellow));
+        console.log(c('  ' + '─'.repeat(68), S.gray));
+        for (const el of def.components) renderGuessElement(el);
+    }
+    if (def.fragments.length) {
+        console.log(c('\n  FRAGMENTS', S.bold, S.yellow));
+        console.log(c('  ' + '─'.repeat(68), S.gray));
+        for (const el of def.fragments) renderGuessElement(el);
+    }
+    if (def.entities.length) {
+        console.log(c('\n  ENTITIES', S.bold, S.yellow));
+        console.log(c('  ' + '─'.repeat(68), S.gray));
+        for (const el of def.entities) renderGuessElement(el);
+    }
+
+    console.log(c('\n' + '━'.repeat(72), S.gray));
+    console.log();
+}
+
+// ─── Full architecture view ───────────────────────────────────────────────────
+
+export function renderStructure(structure: A_FrameDynamicStructure, revision: number): void {
+    process.stdout.write(CLEAR);
+
+    const def    = structure.definition;
+    const result = structure.mapResult;
+
+    if (!def) {
+        console.log(c('  (no architecture generated yet)', S.dim));
+        return;
+    }
+
+    const totalElements =
+        def.containers.length +
+        def.containers.reduce((n, ct) => n + ct.components.length + ct.fragments.length + ct.entities.length, 0) +
+        def.components.length + def.fragments.length + def.entities.length;
+
+    // Header
+    const revLabel = revision === 0 ? 'initial design' : `revision ${revision}`;
+    console.log(c(`\n  ╸ ${revLabel}  ·  v${structure.version}  ·  ${totalElements} elements`, S.dim));
+    console.log(c('━'.repeat(72), S.gray));
+    console.log(c(`\n  Architecture: ${structure.prompt}`, S.bold, S.bcyan));
+
+    // Containers
+    const containers = result?.containers ?? def.containers.map(ct => ({
+        ...asMatchEntry(ct),
+        components: ct.components.map(asMatchEntry),
+        fragments:  ct.fragments.map(asMatchEntry),
+        entities:   ct.entities.map(asMatchEntry),
+    }));
+
+    if (containers.length) {
+        console.log(c(`\n  CONTAINERS`, S.bold, S.yellow));
+        console.log(c('  ' + '─'.repeat(68), S.gray));
+
+        for (const ct of containers) {
+            const matched  = ct.matchedClass !== null;
+            const scoreStr = matched
+                ? c(`[${ct.matchScore.toFixed(3)}]`, ct.matchScore >= 0.75 ? S.bgreen : S.yellow)
+                : c('[?]', S.gray);
+            const nameStr  = matched
+                ? c(ct.matchedClass!, S.bcyan, S.bold)
+                : c(ct.class ?? '(unmapped)', S.gray);
+
+            console.log(`\n  ${scoreStr} ${nameStr}`);
+            for (const line of wrap(ct.prompt, 66)) {
+                console.log(c(`    ${line}`, S.dim));
+            }
+
+            const ctComponents = (ct as any).components as ElementWithMatch[] ?? [];
+            const ctFragments  = (ct as any).fragments  as ElementWithMatch[] ?? [];
+            const ctEntities   = (ct as any).entities   as ElementWithMatch[] ?? [];
+
+            renderSection('components', ctComponents, '    ');
+            renderSection('fragments',  ctFragments,  '    ');
+            renderSection('entities',   ctEntities,   '    ');
+        }
+    }
+
+    // Cross-cutting elements
+    const components = result?.components ?? def.components.map(asMatchEntry);
+    const fragments  = result?.fragments  ?? def.fragments.map(asMatchEntry);
+    const entities   = result?.entities   ?? def.entities.map(asMatchEntry);
+
+    renderSection('COMPONENTS', components);
+    renderSection('FRAGMENTS',  fragments);
+    renderSection('ENTITIES',   entities);
+
+    // Stats
+    if (result) {
+        const allEntries: ElementWithMatch[] = [
+            ...result.containers,
+            ...result.containers.flatMap(ct => [...ct.components, ...ct.fragments, ...ct.entities]),
+            ...result.components,
+            ...result.fragments,
+            ...result.entities,
+        ];
+        const matched = allEntries.filter(e => e.matchedClass !== null).length;
+        console.log(c(`\n  ╸ ${matched}/${allEntries.length} elements matched`, S.dim));
+    }
+
+    console.log(c('\n' + '━'.repeat(72), S.gray));
+}
+
+// ─── Raw JSON view ────────────────────────────────────────────────────────────
+
+export function renderRaw(structure: A_FrameDynamicStructure): void {
+    process.stdout.write(CLEAR);
+    console.log(c('  ╸ raw structure JSON\n', S.dim));
+    const lines = structure.structure.split('\n');
+    for (const line of lines.slice(0, 80)) console.log(c(`  ${line}`, S.gray));
+    if (lines.length > 80) console.log(c(`  … (${lines.length - 80} more lines)`, S.dim));
+}
+
+// ─── Welcome banner ───────────────────────────────────────────────────────────
+
+export function renderWelcome(componentCount: number): void {
+    process.stdout.write(CLEAR);
+    console.log(c('\n  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓', S.bcyan));
+    console.log(c('  ┃', S.bcyan) + c('   Architecture Planner                            ', S.bold) + c('┃', S.bcyan));
+    console.log(c('  ┃', S.bcyan) + c('   Generate guesses → Map to classes → Patch       ', S.dim) + c('┃', S.bcyan));
+    console.log(c('  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛', S.bcyan));
+    console.log(c(`\n  Domain: Node.js server application (${componentCount} registered classes)`, S.dim));
+    console.log(c('  The AI will guess which containers, components, fragments and entities', S.dim));
+    console.log(c('  are needed, then map each guess to the closest registered class.', S.dim));
+    console.log(c('  e.g. "build a REST API with JWT auth and scheduled digest emails"', S.dim));
+    console.log(c('       "create a multi-tenant SaaS backend with file uploads"', S.dim));
+    console.log(c('       "design a WebSocket notification service with rate limiting"\n', S.dim));
+}
+
+// ─── Commands help ────────────────────────────────────────────────────────────
+
+export function renderHelp(): void {
+    console.log(c('  Commands:', S.dim));
+    console.log(c('    Type a patch instruction  ("add a WebSocket notification layer")', S.dim));
+    console.log(c('    "remap"  — re-run class matching without regenerating', S.dim));
+    console.log(c('    "redraw" — redraw the current architecture', S.dim));
+    console.log(c('    "raw"    — show the raw structure JSON', S.dim));
+    console.log(c('    "done"   — exit\n', S.dim));
+}