@ryuu-reinzz/ryuu-cli 0.0.0-stage → 0.3.1

package/src/tools/filesystem.js

@@ -0,0 +1,304 @@
+import { defineTool } from './registry.js';
+import { createUnifiedDiff, diffStats } from '../services/diff.js';
+import { ToolError } from '../utils/errors.js';
+
+const pathSchema = { type: 'string', minLength: 1, maxLength: 4096, description: 'Path relative to the workspace root.' };
+
+const objectSchema = (properties, required = []) => ({
+  type: 'object',
+  properties,
+  required,
+  additionalProperties: false,
+});
+
+const MAX_WRITE_CHARS = 1_000_000;
+
+function assertContentSize(content) {
+  if (content.length > MAX_WRITE_CHARS) {
+    throw new ToolError(`Content is too large (${content.length} chars, max ${MAX_WRITE_CHARS}). Split the change into smaller files.`);
+  }
+}
+
+function previewDiff(relPath, before, after) {
+  const diff = createUnifiedDiff(before, after, { oldLabel: `a/${relPath}`, newLabel: `b/${relPath}` });
+  if (!diff) return `(no changes) ${relPath} is already up to date`;
+  const stats = diffStats(before, after);
+  return `${diff}\n\n(${stats.added} added, ${stats.removed} removed)`;
+}
+
+/**
+ * @param {object} deps
+ * @param {import('../services/workspace.js').Workspace} deps.workspace
+ * @param {object} deps.config
+ */
+export function createFilesystemTools({ workspace, config }) {
+  async function computeEdit({ path: target, old_text: original, new_text: replacement, replace_all = false }) {
+    const file = await workspace.readText(target, { maxBytes: config.maxFileBytes });
+    if (original === replacement) throw new ToolError('old_text and new_text are identical; nothing to change.');
+    let occurrences = 0;
+    let index = file.text.indexOf(original);
+    while (index !== -1) {
+      occurrences += 1;
+      index = file.text.indexOf(original, index + original.length);
+    }
+    if (occurrences === 0) {
+      throw new ToolError(
+        `old_text was not found in ${file.relPath}. Re-read the file and copy the exact text (including indentation).`,
+      );
+    }
+    if (occurrences > 1 && !replace_all) {
+      throw new ToolError(
+        `old_text matches ${occurrences} locations in ${file.relPath}. Include more surrounding context or set replace_all=true.`,
+      );
+    }
+    const after = replace_all
+      ? file.text.split(original).join(replacement)
+      : file.text.slice(0, file.text.indexOf(original)) +
+        replacement +
+        file.text.slice(file.text.indexOf(original) + original.length);
+    return { file, after, occurrences };
+  }
+
+  return [
+    defineTool({
+      name: 'list_files',
+      description: 'List files and directories inside the workspace. Supports substring/wildcard filtering and pagination. Secret files and generated directories are excluded by default.',
+      risk: 'read',
+      schema: objectSchema({
+        path: { ...pathSchema, description: 'Directory to list (default workspace root).' },
+        filter: { type: 'string', maxLength: 200, description: 'Optional case-insensitive name filter; * and ? wildcards allowed.' },
+        limit: { type: 'integer', minimum: 1, maximum: 500, description: 'Maximum entries to return (default 200).' },
+        offset: { type: 'integer', minimum: 0, maximum: 100000, description: 'Pagination offset.' },
+        include_generated: { type: 'boolean', description: 'Include node_modules, .git, dist, etc. (usually not needed).' },
+      }),
+      handler: async (args) => workspace.list(args.path || '.', {
+        limit: Math.min(args.limit ?? 200, 500),
+        offset: args.offset ?? 0,
+        filter: args.filter,
+        includeGenerated: args.include_generated ?? false,
+        includeHidden: args.include_generated ?? false,
+      }),
+    }),
+
+    defineTool({
+      name: 'tree',
+      description: 'Show a bounded directory tree of the workspace.',
+      risk: 'read',
+      schema: objectSchema({
+        path: { ...pathSchema, description: 'Directory to print (default workspace root).' },
+        depth: { type: 'integer', minimum: 1, maximum: 8, description: 'Maximum depth (default 3).' },
+        max_entries: { type: 'integer', minimum: 1, maximum: 2000, description: 'Maximum entries (default 200).' },
+        include_generated: { type: 'boolean' },
+      }),
+      handler: async (args) => workspace.tree(args.path || '.', {
+        depth: args.depth ?? 3,
+        maxEntries: Math.min(args.max_entries ?? 200, 2000),
+        includeGenerated: args.include_generated ?? false,
+      }),
+    }),
+
+    defineTool({
+      name: 'read_file',
+      description:
+        'Read a UTF-8 text file from the workspace. Refuses secret files, binary files, and invalid encodings. A full read refuses files above the configured size limit; with start_line/end_line the requested range is streamed, so it also works for files above that limit.',
+      risk: 'read',
+      schema: objectSchema({
+        path: pathSchema,
+        start_line: { type: 'integer', minimum: 1, description: 'First line to return (1-based).' },
+        end_line: { type: 'integer', minimum: 1, description: 'Last line to return (inclusive).' },
+        max_bytes: { type: 'integer', minimum: 1, maximum: 5 * 1024 * 1024, description: 'Per-call read/output limit.' },
+      }, ['path']),
+      handler: async (args) => {
+        const maxBytes = Math.min(args.max_bytes ?? config.maxFileBytes, config.maxFileBytes);
+        const startLine = args.start_line ?? 1;
+        const endLine = args.end_line ?? null;
+        if (endLine !== null && endLine < startLine) {
+          throw new ToolError('end_line must be greater than or equal to start_line.');
+        }
+
+        // A requested range is streamed: only those lines are decoded and kept,
+        // so the size limit no longer blocks reading part of a large file.
+        if (args.start_line !== undefined || args.end_line !== undefined) {
+          const range = await workspace.readTextRange(args.path, { startLine, endLine, maxBytes });
+          return {
+            path: range.relPath,
+            start_line: range.startLine,
+            end_line: range.endLine,
+            total_lines: range.totalLines,
+            size: range.size,
+            eol: range.eol === '\r\n' ? 'CRLF' : 'LF',
+            truncated: range.truncated,
+            ...(range.capped
+              ? { note: `The requested range exceeds the ${maxBytes}-byte read limit; read a narrower range for the rest.` }
+              : {}),
+            text: range.text,
+          };
+        }
+
+        const file = await workspace.readText(args.path, { maxBytes });
+        const lines = file.text.split(/\r?\n/);
+        if (startLine > lines.length && lines.length > 0) {
+          throw new ToolError(`start_line ${startLine} is beyond the end of ${file.relPath} (${lines.length} lines).`);
+        }
+        const end = Math.min(endLine ?? lines.length, lines.length);
+        const slice = lines.slice(startLine - 1, end);
+        return {
+          path: file.relPath,
+          start_line: startLine,
+          end_line: end,
+          total_lines: lines.length,
+          size: file.size,
+          eol: file.eol === '\r\n' ? 'CRLF' : 'LF',
+          truncated: end < lines.length,
+          text: slice.join('\n'),
+        };
+      },
+    }),
+
+    defineTool({
+      name: 'file_info',
+      description: 'Report metadata for a workspace path: kind, size, timestamps, line count, text/binary hint.',
+      risk: 'read',
+      schema: objectSchema({ path: pathSchema }, ['path']),
+      handler: async (args) => workspace.info(args.path),
+    }),
+
+    defineTool({
+      name: 'create_file',
+      description: 'Create a new text file in the workspace. Fails if the file already exists unless overwrite=true.',
+      risk: 'write',
+      schema: objectSchema({
+        path: pathSchema,
+        content: { type: 'string', maxLength: MAX_WRITE_CHARS },
+        overwrite: { type: 'boolean', description: 'Replace an existing file (default false).' },
+      }, ['path', 'content']),
+      preview: async (args) => {
+        let before = '';
+        try {
+          const existing = await workspace.readText(args.path, { maxBytes: config.maxFileBytes });
+          if (!args.overwrite) return `File already exists: ${args.path}. create_file would fail; use edit_file or write_file.`;
+          before = existing.text;
+        } catch {
+          before = '';
+        }
+        return previewDiff(args.path, before, args.content);
+      },
+      handler: async (args) => {
+        assertContentSize(args.content);
+        return workspace.createText(args.path, args.content, { overwrite: args.overwrite ?? false });
+      },
+    }),
+
+    defineTool({
+      name: 'write_file',
+      description: 'Write a complete text file, replacing existing content. Provide expected_mtime_ms from a previous read/info call to prevent silently overwriting concurrent edits.',
+      risk: 'write',
+      schema: objectSchema({
+        path: pathSchema,
+        content: { type: 'string', maxLength: MAX_WRITE_CHARS },
+        expected_mtime_ms: { type: 'number', description: 'If set, abort when the file mtime differs.' },
+      }, ['path', 'content']),
+      preview: async (args) => {
+        let before = '';
+        try {
+          before = (await workspace.readText(args.path, { maxBytes: config.maxFileBytes })).text;
+        } catch {
+          before = '';
+        }
+        return previewDiff(args.path, before, args.content);
+      },
+      handler: async (args) => {
+        assertContentSize(args.content);
+        return workspace.writeText(args.path, args.content, { expectedMtimeMs: args.expected_mtime_ms });
+      },
+    }),
+
+    defineTool({
+      name: 'edit_file',
+      description: 'Apply a targeted text replacement. old_text must match exactly (including indentation); it must be unique unless replace_all=true. Returns the resulting diff and new mtime. Refuses to overwrite concurrent edits.',
+      risk: 'write',
+      schema: objectSchema({
+        path: pathSchema,
+        old_text: { type: 'string', minLength: 1, maxLength: 100000 },
+        new_text: { type: 'string', maxLength: 100000 },
+        replace_all: { type: 'boolean', description: 'Replace every occurrence (default false).' },
+        expected_mtime_ms: { type: 'number', description: 'Abort if the file changed since this mtime.' },
+      }, ['path', 'old_text', 'new_text']),
+      preview: async (args) => {
+        const { file, after } = await computeEdit(args);
+        return previewDiff(file.relPath, file.text, after);
+      },
+      handler: async (args) => {
+        assertContentSize(args.new_text);
+        const { file, after, occurrences } = await computeEdit(args);
+        const written = await workspace.writeText(args.path, after, {
+          expectedMtimeMs: args.expected_mtime_ms ?? file.mtimeMs,
+        });
+        return {
+          path: written.relPath,
+          occurrences,
+          bytes_written: written.size,
+          lines: written.lines,
+          mtime_ms: written.mtimeMs,
+          diff: createUnifiedDiff(file.text, after, { oldLabel: `a/${written.relPath}`, newLabel: `b/${written.relPath}`, maxLines: 200 }),
+        };
+      },
+    }),
+
+    defineTool({
+      name: 'diff_file',
+      description: 'Show a unified diff without writing anything. Compares the current file against proposed new content, or against provided old/new text.',
+      risk: 'read',
+      schema: objectSchema({
+        path: pathSchema,
+        new_text: { type: 'string', maxLength: MAX_WRITE_CHARS, description: 'Proposed full file content.' },
+        old_text: { type: 'string', maxLength: MAX_WRITE_CHARS, description: 'Optional explicit old content; defaults to the file on disk.' },
+      }, ['path']),
+      handler: async (args) => {
+        let before = args.old_text;
+        if (before === undefined) {
+          before = (await workspace.readText(args.path, { maxBytes: config.maxFileBytes })).text;
+        }
+        if (args.new_text === undefined) throw new ToolError('new_text is required.');
+        const diff = createUnifiedDiff(before, args.new_text, { oldLabel: `a/${args.path}`, newLabel: `b/${args.path}` });
+        return { path: args.path, diff: diff || '(no changes)', stats: diffStats(before, args.new_text) };
+      },
+    }),
+
+    defineTool({
+      name: 'move_file',
+      description: 'Move or rename a file inside the workspace. Requires approval.',
+      risk: 'destructive',
+      schema: objectSchema({
+        from: pathSchema,
+        to: pathSchema,
+        overwrite: { type: 'boolean' },
+      }, ['from', 'to']),
+      preview: async (args) => `Move ${args.from} -> ${args.to}${args.overwrite ? ' (may overwrite destination)' : ''}`,
+      handler: async (args) => workspace.move(args.from, args.to, { overwrite: args.overwrite ?? false }),
+    }),
+
+    defineTool({
+      name: 'delete_file',
+      description: 'Delete a single file or an empty directory inside the workspace. Requires approval. Never follows symlinks.',
+      risk: 'destructive',
+      schema: objectSchema({
+        path: pathSchema,
+        confirm: { type: 'boolean', description: 'Must be true; a second explicit acknowledgement.' },
+      }, ['path', 'confirm']),
+      preview: async (args) => {
+        if (args.confirm !== true) return `delete_file requires confirm=true for ${args.path}`;
+        try {
+          const info = await workspace.info(args.path);
+          return `Delete ${info.kind} ${info.path} (${info.size} bytes)`;
+        } catch {
+          return `Delete ${args.path} (path not found)`;
+        }
+      },
+      handler: async (args) => {
+        if (args.confirm !== true) throw new ToolError('delete_file requires confirm=true.');
+        return workspace.remove(args.path);
+      },
+    }),
+  ];
+}

