octboos 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xoner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# octboos
+
+> One agent to control every AI tool.
+
+[![npm version](https://img.shields.io/npm/v/octboos.svg)](https://www.npmjs.com/package/octboos)
+[![license](https://img.shields.io/npm/l/octboos.svg)](https://www.npmjs.com/package/octboos)
+[![node version](https://img.shields.io/node/v/octboos.svg)](https://www.npmjs.com/package/octboos)
+
+## The Problem
+AI coding tools start from zero every session. They don't remember your project structure, dependencies, or conventions, wasting tokens and breaking context.
+
+## The Solution
+octboos creates a `.agent/` directory in your project—a persistent memory bank that any AI tool can read to understand your codebase instantly.
+
+## Quick Start
+```bash
+npx octboos init
+```
+
+## What it generates
+The `.agent/` directory contains:
+```
+.agent/
+├── config.json     # Octboos configuration and selected AI tools
+├── map.md          # Project structure, dependencies, and tech stack
+├── style.md        # Your coding conventions and preferences
+└── wiki/           # Auto-generated documentation for modules and components
+```
+
+## Supported AI Tools
+| Tool          | Configuration File |
+|---------------|--------------------|
+| Claude Code   | CLAUDE.md          |
+| OpenCode      | AGENTS.md          |
+| Cursor        | .cursor/rules      |
+| Aider         | .aider.conf.yml    |
+| Gemini CLI    | GEMINI.md          |
+| Codex CLI     | (no file, uses context) |
+| Windsurf      | .windsurfrules     |
+| GitHub Copilot| .github/copilot-instructions.md |
+
+## Commands
+- `octboos init`   — Initialize octboos in your project (creates .agent/)
+- `octboos sync`   — Update .agent/ with latest project changes
+- `octboos status` — Show current octboos configuration and file stats
+
+## How it works
+1. **Scan** — octboos analyzes your project structure, dependencies, and files
+2. **Generate** — creates/updates .agent/ with context for AI tools
+3. **AI reads** — your AI tool loads .agent/ files to understand your project instantly
+
+## License
+MIT

package/bin/octboos.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+program
+  .name('octboos')
+  .description('One agent to control every AI tool')
+  .version(pkg.version);
+
+// Commands
+const { initCommand }   = await import('../src/commands/init.js');
+const { syncCommand }   = await import('../src/commands/sync.js');
+const { statusCommand } = await import('../src/commands/status.js');
+
+program
+  .command('init')
+  .description('Initialize Octboos in current project')
+  .option('-y, --yes', 'Skip prompts, use defaults')
+  .option('--adapters <list>', 'Comma-separated adapters: claude,codex,cursor,windsurf,copilot')
+  .action(initCommand);
+
+program
+  .command('sync')
+  .description('Sync and update .agent/ wiki and context')
+  .option('--incremental', 'Only update changed files')
+  .action(syncCommand);
+
+program
+  .command('status')
+  .description('Show current Octboos status for this project')
+  .action(statusCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "octboos",
+  "version": "0.1.2",
+  "description": "One agent to control every AI tool",
+  "keywords": [
+    "ai",
+    "agent",
+    "claude",
+    "codex",
+    "cursor",
+    "context",
+    "memory",
+    "wiki"
+  ],
+  "author": "xoner",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "octboos": "bin/octboos.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "dev": "node bin/octboos.js",
+    "test": "node --test"
+  },
+  "homepage": "https://github.com/Xoner1/octboos",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xoner1/octboos.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Xoner1/octboos/issues"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^3.3.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fast-glob": "^3.3.2",
+    "ora": "^8.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/adapters/index.js

@@ -0,0 +1,116 @@
+// All supported AI tool adapters
+export const ADAPTERS = {
+  claude: {
+    name:        'Claude Code',
+    file:        'CLAUDE.md',
+    description: 'Anthropic Claude Code',
+  },
+  codex: {
+    name:        'Codex / OpenCode',
+    file:        'AGENTS.md',
+    description: 'OpenAI Codex CLI & OpenCode',
+  },
+  cursor: {
+    name:        'Cursor',
+    file:        '.cursor/rules',
+    description: 'Cursor IDE',
+  },
+  windsurf: {
+    name:        'Windsurf',
+    file:        '.windsurfrules',
+    description: 'Windsurf IDE',
+  },
+  copilot: {
+    name:        'GitHub Copilot',
+    file:        '.github/copilot-instructions.md',
+    description: 'GitHub Copilot',
+  },
+  gemini: {
+    name:        'Gemini CLI',
+    file:        'GEMINI.md',
+    description: 'Google Gemini CLI',
+  },
+};
+
+export function generateAdapterContent(adapterKey, projectName) {
+  const header = buildHeader(projectName);
+
+  switch (adapterKey) {
+    case 'claude':
+      return `${header}
+
+## Octboos Instructions
+> This file is auto-managed by Octboos. Edit \`.agent/\` files instead.
+
+## Before Every Task
+1. Read \`.agent/map.md\` for project structure
+2. Check \`.agent/wiki/\` for module documentation
+3. Follow conventions in \`.agent/style.md\`
+4. After completing a task, update relevant \`.agent/wiki/\` files
+
+## Quick Reference
+- Project map: \`.agent/map.md\`
+- Code wiki:   \`.agent/wiki/\`
+- User style:  \`.agent/style.md\`
+- Octboos config: \`.agent/config.json\`
+`;
+
+    case 'codex':
+      return `${header}
+
+## Octboos Context
+> Auto-managed by Octboos. Source of truth: \`.agent/\`
+
+## Required Reading
+Before any task, read:
+- \`.agent/map.md\` — project structure and stack
+- \`.agent/wiki/\` — module documentation  
+- \`.agent/style.md\` — coding conventions
+
+## Update Rule
+After completing any task, sync relevant docs:
+\`\`\`
+npx octboos sync --incremental
+\`\`\`
+`;
+
+    case 'cursor':
+    case 'windsurf':
+      return `# Octboos Context for ${ADAPTERS[adapterKey].name}
+> Auto-managed. Edit .agent/ files instead.
+
+Always read .agent/map.md before starting any task.
+Follow conventions in .agent/style.md.
+Reference .agent/wiki/ for module documentation.
+`;
+
+    case 'copilot':
+      return `# GitHub Copilot Instructions
+> Managed by Octboos
+
+## Context Files
+- \`.agent/map.md\` — project map and stack
+- \`.agent/wiki/\` — module documentation
+- \`.agent/style.md\` — code style and conventions
+
+Always reference these files before suggesting code changes.
+`;
+
+    case 'gemini':
+      return `${header}
+
+## Octboos Context
+Read \`.agent/map.md\` and \`.agent/wiki/\` before any task.
+Follow \`.agent/style.md\` for code conventions.
+`;
+
+    default:
+      return header;
+  }
+}
+
+function buildHeader(projectName) {
+  return `# ${projectName || 'Project'} — Octboos Context
+> Last synced: ${new Date().toISOString().split('T')[0]}
+> Managed by Octboos (https://github.com/Octboos1/octboos.git)`;
+}

package/src/commands/init.js

@@ -0,0 +1,259 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { input, checkbox, confirm } from '@inquirer/prompts';
+import { scanProject, buildFileMap, detectInstalledTools } from '../indexer/scanner.js';
+import { ADAPTERS, generateAdapterContent } from '../adapters/index.js';
+
+const AGENT_DIR = '.agent';
+
+export async function initCommand(options) {
+  console.log('');
+  console.log(chalk.bold.cyan('  ╔═══════════════════════════════╗'));
+  console.log(chalk.bold.cyan('  ║   Octboos — Init               ║'));
+  console.log(chalk.bold.cyan('  ║   Transform your AI tool      ║'));
+  console.log(chalk.bold.cyan('  ╚═══════════════════════════════╝'));
+  console.log('');
+
+  const cwd = process.cwd();
+
+  // Check if already initialized
+  if (existsSync(join(cwd, AGENT_DIR, 'config.json'))) {
+    console.log(chalk.yellow('  ⚠  Octboos already initialized in this project.'));
+    console.log(chalk.gray('     Run ' + chalk.white('npx octboos sync') + ' to update.'));
+    console.log('');
+    return;
+  }
+
+  // Step 0 — Detect installed AI tools
+  let detectedTools = { detected: [], uncertain: [], notFound: [] };
+  try {
+    detectedTools = detectInstalledTools();
+    if (detectedTools.detected.length > 0) {
+      console.log(chalk.gray(`  🔍 Found ${detectedTools.detected.length} tools on your machine`));
+      console.log('');
+    }
+  } catch (err) {
+    // Silently fall back to manual selection if detection fails
+  }
+
+   // Step 1 — Project name
+   let projectName;
+   try {
+     const pkgPath = join(cwd, 'package.json');
+     projectName = existsSync(pkgPath)
+       ? JSON.parse(readFileSync(pkgPath, 'utf8')).name || ''
+       : '';
+   } catch { projectName = ''; }
+
+   if (!options.yes) {
+     projectName = await input({
+       message: 'Project name:',
+       default: projectName || 'my-project',
+     });
+   }
+
+   // Step 2 — Choose adapters
+   let selectedAdapters = [];
+
+   if (!options.yes && !options.adapters) {
+     // Build choices with pre-checked detected tools
+     const choices = Object.entries(ADAPTERS).map(([key, val]) => {
+       let checked = false;
+       let name = `${val.name} (${val.file})`;
+       
+       // Check if detected
+       if (detectedTools.detected.includes(key)) {
+         checked = true;
+       }
+       // Check if uncertain
+       else if (detectedTools.uncertain.includes(key)) {
+         name += ' (not sure)';
+       }
+       
+       return {
+         name,
+         value: key,
+         checked
+       };
+     });
+
+     selectedAdapters = await checkbox({
+       message: 'Which AI tools do you use?',
+       choices
+     });
+   } else if (options.adapters) {
+     selectedAdapters = options.adapters.split(',').map(s => s.trim());
+   } else {
+     // Default fallback when options.yes is true
+     selectedAdapters = ['claude', 'codex'];
+   }
+
+   // Step 3 — Scan project
+  const spinner = ora({
+    text: chalk.gray('Scanning project...'),
+    color: 'cyan',
+  }).start();
+
+  let scanResult;
+  try {
+    scanResult = await scanProject(cwd);
+    spinner.succeed(chalk.green(`Scanned ${scanResult.fileCount} files`));
+  } catch (err) {
+    spinner.fail('Failed to scan project');
+    console.error(err);
+    return;
+  }
+
+  // Step 4 — Create .agent/ directory
+  const agentDir = join(cwd, AGENT_DIR);
+  const wikiDir  = join(agentDir, 'wiki');
+
+  mkdirSync(agentDir, { recursive: true });
+  mkdirSync(wikiDir,  { recursive: true });
+
+  // Step 5 — Generate files
+  const genSpinner = ora({ text: chalk.gray('Generating context files...'), color: 'cyan' }).start();
+
+  // config.json
+  const config = {
+    version:    '0.1.0',
+    projectName,
+    adapters:   selectedAdapters,
+    autoSync:   true,
+    created:    new Date().toISOString(),
+    lastSync:   new Date().toISOString(),
+  };
+  writeFileSync(join(agentDir, 'config.json'), JSON.stringify(config, null, 2));
+
+  // map.md
+  const mapContent = buildFileMap(scanResult, cwd);
+  writeFileSync(join(agentDir, 'map.md'), mapContent);
+
+  // style.md
+  writeFileSync(join(agentDir, 'style.md'), buildStyleTemplate(projectName));
+
+  // wiki/INDEX.md
+  writeFileSync(join(wikiDir, 'INDEX.md'), buildWikiIndex(projectName, scanResult));
+
+  genSpinner.succeed(chalk.green('Generated .agent/ context files'));
+
+  // Step 6 — Generate adapter files
+  const adapterSpinner = ora({ text: chalk.gray('Configuring AI tools...'), color: 'cyan' }).start();
+
+  const generatedAdapters = [];
+  for (const adapterKey of selectedAdapters) {
+    const adapter = ADAPTERS[adapterKey];
+    if (!adapter) continue;
+
+    const filePath = join(cwd, adapter.file);
+    const fileDir  = dirname(filePath);
+
+    mkdirSync(fileDir, { recursive: true });
+
+    // Don't overwrite existing files — append Octboos section
+    if (existsSync(filePath)) {
+      const existing = readFileSync(filePath, 'utf8');
+      if (!existing.includes('Octboos')) {
+        writeFileSync(filePath, existing + '\n\n' + generateAdapterContent(adapterKey, projectName));
+      }
+    } else {
+      writeFileSync(filePath, generateAdapterContent(adapterKey, projectName));
+    }
+
+    generatedAdapters.push(adapter.file);
+  }
+
+  adapterSpinner.succeed(chalk.green(`Configured ${generatedAdapters.length} AI tools`));
+
+  // Step 7 — Add to .gitignore if needed (keep .agent/ tracked)
+  const gitignorePath = join(cwd, '.gitignore');
+  if (existsSync(gitignorePath)) {
+    const gitignore = readFileSync(gitignorePath, 'utf8');
+    if (!gitignore.includes('.agent/graph.html')) {
+      writeFileSync(gitignorePath, gitignore + '\n# Octboos - keep .agent/ tracked except large files\n.agent/graph.html\n');
+    }
+  }
+
+  // Done!
+  console.log('');
+  console.log(chalk.bold.green('  ✓ Octboos initialized successfully!'));
+  console.log('');
+  console.log(chalk.gray('  Created:'));
+  console.log(chalk.white('  .agent/'));
+  console.log(chalk.gray('  ├── ') + chalk.white('config.json  ') + chalk.gray('← Octboos config'));
+  console.log(chalk.gray('  ├── ') + chalk.white('map.md       ') + chalk.gray('← project structure'));
+  console.log(chalk.gray('  ├── ') + chalk.white('style.md     ') + chalk.gray('← coding conventions'));
+  console.log(chalk.gray('  └── ') + chalk.white('wiki/        ') + chalk.gray('← auto documentation'));
+  console.log('');
+  console.log(chalk.gray('  AI configs:'));
+  for (const f of generatedAdapters) {
+    console.log(chalk.gray('  ✓ ') + chalk.white(f));
+  }
+  console.log('');
+  console.log(chalk.bold('  Next steps:'));
+  console.log(chalk.cyan('  1.') + chalk.white(' Edit .agent/style.md with your coding conventions'));
+  console.log(chalk.cyan('  2.') + chalk.white(' Run npx octboos sync to update wiki'));
+  console.log(chalk.cyan('  3.') + chalk.white(' Commit .agent/ to git'));
+  console.log('');
+}
+
+function buildStyleTemplate(projectName) {
+  return `# Coding Style — ${projectName}
+> Edit this file to teach Octboos your preferences.
+> Last updated: ${new Date().toISOString().split('T')[0]}
+
+## General Conventions
+- [ ] Add your naming conventions here
+- [ ] Add your file structure preferences here
+
+## Code Style
+- [ ] Indentation: (tabs / 2 spaces / 4 spaces)
+- [ ] Quotes: (single / double)
+- [ ] Semicolons: (yes / no)
+
+## Architecture Patterns
+- [ ] Describe your patterns here (MVC, Repository, etc.)
+
+## What to Avoid
+- [ ] List anti-patterns specific to this project
+
+## Useful Commands
+\`\`\`bash
+# Add your most-used project commands here
+# npm run dev
+# npm run build
+# npm test
+\`\`\`
+`;
+}
+
+function buildWikiIndex(projectName, scanResult) {
+  const lines = [
+    `# Wiki — ${projectName}`,
+    `> Auto-generated by Octboos | ${new Date().toISOString().split('T')[0]}`,
+    '',
+    '## Modules',
+    '> Add module documentation here or run `npx octboos sync` to auto-generate.',
+    '',
+    '## Stack Summary',
+  ];
+
+  if (scanResult.frameworks.length > 0) {
+    lines.push(`**Frameworks:** ${scanResult.frameworks.join(', ')}`);
+  }
+  if (scanResult.stack.length > 0) {
+    lines.push(`**Libraries:** ${scanResult.stack.join(', ')}`);
+  }
+
+  const langs = Object.entries(scanResult.languages)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 3)
+    .map(([l]) => l);
+  if (langs.length > 0) {
+    lines.push(`**Languages:** ${langs.join(', ')}`);
+  }
+
+  return lines.join('\n');
+}

package/src/commands/status.js

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+
+export async function statusCommand() {
+  const cwd = process.cwd();
+  const configPath = join(cwd, '.agent', 'config.json');
+
+  console.log('');
+
+  if (!existsSync(configPath)) {
+    console.log(chalk.yellow('  ✗ Octboos not initialized in this project'));
+    console.log(chalk.gray('    Run: ') + chalk.white('npx octboos init'));
+    console.log('');
+    return;
+  }
+
+  const config = JSON.parse(readFileSync(configPath, 'utf8'));
+  const lastSync = new Date(config.lastSync);
+  const hoursSince = Math.floor((Date.now() - lastSync) / 1000 / 60 / 60);
+
+  console.log(chalk.bold.cyan('  Octboos Status'));
+  console.log('');
+  console.log(chalk.gray('  Project:    ') + chalk.white(config.projectName));
+  console.log(chalk.gray('  Version:    ') + chalk.white(config.version));
+  console.log(chalk.gray('  Last sync:  ') + (
+    hoursSince < 24
+      ? chalk.green(`${hoursSince}h ago`)
+      : chalk.yellow(`${Math.floor(hoursSince / 24)}d ago — run octboos sync`)
+  ));
+
+  // Files
+  console.log('');
+  console.log(chalk.gray('  Context files:'));
+  const agentFiles = [
+    ['map.md',      'Project structure'],
+    ['style.md',    'Coding style'],
+    ['config.json', 'Octboos config'],
+  ];
+  for (const [file, desc] of agentFiles) {
+    const exists = existsSync(join(cwd, '.agent', file));
+    console.log(
+      '  ' + (exists ? chalk.green('✓') : chalk.red('✗')) + ' ' +
+      chalk.white(`.agent/${file}`) + chalk.gray(` — ${desc}`)
+    );
+  }
+
+  // Wiki
+  const wikiDir = join(cwd, '.agent', 'wiki');
+  if (existsSync(wikiDir)) {
+    const wikiFiles = readdirSync(wikiDir).filter(f => f.endsWith('.md'));
+    console.log('');
+    console.log(chalk.gray(`  Wiki: ${wikiFiles.length} files`));
+    for (const f of wikiFiles.slice(0, 5)) {
+      console.log(chalk.gray('  ·  ') + chalk.white(`.agent/wiki/${f}`));
+    }
+    if (wikiFiles.length > 5) {
+      console.log(chalk.gray(`  ... and ${wikiFiles.length - 5} more`));
+    }
+  }
+
+  // Adapters
+  console.log('');
+  console.log(chalk.gray('  AI tools configured:'));
+  const { ADAPTERS } = await import('../adapters/index.js');
+  for (const adapterKey of config.adapters) {
+    const adapter = ADAPTERS[adapterKey];
+    if (!adapter) continue;
+    const exists = existsSync(join(cwd, adapter.file));
+    console.log(
+      '  ' + (exists ? chalk.green('✓') : chalk.red('✗')) + ' ' +
+      chalk.white(adapter.name) + chalk.gray(` (${adapter.file})`)
+    );
+  }
+
+  console.log('');
+}

package/src/commands/sync.js

@@ -0,0 +1,55 @@
+import { existsSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { scanProject, buildFileMap } from '../indexer/scanner.js';
+import { ADAPTERS, generateAdapterContent } from '../adapters/index.js';
+
+export async function syncCommand(options) {
+  const cwd = process.cwd();
+  const configPath = join(cwd, '.agent', 'config.json');
+
+  if (!existsSync(configPath)) {
+    console.log('');
+    console.log(chalk.yellow('  ⚠  Octboos not initialized.'));
+    console.log(chalk.gray('     Run ' + chalk.white('npx octboos init') + ' first.'));
+    console.log('');
+    return;
+  }
+
+  const config = JSON.parse(readFileSync(configPath, 'utf8'));
+  console.log('');
+  console.log(chalk.bold.cyan(`  Octboos Sync — ${config.projectName}`));
+  console.log('');
+
+  // Scan project
+  const spinner = ora({ text: chalk.gray('Scanning project...'), color: 'cyan' }).start();
+  const scanResult = await scanProject(cwd);
+  spinner.succeed(chalk.green(`Scanned ${scanResult.fileCount} files`));
+
+  // Update map.md
+  const mapSpinner = ora({ text: chalk.gray('Updating map.md...'), color: 'cyan' }).start();
+  const mapContent = buildFileMap(scanResult, cwd);
+  writeFileSync(join(cwd, '.agent', 'map.md'), mapContent);
+  mapSpinner.succeed(chalk.green('Updated .agent/map.md'));
+
+  // Update adapter files
+  const adapterSpinner = ora({ text: chalk.gray('Updating AI tool configs...'), color: 'cyan' }).start();
+  for (const adapterKey of config.adapters) {
+    const adapter = ADAPTERS[adapterKey];
+    if (!adapter) continue;
+    const filePath = join(cwd, adapter.file);
+    if (existsSync(filePath)) {
+      writeFileSync(filePath, generateAdapterContent(adapterKey, config.projectName));
+    }
+  }
+  adapterSpinner.succeed(chalk.green('Updated AI tool configs'));
+
+  // Update lastSync in config
+  config.lastSync = new Date().toISOString();
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+  console.log('');
+  console.log(chalk.bold.green('  ✓ Sync complete!'));
+  console.log('');
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { scanProject, buildFileMap } from './indexer/scanner.js';
+export { ADAPTERS, generateAdapterContent } from './adapters/index.js';

package/src/indexer/scanner.js

@@ -0,0 +1,285 @@
+import { readFileSync, existsSync } from 'fs';
+import { join, extname, relative } from 'path';
+import fg from 'fast-glob';
+import { execSync } from 'child_process';
+
+// File extensions by language
+const LANG_MAP = {
+  '.ts': 'TypeScript', '.tsx': 'TypeScript/React',
+  '.js': 'JavaScript', '.jsx': 'JavaScript/React',
+  '.py': 'Python',     '.go': 'Go',
+  '.rs': 'Rust',       '.java': 'Java',
+  '.php': 'PHP',       '.rb': 'Ruby',
+  '.vue': 'Vue',       '.svelte': 'Svelte',
+  '.css': 'CSS',       '.scss': 'SCSS',
+  '.sql': 'SQL',       '.prisma': 'Prisma',
+};
+
+// Framework detection by file presence
+const FRAMEWORK_SIGNALS = [
+  { file: 'next.config.js',        name: 'Next.js' },
+  { file: 'next.config.ts',        name: 'Next.js' },
+  { file: 'nuxt.config.ts',        name: 'Nuxt.js' },
+  { file: 'vite.config.ts',        name: 'Vite' },
+  { file: 'remix.config.js',       name: 'Remix' },
+  { file: 'astro.config.mjs',      name: 'Astro' },
+  { file: 'svelte.config.js',      name: 'SvelteKit' },
+  { file: 'angular.json',          name: 'Angular' },
+  { file: 'manage.py',             name: 'Django' },
+  { file: 'requirements.txt',      name: 'Python' },
+  { file: 'Cargo.toml',            name: 'Rust' },
+  { file: 'go.mod',                name: 'Go' },
+  { file: 'composer.json',         name: 'PHP/Laravel' },
+  { file: 'artisan',               name: 'Laravel' },
+];
+
+const IGNORE_DIRS = [
+  '**/node_modules/**', '**/.git/**', '**/dist/**',
+  '**/build/**', '**/.next/**', '**/coverage/**',
+  '**/.agent/**', '**/vendor/**', '**/__pycache__/**'
+];
+
+export async function scanProject(cwd = process.cwd()) {
+  const result = {
+    stack:      [],
+    frameworks: [],
+    languages:  {},
+    structure:  [],
+    fileCount:  0,
+    hasTests:   false,
+    hasPrisma:  false,
+    hasDocker:  false,
+    packageJson: null,
+    gitIgnore:  null,
+  };
+
+  // Read package.json if exists
+  const pkgPath = join(cwd, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      result.packageJson = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      result.stack.push(...detectFromPackageJson(result.packageJson));
+    } catch {}
+  }
+
+  // Detect frameworks by file presence
+  for (const signal of FRAMEWORK_SIGNALS) {
+    if (existsSync(join(cwd, signal.file))) {
+      result.frameworks.push(signal.name);
+    }
+  }
+
+  // Scan all files
+  const files = await fg('**/*', {
+    cwd,
+    ignore: IGNORE_DIRS,
+    onlyFiles: true,
+    dot: false,
+  });
+
+  result.fileCount = files.length;
+
+  // Count languages
+  for (const file of files) {
+    const ext = extname(file);
+    if (LANG_MAP[ext]) {
+      result.languages[LANG_MAP[ext]] = (result.languages[LANG_MAP[ext]] || 0) + 1;
+    }
+    if (file.includes('.test.') || file.includes('.spec.') || file.includes('__tests__')) {
+      result.hasTests = true;
+    }
+    if (file.endsWith('.prisma')) result.hasPrisma = true;
+    if (file === 'Dockerfile' || file === 'docker-compose.yml') result.hasDocker = true;
+  }
+
+  // Build top-level structure
+  const topLevel = await fg('*', {
+    cwd,
+    ignore: IGNORE_DIRS,
+    onlyDirectories: true,
+  });
+  result.structure = topLevel;
+
+  return result;
+}
+
+function detectFromPackageJson(pkg) {
+  const stack = [];
+  const allDeps = {
+    ...pkg.dependencies || {},
+    ...pkg.devDependencies || {}
+  };
+
+  const checks = [
+    ['react',          'React'],
+    ['vue',            'Vue'],
+    ['svelte',         'Svelte'],
+    ['express',        'Express'],
+    ['fastify',        'Fastify'],
+    ['prisma',         'Prisma'],
+    ['mongoose',       'MongoDB/Mongoose'],
+    ['typeorm',        'TypeORM'],
+    ['drizzle-orm',    'Drizzle ORM'],
+    ['tailwindcss',    'Tailwind CSS'],
+    ['@mui/material',  'Material UI'],
+    ['next-auth',      'NextAuth'],
+    ['@clerk/nextjs',  'Clerk Auth'],
+    ['zod',            'Zod'],
+    ['trpc',           'tRPC'],
+    ['graphql',        'GraphQL'],
+    ['socket.io',      'Socket.io'],
+    ['jest',           'Jest'],
+    ['vitest',         'Vitest'],
+    ['playwright',     'Playwright'],
+  ];
+
+  for (const [dep, name] of checks) {
+    if (allDeps[dep]) stack.push(name);
+  }
+
+  return stack;
+}
+
+export function buildFileMap(scanResult, cwd) {
+  const lines = [];
+
+  lines.push('# Project File Map');
+  lines.push(`> Generated by Octboos | ${new Date().toISOString().split('T')[0]}`);
+  lines.push('');
+
+  // Frameworks & Stack
+  if (scanResult.frameworks.length > 0) {
+    lines.push('## Frameworks');
+    for (const f of scanResult.frameworks) lines.push(`- ${f}`);
+    lines.push('');
+  }
+
+  if (scanResult.stack.length > 0) {
+    lines.push('## Stack & Libraries');
+    for (const s of scanResult.stack) lines.push(`- ${s}`);
+    lines.push('');
+  }
+
+  // Languages
+  const langs = Object.entries(scanResult.languages)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5);
+  if (langs.length > 0) {
+    lines.push('## Languages');
+    for (const [lang, count] of langs) {
+      lines.push(`- ${lang}: ${count} files`);
+    }
+    lines.push('');
+  }
+
+  // Directory structure
+  if (scanResult.structure.length > 0) {
+    lines.push('## Directory Structure');
+    for (const dir of scanResult.structure) {
+      lines.push(`- \`${dir}/\``);
+    }
+    lines.push('');
+  }
+
+  // Features detected
+  const features = [];
+  if (scanResult.hasTests)  features.push('Tests');
+  if (scanResult.hasPrisma) features.push('Prisma ORM');
+  if (scanResult.hasDocker) features.push('Docker');
+  if (features.length > 0) {
+    lines.push('## Detected Features');
+    for (const f of features) lines.push(`- ${f}`);
+    lines.push('');
+  }
+
+  lines.push(`## Stats`);
+  lines.push(`- Total files: ${scanResult.fileCount}`);
+
+   return lines.join('\n');
+}
+
+export function detectInstalledTools() {
+  const result = {
+    detected: [],
+    uncertain: [],
+    notFound: ['claude', 'opencode', 'cursor', 'aider', 'gemini', 'codex', 'windsurf']
+  };
+
+  // Tools to check via which/where
+  const cliTools = [
+    { name: 'claude', command: 'claude' },
+    { name: 'opencode', command: 'opencode' },
+    { name: 'cursor', command: 'cursor' },
+    { name: 'aider', command: 'aider' },
+    { name: 'gemini', command: 'gemini' },
+    { name: 'codex', command: 'codex' },
+    { name: 'windsurf', command: 'windsurf' }
+  ];
+
+  // Check CLI tools
+  for (const tool of cliTools) {
+    try {
+      const platform = process.platform;
+      let command;
+      if (platform === 'win32') {
+        command = `where ${tool.command}`;
+      } else {
+        command = `which ${tool.command}`;
+      }
+      execSync(command, { stdio: 'ignore' });
+      // Move from notFound to detected
+      result.detected.push(tool.name);
+      result.notFound = result.notFound.filter(t => t !== tool.name);
+    } catch (err) {
+      // Tool not found via CLI, keep in notFound for now
+    }
+  }
+
+  // Check common paths
+  const home = process.env.HOME || process.env.USERPROFILE;
+  const localAppData = process.env.LOCALAPPDATA;
+  const appData = process.env.APPDATA;
+
+  // Mac paths
+  const macPaths = [
+    { tool: 'cursor', path: '/Applications/Cursor.app' },
+    { tool: 'windsurf', path: '/Applications/Windsurf.app' },
+    { tool: 'claude', path: `${home}/.claude/` },
+    { tool: 'aider', path: `${home}/.config/aider/` }
+  ];
+
+  // Windows paths
+  const winPaths = [
+    { tool: 'cursor', path: `${localAppData}\\Programs\\cursor` },
+    { tool: 'claude', path: `${appData}\\Claude\\` }
+  ];
+
+  const pathsToCheck = process.platform === 'win32' ? winPaths : macPaths;
+
+  for (const { tool, path } of pathsToCheck) {
+    try {
+      if (existsSync(path)) {
+        // Move from notFound to detected if not already there
+        if (!result.detected.includes(tool)) {
+          result.detected.push(tool);
+          result.notFound = result.notFound.filter(t => t !== tool);
+        }
+        // If we found it via path but not CLI, mark as uncertain
+        if (!result.detected.includes(tool)) {
+          result.uncertain.push(tool);
+          result.notFound = result.notFound.filter(t => t !== tool);
+          result.detected = result.detected.filter(t => t !== tool);
+        }
+      }
+    } catch (err) {
+      // Path doesn't exist or other error
+    }
+  }
+
+  // Remove duplicates
+  result.detected = [...new Set(result.detected)];
+  result.uncertain = [...new Set(result.uncertain)];
+  result.notFound = [...new Set(result.notFound)];
+
+  return result;
+}