amalfa 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/package.json +1 -1
  2. package/src/cli.ts +1 -1
  3. package/docs/AGENT-METADATA-PATTERNS.md +0 -1021
  4. package/docs/AGENT_PROTOCOLS.md +0 -28
  5. package/docs/ARCHITECTURAL_OVERVIEW.md +0 -123
  6. package/docs/BENTO_BOXING_DEPRECATION.md +0 -281
  7. package/docs/Bun-SQLite.html +0 -464
  8. package/docs/COMMIT_GUIDELINES.md +0 -367
  9. package/docs/CONFIG_E2E_VALIDATION.md +0 -147
  10. package/docs/CONFIG_UNIFICATION.md +0 -187
  11. package/docs/CONFIG_VALIDATION.md +0 -103
  12. package/docs/DEVELOPER_ONBOARDING.md +0 -36
  13. package/docs/Graph and Vector Database Best Practices.md +0 -214
  14. package/docs/LEGACY_DEPRECATION.md +0 -174
  15. package/docs/MCP_SETUP.md +0 -317
  16. package/docs/PERFORMANCE_BASELINES.md +0 -88
  17. package/docs/QUICK_START_MCP.md +0 -168
  18. package/docs/REPOSITORY_CLEANUP_SUMMARY.md +0 -261
  19. package/docs/SESSION-2026-01-06-METADATA-PATTERNS.md +0 -346
  20. package/docs/SETUP.md +0 -464
  21. package/docs/SETUP_COMPLETE.md +0 -464
  22. package/docs/VISION-AGENT-LEARNING.md +0 -1242
  23. package/docs/_current-config-status.md +0 -93
  24. package/docs/edge-generation-methods.md +0 -57
  25. package/docs/elevator-pitch.md +0 -118
  26. package/docs/graph-and-vector-database-playbook.html +0 -480
  27. package/docs/hardened-sqlite.md +0 -85
  28. package/docs/headless-knowledge-management.md +0 -79
  29. package/docs/john-kaye-flux-prompt.md +0 -46
  30. package/docs/keyboard-shortcuts.md +0 -80
  31. package/docs/opinion-proceed-pattern.md +0 -29
  32. package/docs/polyvis-nodes-edges-schema.md +0 -77
  33. package/docs/protocols/lab-protocol.md +0 -30
  34. package/docs/reaction-iquest-loop-coder.md +0 -46
  35. package/docs/services.md +0 -60
  36. package/docs/sqlite-wal-readonly-trap.md +0 -228
  37. package/docs/strategy/css-architecture.md +0 -40
  38. package/docs/test-document-cycle.md +0 -83
  39. package/docs/test_lifecycle_E2E.md +0 -4
  40. package/docs/the-bicameral-graph.md +0 -83
  41. package/docs/user-guide.md +0 -70
  42. package/docs/vision-helper.md +0 -53