package/src/tools/git.js

@@ -0,0 +1,114 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { defineTool } from './registry.js';
+import { ToolError } from '../utils/errors.js';
+
+const execFileAsync = promisify(execFile);
+const MAX_BUFFER = 2 * 1024 * 1024;
+const GIT_TIMEOUT_MS = 15000;
+
+async function runGit(args, { cwd, timeout = GIT_TIMEOUT_MS } = {}) {
+  try {
+    const { stdout, stderr } = await execFileAsync('git', args, {
+      cwd,
+      timeout,
+      maxBuffer: MAX_BUFFER,
+      windowsHide: true,
+      env: { ...process.env, GIT_PAGER: 'cat', GIT_TERMINAL_PROMPT: '0' },
+    });
+    return { ok: true, stdout, stderr, code: 0 };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { ok: false, available: false, stdout: '', stderr: 'git is not installed or not on PATH', code: null };
+    }
+    if (error.killed) {
+      return { ok: false, stdout: error.stdout || '', stderr: `git command timed out after ${timeout}ms`, code: null };
+    }
+    return {
+      ok: false,
+      stdout: error.stdout || '',
+      stderr: error.stderr || error.message,
+      code: typeof error.code === 'number' ? error.code : null,
+    };
+  }
+}
+
+function boundLines(text, maxLines) {
+  const lines = String(text || '').split('\n');
+  if (lines.length <= maxLines) return { text: lines.join('\n'), truncated: false };
+  return { text: `${lines.slice(0, maxLines).join('\n')}\n…[diff truncated]`, truncated: true };
+}
+
+export function createGitTools({ workspace, logger = null }) {
+  return [
+    defineTool({
+      name: 'inspect_git',
+      description:
+        'Read-only Git inspection: status, diff, log, show or branch. Never runs destructive git commands. Returns available=false when Git is not installed.',
+      risk: 'read',
+      schema: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['status', 'diff', 'log', 'show', 'branch'] },
+          path: { type: 'string', minLength: 1, maxLength: 4096, description: 'Optional workspace path to scope diff/status.' },
+          staged: { type: 'boolean', description: 'Show staged diff (diff action only).' },
+          max_lines: { type: 'integer', minimum: 20, maximum: 2000, description: 'Diff/log line cap (default 200).' },
+          limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Log entry count (default 10).' },
+        },
+        required: ['action'],
+        additionalProperties: false,
+      },
+      handler: async (args) => {
+        const maxLines = args.max_lines ?? 200;
+        let relPath = null;
+        if (args.path) relPath = workspace.resolve(args.path).relPath;
+        let gitArgs;
+        switch (args.action) {
+          case 'status':
+            gitArgs = ['status', '--porcelain=v1', '--branch', ...(relPath ? ['--', relPath] : [])];
+            break;
+          case 'diff':
+            gitArgs = ['diff', '--no-color', '--stat', ...(args.staged ? ['--cached'] : []), ...(relPath ? ['--', relPath] : [])];
+            break;
+          case 'log':
+            gitArgs = ['log', '--oneline', '--decorate', '-n', String(args.limit ?? 10)];
+            break;
+          case 'show':
+            gitArgs = ['show', '--stat', '--no-color', 'HEAD'];
+            break;
+          case 'branch':
+            gitArgs = ['branch', '--no-color', '-vv'];
+            break;
+          default:
+            throw new ToolError(`Unsupported git action: ${args.action}`);
+        }
+
+        const result = await runGit(gitArgs, { cwd: workspace.root });
+        if (result.available === false) {
+          return { available: false, action: args.action, message: 'Git is not installed or not available on PATH.' };
+        }
+        const bounded = boundLines(result.stdout, maxLines);
+        let detail = null;
+        if (args.action === 'diff' && result.ok) {
+          const full = await runGit(
+            ['diff', '--no-color', ...(args.staged ? ['--cached'] : []), ...(relPath ? ['--', relPath] : [])],
+            { cwd: workspace.root },
+          );
+          detail = boundLines(full.stdout, maxLines);
+        }
+        logger?.debug('git inspected', { action: args.action, ok: result.ok });
+        return {
+          available: true,
+          action: args.action,
+          ok: result.ok,
+          exit_code: result.code,
+          cwd: workspace.root,
+          output: bounded.text,
+          truncated: bounded.truncated || Boolean(detail?.truncated),
+          ...(detail ? { diff: detail.text } : {}),
+          ...(result.stderr ? { stderr: result.stderr.slice(0, 2000) } : {}),
+        };
+      },
+    }),
+  ];
+}

