@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/overlay/data/tutorials/config/mcp-servers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP Servers Tutorial
+ *
+ * Covers MCP (Model Context Protocol) server configuration, transport types,
+ * the /mcp overlay, and tool discovery.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const mcpServersTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/config/mcp-servers.js

@@ -0,0 +1,155 @@
+/**
+ * MCP Servers Tutorial
+ *
+ * Covers MCP (Model Context Protocol) server configuration, transport types,
+ * the /mcp overlay, and tool discovery.
+ */
+export const mcpServersTutorial = (s) => ({
+    id: 'mcp-servers',
+    title: 'MCP Servers',
+    description: 'Connect external tool servers',
+    pages: [
+        // Page 1: What is MCP?
+        {
+            title: 'MCP Servers',
+            lines: [
+                '',
+                `  ${s.primaryBold('MCP')} (Model Context Protocol) lets you connect external`,
+                `  tool servers to extend the AI's capabilities.`,
+                '',
+                `  ${s.secondary('Examples of MCP servers:')}`,
+                '',
+                `    ${s.muted('•')} Filesystem access (read/write files in specific dirs)`,
+                `    ${s.muted('•')} GitHub integration (issues, PRs, code search)`,
+                `    ${s.muted('•')} Database connections (query, schema inspection)`,
+                `    ${s.muted('•')} Custom APIs (your own tools and services)`,
+                '',
+                `  ${s.secondary('How it works:')}`,
+                '',
+                `    ${s.muted('1.')} Configure servers in ${s.primary('mcp.json')}`,
+                `    ${s.muted('2.')} CLI connects on startup (non-blocking)`,
+                `    ${s.muted('3.')} Server tools are discovered automatically`,
+                `    ${s.muted('4.')} AI can call them like any other tool`,
+                '',
+                `  Tools appear as ${s.muted('mcp_{server}_{tool}')} in the tool list.`,
+                '',
+            ],
+        },
+        // Page 2: Configuration
+        {
+            title: 'Configuration',
+            lines: [
+                '',
+                `  MCP servers are configured in ${s.primaryBold('mcp.json')} files:`,
+                '',
+                `  ${s.secondary('Two config locations (merged):')}`,
+                '',
+                `    ${s.primaryBold('Global')}    ~/.compilr-dev/mcp.json`,
+                `    ${s.primaryBold('Project')}   <project>/.compilr-dev/mcp.json`,
+                '',
+                `  Project config overrides global by server name.`,
+                '',
+                `  ${s.secondary('Example config:')}`,
+                '',
+                `    ${s.muted('{')}`,
+                `    ${s.muted('  "mcpServers": {')}`,
+                `    ${s.muted('    "filesystem": {')}`,
+                `    ${s.muted('      "command": "npx",')}`,
+                `    ${s.muted('      "args": ["-y", "@mcp/server-filesystem", "/tmp"]')}`,
+                `    ${s.muted('    }')}`,
+                `    ${s.muted('  }')}`,
+                `    ${s.muted('}')}`,
+                '',
+                `  Format is compatible with Claude Desktop and Gemini CLI.`,
+                '',
+            ],
+        },
+        // Page 3: Transport Types
+        {
+            title: 'Transport Types',
+            lines: [
+                '',
+                `  ${s.secondary('Two transport types:')}`,
+                '',
+                `  ${s.primaryBold('stdio')} — Local command (spawns a child process)`,
+                '',
+                `    ${s.muted('{')}`,
+                `    ${s.muted('  "command": "npx",')}`,
+                `    ${s.muted('  "args": ["-y", "@mcp/server-github"],')}`,
+                `    ${s.muted('  "env": { "GITHUB_TOKEN": "ghp_xxx" }')}`,
+                `    ${s.muted('}')}`,
+                '',
+                `  ${s.primaryBold('HTTP')} — Remote server (makes HTTP requests)`,
+                '',
+                `    ${s.muted('{')}`,
+                `    ${s.muted('  "url": "https://mcp.example.com/db",')}`,
+                `    ${s.muted('  "headers": { "Authorization": "Bearer tok_xxx" }')}`,
+                `    ${s.muted('}')}`,
+                '',
+                `  ${s.secondary('Additional options:')}`,
+                '',
+                `    ${s.primaryBold('disabled')}   Skip server without removing config`,
+                `    ${s.primaryBold('timeout')}    Connection timeout (default 30s)`,
+                `    ${s.primaryBold('cwd')}        Working directory (stdio only)`,
+                '',
+            ],
+        },
+        // Page 4: The /mcp Overlay
+        {
+            title: 'The /mcp Overlay',
+            lines: [
+                '',
+                `  ${s.primary('/mcp')}  Open the MCP servers overlay.`,
+                '',
+                `  ${s.secondary('List view:')}`,
+                '',
+                `    Shows all servers with name, status, and tool count.`,
+                `    Status: ${s.success('connected')} ${s.warning('connecting')} ${s.error('error')} ${s.muted('disconnected')}`,
+                '',
+                `  ${s.secondary('Navigation:')}`,
+                '',
+                `    ${s.primaryBold('j/k')}     Move between servers`,
+                `    ${s.primaryBold('/')}       Search servers or tools`,
+                `    ${s.primaryBold('Enter')}   View server details and tool list`,
+                `    ${s.primaryBold('a')}       Add a new server (form-based wizard)`,
+                `    ${s.primaryBold('r')}       Restart selected server`,
+                `    ${s.primaryBold('d')}       Disconnect selected server`,
+                '',
+                `  ${s.secondary('Add server wizard:')}`,
+                '',
+                `  Press ${s.primaryBold('a')} to open a form where you enter the server`,
+                `  name, transport type, command/URL, and args. The server`,
+                `  connects immediately and tools are discovered on save.`,
+                '',
+            ],
+        },
+        // Page 5: Tips
+        {
+            title: 'Tips',
+            lines: [
+                '',
+                `  ${s.secondary('Startup behavior:')}`,
+                '',
+                `  MCP servers connect in the background during startup.`,
+                `  The CLI doesn't wait — you can start working immediately.`,
+                `  Status bar shows ${s.muted('mcp: connecting...')} until ready.`,
+                '',
+                `  ${s.secondary('Tool permissions:')}`,
+                '',
+                `  MCP tools go through the same permission system as built-in`,
+                `  tools. The first call to a new MCP tool triggers a prompt.`,
+                '',
+                `  ${s.secondary('Team agents:')}`,
+                '',
+                `  MCP tools are shared with all team agents automatically.`,
+                `  Every agent in the team can use the connected servers.`,
+                '',
+                `  ${s.secondary('Hot-reload:')}`,
+                '',
+                `  Add or restart servers at runtime via ${s.primary('/mcp')} without`,
+                `  restarting the CLI. New tools are available immediately.`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/config/model-selection.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Model Selection Tutorial
+ *
+ * Covers the /model overlay: provider tabs, tiers, API keys, model cycling.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const modelSelectionTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/config/model-selection.js

@@ -0,0 +1,162 @@
+/**
+ * Model Selection Tutorial
+ *
+ * Covers the /model overlay: provider tabs, tiers, API keys, model cycling.
+ */
+export const modelSelectionTutorial = (s) => ({
+    id: 'model-selection',
+    title: 'Model Selection',
+    description: 'Choose your AI model and provider',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Choosing Your AI Model',
+            lines: [
+                '',
+                `  ${s.primaryBold('The /model command opens the model selection overlay.')}`,
+                '',
+                `  compilr.dev supports ${s.primary('multiple AI providers')}:`,
+                '',
+                `    ${s.success('Claude')}          Anthropic's Claude models`,
+                `    ${s.success('OpenAI')}          GPT models`,
+                `    ${s.success('Gemini')}          Google AI Gemini models`,
+                `    ${s.success('Ollama (local)')}  Run models on your machine`,
+                `    ${s.success('Others')}          Together AI, Groq, Perplexity, etc.`,
+                '',
+                `  Each provider offers three ${s.primary('tiers')}:`,
+                '',
+                `    ${s.muted('Fast')}       Quick responses, lower cost`,
+                `    ${s.muted('Balanced')}   Best mix of speed and capability`,
+                `    ${s.muted('Powerful')}   Best reasoning for complex tasks`,
+                '',
+            ],
+        },
+        // Page 2: The Model Overlay
+        {
+            title: 'The Model Overlay',
+            lines: [
+                '',
+                `  ${s.secondary('Run /model to open the overlay:')}`,
+                '',
+                `  ${s.muted('Select Model [3/17]')}`,
+                '',
+                `  ${s.muted(' Claude   OpenAI   Gemini   Ollama (local)   Others ')}`,
+                '',
+                `  ${s.success('●')} API Key: Set`,
+                '',
+                `  ${s.primary('>')} ${s.success('●')} Fast          Haiku 4.5              (active)`,
+                `    ${s.success('●')} Balanced      Sonnet 4.5`,
+                `    ${s.success('●')} Powerful      Opus 4.5`,
+                '',
+                `  ${s.muted('Status indicators:')}`,
+                `    ${s.success('●')} API key set / Ollama installed`,
+                `    ${s.error('○')} Missing credentials`,
+                `    ${s.muted('(active)')} Currently selected model`,
+                `    ${s.warning('*')} Custom model (different from default)`,
+                '',
+            ],
+        },
+        // Page 3: Navigation & Keys
+        {
+            title: 'Navigation',
+            lines: [
+                '',
+                `  ${s.secondary('Main list shortcuts:')}`,
+                '',
+                `    ${s.primary('Tab')}          Switch provider tabs`,
+                `    ${s.primary('1-5')}          Jump to provider by number`,
+                `    ${s.primary('Up/Down')}      Navigate tiers`,
+                `    ${s.primary('Enter')}        Open tier details`,
+                `    ${s.primary('s')}            Set API key`,
+                `    ${s.primary('/')}            Search models`,
+                `    ${s.primary('q/Esc')}        Close`,
+                '',
+                `  ${s.secondary('Detail screen shortcuts:')}`,
+                '',
+                `    ${s.primary('Left/Right')}   Cycle through available models`,
+                `    ${s.primary('e')}            Enter custom model ID`,
+                `    ${s.primary('t')}            Test model connection`,
+                `    ${s.primary('a')}            Set as active model`,
+                `    ${s.primary('d')}            Reset to default`,
+                `    ${s.primary('Esc')}          Back to list`,
+                '',
+            ],
+        },
+        // Page 4: Tier Details
+        {
+            title: 'Tier Configuration',
+            lines: [
+                '',
+                `  ${s.secondary('Press Enter on a tier to see its detail screen:')}`,
+                '',
+                `  ${s.muted('Tier Configuration')}`,
+                `  ${s.muted('─────────────────────')}`,
+                `  Provider:     Claude`,
+                `  Tier:         Fast - Quick, low cost`,
+                `  API Key:      ${s.success('●')} Set`,
+                '',
+                `  ${s.muted('─── Model ID ───')}`,
+                `  Default:      ${s.muted('claude-haiku-4-5-20251001')}`,
+                `  Current:      Haiku 4.5 ${s.muted('[1/5]')}`,
+                '',
+                `  ${s.success('✓')} This is the active model`,
+                '',
+                `  ${s.muted('The [1/5] indicator shows you can cycle through')}`,
+                `  ${s.muted('5 models using Left/Right arrows.')}`,
+                '',
+            ],
+        },
+        // Page 5: API Keys & Ollama
+        {
+            title: 'API Keys & Local Models',
+            lines: [
+                '',
+                `  ${s.primaryBold('Setting API Keys')}`,
+                '',
+                `  Press ${s.primary('s')} in the model overlay to enter your API key.`,
+                `  Keys are stored encrypted in ${s.muted('~/.compilr-dev/credentials.enc')}`,
+                '',
+                `  You can also set keys via ${s.primary('/config')} or at startup.`,
+                '',
+                `  ${s.primaryBold('Local Models with Ollama')}`,
+                '',
+                `  Ollama runs models ${s.primary('locally')} — no API key needed.`,
+                '',
+                `    ${s.muted('1.')} Install Ollama (${s.muted('ollama.com')})`,
+                `    ${s.muted('2.')} Pull a model: ${s.primary('ollama pull llama3')}`,
+                `    ${s.muted('3.')} Select the Ollama tab in /model`,
+                `    ${s.muted('4.')} The CLI auto-detects available models`,
+                '',
+                `  ${s.muted('Server URL defaults to http://localhost:11434')}`,
+                `  ${s.muted('and can be changed in the tier detail screen.')}`,
+                '',
+            ],
+        },
+        // Page 6: Tips
+        {
+            title: 'Model Selection Tips',
+            lines: [
+                '',
+                `  ${s.warning('TIP:')} Match the model to the task:`,
+                '',
+                `    ${s.primary('Fast')} tier ${s.muted('(Haiku, GPT-4o-mini)')}`,
+                `      Simple questions, quick edits, file reads`,
+                '',
+                `    ${s.primary('Balanced')} tier ${s.muted('(Sonnet, GPT-4o)')}`,
+                `      Feature implementation, debugging, code review`,
+                '',
+                `    ${s.primary('Powerful')} tier ${s.muted('(Opus, o1)')}`,
+                `      Architecture decisions, complex refactoring`,
+                '',
+                `  ${s.warning('TIP:')} Team agents can use different tiers.`,
+                `  Use ${s.primary('/team')} to assign Fast tier to simple agents`,
+                `  and Powerful tier to architects.`,
+                '',
+                `  ${s.warning('TIP:')} Press ${s.primary('e')} to type any model ID manually.`,
+                `  This lets you use the latest models before`,
+                `  they appear in the default list.`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/config/permissions-safety.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Permissions & Safety Tutorial
+ *
+ * Covers the /permissions overlay: Rules, Mode, Session tabs.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const permissionsSafetyTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/config/permissions-safety.js

@@ -0,0 +1,163 @@
+/**
+ * Permissions & Safety Tutorial
+ *
+ * Covers the /permissions overlay: Rules, Mode, Session tabs.
+ */
+export const permissionsSafetyTutorial = (s) => ({
+    id: 'permissions',
+    title: 'Permissions & Safety',
+    description: 'Control what the AI can do',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Controlling AI Actions',
+            lines: [
+                '',
+                `  ${s.primaryBold('The permission system controls what tools the AI')}`,
+                `  ${s.primaryBold('can use and when it needs your approval.')}`,
+                '',
+                `  Run ${s.primary('/permissions')} to open the permissions overlay.`,
+                '',
+                `  Three tabs:`,
+                '',
+                `    ${s.primary('Rules')}     Per-tool permission levels`,
+                `    ${s.primary('Mode')}      Global permission mode`,
+                `    ${s.primary('Session')}   Grants given during this session`,
+                '',
+                `  ${s.secondary('Why it matters:')}`,
+                `  The AI can read files, write code, run commands, and`,
+                `  create git commits. Permissions let you decide which`,
+                `  of these actions need your approval first.`,
+                '',
+            ],
+        },
+        // Page 2: Permission Levels
+        {
+            title: 'Permission Levels',
+            lines: [
+                '',
+                `  ${s.secondary('Each tool has one of four permission levels:')}`,
+                '',
+                `    ${s.success('always')}    Always allowed, no prompt`,
+                `              ${s.muted('Best for: read_file, glob, grep')}`,
+                '',
+                `    ${s.primary('session')}   Allowed for the rest of the session`,
+                `              ${s.muted('Best for: run_tests, run_lint')}`,
+                '',
+                `    ${s.warning('once')}      Ask every time`,
+                `              ${s.muted('Best for: bash, write_file, edit')}`,
+                '',
+                `    ${s.error('deny')}      Explicitly blocked`,
+                `              ${s.muted('Best for: tools you never want used')}`,
+                '',
+                `  ${s.muted('Default rules ship with sensible defaults:')}`,
+                `  ${s.muted('read-only tools are "always", write tools are "once".')}`,
+                '',
+            ],
+        },
+        // Page 3: Rules Tab
+        {
+            title: 'Managing Rules',
+            lines: [
+                '',
+                `  ${s.secondary('The Rules tab shows all permission rules:')}`,
+                '',
+                `  ${s.muted('bash                  : once      Execute shell commands')}`,
+                `  ${s.muted('write_file            : once      Write/create files')}`,
+                `  ${s.muted('edit                  : once      Edit file contents')}`,
+                `  ${s.muted('git_commit            : once      Create git commits')}`,
+                `  ${s.muted('read_file             : always    Read files')}`,
+                `  ${s.muted('glob                  : always    Find files by pattern')}`,
+                `  ${s.muted('grep                  : always    Search file contents')}`,
+                '',
+                `  ${s.secondary('Shortcuts:')}`,
+                `    ${s.primary('a')}   Add new rule`,
+                `    ${s.primary('e')}   Edit selected rule (change level)`,
+                `    ${s.primary('d')}   Delete custom rule`,
+                `    ${s.primary('r')}   Reset all rules to defaults`,
+                '',
+                `  ${s.warning('TIP:')} Use wildcards: ${s.primary('git_*')} matches git_commit,`,
+                `  git_branch, and any future git tools.`,
+                '',
+            ],
+        },
+        // Page 4: Permission Modes
+        {
+            title: 'Permission Modes',
+            lines: [
+                '',
+                `  ${s.secondary('The Mode tab sets the global permission behavior:')}`,
+                '',
+                `    ${s.primary('Normal')}`,
+                `      Ask for confirmation before risky actions.`,
+                `      ${s.muted('Recommended for most users.')}`,
+                '',
+                `    ${s.primary('Plan mode')}`,
+                `      AI shows a plan first, then asks to execute.`,
+                `      ${s.muted('Good for learning what the AI wants to do.')}`,
+                '',
+                `    ${s.primary('Auto-accept')}`,
+                `      Automatically approve all actions.`,
+                `      ${s.muted('For experienced users who trust the AI.')}`,
+                '',
+                `  ${s.muted('You can also set the default mode in /config')}`,
+                `  ${s.muted('under "Default permission mode".')}`,
+                '',
+                `  ${s.warning('NOTE:')} Changing modes can optionally clear all`,
+                `  session grants to start fresh.`,
+                '',
+            ],
+        },
+        // Page 5: Session Grants & Safety
+        {
+            title: 'Session Grants & Safety',
+            lines: [
+                '',
+                `  ${s.primaryBold('Session Tab')}`,
+                '',
+                `  Shows tools you have approved during this session:`,
+                '',
+                `    ${s.primary('r')}   Revoke a specific grant`,
+                `    ${s.primary('c')}   Clear all grants`,
+                `    ${s.primary('a')}   Toggle auto-accept mode`,
+                '',
+                `  ${s.primaryBold('Safety Settings (in /config Environment tab)')}`,
+                '',
+                `    ${s.success('Delete protection')}`,
+                `      Only allows file deletion within your projects path.`,
+                `      Prevents accidental deletion of system files.`,
+                '',
+                `    ${s.success('CWD mismatch warning')}`,
+                `      Warns when your terminal directory differs from`,
+                `      the active project. Prevents working in the wrong folder.`,
+                '',
+                `  ${s.muted('Both safety settings are enabled by default.')}`,
+                '',
+            ],
+        },
+        // Page 6: Tips
+        {
+            title: 'Permission Tips',
+            lines: [
+                '',
+                `  ${s.warning('TIP:')} Start with ${s.primary('Normal')} mode and "once" for`,
+                `  write tools. You can always relax permissions later.`,
+                '',
+                `  ${s.warning('TIP:')} Set ${s.primary('run_tests')} and ${s.primary('run_lint')} to "session"`,
+                `  so the AI can iterate on code without asking each time.`,
+                '',
+                `  ${s.warning('TIP:')} When building a feature with /build, consider`,
+                `  switching to ${s.primary('Auto-accept')} mode temporarily so the AI`,
+                `  can work uninterrupted. Switch back after.`,
+                '',
+                `  ${s.warning('TIP:')} Keep ${s.primary('Delete protection')} enabled. It prevents`,
+                `  accidental deletion outside your projects directory.`,
+                '',
+                `  ${s.warning('TIP:')} Custom rules with ${s.primary('deny')} level are useful`,
+                `  for tools you never want the AI to call, like`,
+                `  ${s.muted('git_push')} if you always want to push manually.`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/config/settings-config.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Settings & Config Tutorial
+ *
+ * Covers the /config overlay: Status, Config, Environment, Usage tabs.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const settingsConfigTutorial: TutorialBuilder;