@andespindola/brainlink 0.1.0-alpha.0

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security
+
+Brainlink is local-first.
+
+## Defaults
+
+- The HTTP server binds to `127.0.0.1` by default.
+- The HTTP server refuses non-loopback hosts unless `--allow-public` is passed.
+- The HTTP server is read-only and does not expose note creation, indexing or update routes.
+- The SQLite database is a derived local index.
+- Markdown files are user-owned source data.
+- Brainlink-created Markdown files use `0600` permissions.
+- Brainlink-created directories and `.brainlink` use `0700` permissions.
+
+## Remote Exposure
+
+Do not expose the HTTP server on a public interface without adding authentication, authorization and transport security.
+
+## Sensitive Memory
+
+Brainlink blocks common secret patterns by default when adding notes through the CLI.
+
+Use `--allow-sensitive` only when the vault is intentionally protected by your own storage and access controls.
+
+Avoid storing secrets, credentials, private keys, tokens or regulated personal data in a vault unless the vault is protected by your own storage and access controls.
+
+## Vault Allowlist
+
+External tool wrappers, including MCP servers, should set `BRAINLINK_ALLOWED_VAULTS` to restrict which vault paths the CLI can access.
+
+```bash
+export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
+```
+
+When the allowlist is set, CLI commands fail if `--vault` points outside the allowed roots.

package/dist/application/add-note.js

@@ -0,0 +1,30 @@
+import { writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
+import { validateNoteInput } from '../domain/note-safety.js';
+const slugify = (title) => title
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+export const addNote = async (vaultPath, title, content, agentId = sharedAgentId, options = {}) => {
+    validateNoteInput({
+        title,
+        content,
+        allowSensitive: options.allowSensitive
+    });
+    const sanitizedAgentId = sanitizeAgentId(agentId);
+    const filename = `agents/${sanitizedAgentId}/${slugify(title) || 'untitled'}.md`;
+    const note = [
+        `---`,
+        `title: "${title.replaceAll('"', '\\"')}"`,
+        `agent: "${sanitizedAgentId}"`,
+        `---`,
+        '',
+        `# ${title}`,
+        '',
+        content.trim(),
+        ''
+    ].join('\n');
+    return writeMarkdownFile(vaultPath, filename, note);
+};

package/dist/application/analyze-vault.js

@@ -0,0 +1,28 @@
+import { validateGraph, getBrokenLinks, getOrphanNodes, getVaultStats } from '../domain/graph-analysis.js';
+import { ensureVault, readMarkdownFiles } from '../infrastructure/file-system-vault.js';
+import { getGraph } from './get-graph.js';
+export const getStats = async (vaultPath, agentId) => getVaultStats(await getGraph(vaultPath, agentId));
+export const getBrokenLinksReport = async (vaultPath, agentId) => getBrokenLinks(await getGraph(vaultPath, agentId));
+export const getOrphansReport = async (vaultPath, agentId) => getOrphanNodes(await getGraph(vaultPath, agentId));
+export const validateVault = async (vaultPath, agentId) => validateGraph(await getGraph(vaultPath, agentId));
+const createCheck = (name, ok, message) => ({
+    name,
+    ok,
+    message
+});
+export const doctorVault = async (vaultPath) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const files = await readMarkdownFiles(absoluteVaultPath);
+    const graph = await getGraph(absoluteVaultPath);
+    const validation = validateGraph(graph);
+    const checks = [
+        createCheck('vault', true, `Vault ready at ${absoluteVaultPath}`),
+        createCheck('markdown-files', files.length > 0, `${files.length} markdown files found`),
+        createCheck('index', graph.nodes.length > 0, `${graph.nodes.length} indexed documents found`),
+        createCheck('broken-links', validation.brokenLinks.length === 0, `${validation.brokenLinks.length} broken links found`)
+    ];
+    return {
+        ok: checks.every((check) => check.ok),
+        checks
+    };
+};

package/dist/application/build-context.js