package/src/tools/index.js

@@ -0,0 +1,48 @@
+import { ToolRegistry } from './registry.js';
+import { createFilesystemTools } from './filesystem.js';
+import { createSearchTools } from './search.js';
+import { createGitTools } from './git.js';
+import { createProjectTools } from './project.js';
+import { createShellTools } from './shell.js';
+import { createWebTools } from './web.js';
+import { createUrlTools } from './url.js';
+import { createWebSearchManager } from '../services/websearch/manager.js';
+
+/**
+ * Build the complete built-in tool registry. Collisions throw here.
+ *
+ * One WebSearchManager is shared by `web_search` and `read_url`, so provider
+ * connections are reused and a page-extraction fallback can use a provider
+ * discovered by an earlier search. The manager is exposed on the registry so
+ * `/web` and `close()` can reach the same instance.
+ */
+export function buildToolRegistry({
+  workspace,
+  config,
+  processes,
+  logger = null,
+  webManager = null,
+  onEvent = null,
+}) {
+  const registry = new ToolRegistry({ logger });
+  const manager = webManager || createWebSearchManager({ config, logger, onEvent });
+  const groups = [
+    createFilesystemTools({ workspace, config }),
+    createSearchTools({ workspace, config, logger }),
+    createGitTools({ workspace, logger }),
+    createProjectTools({ workspace, logger }),
+    createShellTools({ workspace, config, processes, logger }),
+    // read_url needs no key, so it is always available: search snippets are
+    // leads, and the model must be able to open the source page. When a local
+    // fetch cannot read the page, an extraction-capable provider is tried.
+    createUrlTools({ logger, webManager: manager }),
+    // Empty when no provider is configured: the model never sees a tool that
+    // cannot run, and the system prompt catalog stays accurate.
+    createWebTools({ config, logger, manager }),
+  ];
+  for (const tools of groups) {
+    for (const tool of tools) registry.register(tool);
+  }
+  registry.webSearchManager = manager;
+  return registry;
+}

