@geminilight/mindos 0.1.0

package/app/lib/agent/prompt.ts

@@ -0,0 +1,32 @@
+// Agent system prompt — v2: uploaded-file awareness + pdfjs extraction fix
+export const AGENT_SYSTEM_PROMPT = `You are MindOS Agent — an execution-oriented AI assistant for a personal knowledge base.
+
+Runtime capabilities already available in this request:
+- bootstrap context (MindOS startup files) is auto-loaded by the server
+- mindos skill guidance is auto-loaded by the server
+- knowledge-base tools are available for file operations
+
+How to operate:
+1. Treat the auto-loaded bootstrap + skill context as your initialization baseline.
+2. If the task needs fresher or broader evidence, call tools proactively (list/search/read) before concluding.
+3. Execute edits safely and minimally, then verify outcomes.
+
+Tool policy:
+- Always read a file before modifying it.
+- Use search/list tools first when file location is unclear.
+- Prefer targeted edits (update_section / insert_after_heading / append_to_file) over full overwrite.
+- Use write_file only when replacing the whole file is required.
+- INSTRUCTION.md is read-only and must not be modified.
+
+Uploaded files:
+- Users may upload local files (PDF, txt, csv, etc.) via the chat interface.
+- The content of uploaded files is ALREADY INCLUDED in this system prompt in a dedicated "⚠️ USER-UPLOADED FILES" section near the end.
+- IMPORTANT: When the user references an uploaded file (e.g. a resume/CV, a report, a document), you MUST use the content from that section directly. Extract specific details, quote relevant passages, and demonstrate that you have read the file thoroughly.
+- Do NOT attempt to use read_file or search tools to find uploaded files — they do not exist in the knowledge base. They are ONLY available in the uploaded files section of this prompt.
+- If the uploaded files section is empty or missing, tell the user the upload may have failed and ask them to re-upload.
+
+Response policy:
+- Answer in the user's language.
+- Be concise, concrete, and action-oriented.
+- Use Markdown for structure when it improves clarity.
+- When relevant, explicitly state whether initialization context appears sufficient or if additional tool reads were needed.`;

package/app/lib/agent/tools.ts