package/docs/Bun-SQLite.html DELETED
@@ -1,464 +0,0 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8">
5
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>Resonance: Technical Research Report</title>
7
- <script src="https://cdn.tailwindcss.com"></script>
8
- <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
9
- <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;800&display=swap" rel="stylesheet">
10
- <style>
11
- /* * COLOR PALETTE: Neon Tech (Based on "Energetic & Playful/Brilliant Blues")
12
- * Background: #0F172A (Slate 900)
13
- * Surface: #1E293B (Slate 800)
14
- * Primary: #4F46E5 (Indigo 600) -> Used for headers, accents
15
- * Secondary: #06B6D4 (Cyan 500) -> Used for data points, highlights
16
- * Accent: #F43F5E (Rose 500) -> Used for alerts, critical stats
17
- * Text: #F8FAFC (Slate 50)
18
- */
19
-
20
- body {
21
- font-family: 'Inter', sans-serif;
22
- background-color: #0F172A;
23
- color: #F8FAFC;
24
- }
25
-
26
- .card {
27
- background-color: #1E293B;
28
- border: 1px solid #334155;
29
- transition: transform 0.2s ease, box-shadow 0.2s ease;
30
- }
31
-
32
- .card:hover {
33
- transform: translateY(-2px);
34
- box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
35
- border-color: #4F46E5;
36
- }
37
-
38
- .gradient-text {
39
- background: linear-gradient(135deg, #22d3ee 0%, #818cf8 100%);
40
- -webkit-background-clip: text;
41
- -webkit-text-fill-color: transparent;
42
- }
43
-
44
- /* Chart Container Styling - Responsive & Constrained */
45
- .chart-container {
46
- position: relative;
47
- width: 100%;
48
- max-width: 600px; /* Max width constraint */
49
- margin-left: auto;
50
- margin-right: auto;
51
- height: 300px; /* Base height */
52
- max-height: 400px;
53
- }
54
-
55
- @media (min-width: 768px) {
56
- .chart-container {
57
- height: 350px;
58
- }
59
- }
60
-
61
- /* Custom Flowchart Nodes */
62
- .flow-node {
63
- background: #1E293B;
64
- border: 2px solid #06B6D4;
65
- padding: 1rem;
66
- border-radius: 0.5rem;
67
- text-align: center;
68
- position: relative;
69
- font-weight: 600;
70
- }
71
-
72
- .flow-arrow {
73
- display: flex;
74
- align-items: center;
75
- justify-content: center;
76
- color: #64748B;
77
- font-size: 1.5rem;
78
- font-weight: bold;
79
- }
80
- </style>
81
- <!--
82
- PLAN NARRATIVE & STRUCTURE:
83
- 1. Header: Title and context setup (Bun + SQLite + Embeddings).
84
- 2. Executive Summary: The immediate answer/recommendation.
85
- 3. Challenge Analysis: Visualizing why the native stack fails (Bun limitations).
86
- 4. Stack Comparison (Radar Chart): Comparing Native, LibSQL, and Custom builds.
87
- 5. Embedding Strategy (Bar Chart): Analyzing size/performance of embedding options.
88
- 6. Architecture Diagram (CSS Flow): Visualizing the final recommended data pipeline.
89
- 7. Detailed Findings: Textual deep dive into specific technical solutions.
90
-
91
- VISUALIZATION CHOICES (NO SVG, NO MERMAID):
92
- - Stack Comparison -> Radar Chart (Chart.js): Best for multi-variable comparison (Stability, Ease, Features).
93
- - Embedding Size -> Bar Chart (Chart.js): Best for comparing quantitative values (MB).
94
- - Pipeline -> CSS Grid/Flexbox Diagram: Best for structural organization without SVG.
95
- -->
96
- </head>
97
- <body class="p-4 md:p-8">
98
-
99
- <!-- Header Section -->
100
- <header class="max-w-6xl mx-auto mb-12 text-center">
101
- <div class="inline-block px-3 py-1 mb-4 text-xs font-semibold tracking-wider text-cyan-400 uppercase bg-slate-800 rounded-full border border-cyan-900">
102
- Technical Research Report
103
- </div>
104
- <h1 class="text-4xl md:text-6xl font-extrabold mb-4 tracking-tight">
105
- Project <span class="gradient-text">Resonance</span>
106
- </h1>
107
- <p class="text-slate-400 text-lg md:text-xl max-w-2xl mx-auto">
108
- Architecting a Single-Binary Local-First CLI with Bun, SQLite, and Vector Search on macOS.
109
- </p>
110
- </header>
111
-
112
- <main class="max-w-6xl mx-auto grid grid-cols-1 md:grid-cols-12 gap-8">
113
-
114
- <!-- Executive Summary (Inform) -->
115
- <section class="md:col-span-12 bg-gradient-to-r from-indigo-900/50 to-slate-900 border border-indigo-500/30 rounded-xl p-8 shadow-lg">
116
- <h2 class="text-2xl font-bold mb-4 text-white flex items-center">
117
- <span class="text-cyan-400 mr-2">➜</span> Executive Verdict
118
- </h2>
119
- <p class="text-slate-300 mb-6 leading-relaxed">
120
- Building a single-binary CLI on macOS with Bun is feasible, but the "Pure Native" path is currently blocked by Bun's static SQLite compilation.
121
- The most robust path <strong>today</strong> is adopting the <strong>Turso/LibSQL</strong> ecosystem for the database layer and <strong>ONNX Runtime</strong> for embeddings.
122
- </p>
123
- <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
124
- <div class="bg-slate-800/80 p-4 rounded-lg border-l-4 border-cyan-500">
125
- <h3 class="font-bold text-cyan-400 mb-1">Database</h3>
126
- <p class="text-sm text-slate-300">Use <strong>LibSQL (local mode)</strong>. It bypasses Bun's extension limits and includes vector search natively.</p>
127
- </div>
128
- <div class="bg-slate-800/80 p-4 rounded-lg border-l-4 border-indigo-500">
129
- <h3 class="font-bold text-indigo-400 mb-1">Embeddings</h3>
130
- <p class="text-sm text-slate-300">Use <strong>Transformers.js</strong> with <code class="bg-slate-900 px-1 rounded">sharp</code> disabled, or direct <strong>ONNX Runtime</strong>.</p>
131
- </div>
132
- <div class="bg-slate-800/80 p-4 rounded-lg border-l-4 border-pink-500">
133
- <h3 class="font-bold text-pink-400 mb-1">Compilation</h3>
134
- <p class="text-sm text-slate-300">Use <strong>Bun Compile</strong>. Configure asset loading for the `.wasm` or `.node` bindings.</p>
135
- </div>
136
- </div>
137
- </section>
138
-
139
- <!-- Stack Comparison Chart (Compare) -->
140
- <section class="md:col-span-6 card rounded-xl p-6 flex flex-col">
141
- <h3 class="text-xl font-bold mb-2 text-indigo-300">Architecture Trade-off Matrix</h3>
142
- <p class="text-sm text-slate-400 mb-6">
143
- Comparing three potential stacks for stability, ease of bundling, and vector capabilities on macOS.
144
- </p>
145
- <div class="chart-container flex-grow">
146
- <canvas id="stackRadarChart"></canvas>
147
- </div>
148
- <div class="mt-4 text-xs text-slate-500 text-center">
149
- Score 0-10 (Higher is Better) • Source: Technical Investigation
150
- </div>
151
- </section>
152
-
153
- <!-- The "Why it Fails" Diagram (Organize) -->
154
- <section class="md:col-span-6 card rounded-xl p-6">
155
- <h3 class="text-xl font-bold mb-2 text-pink-400">The "Bun Native" Blockers</h3>
156
- <p class="text-sm text-slate-400 mb-6">
157
- Why standard libraries fail in a single-binary Bun environment on macOS.
158
- </p>
159
-
160
- <div class="flex flex-col gap-4 h-full justify-center pb-8">
161
- <!-- Step 1 -->
162
- <div class="flex items-center gap-4">
163
- <div class="w-12 h-12 rounded-full bg-slate-700 flex items-center justify-center text-xl font-bold text-white">1</div>
164
- <div class="bg-slate-800 border border-slate-600 p-3 rounded w-full">
165
- <div class="font-bold text-indigo-400">bun:sqlite</div>
166
- <div class="text-xs text-slate-300">Statically linked. No `loadExtension` symbol exported on macOS.</div>
167
- </div>
168
- </div>
169
- <!-- Arrow -->
170
- <div class="flex justify-center -my-2">
171
- <span class="text-slate-600 text-2xl">⬇</span>
172
- </div>
173
- <!-- Step 2 -->
174
- <div class="flex items-center gap-4">
175
- <div class="w-12 h-12 rounded-full bg-slate-700 flex items-center justify-center text-xl font-bold text-white">2</div>
176
- <div class="bg-slate-800 border border-slate-600 p-3 rounded w-full">
177
- <div class="font-bold text-pink-400">better-sqlite3</div>
178
- <div class="text-xs text-slate-300">Native Module (`.node`). Often fails DLOPEN in bundled context.</div>
179
- </div>
180
- </div>
181
- <!-- Arrow -->
182
- <div class="flex justify-center -my-2">
183
- <span class="text-slate-600 text-2xl">⬇</span>
184
- </div>
185
- <!-- Step 3 -->
186
- <div class="flex items-center gap-4">
187
- <div class="w-12 h-12 rounded-full bg-slate-700 flex items-center justify-center text-xl font-bold text-white">3</div>
188
- <div class="bg-slate-800 border border-slate-600 p-3 rounded w-full">
189
- <div class="font-bold text-cyan-400">@xenova/transformers</div>
190
- <div class="text-xs text-slate-300">Tries to load `sharp` for image resizing, breaking text-only builds.</div>
191
- </div>
192
- </div>
193
- </div>
194
- </section>
195
-
196
- <!-- Detailed Findings: Database -->
197
- <section class="md:col-span-12 lg:col-span-8 card rounded-xl p-6">
198
- <h3 class="text-xl font-bold mb-4 text-white">Research Focus: Database Layer</h3>
199
- <div class="space-y-4">
200
- <div class="bg-slate-900/50 p-4 rounded border-l-2 border-indigo-500">
201
- <h4 class="font-bold text-indigo-300">1. Bun & Extensions</h4>
202
- <p class="text-sm text-slate-400 mt-1">
203
- `bun:sqlite` is compiled with `SQLITE_OMIT_LOAD_EXTENSION` on some platforms or simply doesn't expose the C-API required for dynamic loading. While you can technically use `bun:ffi` to load a custom `libsqlite3.dylib`, this defeats the purpose of using the built-in standard library and complicates the single-binary build process significantly.
204
- </p>
205
- </div>
206
- <div class="bg-slate-900/50 p-4 rounded border-l-2 border-cyan-500">
207
- <h4 class="font-bold text-cyan-300">2. The Turso / LibSQL Advantage</h4>
208
- <p class="text-sm text-slate-400 mt-1">
209
- LibSQL is a fork of SQLite that includes vector search features out of the box. By using `@libsql/client` with a `file:` url, you are bypassing Bun's internal SQLite entirely. The client uses a NAPI or Wasm binding that includes the vector logic. This is currently the most reliable way to get Vector Search + Local DB + JS Runtime.
210
- </p>
211
- </div>
212
- </div>
213
- </section>
214
-
215
- <!-- Binary Size / Embeddings Chart (Compare) -->
216
- <section class="md:col-span-12 lg:col-span-4 card rounded-xl p-6 flex flex-col">
217
- <h3 class="text-xl font-bold mb-2 text-cyan-300">Embedding Overhead</h3>
218
- <p class="text-sm text-slate-400 mb-6">
219
- Estimated impact on final binary size for different embedding strategies.
220
- </p>
221
- <div class="chart-container flex-grow">
222
- <canvas id="embeddingsChart"></canvas>
223
- </div>
224
- <div class="mt-4 text-xs text-slate-500">
225
- *Estimated sizes. Pure JS is smallest but slowest. ONNX offers best balance.
226
- </div>
227
- </section>
228
-
229
- <!-- Proposed Architecture Flow (Organize) -->
230
- <section class="md:col-span-12 card rounded-xl p-8 bg-slate-900 border border-slate-700">
231
- <h3 class="text-2xl font-bold mb-6 text-center text-white">Recommended "Resonance" Architecture</h3>
232
-
233
- <div class="grid grid-cols-1 md:grid-cols-5 gap-4 items-center">
234
-
235
- <!-- Input -->
236
- <div class="flow-node">
237
- <div class="text-2xl mb-2">💻</div>
238
- <div class="text-slate-200">CLI User Input</div>
239
- </div>
240
-
241
- <!-- Arrow -->
242
- <div class="flow-arrow hidden md:flex">➜</div>
243
- <div class="flow-arrow md:hidden">⬇</div>
244
-
245
- <!-- Embeddings -->
246
- <div class="flow-node border-pink-500">
247
- <div class="text-xs text-pink-400 uppercase tracking-widest mb-1">Vectorization</div>
248
- <div class="font-bold text-white">Transformers.js</div>
249
- <div class="text-xs text-slate-400 mt-1">Model: all-MiniLM-L6-v2<br>(Quantized)</div>
250
- </div>
251
-
252
- <!-- Arrow -->
253
- <div class="flow-arrow hidden md:flex">➜</div>
254
- <div class="flow-arrow md:hidden">⬇</div>
255
-
256
- <!-- Database -->
257
- <div class="flow-node border-indigo-500">
258
- <div class="text-xs text-indigo-400 uppercase tracking-widest mb-1">Storage</div>
259
- <div class="font-bold text-white">LibSQL Local</div>
260
- <div class="text-xs text-slate-400 mt-1">Native Vector Search<br>(File Mode)</div>
261
- </div>
262
-
263
- </div>
264
-
265
- <div class="mt-8 grid grid-cols-1 md:grid-cols-2 gap-6">
266
- <div>
267
- <h4 class="text-lg font-bold text-white mb-2">Implementation Snippet: Embeddings</h4>
268
- <pre class="bg-black p-4 rounded text-xs text-green-400 font-mono overflow-x-auto">
269
- // Fix Sharp error by mocking or exclusion
270
- import { pipeline, env } from '@xenova/transformers';
271
-
272
- // Skip local checks that trigger sharp
273
- env.allowLocalModels = false;
274
- env.useBrowserCache = false;
275
-
276
- const embedder = await pipeline(
277
- 'feature-extraction',
278
- 'Xenova/all-MiniLM-L6-v2'
279
- );
280
- </pre>
281
- </div>
282
- <div>
283
- <h4 class="text-lg font-bold text-white mb-2">Implementation Snippet: LibSQL</h4>
284
- <pre class="bg-black p-4 rounded text-xs text-cyan-400 font-mono overflow-x-auto">
285
- import { createClient } from "@libsql/client";
286
-
287
- const db = createClient({
288
- url: "file:local.db",
289
- });
290
-
291
- // Native Vector Search (LibSQL specific syntax)
292
- await db.execute(`
293
- SELECT * FROM vectors
294
- ORDER BY vector_distance_cos(embedding, ?)
295
- LIMIT 5
296
- `, [vector]);
297
- </pre>
298
- </div>
299
- </div>
300
- </section>
301
-
302
- </main>
303
-
304
- <footer class="text-center text-slate-600 py-8 text-sm">
305
- <p>Generated by Canvas Infographics AI • Focused on Modern JavaScript Tooling</p>
306
- </footer>
307
-
308
- <!-- CHART JS LOGIC -->
309
- <script>
310
- // 16-char label wrapping utility
311
- function wrapLabels(labels) {
312
- return labels.map(label => {
313
- if (label.length <= 16) return label;
314
- const words = label.split(' ');
315
- const lines = [];
316
- let currentLine = words[0];
317
-
318
- for (let i = 1; i < words.length; i++) {
319
- if ((currentLine + " " + words[i]).length > 16) {
320
- lines.push(currentLine);
321
- currentLine = words[i];
322
- } else {
323
- currentLine += " " + words[i];
324
- }
325
- }
326
- lines.push(currentLine);
327
- return lines;
328
- });
329
- }
330
-
331
- // Global Chart Defaults for "Neon Tech" theme
332
- Chart.defaults.color = '#94a3b8';
333
- Chart.defaults.font.family = "'Inter', sans-serif";
334
- Chart.defaults.scale.grid.color = '#334155';
335
-
336
- // Tooltip Configuration for Multi-line support
337
- const tooltipConfig = {
338
- callbacks: {
339
- title: (tooltipItems) => {
340
- const item = tooltipItems[0];
341
- const label = item.chart.data.labels[item.dataIndex];
342
- if (Array.isArray(label)) {
343
- return label.join(' ');
344
- } else {
345
- return label;
346
- }
347
- }
348
- }
349
- };
350
-
351
- // --- CHART 1: Architecture Comparison (Radar) ---
352
- const ctxRadar = document.getElementById('stackRadarChart').getContext('2d');
353
- const radarLabels = wrapLabels([
354
- 'Vector Capabilities',
355
- 'Build Stability',
356
- 'Performance',
357
- 'Bun Compatibility',
358
- 'Ease of Setup'
359
- ]);
360
-
361
- new Chart(ctxRadar, {
362
- type: 'radar',
363
- data: {
364
- labels: radarLabels,
365
- datasets: [
366
- {
367
- label: 'Recommended: LibSQL',
368
- data: [9, 9, 8, 9, 8],
369
- backgroundColor: 'rgba(6, 182, 212, 0.2)', // Cyan transparent
370
- borderColor: '#06B6D4',
371
- pointBackgroundColor: '#06B6D4',
372
- borderWidth: 2
373
- },
374
- {
375
- label: 'Pure Bun Native',
376
- data: [2, 8, 9, 10, 5],
377
- backgroundColor: 'rgba(244, 63, 94, 0.2)', // Pink transparent
378
- borderColor: '#F43F5E',
379
- pointBackgroundColor: '#F43F5E',
380
- borderWidth: 2
381
- },
382
- {
383
- label: 'Better-SQLite3',
384
- data: [5, 4, 7, 3, 4],
385
- backgroundColor: 'rgba(99, 102, 241, 0.2)', // Indigo transparent
386
- borderColor: '#6366F1',
387
- pointBackgroundColor: '#6366F1',
388
- borderWidth: 2
389
- }
390
- ]
391
- },
392
- options: {
393
- maintainAspectRatio: false,
394
- scales: {
395
- r: {
396
- angleLines: { color: '#334155' },
397
- grid: { color: '#334155' },
398
- pointLabels: {
399
- color: '#F8FAFC',
400
- font: { size: 12, weight: 'bold' }
401
- },
402
- ticks: { display: false, backdropColor: 'transparent' },
403
- suggestedMin: 0,
404
- suggestedMax: 10
405
- }
406
- },
407
- plugins: {
408
- legend: {
409
- labels: { color: '#F8FAFC' }
410
- },
411
- tooltip: tooltipConfig
412
- }
413
- }
414
- });
415
-
416
- // --- CHART 2: Embeddings Binary Size (Bar) ---
417
- const ctxBar = document.getElementById('embeddingsChart').getContext('2d');
418
- const barLabels = wrapLabels([
419
- 'Pure JS (Custom)',
420
- 'ONNX Runtime Node',
421
- 'Transformers.js (Optimized)',
422
- 'Python Sidecar (Avoid)'
423
- ]);
424
-
425
- new Chart(ctxBar, {
426
- type: 'bar',
427
- data: {
428
- labels: barLabels,
429
- datasets: [{
430
- label: 'Est. Added Binary Size (MB)',
431
- data: [2, 15, 25, 120],
432
- backgroundColor: [
433
- '#10B981', // Emerald (Custom JS)
434
- '#06B6D4', // Cyan (ONNX - Good)
435
- '#6366F1', // Indigo (Transformers - OK)
436
- '#F43F5E' // Pink (Python - Bad)
437
- ],
438
- borderWidth: 0,
439
- borderRadius: 4
440
- }]
441
- },
442
- options: {
443
- maintainAspectRatio: false,
444
- indexAxis: 'y', // Horizontal Bar for better label reading
445
- scales: {
446
- x: {
447
- grid: { display: false },
448
- ticks: { color: '#94a3b8' }
449
- },
450
- y: {
451
- grid: { display: false },
452
- ticks: { color: '#F8FAFC', font: { weight: '600' } }
453
- }
454
- },
455
- plugins: {
456
- legend: { display: false },
457
- tooltip: tooltipConfig
458
- }
459
- }
460
- });
461
-
462
- </script>
463
- </body>
464
- </html>