@@ -0,0 +1,15 @@
+import { formatContextPackage, selectContextSections } from '../domain/context.js';
+import { searchKnowledge } from './search-knowledge.js';
+export const buildContextPackage = async (vaultPath, query, limit, maxTokens, agentId, mode) => {
+    const results = await searchKnowledge(vaultPath, query, limit, agentId, mode);
+    const sections = selectContextSections(results, maxTokens);
+    return {
+        query,
+        sections,
+        content: formatContextPackage(query, sections)
+    };
+};
+export const buildContext = async (vaultPath, query, limit, maxTokens, agentId, mode) => {
+    const contextPackage = await buildContextPackage(vaultPath, query, limit, maxTokens, agentId, mode);
+    return contextPackage.content;
+};

package/dist/application/frontend/client-css.js

@@ -0,0 +1,294 @@
+export const createClientCss = () => `:root {
+  color-scheme: dark;
+  --bg: #0d0f12;
+  --panel: #15191f;
+  --panel-strong: #1c222b;
+  --line: #29313c;
+  --text: #edf2f7;
+  --muted: #99a5b5;
+  --accent: #35d0a2;
+  --accent-weak: rgba(53, 208, 162, 0.14);
+  --danger: #ff6b6b;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+button,
+input,
+select {
+  font: inherit;
+}
+
+.shell {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 360px;
+  width: 100%;
+  height: 100svh;
+  overflow: hidden;
+}
+
+.workspace {
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+}
+
+#graph {
+  display: block;
+  width: 100%;
+  height: 100%;
+  background:
+    radial-gradient(circle at 18% 20%, rgba(53, 208, 162, 0.12), transparent 28rem),
+    linear-gradient(135deg, #0d0f12 0%, #12161c 55%, #0a0d10 100%);
+  cursor: grab;
+}
+
+#graph:active {
+  cursor: grabbing;
+}
+
+.topbar {
+  position: absolute;
+  top: 18px;
+  left: 18px;
+  right: 18px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 18px;
+  pointer-events: none;
+}
+
+.topbar > div {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+}
+
+.topbar strong {
+  font-size: 18px;
+}
+
+.topbar span,
+.eyebrow,
+.inspector small {
+  color: var(--muted);
+  font-size: 12px;
+}
+
+.search {
+  width: min(420px, 42vw);
+  pointer-events: auto;
+}
+
+.agent-filter {
+  width: min(220px, 28vw);
+  pointer-events: auto;
+}
+
+.search input,
+.agent-filter select {
+  width: 100%;
+  height: 40px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  outline: none;
+  background: rgba(21, 25, 31, 0.88);
+  color: var(--text);
+  padding: 0 14px;
+}
+
+.search input:focus,
+.agent-filter select:focus {
+  border-color: var(--accent);
+}
+
+.toolbar {
+  position: absolute;
+  left: 18px;
+  bottom: 18px;
+  display: flex;
+  gap: 8px;
+}
+
+.toolbar button {
+  width: 38px;
+  height: 38px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: rgba(21, 25, 31, 0.88);
+  color: var(--text);
+  cursor: pointer;
+}
+
+.toolbar button:hover {
+  border-color: var(--accent);
+  color: var(--accent);
+}
+
+.inspector {
+  display: grid;
+  grid-template-rows: auto auto auto auto auto 1fr 1fr;
+  gap: 22px;
+  min-width: 0;
+  height: 100%;
+  padding: 24px;
+  border-left: 1px solid var(--line);
+  background: var(--panel);
+  overflow: auto;
+}
+
+.inspector h1,
+.inspector h2,
+.inspector p {
+  margin: 0;
+}
+
+.inspector h1 {
+  margin-top: 6px;
+  font-size: 26px;
+  line-height: 1.12;
+  overflow-wrap: anywhere;
+}
+
+.inspector h2 {
+  margin-bottom: 10px;
+  color: var(--muted);
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+#path {
+  margin-top: 10px;
+  color: var(--muted);
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+
+.metrics {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.metrics div {
+  display: grid;
+  gap: 4px;
+  padding: 14px;
+  background: var(--panel-strong);
+}
+
+.metrics div + div {
+  border-left: 1px solid var(--line);
+}
+
+.metrics span {
+  font-size: 22px;
+  font-weight: 700;
+}
+
+.tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.tags span {
+  max-width: 100%;
+  padding: 6px 9px;
+  border-radius: 999px;
+  background: var(--accent-weak);
+  color: var(--accent);
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+
+ul {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+li {
+  padding: 10px 0;
+  border-bottom: 1px solid var(--line);
+  color: var(--text);
+  overflow-wrap: anywhere;
+}
+
+li button {
+  width: 100%;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: var(--text);
+  text-align: left;
+  cursor: pointer;
+}
+
+li button:hover {
+  color: var(--accent);
+}
+
+li small {
+  display: block;
+  margin-top: 4px;
+}
+
+.note-content {
+  max-height: 32svh;
+  margin: 0;
+  padding: 12px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: #101419;
+  color: var(--text);
+  white-space: pre-wrap;
+  overflow: auto;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  font-size: 12px;
+  line-height: 1.5;
+}
+
+@media (max-width: 860px) {
+  .shell {
+    grid-template-columns: 1fr;
+    grid-template-rows: minmax(0, 1fr) 42svh;
+  }
+
+  .inspector {
+    border-left: 0;
+    border-top: 1px solid var(--line);
+    padding: 18px;
+  }
+
+  .topbar {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .search {
+    width: 100%;
+  }
+
+  .agent-filter {
+    width: 100%;
+  }
+}`;