@@ -0,0 +1,151 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import {
+  searchFiles, getFileContent, getFileTree, getRecentlyModified,
+  saveFileContent, createFile, appendToFile, insertAfterHeading, updateSection,
+} from '@/lib/fs';
+import { assertNotProtected } from '@/lib/core';
+
+// Max chars per file to avoid token overflow (~100k chars ≈ ~25k tokens)
+const MAX_FILE_CHARS = 20_000;
+
+export function truncate(content: string): string {
+  if (content.length <= MAX_FILE_CHARS) return content;
+  return content.slice(0, MAX_FILE_CHARS) + `\n\n[...truncated — file is ${content.length} chars, showing first ${MAX_FILE_CHARS}]`;
+}
+
+/** Checks write-protection using core's assertNotProtected */
+export function assertWritable(filePath: string): void {
+  assertNotProtected(filePath, 'modified by AI agent');
+}
+
+// ─── Knowledge base tools ─────────────────────────────────────────────────────
+
+export const knowledgeBaseTools = {
+  list_files: tool({
+    description: 'List the full file tree of the knowledge base. Use this to browse what files exist.',
+    inputSchema: z.object({}),
+    execute: async () => {
+      const tree = getFileTree();
+      return JSON.stringify(tree, null, 2);
+    },
+  }),
+
+  read_file: tool({
+    description: 'Read the content of a file by its relative path. Always read a file before modifying it.',
+    inputSchema: z.object({ path: z.string().describe('Relative file path, e.g. "Profile/👤 Identity.md"') }),
+    execute: async ({ path }) => {
+      try {
+        return truncate(getFileContent(path));
+      } catch (e: unknown) {
+        return `Error: ${e instanceof Error ? e.message : String(e)}`;
+      }
+    },
+  }),
+
+  search: tool({
+    description: 'Full-text search across all files in the knowledge base. Returns matching files with context snippets.',
+    inputSchema: z.object({ query: z.string().describe('Search query (case-insensitive)') }),
+    execute: async ({ query }) => {
+      const results = searchFiles(query);
+      if (results.length === 0) return 'No results found.';
+      return results.map(r => `- **${r.path}**: ${r.snippet}`).join('\n');
+    },
+  }),
+
+  get_recent: tool({
+    description: 'Get the most recently modified files in the knowledge base.',
+    inputSchema: z.object({ limit: z.number().min(1).max(50).default(10).describe('Number of files to return') }),
+    execute: async ({ limit }) => {
+      const files = getRecentlyModified(limit);
+      return files.map(f => `- ${f.path} (${new Date(f.mtime).toISOString()})`).join('\n');
+    },
+  }),
+
+  write_file: tool({
+    description: 'Overwrite the entire content of an existing file. Use read_file first to see current content. Prefer update_section or insert_after_heading for partial edits.',
+    inputSchema: z.object({
+      path: z.string().describe('Relative file path'),
+      content: z.string().describe('New full content'),
+    }),
+    execute: async ({ path, content }) => {
+      try {
+        assertWritable(path);
+        saveFileContent(path, content);
+        return `File written: ${path}`;
+      } catch (e: unknown) {
+        return `Error: ${e instanceof Error ? e.message : String(e)}`;
+      }
+    },
+  }),
+
+  create_file: tool({
+    description: 'Create a new file. Only .md and .csv files are allowed. Parent directories are created automatically.',
+    inputSchema: z.object({
+      path: z.string().describe('Relative file path (must end in .md or .csv)'),
+      content: z.string().default('').describe('Initial file content'),
+    }),
+    execute: async ({ path, content }) => {
+      try {
+        assertWritable(path);
+        createFile(path, content);
+        return `File created: ${path}`;
+      } catch (e: unknown) {
+        return `Error: ${e instanceof Error ? e.message : String(e)}`;
+      }
+    },
+  }),
+
+  append_to_file: tool({
+    description: 'Append text to the end of an existing file. A blank line separator is added automatically.',
+    inputSchema: z.object({
+      path: z.string().describe('Relative file path'),
+      content: z.string().describe('Content to append'),
+    }),
+    execute: async ({ path, content }) => {
+      try {
+        assertWritable(path);
+        appendToFile(path, content);
+        return `Content appended to: ${path}`;
+      } catch (e: unknown) {
+        return `Error: ${e instanceof Error ? e.message : String(e)}`;
+      }
+    },
+  }),
+
+  insert_after_heading: tool({
+    description: 'Insert content right after a Markdown heading. Useful for adding items under a specific section.',
+    inputSchema: z.object({
+      path: z.string().describe('Relative file path'),
+      heading: z.string().describe('Heading text to find (e.g. "## Tasks" or just "Tasks")'),
+      content: z.string().describe('Content to insert after the heading'),
+    }),
+    execute: async ({ path, heading, content }) => {
+      try {
+        assertWritable(path);
+        insertAfterHeading(path, heading, content);
+        return `Content inserted after heading "${heading}" in ${path}`;
+      } catch (e: unknown) {
+        return `Error: ${e instanceof Error ? e.message : String(e)}`;
+      }
+    },
+  }),
+
+  update_section: tool({
+    description: 'Replace the content of a Markdown section identified by its heading. The section spans from the heading to the next heading of equal or higher level.',
+    inputSchema: z.object({
+      path: z.string().describe('Relative file path'),
+      heading: z.string().describe('Heading text to find (e.g. "## Status")'),
+      content: z.string().describe('New content for the section'),
+    }),
+    execute: async ({ path, heading, content }) => {
+      try {
+        assertWritable(path);
+        updateSection(path, heading, content);
+        return `Section "${heading}" updated in ${path}`;
+      } catch (e: unknown) {
+        return `Error: ${e instanceof Error ? e.message : String(e)}`;
+      }
+    },
+  }),
+};

package/app/lib/api.ts

