@compilr-dev/cli 0.5.0 → 0.5.2

package/dist/ui/overlay/data/tutorials/basics/welcome.js

@@ -0,0 +1,174 @@
+/**
+ * Welcome Tutorial
+ *
+ * Introduces the five pillars philosophy and development workflow overview.
+ */
+export const welcomeTutorial = (s) => ({
+    id: 'welcome',
+    title: 'Welcome & Philosophy',
+    description: 'Core principles and workflow overview',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Welcome to compilr.dev',
+            lines: [
+                '',
+                `  ${s.primaryBold('Stop rebuilding. Start structuring.')}`,
+                '',
+                `  Have you ever:`,
+                `    ${s.muted('•')} Built the same feature three times?`,
+                `    ${s.muted('•')} Lost context between sessions?`,
+                `    ${s.muted('•')} Watched your codebase become a patchwork of patterns?`,
+                '',
+                `  This is ${s.warning('vibe coding')} - the chaos that emerges when powerful AI`,
+                `  tools meet undisciplined workflows.`,
+                '',
+                `  ${s.primary('compilr.dev')} provides the structure to make AI coding assistants`,
+                `  actually productive.`,
+                '',
+            ],
+        },
+        // Page 2: Pillar 1 - Structured
+        {
+            title: 'Pillar 1: Structured Coding',
+            lines: [
+                '',
+                `  ${s.primaryBold('Every project deserves a skeleton before it has muscles.')}`,
+                '',
+                `  That means:`,
+                '',
+                `    ${s.success('✓')} Explicit folder structures (code + documentation)`,
+                `    ${s.success('✓')} A ${s.primary('COMPILR.md')} file that persists project context`,
+                `    ${s.success('✓')} A ${s.primary('backlog')} that tracks what's done and what's next`,
+                `    ${s.success('✓')} Architecture decisions documented before implemented`,
+                '',
+                `  ${s.muted('Structure isn\'t bureaucracy.')}`,
+                `  ${s.muted('It\'s the difference between building a house and piling up bricks.')}`,
+                '',
+            ],
+        },
+        // Page 3: Pillar 2 - Disciplined
+        {
+            title: 'Pillar 2: Disciplined Development',
+            lines: [
+                '',
+                `  ${s.primaryBold('Discipline is doing the boring things that prevent expensive things.')}`,
+                '',
+                `  That means:`,
+                '',
+                `    ${s.success('✓')} Committing early and often (not "I'll commit when it's done")`,
+                `    ${s.success('✓')} Tracking progress in a backlog (not "I'll remember")`,
+                `    ${s.success('✓')} Following coding standards (not "the AI knows best")`,
+                `    ${s.success('✓')} Reviewing changes before accepting (not "ship it and pray")`,
+                '',
+                `  ${s.muted('Discipline compounds. Undisciplined code compounds too -')}`,
+                `  ${s.muted('in bugs, rework, and frustration.')}`,
+                '',
+            ],
+        },
+        // Page 4: Pillar 3 - Intentional
+        {
+            title: 'Pillar 3: Intentional Decisions',
+            lines: [
+                '',
+                `  ${s.primaryBold('Every choice should be deliberate.')}`,
+                '',
+                `  That means:`,
+                '',
+                `    ${s.success('✓')} Technology stack evaluated upfront, not mid-project`,
+                `    ${s.success('✓')} Database schemas normalized, not ad-hoc`,
+                `    ${s.success('✓')} Security and performance from day one, not bolted on`,
+                `    ${s.success('✓')} Trade-offs documented, not buried in chat`,
+                '',
+                `  ${s.muted('"It just happened" is never the right answer for')}`,
+                `  ${s.muted('how your architecture emerged.')}`,
+                '',
+            ],
+        },
+        // Page 5: Pillar 4 - Engineering-First
+        {
+            title: 'Pillar 4: Engineering-First AI',
+            lines: [
+                '',
+                `  ${s.primaryBold('AI is a tool, not a replacement for engineering judgment.')}`,
+                '',
+                `  That means:`,
+                '',
+                `    ${s.success('✓')} The human sets direction; AI accelerates execution`,
+                `    ${s.success('✓')} DRY principle enforced (AI should know when it duplicates)`,
+                `    ${s.success('✓')} Breaking changes detected before they break things`,
+                `    ${s.success('✓')} Context preserved across sessions, not lost to tokens`,
+                '',
+                `  ${s.muted('The goal isn\'t to code faster.')}`,
+                `  ${s.muted('The goal is to build better software, faster.')}`,
+                '',
+            ],
+        },
+        // Page 6: Pillar 5 - Flexible
+        {
+            title: 'Pillar 5: Flexible Execution',
+            lines: [
+                '',
+                `  ${s.primaryBold('Structure enables change - it doesn\'t prevent it.')}`,
+                '',
+                `  That means:`,
+                '',
+                `    ${s.success('✓')} The backlog is a living document, not a contract`,
+                `    ${s.success('✓')} Priorities shift based on learnings and feedback`,
+                `    ${s.success('✓')} New tasks emerge and get slotted in naturally`,
+                `    ${s.success('✓')} You can pivot features or reorder phases`,
+                '',
+                `  ${s.muted('The difference between flexibility and chaos? Foundations.')}`,
+                `  ${s.muted('Without structure, every change is a risk.')}`,
+                '',
+            ],
+        },
+        // Page 7: The Workflow
+        {
+            title: 'The Development Workflow',
+            lines: [
+                '',
+                `  ${s.secondary('The CLI guides you through five main stages:')}`,
+                '',
+                `    ${s.primary('/new')}        Create your project`,
+                `                 ${s.muted('Sets up structure, COMPILR.md, database record')}`,
+                '',
+                `    ${s.primary('/design')}     Gather requirements`,
+                `                 ${s.muted('Creates a PRD and backlog items')}`,
+                '',
+                `    ${s.primary('/backlog')}    Manage work items`,
+                `                 ${s.muted('Track status, prioritize, break down tasks')}`,
+                '',
+                `    ${s.primary('/build')}      Implement features`,
+                `                 ${s.muted('AI-assisted coding with your approval')}`,
+                '',
+                `    ${s.primary('/workflow')}   Check progress`,
+                `                 ${s.muted('See where you are and what\'s next')}`,
+                '',
+            ],
+        },
+        // Page 8: Getting Started
+        {
+            title: 'Getting Started',
+            lines: [
+                '',
+                `  ${s.secondary('Ready to start? Here are your next steps:')}`,
+                '',
+                `    ${s.muted('1.')} Run ${s.primary('/new')} to create a project`,
+                `        ${s.muted('Or /sketch for a quick outline')}`,
+                '',
+                `    ${s.muted('2.')} Run ${s.primary('/design')} to gather requirements`,
+                `        ${s.muted('Creates a PRD and backlog items')}`,
+                '',
+                `    ${s.muted('3.')} Run ${s.primary('/backlog')} to see your work items`,
+                `        ${s.muted('Pick one and start building!')}`,
+                '',
+                `  ${s.warning('TIP:')} Browse this tutorial to learn all the features.`,
+                `       Use ←/→ to see other topics.`,
+                '',
+                `  ${s.muted('Your AI assistant, your discipline, your code.')}`,
+                '',
+            ],
+        },
+    ],
+});

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

