@adaas/a-frame 0.1.1 → 0.1.2

package/examples/feature/file-system.components.ts

@@ -0,0 +1,211 @@
+/**
+ * File-system domain components.
+ *
+ * All classes below are registered under the "file-system" namespace so the
+ * A_FrameIndex can scope searches and the mapper can resolve workflow steps to
+ * concrete service methods via cosine similarity.
+ */
+
+import { A_Component, A_Fragment } from '@adaas/a-concept';
+import { A_Frame } from '@adaas/a-frame/core';
+
+export const FILE_SYSTEM_NAMESPACE = 'file-system';
+
+// ─── Reader ───────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: FILE_SYSTEM_NAMESPACE,
+    description: 'A service component for reading files and listing directory contents. Handles reading file content, listing directory entries, and checking whether a path exists.',
+})
+export class FileReaderService extends A_Component {
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Reads the entire content of a file at the given path and returns it as a string. Throws if the path does not exist or is not readable.',
+    })
+    readFile(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Lists all entries (files and sub-directories) inside the given directory. Returns an array of names. Optionally recurses into sub-directories.',
+    })
+    listDirectory(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Checks whether a file or directory exists at the given path. Returns true if it exists, false otherwise. Does not throw on missing paths.',
+    })
+    exists(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Reads and parses a JSON file at the given path, returning the parsed object. Throws a parse error if the file content is not valid JSON.',
+    })
+    readJson(): void {}
+}
+
+// ─── Writer ───────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: FILE_SYSTEM_NAMESPACE,
+    description: 'A service component for writing, appending, and creating files. Handles writing new content, appending to existing files, and creating directories.',
+})
+export class FileWriterService extends A_Component {
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Writes the given string content to a file at the specified path. Creates the file if it does not exist; overwrites it if it does.',
+    })
+    writeFile(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Appends a string to the end of an existing file without erasing its current content. Creates the file if it does not exist.',
+    })
+    appendToFile(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Creates a new empty directory at the given path, including any missing parent directories. Is a no-op if the directory already exists.',
+    })
+    createDirectory(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Writes a JavaScript object to a file as formatted JSON. Pretty-prints with 2-space indentation. Creates or overwrites the file.',
+    })
+    writeJson(): void {}
+}
+
+// ─── Move / Copy / Delete ─────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: FILE_SYSTEM_NAMESPACE,
+    description: 'A service component for moving, copying, renaming, and deleting files and directories on disk.',
+})
+export class FileMoveService extends A_Component {
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Copies a file from the source path to the destination path. Overwrites the destination if it already exists. Does not copy directories.',
+    })
+    copyFile(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Moves a file or directory from the source path to the destination path. Equivalent to a rename when staying on the same filesystem.',
+    })
+    moveFile(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Deletes a file at the given path permanently. Throws if the path does not exist or refers to a directory.',
+    })
+    deleteFile(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Deletes a directory and all its contents recursively. Use with caution — this is irreversible.',
+    })
+    deleteDirectory(): void {}
+}
+
+// ─── Search ───────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: FILE_SYSTEM_NAMESPACE,
+    description: 'A service component for searching file contents and file-system paths. Supports glob patterns, regex content search, and text-string search.',
+})
+export class FileSearchService extends A_Component {
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Finds all file paths under a root directory that match the given glob pattern (e.g. "**/*.ts"). Returns an array of matching absolute paths.',
+    })
+    findByGlob(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Searches the content of all files under a directory for lines matching a regular expression. Returns an array of { file, line, match } objects.',
+    })
+    searchInFiles(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Returns the paths of all files in a directory that were modified after the given timestamp. Useful for incremental processing.',
+    })
+    findModifiedAfter(): void {}
+}
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: FILE_SYSTEM_NAMESPACE,
+    description: 'A service component for reading and writing file metadata: permissions, timestamps, size, MIME type, and extended attributes.',
+})
+export class FileMetaService extends A_Component {
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Returns the size in bytes, creation time, modification time, and file type (file vs directory) for the given path.',
+    })
+    getStats(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Sets the POSIX read/write/execute permissions on a file using an octal mode string (e.g. "0644").',
+    })
+    setPermissions(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Renames a file in-place within the same directory, updating only the file name portion of the path.',
+    })
+    renameFile(): void {}
+}
+
+// ─── Archive ──────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: FILE_SYSTEM_NAMESPACE,
+    description: 'A service component for archiving and compressing files. Creates zip archives, extracts archives, and computes checksums.',
+})
+export class FileArchiveService extends A_Component {
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Creates a zip archive at the output path containing all files matched by the given source paths or glob patterns.',
+    })
+    createZip(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Extracts the contents of a zip archive to the given destination directory. Overwrites existing files by default.',
+    })
+    extractZip(): void {}
+
+    @A_Frame.Define({
+        namespace: FILE_SYSTEM_NAMESPACE,
+        description: 'Computes and returns the MD5 or SHA-256 checksum of a file at the given path. Useful for integrity verification.',
+    })
+    checksum(): void {}
+}
+
+// ─── Context fragment ─────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: FILE_SYSTEM_NAMESPACE,
+    description: 'A fragment that carries the root working directory, active glob filters, dry-run flag, and per-step results throughout a file-operation workflow.',
+})
+export class FileOperationContext extends A_Fragment {}
+
+// ─── Convenience array of all service components ──────────────────────────────
+
+export const FS_COMPONENTS = [
+    FileReaderService,
+    FileWriterService,
+    FileMoveService,
+    FileSearchService,
+    FileMetaService,
+    FileArchiveService,
+];

