@compilr-dev/cli 0.7.1 → 0.7.3

package/dist/index.js

@@ -100,20 +100,24 @@ Options:
   --version, -v               Show version number
   --help, -h                  Show this help
 
-Environment Variables:
-  ANTHROPIC_API_KEY           Required for Claude provider
-  OPENAI_API_KEY              Required for OpenAI provider
-  GOOGLE_AI_API_KEY           Required for Gemini provider
+API Keys:
+  Run /init inside the REPL to set up API keys (encrypted local storage).
+  Alternatively, set environment variables:
+  ANTHROPIC_API_KEY           Claude provider
+  OPENAI_API_KEY              OpenAI provider
+  GOOGLE_AI_API_KEY           Gemini provider
+
+Other Environment Variables:
   NO_COLOR                    Disable ANSI colors
   COMPILR_NO_UPDATE_CHECK     Skip the npm registry update check at startup
   CI                          Auto-skips the update check
 
 Examples:
-  compilr
-  compilr --model claude-sonnet-4-6
+  compilr                                          Start with auto-detected provider
+  compilr --model claude-sonnet-4-6                Use a specific model
   compilr --provider gemini --model gemini-2.0-flash
-  compilr --minimal --show-filtering
-  compilr --update
+  compilr --minimal --show-filtering               Minimal tools with analysis
+  compilr --update                                 Check for updates
 `);
 }
 // =============================================================================

package/dist/ui/overlay/data/tutorial-registry.js

@@ -9,11 +9,13 @@ import { welcomeTutorial } from './tutorials/basics/welcome.js';
 import { firstProjectTutorial } from './tutorials/basics/first-project.js';
 import { firstConversationTutorial } from './tutorials/basics/first-conversation.js';
 import { navigationTutorial } from './tutorials/basics/navigation.js';
+import { imageSupportTutorial } from './tutorials/basics/image-support.js';
 import { newProjectTutorial } from './tutorials/projects/new-project.js';
 import { managingProjectsTutorial } from './tutorials/projects/managing-projects.js';
 import { sessionManagementTutorial } from './tutorials/projects/session-management.js';
 import { anchorsTutorial } from './tutorials/projects/anchors.js';
 import { importProjectTutorial } from './tutorials/projects/import-project.js';
+import { appModelTutorial } from './tutorials/projects/app-model.js';
 import { designTutorial } from './tutorials/planning/design.js';
 import { backlogTutorial } from './tutorials/planning/backlog.js';
 import { sketchTutorial } from './tutorials/planning/sketch.js';
@@ -51,6 +53,7 @@ export function buildTutorialRegistry(s) {
                 firstProjectTutorial(s),
                 firstConversationTutorial(s),
                 navigationTutorial(s),
+                imageSupportTutorial(s),
             ],
         },
         // =========================================================================
@@ -65,6 +68,7 @@ export function buildTutorialRegistry(s) {
                 managingProjectsTutorial(s),
                 sessionManagementTutorial(s),
                 anchorsTutorial(s),
+                appModelTutorial(s),
             ],
         },
         // =========================================================================

package/dist/ui/overlay/data/tutorials/basics/image-support.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Image Support Tutorial
+ *
+ * How to share images (screenshots, mockups, diagrams) with the agent
+ * for visual analysis.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const imageSupportTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/basics/image-support.js

@@ -0,0 +1,91 @@
+/**
+ * Image Support Tutorial
+ *
+ * How to share images (screenshots, mockups, diagrams) with the agent
+ * for visual analysis.
+ */
+export const imageSupportTutorial = (s) => ({
+    id: 'image-support',
+    title: 'Image Support',
+    description: 'Share screenshots and diagrams',
+    pages: [
+        // Page 1: Overview
+        {
+            title: 'Sharing Images',
+            lines: [
+                '',
+                `  The agent can ${s.primaryBold('see images')} — screenshots, mockups, diagrams,`,
+                `  error dialogs — and reason about them visually.`,
+                '',
+                `  ${s.secondary('Useful for:')}`,
+                '',
+                `    ${s.muted('•')} Showing a UI bug: ${s.muted('"Why is this button misaligned?"')}`,
+                `    ${s.muted('•')} Translating a mockup into code`,
+                `    ${s.muted('•')} Asking about an error screenshot`,
+                `    ${s.muted('•')} Reviewing a diagram or architecture sketch`,
+                '',
+                `  ${s.secondary('Supported formats:')}`,
+                '',
+                `    ${s.primaryBold('PNG')} · ${s.primaryBold('JPEG')} · ${s.primaryBold('GIF')} · ${s.primaryBold('WebP')}`,
+                '',
+                `  ${s.secondary('Supported by:')} Claude, GPT-4o, Gemini (all major vision models)`,
+                '',
+            ],
+        },
+        // Page 2: How to Share
+        {
+            title: 'How to Share an Image',
+            lines: [
+                '',
+                `  Just point the agent at the file path. It will call the`,
+                `  ${s.primaryBold('view_image')} tool to load and analyze it.`,
+                '',
+                `  ${s.secondary('Examples:')}`,
+                '',
+                `    ${s.muted('"Look at /tmp/screenshot.png — what is wrong with the layout?"')}`,
+                '',
+                `    ${s.muted('"Open ~/Desktop/mockup.png and turn it into a React component"')}`,
+                '',
+                `    ${s.muted('"Check the error in ./bug.jpg"')}`,
+                '',
+                `  ${s.secondary('Where images can live:')}`,
+                '',
+                `    ${s.muted('•')} Anywhere on disk (absolute or relative paths work)`,
+                `    ${s.muted('•')} In your project's knowledge base (pin them with /kb)`,
+                `    ${s.muted('•')} In a project folder — the agent can list and pick them`,
+                '',
+                `  ${s.warning('TIP:')} If you have multiple shots of the same bug, share them`,
+                `  in one message — the agent compares views in a single pass.`,
+                '',
+            ],
+        },
+        // Page 3: Limits and Token Cost
+        {
+            title: 'Limits and Token Cost',
+            lines: [
+                '',
+                `  Images consume tokens. The CLI handles this automatically:`,
+                '',
+                `  ${s.primaryBold('Auto-resize:')}`,
+                `    Images larger than ${s.primaryBold('1568px')} are resized down to save`,
+                `    tokens. You don't need to pre-process screenshots.`,
+                '',
+                `  ${s.primaryBold('File size cap:')}`,
+                `    Maximum ${s.primaryBold('10 MB')} per image. Larger files are rejected.`,
+                '',
+                `  ${s.primaryBold('Image masking:')}`,
+                `    After a few turns, old images are replaced with text`,
+                `    placeholders (saves ~1000+ tokens per image). The agent`,
+                `    can still reference them by description.`,
+                '',
+                `  ${s.secondary('Typical cost per image (post-resize):')}`,
+                '',
+                `    ${s.muted('~800 — 1.500 tokens for a UI screenshot')}`,
+                `    ${s.muted('~1.500 — 3.000 tokens for a dense diagram')}`,
+                '',
+                `  See ${s.primary('/context')} to inspect current image + token usage.`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/projects/app-model.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Application Model Tutorial
+ *
+ * Walkthrough of the /app command and ApplicationModel — the structured
+ * project blueprint that drives factory_scaffold and entity-aware codegen.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const appModelTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/projects/app-model.js

@@ -0,0 +1,120 @@
+/**
+ * Application Model Tutorial
+ *
+ * Walkthrough of the /app command and ApplicationModel — the structured
+ * project blueprint that drives factory_scaffold and entity-aware codegen.
+ */
+export const appModelTutorial = (s) => ({
+    id: 'app-model',
+    title: 'Application Model',
+    description: 'View entities, relationships, features',
+    pages: [
+        // Page 1: What is the Application Model
+        {
+            title: 'What is the Application Model?',
+            lines: [
+                '',
+                `  The ${s.primaryBold('Application Model')} is a structured blueprint of your`,
+                `  project — entities, fields, relationships, and features.`,
+                '',
+                `  It's the bridge between ${s.primary('/design')} (planning) and`,
+                `  ${s.primary('/scaffold')} (code generation).`,
+                '',
+                `  ${s.secondary('When you have a model, the agent can:')}`,
+                '',
+                `    ${s.muted('•')} Generate full-stack code via ${s.primaryBold('factory_scaffold')}`,
+                `    ${s.muted('•')} Add entity CRUD pages, API routes, seed data automatically`,
+                `    ${s.muted('•')} Keep frontend ↔ backend types in sync`,
+                `    ${s.muted('•')} Apply consistent naming and validation across the app`,
+                '',
+                `  Without a model, scaffolding is best-effort from prose READMEs.`,
+                `  With a model, scaffolding is precise and reproducible.`,
+                '',
+            ],
+        },
+        // Page 2: The /app Command
+        {
+            title: 'The /app Command',
+            lines: [
+                '',
+                `  The ${s.primary('/app')} command opens an interactive overlay`,
+                `  showing the ApplicationModel for the current project.`,
+                '',
+                `  ${s.secondary('Three tabs (cycle with Tab):')}`,
+                '',
+                `    ${s.primaryBold('Entities')}        Browse each entity with fields, types,`,
+                `                    constraints, and relationships`,
+                '',
+                `    ${s.primaryBold('Relationships')}   See the connection map: which entities`,
+                `                    link to which (hasMany, belongsTo)`,
+                '',
+                `    ${s.primaryBold('Summary')}         Project identity, theme, tech stack,`,
+                `                    feature toggles (auth, search, dark mode)`,
+                '',
+                `  ${s.secondary('Navigation:')}`,
+                '',
+                `    ${s.muted('↑/↓')}   Navigate items`,
+                `    ${s.muted('Enter')} Open entity detail (fields + relationships)`,
+                `    ${s.muted('/')}     Search`,
+                `    ${s.muted('q/Esc')} Close overlay`,
+                '',
+            ],
+        },
+        // Page 3: How the Model is Built
+        {
+            title: 'How the Model is Built',
+            lines: [
+                '',
+                `  The ApplicationModel is stored as a project document of type`,
+                `  ${s.primaryBold('app-model')}. The agent maintains it through three tools:`,
+                '',
+                `  ${s.primaryBold('app_model_get')}      Read the current model (scoped reads)`,
+                `  ${s.primaryBold('app_model_update')}   Apply semantic operations:`,
+                `                       ${s.muted('add/remove/rename entity')}`,
+                `                       ${s.muted('add/remove/rename field')}`,
+                `                       ${s.muted('add/remove relationship')}`,
+                `                       ${s.muted('set identity/theme/tech stack')}`,
+                `  ${s.primaryBold('app_model_validate')} Check consistency before scaffolding`,
+                '',
+                `  ${s.secondary('Typical workflow:')}`,
+                '',
+                `    ${s.primary('1.')} ${s.primary('/design')} or ${s.primary('/prd')} captures entities + features in prose`,
+                `    ${s.primary('2.')} ${s.primary('/app')} (or the agent) builds the model incrementally`,
+                `    ${s.primary('3.')} ${s.primary('/scaffold')} reads the model and generates code`,
+                '',
+                `  You don't usually edit the model by hand — ask the agent.`,
+                '',
+            ],
+        },
+        // Page 4: When a Model Exists
+        {
+            title: 'When a Model Exists',
+            lines: [
+                '',
+                `  If ${s.primary('/app')} shows ${s.warning('"No application model found"')}, you have two`,
+                `  options to create one:`,
+                '',
+                `  ${s.primaryBold('Option 1 — Start fresh:')}`,
+                '',
+                `    ${s.muted('"Build an app model for this project"')}`,
+                `    ${s.muted('"What entities should we model for a TODO app?"')}`,
+                '',
+                `    The agent will ask clarifying questions and call`,
+                `    ${s.muted('app_model_update')} to build the model step by step.`,
+                '',
+                `  ${s.primaryBold('Option 2 — Derive from existing planning docs:')}`,
+                '',
+                `    If you already have a PRD or design doc, just say:`,
+                '',
+                `    ${s.muted('"Build the app model from the PRD"')}`,
+                '',
+                `    The agent reads ${s.primary('project_document_get')} and extracts entities,`,
+                `    relationships, and features into a structured model.`,
+                '',
+                `  Once the model exists, ${s.primary('/scaffold')} will detect it and use`,
+                `  ${s.primaryBold('factory_scaffold')} to generate matching code.`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/utils/credentials.js

@@ -148,7 +148,7 @@ export function getApiKey(provider) {
     const envVarMap = {
         anthropic: 'ANTHROPIC_API_KEY',
         openai: 'OPENAI_API_KEY',
-        google: 'GOOGLE_API_KEY',
+        google: 'GOOGLE_AI_API_KEY',
         ollama: '', // No key needed
         together: 'TOGETHER_API_KEY',
         groq: 'GROQ_API_KEY',
@@ -239,7 +239,7 @@ export function isKeyFromEnv(provider) {
     const envVarMap = {
         anthropic: 'ANTHROPIC_API_KEY',
         openai: 'OPENAI_API_KEY',
-        google: 'GOOGLE_API_KEY',
+        google: 'GOOGLE_AI_API_KEY',
         ollama: '',
         together: 'TOGETHER_API_KEY',
         groq: 'GROQ_API_KEY',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/cli",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "AI-powered coding assistant CLI using @compilr-dev/agents",
   "type": "module",
   "main": "dist/index.js",
@@ -60,7 +60,7 @@
     "@compilr-dev/editor-core": "^0.0.2",
     "@compilr-dev/factory": "^0.1.30",
     "@compilr-dev/logger": "^0.1.0",
-    "@compilr-dev/sdk": "^0.10.8",
+    "@compilr-dev/sdk": "^0.10.9",
     "@compilr-dev/ui-core": "^0.0.1",
     "@modelcontextprotocol/sdk": "^1.23.0",
     "ansi-escapes": "^7.3.0",