package/src/tools/project.js

@@ -0,0 +1,160 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { defineTool } from './registry.js';
+import { isIgnoredName, isSecretPath } from '../services/workspace.js';
+import { ToolError } from '../utils/errors.js';
+
+const LANGUAGE_BY_EXT = {
+  '.js': 'JavaScript', '.mjs': 'JavaScript', '.cjs': 'JavaScript',
+  '.ts': 'TypeScript', '.tsx': 'TypeScript', '.jsx': 'JavaScript',
+  '.py': 'Python', '.go': 'Go', '.rs': 'Rust', '.java': 'Java', '.rb': 'Ruby',
+  '.php': 'PHP', '.cs': 'C#', '.cpp': 'C++', '.c': 'C', '.sh': 'Shell',
+  '.css': 'CSS', '.scss': 'SCSS', '.html': 'HTML', '.md': 'Markdown',
+  '.json': 'JSON', '.yml': 'YAML', '.yaml': 'YAML', '.sql': 'SQL',
+};
+
+const MAX_FILES = 3000;
+
+export async function buildProjectSummary({ workspace }) {
+  const summary = {
+    workspace: workspace.root,
+    name: null,
+    version: null,
+    description: null,
+    packageManager: null,
+    scripts: {},
+    dependencies: [],
+    devDependencies: [],
+    engines: null,
+    entryPoints: [],
+    languages: {},
+    modules: [],
+    topLevel: [],
+    totalFilesScanned: 0,
+    hasReadme: false,
+    hasTests: false,
+    hasGit: false,
+    truncated: false,
+  };
+
+  try {
+    const listing = await workspace.list('.', { limit: 50, includeGenerated: false, includeHidden: true });
+    summary.topLevel = listing.entries.map((entry) => `${entry.kind === 'dir' ? 'dir ' : 'file'} ${entry.name}`);
+    summary.hasReadme = listing.entries.some((entry) => /^readme(\.(md|txt|rst))?$/i.test(entry.name));
+    summary.hasTests = listing.entries.some((entry) => /^(tests?|__tests__|spec)$/i.test(entry.name));
+    // Immediate sub-directories of every top-level directory: the module
+    // layout the model needs to know (e.g. plugins/<category>/<command>).
+    for (const entry of listing.entries) {
+      if (entry.kind !== 'dir') continue;
+      if (summary.modules.length >= 120) break;
+      const children = await workspace.list(entry.name, { limit: 60, includeGenerated: false, includeHidden: false });
+      for (const child of children.entries) {
+        if (child.kind !== 'dir') continue;
+        summary.modules.push(`${entry.name}/${child.name}`);
+        if (summary.modules.length >= 120) break;
+      }
+    }
+  } catch {
+    // Listing failures are reported by the languages walk below.
+  }
+
+  summary.hasGit = await fileExists(path.join(workspace.root, '.git'));
+
+  let pkg = null;
+  try {
+    pkg = JSON.parse(await fsp.readFile(path.join(workspace.root, 'package.json'), 'utf8'));
+  } catch {
+    pkg = null;
+  }
+  if (pkg) {
+    summary.name = pkg.name || null;
+    summary.version = pkg.version || null;
+    summary.description = pkg.description || null;
+    summary.scripts = pkg.scripts || {};
+    summary.dependencies = Object.keys(pkg.dependencies || {}).sort();
+    summary.devDependencies = Object.keys(pkg.devDependencies || {}).sort();
+    summary.engines = pkg.engines || null;
+    summary.packageManager = pkg.packageManager || null;
+    summary.entryPoints = [pkg.main, pkg.module, pkg.bin && (typeof pkg.bin === 'string' ? pkg.bin : Object.values(pkg.bin)[0])]
+      .filter(Boolean);
+  }
+  if (!summary.packageManager) {
+    for (const [file, manager] of [['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['package-lock.json', 'npm'], ['bun.lockb', 'bun']]) {
+      if (await fileExists(path.join(workspace.root, file))) {
+        summary.packageManager = manager;
+        break;
+      }
+    }
+  }
+
+  const stack = [workspace.root];
+  let scanned = 0;
+  while (stack.length > 0 && scanned < MAX_FILES) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await fsp.readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        if (isIgnoredName(entry.name)) continue;
+        stack.push(path.join(dir, entry.name));
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const rel = path.relative(workspace.root, path.join(dir, entry.name)).split(path.sep).join('/');
+      if (isSecretPath(rel)) continue;
+      scanned += 1;
+      if (scanned >= MAX_FILES) {
+        summary.truncated = true;
+        break;
+      }
+      const language = LANGUAGE_BY_EXT[path.extname(entry.name).toLowerCase()];
+      if (language) summary.languages[language] = (summary.languages[language] || 0) + 1;
+    }
+  }
+  summary.totalFilesScanned = scanned;
+  summary.languages = Object.fromEntries(
+    Object.entries(summary.languages).sort((a, b) => b[1] - a[1]),
+  );
+  return summary;
+}
+
+async function fileExists(target) {
+  try {
+    await fsp.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function createProjectTools({ workspace }) {
+  return [
+    defineTool({
+      name: 'project_summary',
+      description:
+        'Summarize the project from real files: manifests, scripts, dependencies, entry points, language mix, top-level layout, tests and Git presence. Use this instead of guessing.',
+      risk: 'read',
+      schema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', minLength: 1, maxLength: 4096, description: 'Subdirectory to summarize (default workspace root).' },
+        },
+        additionalProperties: false,
+      },
+      handler: async (args) => {
+        if (args.path && args.path !== '.') {
+          const resolved = workspace.resolve(args.path);
+          const stat = await fsp.stat(resolved.absPath).catch(() => null);
+          if (!stat) throw new ToolError(`Path not found: ${args.path}`);
+          if (!stat.isDirectory()) throw new ToolError('project_summary expects a directory.');
+        }
+        return buildProjectSummary({ workspace });
+      },
+    }),
+  ];
+}