@compilr-dev/cli 0.5.0 → 0.5.1

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;

package/dist/ui/overlay/data/tutorials/config/settings-config.js

@@ -0,0 +1,166 @@
+/**
+ * Settings & Config Tutorial
+ *
+ * Covers the /config overlay: Status, Config, Environment, Usage tabs.
+ */
+export const settingsConfigTutorial = (s) => ({
+    id: 'settings',
+    title: 'Settings & Config',
+    description: 'Customize the CLI behavior and environment',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'The /config Command',
+            lines: [
+                '',
+                `  ${s.primaryBold('Run /config to open the settings overlay.')}`,
+                '',
+                `  The overlay has ${s.primary('4 tabs')}:`,
+                '',
+                `    ${s.primary('Status')}        Session info (version, model, tools)`,
+                `    ${s.primary('Config')}        Toggle preferences`,
+                `    ${s.primary('Environment')}   Paths and safety settings`,
+                `    ${s.primary('Usage')}         Token usage statistics`,
+                '',
+                `  ${s.secondary('Navigation:')}`,
+                '',
+                `    ${s.primary('Tab')}           Switch between tabs`,
+                `    ${s.primary('1-4')}           Jump to tab by number`,
+                `    ${s.primary('Up/Down')}       Navigate settings`,
+                `    ${s.primary('Enter/Space')}   Toggle or edit value`,
+                `    ${s.primary('q/Esc')}         Close`,
+                '',
+            ],
+        },
+        // Page 2: Status Tab
+        {
+            title: 'Status Tab',
+            lines: [
+                '',
+                `  ${s.secondary('The Status tab shows read-only session info:')}`,
+                '',
+                `    ${s.muted('Version')}        CLI version`,
+                `    ${s.muted('Session ID')}     Unique 8-char hex identifier`,
+                `    ${s.muted('Uptime')}         How long the session has been running`,
+                `    ${s.muted('Provider')}       Current LLM provider (Claude, OpenAI, etc.)`,
+                `    ${s.muted('Model')}          Active model name`,
+                `    ${s.muted('Tools')}          Tool count breakdown`,
+                `    ${s.muted('Cwd')}            Current working directory`,
+                `    ${s.muted('Memory File')}    COMPILR.md or CLAUDE.md if present`,
+                `    ${s.muted('Settings File')}  Path to settings.json`,
+                '',
+                `  ${s.muted('Use this tab to quickly check what model and')}`,
+                `  ${s.muted('provider you are using in the current session.')}`,
+                '',
+            ],
+        },
+        // Page 3: Config Tab
+        {
+            title: 'Config Tab - Preferences',
+            lines: [
+                '',
+                `  ${s.secondary('Toggle and cycle through preferences:')}`,
+                '',
+                `    ${s.primary('Auto-compact')}              ${s.muted('true/false')}`,
+                `      Auto-compress old messages for context`,
+                '',
+                `    ${s.primary('Verbose output')}             ${s.muted('true/false')}`,
+                `      Show debug information`,
+                '',
+                `    ${s.primary('Terminal progress bar')}       ${s.muted('true/false')}`,
+                `      Display progress during execution`,
+                '',
+                `    ${s.primary('Default permission mode')}     ${s.muted('cycle')}`,
+                `      Normal / Plan mode / Accept edits / Don't ask`,
+                '',
+                `    ${s.primary('Theme')}                       ${s.muted('opens submenu')}`,
+                `    ${s.primary('Model')}                       ${s.muted('opens submenu')}`,
+                `    ${s.primary('Mascot')}                      ${s.muted('opens submenu')}`,
+                '',
+            ],
+        },
+        // Page 4: More Config + Startup
+        {
+            title: 'Config Tab - Startup & Sessions',
+            lines: [
+                '',
+                `  ${s.secondary('More preferences in the Config tab:')}`,
+                '',
+                `    ${s.primary('Terminal notifications')}      ${s.muted('Auto / Bell / Disabled')}`,
+                `      How to notify when tasks complete`,
+                '',
+                `    ${s.primary('Check for updates')}           ${s.muted('true/false')}`,
+                `      Check npm for new versions on startup`,
+                '',
+                `    ${s.primary('Startup behavior')}            ${s.muted('Show menu / Direct to REPL')}`,
+                `      What to show when the CLI starts`,
+                '',
+                `    ${s.primary('Auto-open project')}           ${s.muted('Last opened / Off')}`,
+                `      Automatically open your last project`,
+                '',
+                `    ${s.primary('Session restore mode')}        ${s.muted('Auto / Ask / Fresh')}`,
+                `      What to do with previous sessions`,
+                '',
+                `  ${s.warning('TIP:')} Set ${s.primary('Auto-open project')} to "Last opened" and`,
+                `  ${s.primary('Session restore mode')} to "Auto" for the fastest startup.`,
+                '',
+            ],
+        },
+        // Page 5: Environment Tab
+        {
+            title: 'Environment Tab',
+            lines: [
+                '',
+                `  ${s.secondary('Configure paths and safety settings:')}`,
+                '',
+                `  ${s.primaryBold('Path Configuration')}`,
+                `    Workspace path      ${s.muted('/home/user')}`,
+                `    Projects path        ${s.muted('/home/user/projects')}`,
+                `    Data path            ${s.muted('~/.compilr-dev')}`,
+                '',
+                `  ${s.primaryBold('Git Configuration')}`,
+                `    Git user name        ${s.muted('your-name')}`,
+                `    Git user email       ${s.muted('your@email.com')}`,
+                '',
+                `  ${s.primaryBold('Safety Settings')}`,
+                `    ${s.success('Delete protection')}       ${s.muted('enabled')}`,
+                `      Only allow file deletion within projects path`,
+                '',
+                `    ${s.success('CWD mismatch warning')}    ${s.muted('enabled')}`,
+                `      Warn when working outside active project`,
+                '',
+                `  ${s.muted('Press Enter to edit a path, Enter again to save.')}`,
+                '',
+            ],
+        },
+        // Page 6: Usage Tab + Theme/Mascot
+        {
+            title: 'Usage Tab & Submenus',
+            lines: [
+                '',
+                `  ${s.secondary('The Usage tab shows real-time token statistics:')}`,
+                '',
+                `    ${s.muted('Session Tokens:')}  Input / Output / Total`,
+                `    ${s.muted('Context Window:')}  Progress bar + percentage`,
+                `    ${s.muted('Session Activity:')} Requests and messages count`,
+                '',
+                `  ${s.muted('Progress bar colors: green <60%, yellow 60-80%, red >80%')}`,
+                '',
+                `  ${s.primaryBold('Submenus')}`,
+                '',
+                `  Three settings open dedicated overlays:`,
+                '',
+                `    ${s.primary('Theme')}   418 terminal themes with live preview`,
+                `            Tabs: Curated, All, Dark, Light`,
+                '',
+                `    ${s.primary('Model')}   Full model selection (see Model Selection tutorial)`,
+                '',
+                `    ${s.primary('Mascot')}  Choose your CLI companion (13 options)`,
+                `            None, Random, or a specific expression`,
+                '',
+                `  ${s.muted('All settings are saved to ~/.compilr-dev/settings.json')}`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/planning/arch.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Architecture Tutorial
+ *
+ * Walkthrough of the /arch command for creating architecture documentation.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const archTutorial: TutorialBuilder;