mycontext-cli 4.2.17 → 4.2.19

package/README.md

@@ -1,106 +1,469 @@
-# MyContext CLI - Deterministic Full-Stack App Compiler
+# mycontext-cli
 
-Transform natural language into production-ready Next.js applications through deterministic compilation.
+> The Context Engine for AI-Native Development.  
+> Generate high-fidelity scaffolds, maintain a **Living Brain**, and drive your entire codebase with a single source of truth.
 
-MyContext is not an AI code generator—it's a natural-language-to-project compiler that uses LLMs only for intent parsing, while all code generation is performed by deterministic script templates. No hallucinations. No guessing. Just facts → manifest → complete application.
+[![npm version](https://img.shields.io/npm/v/mycontext-cli)](https://www.npmjs.com/package/mycontext-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-[![npm version](https://img.shields.io/npm/v/mycontext-cli.svg)](https://www.npmjs.com/package/mycontext-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+---
+
+## Table of Contents
+
+- [What is MyContext?](#what-is-mycontext)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Command Reference](#command-reference)
+  - [Project Setup](#project-setup)
+  - [Living Brain](#living-brain)
+  - [AI Agent & Planning](#ai-agent--planning)
+  - [Code Generation](#code-generation)
+  - [Analysis & Diagnostics](#analysis--diagnostics)
+  - [Maintenance](#maintenance)
+- [Typical Workflow](#typical-workflow)
+- [Environment Variables](#environment-variables)
+- [Configuration](#configuration)
+
+---
+
+## What is MyContext?
+
+MyContext treats your project spec as a **Living Brain** — a structured JSON document (`.mycontext/context.json`) that describes your app's goals, architecture, components, and design system. Every CLI command reads from and writes back to this Brain, keeping your code and your spec permanently in sync.
+
+---
+
+## Installation
+
+```bash
+npm install -g mycontext-cli
+# or
+pnpm add -g mycontext-cli
+```
+
+Verify:
+
+```bash
+mycontext --version
+```
 
 ---
 
-## 🧠 Core Philosophy
+## Quick Start
+
+```bash
+# 1. Go to your project folder (or an empty directory)
+cd my-app
+
+# 2. Initialise the Living Brain
+mycontext init
+
+# 3. Configure your AI provider
+mycontext setup
+
+# 4. Generate the full context from your PRD
+mycontext generate context --full
+
+# 5. Scaffold the entire application
+mycontext build
+```
+
+---
 
-### Zero-Hallucination Compilation
-Most AI tools act as "chat-driven coders" that guess your requirements. MyContext acts as a **Natural Language Compiler**:
-1. **Analyze**: LLM parses your intent into a strict JSON manifest (FSR).
-2. **Clarify**: The CLI identifies gaps and prompts you *before* any code is written.
-3. **Generate**: Deterministic script templates render valid, typed Next.js code.
+## Core Concepts
 
-### The Living Brain (`.mycontext/`)
-Every project is governed by a local "brain" folder that ensures your code, types, and design tokens never drift:
-- `context.json`: The master source of truth for your project features.
-- `design_manifest.json`: Your premium design tokens and layout rules.
-- `registry/`: Automated tracking of all generated components and actions.
+| Concept | What it is |
+|---|---|
+| **Living Brain** | `.mycontext/context.json` — single source of truth for your project |
+| **PRD** | `.mycontext/01-prd.md` — your product requirements document |
+| **Design Manifest** | AI-derived design system snapshot |
+| **Sub-agents** | Specialised AI workers (CodeGen, QA, Architect, Security, …) |
+| **FSR** | Feature Spec Record — structured description of a single feature |
 
 ---
 
-## 🚀 NEW: Phase 0.7 Premium Features (VERIFIED ✓)
+## Command Reference
+
+### Project Setup
+
+#### `mycontext init [project-name]`
+
+Initialise a new MyContext project. Creates `.mycontext/` with your PRD template, context skeleton, and (optionally) a framework scaffold.
+
+```bash
+mycontext init my-saas-app
+mycontext init --framework nextjs          # Next.js + shadcn/ui
+mycontext init --framework instantdb       # Next.js + InstantDB + shadcn (default)
+mycontext init --framework other           # MyContext files only
+mycontext init --interactive               # Guided 100%-complete spec wizard
+mycontext init --spec-only                 # Context files only, no framework setup
+```
+
+#### `mycontext setup`
+
+Configure AI providers (Anthropic, OpenAI, xAI) and your development stack.
+
+```bash
+mycontext setup
+mycontext setup --stack nextjs-tailwind-shadcn
+```
+
+#### `mycontext auth`
+
+Authenticate with the MyContext AI cloud service.
+
+```bash
+mycontext auth --login
+mycontext auth --status
+mycontext auth --logout
+```
+
+#### `mycontext setup-shadcn`
+
+Add shadcn/ui to an existing project and wire it to the Living Brain.
+
+#### `mycontext setup-database`
+
+Set up a database provider (InstantDB, Supabase, Firebase) with schema and auth components.
+
+```bash
+mycontext setup-database --provider instantdb
+```
+
+#### `mycontext setup-instantdb`
+
+Full InstantDB + MCP integration wizard.
+
+```bash
+mycontext setup-instantdb --app-id <id> --token <token>
+```
+
+#### `mycontext setup-mcp`
+
+Configure a Model Context Protocol (MCP) server for AI-powered tooling.
 
-- **Smart Layout Engine**: Autonomic 8/12 grid placement based on component `weight`.
-- **Test-Mode Fast-Forward**: Detects `__MYCONTEXT_TEST_MODE__` to speed up animations 60x.
-- **Auto-Test Generation**: `mycontext test:generate` creates Playwright specs from your FSR.
-- **Density Guardrails**: Visual checks to prevent "rammed UI" and visual clutter.
+```bash
+mycontext setup-mcp --provider instantdb
+mycontext setup-mcp --provider github
+mycontext setup-mcp --provider custom --server <url>
+```
 
 ---
 
+### Living Brain
+
+#### `mycontext generate [type]`
+
+Orchestrate the Living Brain — generate context files, types, brand tokens, and more.
+
+```bash
+mycontext generate context --full          # Full PRD + A/B/C/D context files
+mycontext generate context                 # Incremental update
+mycontext generate --from-schema           # Types from InstantDB schema
+mycontext generate design-prompt           # AI design brief
+mycontext generate screens                 # Screen list from user flows
+mycontext generate components-manifest     # Component props + sample data
+mycontext generate actions                 # UI→backend action hooks
+mycontext generate assets                  # Planned asset list
+mycontext generate sample-data             # Seed data for development
+```
+
+#### `mycontext sync`
+
+Auto-update `context.json` and `README.md` by scanning the live codebase.
+
+```bash
+mycontext sync                   # Sync both
+mycontext sync --context         # context.json only
+mycontext sync --readme          # README.md only
+mycontext sync --dry-run         # Preview changes without writing
+```
+
+#### `mycontext sync-readme`
+
+Synchronise the root `README.md` with your design manifest.
+
+#### `mycontext validate <target>`
+
+Validate your PRD or context files for completeness.
+
+```bash
+mycontext validate prd
+mycontext validate context
+mycontext validate --interactive
+```
+
+#### `mycontext status`
+
+Show current project status and progress against the Living Brain.
+
+```bash
+mycontext status
+mycontext status --detailed
+```
+
 ---
 
-## 🚀 The Brain-First Workflow
+### AI Agent & Planning
+
+#### `mycontext agent [prompt]`
+
+Assess a natural-language prompt against the Living Brain and propose (or apply) changes.
 
-Transforming natural language into project intent involves three core stages, all mediated by the **Living Brain (`.mycontext/context.json`)**.
+```bash
+mycontext agent "Add a dark mode toggle to the nav"
+mycontext agent "Add a dark mode toggle" --execute   # Apply changes
+mycontext agent "..." --execute --yes                # Skip confirmation
+```
+
+#### `mycontext plan`
+
+Interactive feature planning session — produces an FSR (Feature Spec Record).
 
-### 1. Initialization (`mycontext init`)
-Establish the `.mycontext` directory and establish the source of truth.
 ```bash
-mycontext init --interactive
+mycontext plan
 ```
-*AI auto-infers project framework, core entities, and foundational requirements.*
 
-### 2. High-Fidelity Sync (`mycontext generate context --full`)
-The most critical step. This command performs a unified AI pass to synchronize:
-- **Requirements**: Functional and non-functional specs (PRD).
-- **Features**: Atomic feature breakdown with technical specifications.
-- **Types**: Shared TypeScript entity definitions and database schemas.
-- **Brand**: Visual design tokens (colors, typography).
-- **Registry**: Auto-discovery of existing code to prevent drift.
+#### `mycontext build-strategy`
+
+Generate an AI-powered build strategy and execution plan from the current Brain state.
+
+#### `mycontext ideate`
+
+Generate creative UI/UX concepts based on project context.
 
 ```bash
-mycontext generate context --full --description "A removal tool for image backgrounds"
+mycontext ideate --industry fintech --count 5
 ```
 
-### 3. Component Orchestration (`mycontext generate-components`)
-Render the specifications in the brain into production-ready React code.
+---
+
+### Code Generation
+
+#### `mycontext build`
+
+Scaffold the **entire** application from the Living Brain in one shot.
+
+```bash
+mycontext build
+mycontext build --force    # Regenerate all components
+```
+
+#### `mycontext build-feature`
+
+Build a single feature end-to-end from an FSR.
+
+#### `mycontext generate-components [target]`
+
+Generate React components from the component manifest.
+
 ```bash
-# Generate everything in the brain
 mycontext generate-components all
+mycontext generate-components --core-only     # First 10 components only
+mycontext generate-components --group forms
+mycontext generate-components all --with-tests
+```
+
+#### `mycontext add <component>`
+
+Add a context-aware component (shadcn primitive or custom).
+
+```bash
+mycontext add button
+mycontext add UserCard --group cards
+mycontext add dialog --shadcn
+```
+
+#### `mycontext enhance`
+
+Enhance the project or specific components with AI suggestions.
+
+#### `mycontext refine`
+
+Refine context or components.
+
+#### `mycontext refine:component <componentName>`
 
-# Or target a specific group
-mycontext generate-components gallery
+Refine a single component with targeted AI feedback.
+
+```bash
+mycontext refine:component HeroSection --variant mobile
+mycontext refine:component NavBar --in-place
 ```
 
-### 4. Project Cockpit (The Dashboard)
-Run `mycontext` without arguments to launch the interactive dashboard.
-- **Project Health**: View feature completeness and type coverage.
-- **Registry Manager**: Browse generated components and schemas.
-- **Sync Trigger**: Instantly refresh the brain from the dashboard.
+#### `mycontext migrate [target]`
+
+Migrate components to new standards.
+
+```bash
+mycontext migrate rtl                          # RTL-friendly logical CSS properties
+mycontext migrate rtl --path src/components/Nav.tsx
+mycontext migrate radix --all                  # Refactor to Radix/shadcn primitives
+```
 
 ---
 
-## 🛠️ Diagnostics & Maintenance
+### Analysis & Diagnostics
+
+#### `mycontext analyze`
+
+Analyse an **existing** project and generate context files from the live codebase.
+
+```bash
+mycontext analyze
+mycontext analyze --image ./screenshot.png    # Analyse a mockup instead
+mycontext analyze --verbose
+```
+
+#### `mycontext design`
+
+Design system analysis and manifest generation.
+
+```bash
+mycontext design --analyze
+mycontext design --validate
+mycontext design --summary
+mycontext design --regenerate
+```
+
+#### `mycontext scan`
+
+Scan the project tree and assess progress against the Living Brain.
+
+```bash
+mycontext scan
+mycontext scan --assess          # AI progress assessment
+mycontext scan --assess --json   # Machine-readable output
+```
+
+#### `mycontext health-check`
+
+Run health checks across the project.
+
+#### `mycontext doctor`
+
+Full diagnostic check with auto-fix suggestions.
+
+#### `mycontext sanitize`
+
+Find and optionally remove redundant, duplicate, or unreachable code.
+
+```bash
+mycontext sanitize
+mycontext sanitize --fix
+mycontext sanitize --verbose
+```
 
-- **`mycontext doctor`**: Verify project health, type safety, and schema alignment.
-- **`mycontext sync --readme`**: Synchronize the root README with the brain's latest design manifest.
-- **`mycontext status`**: Quick check of the current project state.
+#### `mycontext generate-todos`
+
+Generate a contextual todo list from the project's current state.
+
+```bash
+mycontext generate-todos --count 10 --energy high --complexity moderate
+```
 
 ---
 
-## 📦 Installation
+### Maintenance
+
+#### `mycontext update`
+
+Update the CLI to the latest published version.
+
 ```bash
-npm install -g mycontext-cli
+mycontext update
+```
+
+#### `mycontext clean`
+
+Clean and repair malformed context files.
+
+```bash
+mycontext clean
+mycontext clean --project ./path/to/project
+```
+
+#### `mycontext help [topic]`
+
+Context-aware help for any topic or command.
+
+```bash
+mycontext help
+mycontext help agent
+mycontext help generate --verbose
 ```
 
 ---
 
-## 🛣️ Roadmap
-- [x] **Phase 0.7**: Brain-First Architecture & TUI Dashboard
-- [x] **Phase 0.8**: Smart Layout Engine & Deterministic Scaffolding
-- [ ] **Phase 1**: Multi-Agent Orchestration (Backend/Security/QA)
-- [ ] **Phase 2**: Granular component-level targeted LLM refactors
+## Typical Workflow
+
+### Starting a new project
+
+```bash
+mkdir my-app && cd my-app
+mycontext init --interactive          # Guided spec wizard
+mycontext setup                       # Configure AI keys
+mycontext generate context --full     # Build the Living Brain
+mycontext generate components-manifest
+mycontext build                       # Scaffold the whole app
+```
+
+### Adding a feature to an existing project
+
+```bash
+mycontext plan                        # Describe the feature interactively
+mycontext build-feature               # Generate code from the FSR
+mycontext sync                        # Keep context.json in sync
+```
+
+### Adopting MyContext on an existing codebase
+
+```bash
+cd existing-project
+mycontext analyze                     # Reverse-engineer context from code
+mycontext generate context            # Fill gaps with AI
+mycontext status                      # See what's covered
+```
+
+---
+
+## Environment Variables
+
+MyContext loads `.env` files from your project automatically. You can also set these directly:
+
+| Variable | Description |
+|---|---|
+| `ANTHROPIC_API_KEY` | Anthropic Claude API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| `XAI_API_KEY` | xAI (Grok) API key |
+| `MYCONTEXT_API_KEY` | MyContext cloud service key |
+| `INSTANTDB_APP_ID` | InstantDB application ID |
+
+Loaded in order (first match wins):  
+`.mycontext/.env.local` → `.mycontext/.env` → `.env.local` → `.env`
+
+---
+
+## Configuration
+
+All project configuration lives in `.mycontext/`:
+
+```
+.mycontext/
+├── context.json        ← Living Brain (source of truth)
+├── 01-prd.md           ← Product Requirements Document
+├── .env.local          ← Local secrets (git-ignored)
+└── ...                 ← Generated context files
+```
+
+---
+
+## Links
+
+- [GitHub](https://github.com/farajabien/mycontext-cli)
+- [Issues](https://github.com/farajabien/mycontext-cli/issues)
+- [npm](https://www.npmjs.com/package/mycontext-cli)
 
 ---
 
-## 📄 License & Links
-MIT © [MyContext Team](https://github.com/farajabien/mycontext-cli)
-- [Documentation](https://mycontext.framer.website)
-- [NPM: mycontext-cli](https://www.npmjs.com/package/mycontext-cli)
+*Built with MyContext — spec-driven development for the AI era.*

package/dist/agents/implementations/SolverAgent.d.ts

@@ -0,0 +1,42 @@
+/**
+ * SolverAgent
+ *
+ * Research sub-agent that implements Phase 2–4 of the "Structured Reasoning
+ * Systems" research plan:
+ *
+ *   NL → LLM → ConstraintSpec (JSON Brain) → Solver → SolveResult + metrics
+ *
+ * The solver operates in pure TypeScript with no external dependencies so the
+ * pipeline can run immediately. Swap the `_nativeSolve` call for a Z3 /
+ * OR-Tools binding once you want to scale to harder instances.
+ *
+ * Key design choices:
+ *  - Expression evaluation uses a recursive-descent parser (NO eval()).
+ *  - Three interchangeable strategies: brute-force, constraint-propagation,
+ *    llm-guided (LLM trims the domain before search).
+ *  - Every run produces a SolveTrace with operations count, search-space size,
+ *    pruning ratio — the numbers for Phase 4 / 5 measurement tables.
+ */
+import { SubAgent } from "../interfaces/SubAgent";
+import { SolverInput, SolverOutput, ConstraintSpec } from "../../types/constraint";
+export declare class SolverAgent implements SubAgent<SolverInput, SolverOutput> {
+    name: string;
+    description: string;
+    personality: string;
+    llmProvider: string;
+    expertise: string[];
+    private ai;
+    constructor();
+    validate(input: SolverInput): Promise<boolean>;
+    run(input: SolverInput): Promise<SolverOutput>;
+    private _translateNL;
+    private _llmNarrowDomains;
+    getStatus(): Promise<{
+        name: string;
+        status: "idle";
+        errorCount: number;
+        successCount: number;
+    }>;
+}
+export declare function createFactorizationSpec(N: number): ConstraintSpec;
+//# sourceMappingURL=SolverAgent.d.ts.map

package/dist/agents/implementations/SolverAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SolverAgent.d.ts","sourceRoot":"","sources":["../../../src/agents/implementations/SolverAgent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,OAAO,EACL,WAAW,EACX,YAAY,EACZ,cAAc,EAQf,MAAM,wBAAwB,CAAC;AAwbhC,qBAAa,WAAY,YAAW,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;IACrE,IAAI,SAAiB;IACrB,WAAW,SACsJ;IACjK,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB,OAAO,CAAC,EAAE,CAAiB;;IAWrB,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAI9C,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;YAuCtC,YAAY;YAqCZ,iBAAiB;IA8BzB,SAAS;;;;;;CAQhB;AAMD,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,GAAG,cAAc,CAqBjE"}