@@ -0,0 +1,55 @@
+/**
+ * Typed fetch wrapper with error handling and optional timeout.
+ *
+ * - Checks `res.ok` and throws on non-2xx status.
+ * - Extracts `{ error }` from JSON error responses when available.
+ * - Supports AbortController timeout (default 30s).
+ */
+
+export class ApiError extends Error {
+  status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+  }
+}
+
+interface ApiFetchOptions extends Omit<RequestInit, 'signal'> {
+  /** Timeout in ms (default 30000). Set to 0 to disable. */
+  timeout?: number;
+  /** External AbortSignal (merged with timeout signal). */
+  signal?: AbortSignal;
+}
+
+export async function apiFetch<T>(url: string, opts: ApiFetchOptions = {}): Promise<T> {
+  const { timeout = 30_000, signal: externalSignal, ...fetchOpts } = opts;
+
+  let controller: AbortController | undefined;
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  if (timeout > 0) {
+    controller = new AbortController();
+    timeoutId = setTimeout(() => controller!.abort(), timeout);
+  }
+
+  // Merge external signal if provided
+  const signal = externalSignal ?? controller?.signal;
+
+  try {
+    const res = await fetch(url, { ...fetchOpts, signal });
+
+    if (!res.ok) {
+      let msg = `Request failed (${res.status})`;
+      try {
+        const body = await res.json();
+        if (body?.error) msg = body.error;
+      } catch { /* non-JSON error body */ }
+      throw new ApiError(msg, res.status);
+    }
+
+    return (await res.json()) as T;
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+}

package/app/lib/core/backlinks.ts

@@ -0,0 +1,40 @@
+import path from 'path';
+import { collectAllFiles } from './tree';
+import { readFile } from './fs-ops';
+import type { BacklinkEntry } from './types';
+
+/**
+ * Finds files that reference the given targetPath via wikilinks,
+ * markdown links, or backtick references.
+ */
+export function findBacklinks(mindRoot: string, targetPath: string): BacklinkEntry[] {
+  const allFiles = collectAllFiles(mindRoot).filter(f => f.endsWith('.md') && f !== targetPath);
+  const results: BacklinkEntry[] = [];
+  const bname = path.basename(targetPath, '.md');
+  const escapedTarget = targetPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const escapedBname = bname.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  const patterns = [
+    new RegExp(`\\[\\[${escapedBname}(?:[|#][^\\]]*)?\\]\\]`, 'i'),
+    new RegExp(`\\[\\[${escapedTarget}(?:[|#][^\\]]*)?\\]\\]`, 'i'),
+    new RegExp(`\\[[^\\]]+\\]\\(${escapedTarget}(?:#[^)]*)?\\)`, 'i'),
+    new RegExp(`\\[[^\\]]+\\]\\([^)]*${escapedBname}\\.md(?:#[^)]*)?\\)`, 'i'),
+    new RegExp('`' + escapedTarget.replace(/\//g, '\\/') + '`'),
+  ];
+
+  for (const filePath of allFiles) {
+    let content: string;
+    try { content = readFile(mindRoot, filePath); } catch { continue; }
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (patterns.some(p => p.test(lines[i]))) {
+        const start = Math.max(0, i - 1);
+        const end = Math.min(lines.length - 1, i + 1);
+        const ctx = lines.slice(start, end + 1).join('\n').trim();
+        results.push({ source: filePath, line: i + 1, context: ctx });
+        break;
+      }
+    }
+  }
+  return results;
+}

package/app/lib/core/csv.ts

@@ -0,0 +1,28 @@
+import fs from 'fs';
+import path from 'path';
+import { resolveSafe } from './security';
+
+/**
+ * Appends a single row to a CSV file with RFC 4180 escaping.
+ * Creates parent directories if they don't exist.
+ * Returns the new total row count.
+ */
+export function appendCsvRow(mindRoot: string, filePath: string, row: string[]): { newRowCount: number } {
+  const resolved = resolveSafe(mindRoot, filePath);
+  if (!filePath.endsWith('.csv')) throw new Error('Only .csv files support row append');
+
+  const escaped = row.map((cell) => {
+    if (cell.includes(',') || cell.includes('"') || cell.includes('\n')) {
+      return `"${cell.replace(/"/g, '""')}"`;
+    }
+    return cell;
+  });
+  const line = escaped.join(',') + '\n';
+
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  fs.appendFileSync(resolved, line, 'utf-8');
+
+  const content = fs.readFileSync(resolved, 'utf-8');
+  const newRowCount = content.trim().split('\n').length;
+  return { newRowCount };
+}

package/app/lib/core/fs-ops.ts

@@ -0,0 +1,118 @@
+import fs from 'fs';
+import path from 'path';
+import { resolveSafe, assertWithinRoot } from './security';
+
+/**
+ * Reads the content of a file given a relative path from mindRoot.
+ */
+export function readFile(mindRoot: string, filePath: string): string {
+  const resolved = resolveSafe(mindRoot, filePath);
+  return fs.readFileSync(resolved, 'utf-8');
+}
+
+/**
+ * Atomically writes content to a file (temp file + rename).
+ * Creates parent directories as needed.
+ */
+export function writeFile(mindRoot: string, filePath: string, content: string): void {
+  const resolved = resolveSafe(mindRoot, filePath);
+  const dir = path.dirname(resolved);
+  const tmp = path.join(dir, `.tmp-${Date.now()}-${path.basename(resolved)}`);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(tmp, content, 'utf-8');
+    fs.renameSync(tmp, resolved);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+/**
+ * Creates a new file. Throws if the file already exists.
+ * Creates parent directories as needed.
+ */
+export function createFile(mindRoot: string, filePath: string, initialContent = ''): void {
+  const resolved = resolveSafe(mindRoot, filePath);
+  if (fs.existsSync(resolved)) {
+    throw new Error(`File already exists: ${filePath}`);
+  }
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  fs.writeFileSync(resolved, initialContent, 'utf-8');
+}
+
+/**
+ * Deletes a file. Throws if the file does not exist.
+ */
+export function deleteFile(mindRoot: string, filePath: string): void {
+  const resolved = resolveSafe(mindRoot, filePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+  fs.unlinkSync(resolved);
+}
+
+/**
+ * Renames a file within its current directory.
+ * newName must be a plain filename (no path separators).
+ * Returns the new relative path.
+ */
+export function renameFile(mindRoot: string, oldPath: string, newName: string): string {
+  if (newName.includes('/') || newName.includes('\\')) {
+    throw new Error('Invalid filename: must not contain path separators');
+  }
+  const root = path.resolve(mindRoot);
+  const oldResolved = path.resolve(path.join(root, oldPath));
+  assertWithinRoot(oldResolved, root);
+
+  const dir = path.dirname(oldResolved);
+  const newResolved = path.join(dir, newName);
+  assertWithinRoot(newResolved, root);
+
+  if (fs.existsSync(newResolved)) {
+    throw new Error('A file with that name already exists');
+  }
+  fs.renameSync(oldResolved, newResolved);
+  return path.relative(root, newResolved);
+}
+
+/**
+ * Moves a file from one path to another within mindRoot.
+ * Returns the new path and a list of files that referenced the old path.
+ */
+export function moveFile(
+  mindRoot: string,
+  fromPath: string,
+  toPath: string,
+  findBacklinksFn: (mindRoot: string, targetPath: string) => Array<{ source: string }>
+): { newPath: string; affectedFiles: string[] } {
+  const fromResolved = resolveSafe(mindRoot, fromPath);
+  const toResolved = resolveSafe(mindRoot, toPath);
+  if (!fs.existsSync(fromResolved)) throw new Error(`Source not found: ${fromPath}`);
+  if (fs.existsSync(toResolved)) throw new Error(`Destination already exists: ${toPath}`);
+  fs.mkdirSync(path.dirname(toResolved), { recursive: true });
+  fs.renameSync(fromResolved, toResolved);
+  const backlinks = findBacklinksFn(mindRoot, fromPath);
+  return { newPath: toPath, affectedFiles: backlinks.map(b => b.source) };
+}
+
+/**
+ * Returns files sorted by modification time, descending.
+ */
+export function getRecentlyModified(
+  mindRoot: string,
+  allFiles: string[],
+  limit = 10
+): Array<{ path: string; mtime: number; mtimeISO: string }> {
+  const withMtime = allFiles.flatMap((filePath) => {
+    try {
+      const abs = path.join(mindRoot, filePath);
+      const stat = fs.statSync(abs);
+      return [{ path: filePath, mtime: stat.mtimeMs, mtimeISO: stat.mtime.toISOString() }];
+    } catch {
+      return [];
+    }
+  });
+  withMtime.sort((a, b) => b.mtime - a.mtime);
+  return withMtime.slice(0, limit);
+}

package/app/lib/core/git.ts

@@ -0,0 +1,50 @@
+import { execSync } from 'child_process';
+import { resolveSafe } from './security';
+import type { GitLogEntry } from './types';
+
+/**
+ * Checks if the mindRoot directory is inside a git repository.
+ */
+export function isGitRepo(mindRoot: string): boolean {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { cwd: mindRoot, stdio: 'pipe' });
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Returns git log entries for a given file.
+ */
+export function gitLog(mindRoot: string, filePath: string, limit: number): GitLogEntry[] {
+  const resolved = resolveSafe(mindRoot, filePath);
+  const output = execSync(
+    `git log --follow --format="%H%x00%aI%x00%s%x00%an" -n ${limit} -- "${resolved}"`,
+    { cwd: mindRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+  ).trim();
+  if (!output) return [];
+  return output.split('\n').map(line => {
+    const [hash, date, message, author] = line.split('\0');
+    return { hash, date, message, author };
+  });
+}
+
+/**
+ * Returns the content of a file at a specific git commit.
+ */
+export function gitShowFile(mindRoot: string, filePath: string, commitHash: string): string {
+  const resolved = resolveSafe(mindRoot, filePath);
+  const relFromGitRoot = execSync(
+    `git ls-files --full-name "${resolved}"`,
+    { cwd: mindRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+  ).trim();
+  if (!relFromGitRoot) {
+    return execSync(
+      `git show ${commitHash}:"${filePath}"`,
+      { cwd: mindRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+  }
+  return execSync(
+    `git show ${commitHash}:"${relFromGitRoot}"`,
+    { cwd: mindRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+  );
+}

package/app/lib/core/index.ts

@@ -0,0 +1,58 @@
+// Types
+export type {
+  FileNode,
+  SearchResult,
+  BacklinkEntry,
+  SearchOptions,
+  GitLogEntry,
+  MoveResult,
+} from './types';
+
+// Security
+export {
+  assertWithinRoot,
+  resolveSafe,
+  isRootProtected,
+  assertNotProtected,
+} from './security';
+
+// File operations
+export {
+  readFile,
+  writeFile,
+  createFile,
+  deleteFile,
+  renameFile,
+  moveFile,
+  getRecentlyModified,
+} from './fs-ops';
+
+// Tree
+export {
+  getFileTree,
+  collectAllFiles,
+  renderTree,
+} from './tree';
+export type { TreeOptions } from './tree';
+
+// Search
+export { searchFiles } from './search';
+
+// Line-level operations
+export {
+  readLines,
+  insertLines,
+  updateLines,
+  appendToFile,
+  insertAfterHeading,
+  updateSection,
+} from './lines';
+
+// CSV
+export { appendCsvRow } from './csv';
+
+// Backlinks
+export { findBacklinks } from './backlinks';
+
+// Git
+export { isGitRepo, gitLog, gitShowFile } from './git';

package/app/lib/core/lines.ts

@@ -0,0 +1,89 @@
+import { readFile, writeFile } from './fs-ops';
+
+/**
+ * Reads a file and returns its content split into lines.
+ */
+export function readLines(mindRoot: string, filePath: string): string[] {
+  return readFile(mindRoot, filePath).split('\n');
+}
+
+/**
+ * Validates line indices are within bounds.
+ */
+function validateLineRange(totalLines: number, start: number, end: number): void {
+  if (start < 0 || end < 0) throw new Error('Invalid line index: indices must be >= 0');
+  if (start > end) throw new Error(`Invalid range: start (${start}) > end (${end})`);
+  if (start >= totalLines) throw new Error(`Invalid line index: start (${start}) >= total lines (${totalLines})`);
+}
+
+/**
+ * Inserts lines after the given 0-based index.
+ * Use afterIndex = -1 to prepend at the start.
+ */
+export function insertLines(mindRoot: string, filePath: string, afterIndex: number, lines: string[]): void {
+  const existing = readLines(mindRoot, filePath);
+  if (afterIndex >= existing.length) {
+    throw new Error(`Invalid after_index: ${afterIndex} >= total lines (${existing.length})`);
+  }
+  const insertAt = afterIndex < 0 ? 0 : afterIndex + 1;
+  existing.splice(insertAt, 0, ...lines);
+  writeFile(mindRoot, filePath, existing.join('\n'));
+}
+
+/**
+ * Replaces lines from startIndex to endIndex (inclusive) with newLines.
+ */
+export function updateLines(mindRoot: string, filePath: string, startIndex: number, endIndex: number, newLines: string[]): void {
+  const existing = readLines(mindRoot, filePath);
+  validateLineRange(existing.length, startIndex, endIndex);
+  existing.splice(startIndex, endIndex - startIndex + 1, ...newLines);
+  writeFile(mindRoot, filePath, existing.join('\n'));
+}
+
+/**
+ * Appends content to the end of a file, adding a newline separator if needed.
+ */
+export function appendToFile(mindRoot: string, filePath: string, content: string): void {
+  const existing = readFile(mindRoot, filePath);
+  const separator = existing.length > 0 && !existing.endsWith('\n\n') ? '\n' : '';
+  writeFile(mindRoot, filePath, existing + separator + content);
+}
+
+/**
+ * Inserts content after the first occurrence of a Markdown heading.
+ */
+export function insertAfterHeading(mindRoot: string, filePath: string, heading: string, content: string): void {
+  const lines = readLines(mindRoot, filePath);
+  const idx = lines.findIndex(l => {
+    const trimmed = l.trim();
+    return trimmed === heading || trimmed.replace(/^#+\s*/, '') === heading.replace(/^#+\s*/, '');
+  });
+  if (idx === -1) throw new Error(`Heading not found: "${heading}"`);
+  let insertAt = idx + 1;
+  while (insertAt < lines.length && lines[insertAt].trim() === '') insertAt++;
+  insertLines(mindRoot, filePath, insertAt - 1, ['', content]);
+}
+
+/**
+ * Replaces the content of a Markdown section identified by its heading.
+ */
+export function updateSection(mindRoot: string, filePath: string, heading: string, newContent: string): void {
+  const lines = readLines(mindRoot, filePath);
+  const idx = lines.findIndex(l => {
+    const trimmed = l.trim();
+    return trimmed === heading || trimmed.replace(/^#+\s*/, '') === heading.replace(/^#+\s*/, '');
+  });
+  if (idx === -1) throw new Error(`Heading not found: "${heading}"`);
+
+  const headingLevel = (lines[idx].match(/^#+/) ?? [''])[0].length;
+  let sectionEnd = lines.length - 1;
+  for (let i = idx + 1; i < lines.length; i++) {
+    const m = lines[i].match(/^(#+)\s/);
+    if (m && m[1].length <= headingLevel) {
+      sectionEnd = i - 1;
+      break;
+    }
+  }
+  while (sectionEnd > idx && lines[sectionEnd].trim() === '') sectionEnd--;
+  updateLines(mindRoot, filePath, idx + 1, sectionEnd, ['', newContent]);
+}