@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/ui/overlay/data/tutorials/basics/first-conversation.js

@@ -0,0 +1,220 @@
+/**
+ * Your First Conversation Tutorial
+ *
+ * How to interact with the AI in REPL mode.
+ */
+export const firstConversationTutorial = (s) => ({
+    id: 'first-conversation',
+    title: 'Your First Conversation',
+    description: 'How to chat with the AI assistant',
+    pages: [
+        // Page 1: Starting from Dashboard
+        {
+            title: 'Starting from Dashboard',
+            lines: [
+                '',
+                `  After creating a project, you'll see the Dashboard:`,
+                '',
+                `    ${s.muted('─'.repeat(50))}`,
+                `       ${s.muted('Dashboard')}  │  ${s.muted('More')}`,
+                `    ${s.muted('─'.repeat(50))}`,
+                '',
+                `      ${s.secondary('CURRENT PROJECT')}`,
+                `      ${s.primaryBold('★ My First Project')}`,
+                `        ${s.muted('/workspace/projects/my-first-project │ active │ flexible')}`,
+                '',
+                `      ${s.secondary('ACTIONS')}`,
+                `      ${s.primary('❯')} Continue with My First Project   ${s.muted('Resume working on current project')}`,
+                '',
+                `      ${s.muted('↑↓/jk Navigate   Enter Select   q Quit')}`,
+                '',
+                `  Press ${s.primary('Enter')} to continue with your project.`,
+                '',
+            ],
+        },
+        // Page 2: The REPL
+        {
+            title: 'The REPL',
+            lines: [
+                '',
+                `  After pressing Enter, you'll see the REPL (Read-Eval-Print Loop):`,
+                '',
+                `    ${s.muted('✓ Agent connected')}`,
+                '',
+                `    ${s.muted('Model: gemini-2.5-flash')}`,
+                `    ${s.muted('Provider: gemini')}`,
+                `    ${s.muted('[^_^] Switched to project: My First Project')}`,
+                '',
+                `    ${s.muted('─'.repeat(40))}`,
+                `    ${s.primary('compilr>')} ${s.muted('█')}`,
+                `    ${s.muted('─'.repeat(40))}`,
+                `    ${s.muted('mode: Normal                    Project: My First Project')}`,
+                '',
+                `  Type your message and press ${s.primary('Enter')} to chat with the AI.`,
+                '',
+            ],
+        },
+        // Page 3: File References
+        {
+            title: 'File References with @',
+            lines: [
+                '',
+                `  Reference files by typing ${s.primary('@')} followed by a path:`,
+                '',
+                `    ${s.primary('compilr>')} Fix the bug in ${s.secondary('@src/utils.ts')}`,
+                '',
+                `  ${s.secondary('Autocomplete:')} Press ${s.primary('Tab')} after ${s.primary('@')} to see matches.`,
+                '',
+                `    ${s.primary('compilr>')} Explain ${s.secondary('@src/')}`,
+                `        ${s.muted('src/index.ts')}`,
+                `        ${s.muted('src/utils.ts')}`,
+                `        ${s.muted('src/config.ts')}`,
+                '',
+                `  ${s.secondary('Multiple files:')}`,
+                '',
+                `    ${s.primary('compilr>')} Compare ${s.secondary('@src/old.ts')} with ${s.secondary('@src/new.ts')}`,
+                '',
+                `  The AI will read the files and understand the context.`,
+                '',
+            ],
+        },
+        // Page 4: Slash Commands
+        {
+            title: 'Slash Commands',
+            lines: [
+                '',
+                `  Commands start with ${s.primary('/')}:`,
+                '',
+                `    ${s.primary('/help')}       Show available commands`,
+                `    ${s.primary('/clear')}      Clear the screen`,
+                `    ${s.primary('/exit')}       Exit the CLI`,
+                `    ${s.primary('/design')}     Start requirements gathering`,
+                `    ${s.primary('/backlog')}    View your work items`,
+                '',
+                `  ${s.secondary('Autocomplete:')} Type ${s.primary('/')} and press ${s.primary('Tab')}`,
+                '',
+                `    ${s.primary('compilr>')} /he`,
+                `        ${s.muted('/help')}`,
+                `        ${s.muted('/health')}`,
+                '',
+                `  ${s.warning('TIP:')} Run ${s.primary('/help')} to see all commands,`,
+                `       or ${s.primary('/tutorial')} to browse these guides!`,
+                '',
+            ],
+        },
+        // Page 5: What the AI Can Do
+        {
+            title: 'What the AI Can Do',
+            lines: [
+                '',
+                `  The AI can help with:`,
+                '',
+                `    ${s.success('✓')} ${s.primary('Read files')} - Understand your code`,
+                `    ${s.success('✓')} ${s.primary('Write files')} - Create or modify code`,
+                `    ${s.success('✓')} ${s.primary('Run commands')} - Execute shell commands`,
+                `    ${s.success('✓')} ${s.primary('Search code')} - Find patterns in your codebase`,
+                `    ${s.success('✓')} ${s.primary('Git operations')} - Commit, diff, status`,
+                `    ${s.success('✓')} ${s.primary('Answer questions')} - Explain code, debug issues`,
+                '',
+                `  ${s.secondary('Example requests:')}`,
+                '',
+                `    ${s.muted('"Create a login component"')}`,
+                `    ${s.muted('"Why is this test failing?"')}`,
+                `    ${s.muted('"Refactor this function to use async/await"')}`,
+                '',
+            ],
+        },
+        // Page 6: Permission Prompts
+        {
+            title: 'Permission Prompts',
+            lines: [
+                '',
+                `  The AI asks permission before making changes:`,
+                '',
+                `    ┌─ Permission Required ───────────────────────┐`,
+                `    │                                             │`,
+                `    │  The agent wants to create a file:          │`,
+                `    │  ${s.primary('src/components/Login.tsx')}                   │`,
+                `    │                                             │`,
+                `    │  ${s.success('[Allow]')}  ${s.muted('[Allow Always]')}  ${s.error('[Deny]')}            │`,
+                `    │                                             │`,
+                `    └─────────────────────────────────────────────┘`,
+                '',
+                `    ${s.success('Allow')}        - Approve this specific action`,
+                `    ${s.muted('Allow Always')} - Auto-approve this tool for the session`,
+                `    ${s.error('Deny')}         - Reject this action`,
+                '',
+                `  ${s.muted('You\'re always in control of what changes are made.')}`,
+                '',
+            ],
+        },
+        // Page 7: Stopping and Canceling
+        {
+            title: 'Stopping and Canceling',
+            lines: [
+                '',
+                `  ${s.secondary('While the AI is working:')}`,
+                '',
+                `    ${s.primary('Esc')}      Stop the current operation`,
+                `                ${s.muted('The AI will finish its current thought')}`,
+                '',
+                `    ${s.primary('Ctrl+C')}   Force stop immediately`,
+                `                ${s.muted('Use when Esc doesn\'t respond')}`,
+                '',
+                `  ${s.secondary('While typing:')}`,
+                '',
+                `    ${s.primary('Ctrl+C')}   Clear current input`,
+                `    ${s.primary('Ctrl+C')} ${s.muted('twice')}  Exit the CLI`,
+                '',
+                `  ${s.warning('TIP:')} If the AI is taking too long, just press Esc.`,
+                `       You can continue the conversation afterward.`,
+                '',
+            ],
+        },
+        // Page 8: Context and Memory
+        {
+            title: 'Context and Memory',
+            lines: [
+                '',
+                `  The AI remembers your conversation within a session.`,
+                '',
+                `  ${s.secondary('What the AI knows:')}`,
+                `    ${s.muted('•')} Your project info (from COMPILR.md)`,
+                `    ${s.muted('•')} Files you've referenced`,
+                `    ${s.muted('•')} Previous messages in this session`,
+                `    ${s.muted('•')} Anchors (persistent notes)`,
+                '',
+                `  ${s.secondary('Context commands:')}`,
+                `    ${s.primary('/context')}   See current context usage`,
+                `    ${s.primary('/compact')}   Summarize old messages (free up space)`,
+                `    ${s.primary('/anchors')}   View/add persistent notes`,
+                '',
+                `  ${s.muted('Sessions auto-save. Use')} ${s.primary('/resume')} ${s.muted('to continue later.')}`,
+                '',
+            ],
+        },
+        // Page 9: Next Steps
+        {
+            title: 'Next Steps',
+            lines: [
+                '',
+                `  ${s.secondary('You\'re ready to start building!')}`,
+                '',
+                `  ${s.primary('Recommended workflow:')}`,
+                '',
+                `    ${s.muted('1.')} Run ${s.primary('/design')} to plan your features`,
+                `        ${s.muted('The AI will help create a PRD and backlog')}`,
+                '',
+                `    ${s.muted('2.')} Run ${s.primary('/backlog')} to see your work items`,
+                `        ${s.muted('Pick one to start building')}`,
+                '',
+                `    ${s.muted('3.')} Ask the AI to implement features`,
+                `        ${s.muted('"Build the user authentication from REQ-001"')}`,
+                '',
+                `  ${s.warning('TIP:')} Browse the other tutorials to learn about`,
+                `       ${s.primary('/design')}, ${s.primary('/backlog')}, and team agents!`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/basics/first-project.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Your First Project Tutorial
+ *
+ * Guides users through the dashboard and /new wizard.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const firstProjectTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/basics/first-project.js

@@ -0,0 +1,284 @@
+/**
+ * Your First Project Tutorial
+ *
+ * Guides users through the dashboard and /new wizard.
+ */
+export const firstProjectTutorial = (s) => ({
+    id: 'first-project',
+    title: 'Your First Project',
+    description: 'Dashboard and /new wizard walkthrough',
+    pages: [
+        // Page 1: What you see first
+        {
+            title: 'What You See First',
+            lines: [
+                '',
+                `  When you run ${s.primary('compilr')} for the first time, you'll see the Dashboard:`,
+                '',
+                `    ${s.muted('─'.repeat(50))}`,
+                `       ${s.muted('Dashboard')}  │  ${s.muted('More')}`,
+                `    ${s.muted('─'.repeat(50))}`,
+                '',
+                `      ${s.primaryBold('WELCOME TO COMPILR DEV CLI')}`,
+                '',
+                `      ${s.muted('Get started by creating a new project or importing an existing')}`,
+                `      ${s.muted('repository. Or use Quick Chat for general assistance.')}`,
+                '',
+                `      ${s.secondary('ACTIONS')}`,
+                `      ${s.primary('❯')} /new Project                 ${s.muted('Create new or import existing project')}`,
+                `        Quick Chat                   ${s.muted('Chat without project context')}`,
+                '',
+                `      ${s.muted('↑↓/jk Navigate   Enter Select   q Quit')}`,
+                '',
+            ],
+        },
+        // Page 2: Your options
+        {
+            title: 'Your Options',
+            lines: [
+                '',
+                `  From the Dashboard you have two choices:`,
+                '',
+                `    ${s.primary('/new Project')}`,
+                `    Create a new project or import an existing one.`,
+                `    Sets up the workflow structure for AI-assisted development.`,
+                '',
+                `    ${s.primary('Quick Chat')}`,
+                `    Chat without project context.`,
+                `    For quick questions or one-off tasks.`,
+                '',
+                `  ${s.secondary('Navigation:')}`,
+                `    ${s.muted('↑/↓')} or ${s.muted('j/k')} to move between options`,
+                `    ${s.muted('Enter')} to select`,
+                `    ${s.muted('Tab')} to switch to the "More" tab`,
+                '',
+            ],
+        },
+        // Page 3: Starting /new [0/8]
+        {
+            title: 'Starting /new',
+            lines: [
+                '',
+                `  Select ${s.primary('/new Project')} and press Enter. You'll see:`,
+                '',
+                `     ${s.primaryBold('Initialize New Project')} ${s.muted('[0/8]')}`,
+                '',
+                `     ${s.primary('What would you like to do?')}`,
+                '',
+                `     ${s.primary('>')} 1. Start a new project`,
+                `       2. Add workflow to existing project ${s.muted('(coming soon)')}`,
+                '',
+                `     ${s.muted('Start fresh with a structured project layout')}`,
+                `     ${s.muted('optimized for AI-assisted development.')}`,
+                '',
+                `     ${s.muted('Up/Down Navigate | Enter Select | q/Esc Cancel')}`,
+                '',
+                `  Select "Start a new project" and press Enter.`,
+                '',
+            ],
+        },
+        // Page 4: Project Name [1/8]
+        {
+            title: 'Project Name',
+            lines: [
+                '',
+                `     ${s.primaryBold('Initialize New Project')} ${s.muted('[1/8]')}`,
+                '',
+                `     ${s.primary('Project name')}`,
+                '',
+                `     ${s.primary('>')} my-first-project${s.muted('|')}`,
+                '',
+                `     ${s.muted('Use lowercase letters, numbers, hyphens (e.g., my-saas-app)')}`,
+                `     ${s.muted('2-50 characters, must start with a letter')}`,
+                '',
+                `     ${s.muted('Enter Confirm | Esc Back')}`,
+                '',
+                `  ${s.warning('TIP:')} Choose a descriptive name - it becomes your folder name.`,
+                '',
+            ],
+        },
+        // Page 5: Description [2/8]
+        {
+            title: 'Description',
+            lines: [
+                '',
+                `     ${s.primaryBold('Initialize New Project')} ${s.muted('[2/8]')}`,
+                '',
+                `     ${s.primary('What are you building?')}`,
+                '',
+                `     ${s.primary('>')} A note-taking app with markdown support${s.muted('|')}`,
+                '',
+                `     ${s.muted('Brief description (1-2 sentences)')}`,
+                `     ${s.muted('Example: "A task management SaaS for small teams"')}`,
+                '',
+                `     ${s.muted('Enter Confirm | Esc Back')}`,
+                '',
+                `  ${s.warning('TIP:')} Be specific! The AI uses this to understand your project.`,
+                '',
+            ],
+        },
+        // Page 6: Documentation Structure [3/8]
+        {
+            title: 'Documentation Structure',
+            lines: [
+                '',
+                `     ${s.primaryBold('Initialize New Project')} ${s.muted('[3/8]')}`,
+                '',
+                `     ${s.primary('Documentation structure')}`,
+                '',
+                `     ${s.primary('>')} 1. Single repo (.compilr/ folder + COMPILR.md in project root)`,
+                `       2. Two repos (project/ + project-docs/ separate repositories)`,
+                '',
+                `     ${s.muted('Single repo: All files in one repository')}`,
+                `     ${s.muted('Two repos: Code and docs in separate repositories')}`,
+                '',
+                `     ${s.muted('Up/Down Navigate | Enter Select | Esc Back')}`,
+                '',
+                `  ${s.warning('TIP:')} Single repo is simpler for most projects.`,
+                '',
+            ],
+        },
+        // Page 7: Tech Stack [4/8]
+        {
+            title: 'Tech Stack',
+            lines: [
+                '',
+                `     ${s.primaryBold('Initialize New Project')} ${s.muted('[4/8]')}`,
+                '',
+                `     ${s.primary('Tech stack')}`,
+                '',
+                `     ${s.primary('>')} 1. React + Node.js + PostgreSQL`,
+                `       2. React + Python + PostgreSQL`,
+                `       3. Vue + Node.js + PostgreSQL`,
+                `       4. Custom (configure later)`,
+                '',
+                `     ${s.muted('Choose a preset or configure later')}`,
+                '',
+                `     ${s.muted('Up/Down Navigate | Enter Select | Esc Back')}`,
+                '',
+                `  ${s.warning('TIP:')} You can change this later in your COMPILR.md file.`,
+                '',
+            ],
+        },
+        // Page 8: Coding Standards [5/8]
+        {
+            title: 'Coding Standards',
+            lines: [
+                '',
+                `     ${s.primaryBold('Initialize New Project')} ${s.muted('[5/8]')}`,
+                '',
+                `     ${s.primary('Coding standards preset')}`,
+                '',
+                `     ${s.primary('>')} 1. TypeScript Strict (recommended)`,
+                `       2. TypeScript Relaxed`,
+                `       3. Custom (configure later)`,
+                '',
+                `     ${s.muted('Strict: Full TypeScript with strict mode + ESLint')}`,
+                `     ${s.muted('Relaxed: TypeScript with basic strict mode')}`,
+                `     ${s.muted('Custom: Configure your own standards later')}`,
+                '',
+                `     ${s.muted('Up/Down Navigate | Enter Select | Esc Back')}`,
+                '',
+            ],
+        },
+        // Page 9: Git Repository [6/8]
+        {
+            title: 'Git Repository',
+            lines: [
+                '',
+                `     ${s.primaryBold('Initialize New Project')} ${s.muted('[6/8]')}`,
+                '',
+                `     ${s.primary('Initialize git repository?')}`,
+                '',
+                `     ${s.primary('>')} Yes`,
+                `       No`,
+                '',
+                `     ${s.muted('Creates git repo with initial commit')}`,
+                '',
+                `     ${s.muted('Up/Down Navigate | Enter Select | Esc Back')}`,
+                '',
+                `  If you select Yes, you can optionally add a remote URL:`,
+                '',
+                `     ${s.primary('Git remote URL (optional)')}`,
+                '',
+                `     ${s.primary('>')} https://github.com/user/my-first-project${s.muted('|')}`,
+                '',
+                `     ${s.muted('Enter Continue · Esc Skip')}`,
+                '',
+            ],
+        },
+        // Page 10: Workflow Mode [7/8]
+        {
+            title: 'Workflow Mode',
+            lines: [
+                '',
+                `     ${s.primaryBold('Initialize New Project')} ${s.muted('[7/8]')}`,
+                '',
+                `     ${s.primary('Workflow mode')}`,
+                '',
+                `     ${s.primary('>')} 1. Flexible (user-driven, exploratory) ${s.muted('(recommended)')}`,
+                `       2. Guided (structured step-by-step workflow)`,
+                '',
+                `     ${s.muted('Flexible: Work at your own pace, agent responds to requests')}`,
+                `     ${s.muted('Guided: Agent suggests next steps, tracks work item progress')}`,
+                '',
+                `     ${s.muted('Up/Down Navigate | Enter Select | Esc Back')}`,
+                '',
+                `  ${s.warning('TIP:')} Start with Flexible. Switch to Guided anytime via ${s.primary('/workflow')}.`,
+                '',
+            ],
+        },
+        // Page 11: Confirmation [8/8]
+        {
+            title: 'Confirmation',
+            lines: [
+                '',
+                `     ${s.primaryBold('Initialize New Project')} ${s.muted('[8/8]')}`,
+                '',
+                `     ${s.primary('Ready to create project?')}`,
+                '',
+                `     Project:     ${s.primary('my-first-project')}`,
+                `     Location:    ${s.primary('./my-first-project/')}`,
+                `     Structure:   ${s.primary('Single repo')}`,
+                `     Tech:        ${s.primary('React + Node.js + PostgreSQL')}`,
+                `     Standards:   ${s.primary('TypeScript Strict (recommended)')}`,
+                `     Git:         ${s.primary('Yes')}`,
+                `     Remote:      ${s.primary('https://github.com/user/my-first-project')}`,
+                `     Workflow:    ${s.primary('Flexible (user-driven, exploratory)')}`,
+                '',
+                `     ${s.primary('>')} Create`,
+                `       Cancel`,
+                '',
+                `     ${s.muted('Up/Down Navigate | Enter Confirm | Esc Back')}`,
+                '',
+            ],
+        },
+        // Page 12: After Creation
+        {
+            title: 'After Creation',
+            lines: [
+                '',
+                `  After creating your project, you'll see the Dashboard with your project:`,
+                '',
+                `    ${s.muted('─'.repeat(50))}`,
+                `       ${s.muted('Dashboard')}  │  ${s.muted('More')}`,
+                `    ${s.muted('─'.repeat(50))}`,
+                '',
+                `      ${s.secondary('CURRENT PROJECT')}`,
+                `      ${s.primaryBold('★ My First Project')}`,
+                `        ${s.muted('/workspace/projects/my-first-project │ active │ flexible')}`,
+                '',
+                `      ${s.secondary('ACTIONS')}`,
+                `      ${s.primary('❯')} Continue with My First Project   ${s.muted('Resume working on current project')}`,
+                '',
+                `      ${s.muted('[n] /new   [p] Projects   [c] Chat   [w] Workflow')}`,
+                '',
+                `      ${s.muted('↑↓/jk Navigate   Enter Select   q Quit')}`,
+                '',
+                `  Select ${s.primary('Continue')} and press Enter to start chatting!`,
+                `  Try ${s.primary('/design')} to plan your features.`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/basics/navigation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Navigation & Help Tutorial
+ *
+ * How to find your way around the CLI.
+ * Uses shared content from shared-content.ts for consistency with guide tool.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const navigationTutorial: TutorialBuilder;

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

@@ -0,0 +1,22 @@
+/**
+ * Navigation & Help Tutorial
+ *
+ * How to find your way around the CLI.
+ * Uses shared content from shared-content.ts for consistency with guide tool.
+ */
+import { CONTENT_TOPICS } from '../../../../../guide/shared-content.js';
+import { topicsToPages } from '../../../../../guide/tutorial-helpers.js';
+// Topic IDs from shared content that form this tutorial
+const NAVIGATION_TOPIC_IDS = [
+    'help',
+    'overlay-navigation',
+    'dashboard',
+    'repl',
+    'commands-quick',
+];
+export const navigationTutorial = (s) => ({
+    id: 'navigation',
+    title: 'Navigation & Help',
+    description: 'Finding your way around',
+    pages: topicsToPages(NAVIGATION_TOPIC_IDS, CONTENT_TOPICS, s),
+});

package/dist/ui/overlay/data/tutorials/basics/welcome.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Welcome Tutorial
+ *
+ * Introduces the five pillars philosophy and development workflow overview.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const welcomeTutorial: TutorialBuilder;