package/examples/feature/main.ts

@@ -0,0 +1,374 @@
+/**
+ * Interactive Feature Workflow Planner
+ *
+ * Plan and refine an executable workflow from natural language.
+ * The framework generates an ordered sequence of steps, maps each step to a
+ * real registered method on a service component, and shows the full plan in the
+ * terminal.  You can then apply natural-language patches to refine the plan.
+ *
+ * Domain: file-system operations (create, read, write, move, search files, etc.)
+ *
+ * Usage:
+ *   npx ts-node examples/feature/main.ts
+ *
+ * Flow:
+ *   1. You enter a goal ("copy all .ts files to a backup folder")
+ *   2. The AI generates a step-by-step workflow and maps each step to a method
+ *   3. The full plan is rendered — title, description, every step with class +
+ *      method + score, plus the supporting components / entities
+ *   4. You type a patch instruction ("add a step to compress the backup") or a
+ *      command ("remap", "raw", "done")
+ *   5. The plan is updated and re-rendered
+ *   6. Repeat until satisfied
+ *
+ * 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_FrameDynamicFeature } from '@adaas/a-frame/dynamic-feature';
+import { config } from 'dotenv';
+import { createInterface } from 'readline';
+import { FileLogger } from '../logger';
+import { FS_COMPONENTS } from './file-system.components';
+
+config();
+// process.env.A_FRAME_SYNC = 'false';
+
+const MIN_SCORE = 0.6;
+
+// ─── Terminal colours ─────────────────────────────────────────────────────────
+
+const ESC = '\x1b[';
+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`,
+};
+const c = (s: string, ...st: string[]) => st.join('') + s + S.reset;
+const CLEAR = '\x1b[2J\x1b[H';
+
+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;
+}
+
+// ─── Rendering helpers ────────────────────────────────────────────────────────
+
+function renderWorkflow(feature: A_FrameDynamicFeature, revision: number): void {
+    process.stdout.write(CLEAR);
+
+    const def    = feature.definition;
+    const result = feature.mapResult;
+
+    if (!def) {
+        console.log(c('  (no workflow generated yet)', S.dim));
+        return;
+    }
+
+    // ── Header ───────────────────────────────────────────────────────────────
+    const revLabel = revision === 0 ? 'initial plan' : `revision ${revision}`;
+    console.log(c(`\n  ╸ ${revLabel}  ·  v${feature.version}  ·  ${def.steps.length} steps`, S.dim));
+    console.log(c('━'.repeat(72), S.gray));
+
+    // ── Title & Description ───────────────────────────────────────────────────
+    console.log(c(`\n  ${def.title}`, S.bold, S.bcyan));
+    for (const line of wrap(def.description)) {
+        console.log(c(`  ${line}`, S.dim));
+    }
+
+    // ── Steps ─────────────────────────────────────────────────────────────────
+    console.log(c(`\n  STEPS`, S.bold, S.yellow));
+    console.log(c('  ' + '─'.repeat(68), S.gray));
+
+    const steps = result?.steps ?? def.steps.map(s => ({
+        prompt: s.prompt,
+        inputs: s.inputs, outputs: s.outputs,
+        matchedClass: null, matchedMethod: null, matchScore: 0, matchError: null,
+    }));
+
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        const num  = c(`  ${String(i + 1).padStart(2)}.`, S.bold, S.gray);
+
+        if (result) {
+            // Mapped view
+            const matched = step.matchedMethod !== null;
+            const errored = !matched && (step as any).matchError;
+            const scoreStr = matched
+                ? c(`[${(step.matchScore).toFixed(3)}]`, step.matchScore >= 0.75 ? S.bgreen : S.yellow)
+                : errored
+                    ? c('[✗]', S.red)
+                    : c('[?]', S.gray);
+
+            const methodStr = matched
+                ? c(`${step.matchedClass}.${step.matchedMethod}`, S.bgreen, S.bold)
+                : errored
+                    ? c('unmatched', S.red)
+                    : c('unmapped', S.gray);
+
+            console.log(`${num} ${scoreStr} ${methodStr}`);
+
+            for (const line of wrap(step.prompt, 64)) {
+                console.log(c(`       ${line}`, S.dim));
+            }
+
+            if ((step as any).matchError) {
+                console.log(c(`       ↳ ${(step as any).matchError.description.slice(0, 70)}`, S.red));
+            }
+        } else {
+            // Pre-map view — steps are description-only before mapping
+            console.log(`${num}`);
+            for (const line of wrap(step.prompt, 64)) {
+                console.log(c(`       ${line}`, S.dim));
+            }
+        }
+
+        // Inputs / outputs compact summary
+        if (step.inputs?.length) {
+            const ins = step.inputs.map((p: any) => `${p.name}: ${p.type}`).join(', ');
+            console.log(c(`       ← ${ins}`, S.blue));
+        }
+        if (step.outputs?.length) {
+            const outs = step.outputs.map((p: any) => `${p.name}: ${p.type}`).join(', ');
+            console.log(c(`       → ${outs}`, S.bgreen));
+        }
+    }
+
+    // ── Supporting elements ───────────────────────────────────────────────────
+    const elements = [
+        ...(result?.components ?? def.components.map(e => ({ ...e, matchedClass: null, matchScore: 0 }))),
+        ...(result?.fragments  ?? def.fragments.map(e => ({ ...e, matchedClass: null, matchScore: 0 }))),
+        ...(result?.entities   ?? def.entities.map(e => ({ ...e, matchedClass: null, matchScore: 0 }))),
+    ];
+
+    if (elements.length) {
+        console.log(c(`\n  BUILDING BLOCKS`, S.bold, S.yellow));
+        console.log(c('  ' + '─'.repeat(68), S.gray));
+
+        for (const el of elements) {
+            const name = (el as any).matchedClass
+                ? c((el as any).matchedClass, S.bgreen, S.bold)
+                : c('(unresolved)', S.gray);
+            const score = (el as any).matchedClass
+                ? c(` [${(el.matchScore as number).toFixed(3)}]`, S.dim)
+                : '';
+            console.log(`  ${name}${score}`);
+            for (const line of wrap(el.prompt, 64)) {
+                console.log(c(`    ${line}`, S.dim));
+            }
+        }
+    }
+
+    // ── Stats ─────────────────────────────────────────────────────────────────
+    if (result) {
+        const matchedSteps  = result.steps.filter(s => s.matchedMethod !== null).length;
+        const matchedEls    = elements.filter((e: any) => e.matchedClass !== null).length;
+        console.log(c(`\n  ╸ steps ${matchedSteps}/${result.steps.length} matched  ·  elements ${matchedEls}/${elements.length} matched`, S.dim));
+    }
+
+    console.log(c('\n' + '━'.repeat(72), S.gray));
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+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));
+
+    process.stdout.write(CLEAR);
+    console.log(c('\n  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓', S.bcyan));
+    console.log(c('  ┃', S.bcyan) + c('   Feature Workflow Planner                        ', S.bold) + c('┃', S.bcyan));
+    console.log(c('  ┃', S.bcyan) + c('   Generate → Map methods → Patch → Repeat         ', S.dim) + c('┃', S.bcyan));
+    console.log(c('  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛', S.bcyan));
+    console.log(c('\n  Domain: file-system operations', S.dim));
+    console.log(c('  Services: FileReaderService, FileWriterService, FileMoveService,', S.dim));
+    console.log(c('            FileSearchService, FileMetaService, FileArchiveService\n', S.dim));
+
+    const presetGoal = process.argv[2]?.trim();
+    const goal = presetGoal
+        ? (console.log(c(`  Goal: ${presetGoal}`, S.bcyan)), presetGoal)
+        : (await ask(c('  Describe the file operation you want to automate:\n  ▸ ', S.bcyan))).trim();
+    if (!goal) { console.log('  No goal given.'); rl.close(); return; }
+
+    const log = new FileLogger(goal);
+
+    console.log(c('\n  Setting up framework…', S.dim));
+
+    // ── Framework setup ────────────────────────────────────────────────────────
+    const container = new A_Container({ name: 'FileOpsWorkspace', components: FS_COMPONENTS });
+    const concept   = new A_Concept({
+        name: 'FeatureWorkflowPlanner',
+        components: [A_Frame],
+        containers: [container],
+    });
+    await concept.load();
+
+    const index = concept.scope.resolve(A_FrameIndex)!;
+
+    // Embed all definitions (sync=false so we do it explicitly)
+    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: FS_COMPONENTS.length,
+        indexed: defs.length,
+        embedded: index.listDefinitions({}).filter(d => d.isEmbed).length,
+    });
+
+    // ── Create the DynamicFeature ──────────────────────────────────────────────
+    const feature = new A_FrameDynamicFeature({
+        prompt: goal,
+        options: { minScore: MIN_SCORE },
+    });
+    container.scope.register(feature);
+
+    // ── Generate ───────────────────────────────────────────────────────────────
+    console.log(c('  Generating workflow…', S.dim));
+    const t0 = Date.now();
+    await feature.generate();
+    log.info('Generated', {
+        title: feature.definition?.title,
+        steps: feature.definition?.steps.length ?? 0,
+        ms: Date.now() - t0,
+    });
+
+    // ── Map ────────────────────────────────────────────────────────────────────
+    console.log(c('  Mapping steps to methods…', S.dim));
+    const t1 = Date.now();
+    await feature.map();
+    log.info('Mapped', {
+        matched: feature.mapResult?.steps.filter(s => s.matchedMethod !== null).length ?? 0,
+        total:   feature.mapResult?.steps.length ?? 0,
+        ms: Date.now() - t1,
+    });
+
+    let revision = 0;
+    renderWorkflow(feature, revision);
+
+    // ── Help text ──────────────────────────────────────────────────────────────
+    console.log(c('  Commands:', S.dim));
+    console.log(c('    Type a patch instruction  ("add a compression step at the end")', S.dim));
+    console.log(c('    "remap"  — re-run method matching without regenerating', S.dim));
+    console.log(c('    "raw"    — show the raw workflow JSON', S.dim));
+    console.log(c('    "done"   — exit\n', S.dim));
+
+    // ── Interactive patch loop ─────────────────────────────────────────────────
+    while (true) {
+        const input = (await ask(c('  ▸ ', S.yellow))).trim();
+
+        if (!input) continue;
+
+        const cmd = input.toLowerCase();
+
+        // ── Exit ────────────────────────────────────────────────────────────────
+        if (cmd === 'done' || cmd === 'exit' || cmd === 'quit') {
+            console.log(c(`\n  ✓ Final workflow: "${feature.definition?.title}"`, S.green));
+            console.log(c(`    ${feature.definition?.steps.length ?? 0} steps  ·  ${revision} revision(s)`, S.dim));
+            console.log(c(`  ✓ Log: ${log.path}\n`, S.dim));
+            break;
+        }
+
+        // ── Redraw ──────────────────────────────────────────────────────────────
+        if (cmd === 'redraw') {
+            renderWorkflow(feature, revision);
+            continue;
+        }
+
+        // ── Show raw JSON ────────────────────────────────────────────────────────
+        if (cmd === 'raw') {
+            process.stdout.write(CLEAR);
+            console.log(c('  ╸ raw workflow JSON\n', S.dim));
+            const lines = feature.workflow.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));
+            continue;
+        }
+
+        // ── Re-map without regenerating ──────────────────────────────────────────
+        if (cmd === 'remap') {
+            console.log(c('  Re-mapping steps to methods…', S.dim));
+            const rt = Date.now();
+            await feature.map();
+            log.info('Remapped', {
+                matched: feature.mapResult?.steps.filter(s => s.matchedMethod !== null).length ?? 0,
+                total:   feature.mapResult?.steps.length ?? 0,
+                ms: Date.now() - rt,
+            });
+            renderWorkflow(feature, revision);
+            console.log(c('  ✓ Re-mapped\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 feature.patch(input);
+            log.info('Patched', {
+                version: feature.version,
+                steps: feature.definition?.steps.length ?? 0,
+                ms: Date.now() - pt,
+            });
+
+            console.log(c('  Re-mapping after patch…', S.dim));
+            const mt = Date.now();
+            await feature.map();
+            log.info('Mapped after patch', {
+                matched: feature.mapResult?.steps.filter(s => s.matchedMethod !== null).length ?? 0,
+                total:   feature.mapResult?.steps.length ?? 0,
+                ms: Date.now() - mt,
+            });
+
+            revision++;
+            renderWorkflow(feature, revision);
+
+            const matched = feature.mapResult?.steps.filter(s => s.matchedMethod !== null).length ?? 0;
+            const total   = feature.mapResult?.steps.length ?? 0;
+            console.log(c(`  ✓ Revision ${revision} (${matched}/${total} steps matched)\n`, S.green));
+
+        } catch (err) {
+            log.error('Patch failed', err);
+            const msg = err instanceof A_Error ? err.message : String(err);
+            console.log(c(`  ✗ Patch failed: ${msg.slice(0, 80)}`, S.red));
+            console.log(c('  Previous workflow preserved. Try a different instruction.\n', S.dim));
+        }
+    }
+
+    rl.close();
+}
+
+main().catch(err => {
+    if (err instanceof A_Error) {
+        console.error(c('\n  ✗ A_Error:', S.red), JSON.stringify(err.toJSON(), null, 2));
+    } else {
+        console.error(c('\n  ✗ Error:', S.red), err);
+    }
+    process.exit(1);
+});