@@ -0,0 +1,7 @@
+/**
+ * Context Management Tutorial
+ *
+ * Covers /context, /compact, /tokens, /anchors, and auto-compact.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const contextManagementTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/config/context-management.js

@@ -0,0 +1,158 @@
+/**
+ * Context Management Tutorial
+ *
+ * Covers /context, /compact, /tokens, /anchors, and auto-compact.
+ */
+export const contextManagementTutorial = (s) => ({
+    id: 'context-mgmt',
+    title: 'Context Management',
+    description: 'Manage AI memory and token usage',
+    pages: [
+        // Page 1: Introduction
+        {
+            title: 'Understanding Context',
+            lines: [
+                '',
+                `  ${s.primaryBold('Every AI model has a context window — a limit on')}`,
+                `  ${s.primaryBold('how much information it can process at once.')}`,
+                '',
+                `  As your conversation grows, you use more of the window.`,
+                `  When it fills up, the AI loses access to older messages.`,
+                '',
+                `  ${s.secondary('Context management commands:')}`,
+                '',
+                `    ${s.primary('/context')}    View current context usage`,
+                `    ${s.primary('/compact')}    Summarize old messages to free space`,
+                `    ${s.primary('/tokens')}     Detailed token breakdown`,
+                `    ${s.primary('/status')}     Session overview`,
+                `    ${s.primary('/anchors')}    Persistent notes (survive compaction)`,
+                `    ${s.primary('/export')}     Save conversation to markdown`,
+                '',
+            ],
+        },
+        // Page 2: /context
+        {
+            title: 'Viewing Context Usage',
+            lines: [
+                '',
+                `  ${s.secondary('Run /context to see how full your context window is:')}`,
+                '',
+                `  ${s.muted('Context Usage')}`,
+                `  ${s.muted('────────────────────')}`,
+                `  Agent:    ${s.primary('[▲_▲] $dev')}`,
+                `  Usage:    ${s.success('████')}${s.muted('░░░░░░░░░░░░░░░░')} 18.5%`,
+                `  Tokens:   ${s.primary('37,000')} / ${s.muted('200,000')}`,
+                `  Messages: ${s.primary('42')}`,
+                `  Turns:    ${s.primary('21')}`,
+                '',
+                `  ${s.muted('By Agent')}`,
+                `  ${s.muted('────────────────────')}`,
+                `  ${s.success('●')} $dev     ${s.success('████')}${s.muted('░░░░░░')} 18.5%  ${s.muted('200K')}  (42 msgs)`,
+                `  ${s.muted('○')} $pm      ${s.muted('█')}${s.muted('░░░░░░░░░')}  2.1%  ${s.muted('200K')}  (6 msgs)`,
+                '',
+                `  Each agent shows its model's context window (200K, 128K, 1M).`,
+                `  ${s.success('●')} = active agent   ${s.muted('○')} = inactive`,
+                '',
+            ],
+        },
+        // Page 3: /compact
+        {
+            title: 'Compacting Context',
+            lines: [
+                '',
+                `  ${s.primaryBold('When context gets too full, run /compact.')}`,
+                '',
+                `  This summarizes older messages while preserving key info:`,
+                '',
+                `    ${s.success('✓')} Tool results converted to file references`,
+                `    ${s.success('✓')} Conversation history summarized`,
+                `    ${s.success('✓')} Recent messages kept intact`,
+                `    ${s.success('✓')} Anchors always preserved`,
+                '',
+                `  ${s.secondary('Multi-agent compact modes:')}`,
+                '',
+                `    ${s.primary('/compact')}         Use default mode (set in /config)`,
+                `    ${s.primary('/compact all')}     Compact all initialized agents`,
+                `    ${s.primary('/compact auto')}    Compact agents above 70% usage`,
+                `    ${s.primary('/compact $pm')}     Compact a specific agent`,
+                '',
+                `  ${s.warning('TIP:')} Enable ${s.primary('Auto-compact')} in /config for automatic`,
+                `  compaction. Set ${s.primary('Default compact mode')} to control /compact.`,
+                '',
+            ],
+        },
+        // Page 4: Anchors
+        {
+            title: 'Persistent Notes with /anchors',
+            lines: [
+                '',
+                `  ${s.primaryBold('Anchors are notes that survive compaction and persist')}`,
+                `  ${s.primaryBold('across sessions. The AI always sees them.')}`,
+                '',
+                `  ${s.secondary('Use anchors for:')}`,
+                `    Project conventions: ${s.muted('"Always use async/await"')}`,
+                `    Decisions: ${s.muted('"We chose PostgreSQL because..."')}`,
+                `    Reminders: ${s.muted('"Don\'t modify the auth module"')}`,
+                '',
+                `  ${s.secondary('Creating anchors:')}`,
+                `    In the REPL, say: ${s.primary('"Remember that we use tabs not spaces"')}`,
+                `    Or use the /anchors overlay: press ${s.primary('a')} to add`,
+                '',
+                `  ${s.secondary('Anchor properties:')}`,
+                `    Priority:  ${s.error('[!]')} Critical  ${s.warning('[S]')} Safety  ${s.muted('[i]')} Info`,
+                `    Scope:     ${s.primary('[G]')} Global (all projects)  ${s.primary('[P]')} Project only`,
+                '',
+            ],
+        },
+        // Page 5: Anchors Overlay
+        {
+            title: 'The /anchors Overlay',
+            lines: [
+                '',
+                `  ${s.secondary('Tabs filter anchors by priority and scope:')}`,
+                '',
+                `    ${s.muted('All | Critical | Safety | Info | Global | Project')}`,
+                '',
+                `  ${s.secondary('Shortcuts:')}`,
+                '',
+                `    ${s.primary('Up/Down')}      Navigate anchors`,
+                `    ${s.primary('Tab/1-6')}      Switch filter tabs`,
+                `    ${s.primary('a')}            Add new anchor`,
+                `    ${s.primary('e')}            Edit selected anchor`,
+                `    ${s.primary('d')}            Delete (with confirmation)`,
+                `    ${s.primary('/')}            Search anchors`,
+                `    ${s.primary('q/Esc')}        Close`,
+                '',
+                `  ${s.secondary('When adding/editing:')}`,
+                `    Type content (up to 500 chars)`,
+                `    Cycle priority and scope with arrow keys`,
+                `    ${s.primary('Enter')} to save, ${s.primary('Esc')} to cancel`,
+                '',
+            ],
+        },
+        // Page 6: Tips
+        {
+            title: 'Context Tips',
+            lines: [
+                '',
+                `  ${s.warning('TIP:')} Watch for yellow/red in your context bar.`,
+                `  Above 80% the AI starts losing earlier context.`,
+                '',
+                `  ${s.warning('TIP:')} Use ${s.primary('/export')} to save important conversations`,
+                `  before compacting. Example:`,
+                `    ${s.primary('/export meeting-notes.md')}`,
+                '',
+                `  ${s.warning('TIP:')} Create ${s.error('[!]')} Critical anchors for rules the AI`,
+                `  must never forget, even across sessions.`,
+                '',
+                `  ${s.warning('TIP:')} ${s.primary('/tokens')} shows input vs output breakdown.`,
+                `  High output tokens may mean the AI is being verbose -`,
+                `  create an anchor: "Be concise in responses"`,
+                '',
+                `  ${s.warning('TIP:')} When team agents each have their own context,`,
+                `  use ${s.primary('/context')} to see which agent is using the most.`,
+                '',
+            ],
+        },
+    ],
+});

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;