package/dist/application/frontend/client-html.js

@@ -0,0 +1,66 @@
+export const createClientHtml = () => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Brainlink Graph</title>
+    <link rel="stylesheet" href="/styles.css" />
+  </head>
+  <body>
+    <main class="shell">
+      <section class="workspace" aria-label="Knowledge graph">
+        <canvas id="graph" aria-label="Brainlink knowledge graph"></canvas>
+        <div class="topbar">
+          <div>
+            <strong>Brainlink</strong>
+            <span id="stats">Loading graph</span>
+          </div>
+          <label class="search">
+            <input id="search" type="search" placeholder="Filter notes, tags or paths" autocomplete="off" />
+          </label>
+          <label class="agent-filter">
+            <select id="agent"></select>
+          </label>
+        </div>
+        <div class="toolbar" aria-label="Graph controls">
+          <button id="zoomIn" type="button" title="Zoom in">+</button>
+          <button id="zoomOut" type="button" title="Zoom out">-</button>
+          <button id="reset" type="button" title="Reset view">⌂</button>
+        </div>
+      </section>
+      <aside class="inspector" aria-label="Selected note">
+        <div>
+          <span class="eyebrow">Selected note</span>
+          <h1 id="title">Graph Overview</h1>
+          <p id="path">Select a node to inspect links and backlinks.</p>
+        </div>
+        <div class="metrics">
+          <div><span id="nodeCount">0</span><small>Notes</small></div>
+          <div><span id="edgeCount">0</span><small>Links</small></div>
+          <div><span id="tagCount">0</span><small>Tags</small></div>
+        </div>
+        <section>
+          <h2>Tags</h2>
+          <div id="tags" class="tags"></div>
+        </section>
+        <section>
+          <h2>Notes</h2>
+          <ul id="notes"></ul>
+        </section>
+        <section>
+          <h2>Content</h2>
+          <pre id="content" class="note-content"></pre>
+        </section>
+        <section>
+          <h2>Outgoing</h2>
+          <ul id="outgoing"></ul>
+        </section>
+        <section>
+          <h2>Backlinks</h2>
+          <ul id="incoming"></ul>
+        </section>
+      </aside>
+    </main>
+    <script src="/app.js"></script>
+  </body>
+</html>`;