@husar.ai/cli 0.4.0 → 0.4.2

package/AGENTS.md

@@ -0,0 +1,835 @@
+# @husar.ai/cli
+
+Command-line interface and MCP server for Husar CMS integration.
+
+## Package Overview
+
+| Property | Value           |
+| -------- | --------------- |
+| Name     | `@husar.ai/cli` |
+| Version  | `0.4.1`         |
+| Binary   | `husar.ai`      |
+| Location | `packages/cli`  |
+
+## Dependencies
+
+- `commander` - CLI framework
+- `config-maker` - Configuration management (husar.json)
+- `@husar.ai/ssr` - Code generation (generateZeus)
+- `@husar.ai/genai` - AI tools and ORM tool definitions
+- `@modelcontextprotocol/sdk` - MCP server implementation
+- `zod` - Input validation
+- `graphql` - Schema introspection and SDL generation
+
+## Source Files
+
+| File                        | Purpose                                    |
+| --------------------------- | ------------------------------------------ |
+| `src/cli.ts`                | Main CLI entry point with commander setup  |
+| `src/mcp.ts`                | Full MCP server implementation             |
+| `src/index.ts`              | Exports parser function for external use   |
+| `src/functions/generate.ts` | Generate command implementation            |
+| `src/functions/parser.ts`   | File parsing and CMS upload utilities      |
+| `src/functions/create.ts`   | Create command (project scaffolding)       |
+| `src/auth/api.ts`           | Cloud API client (getProjects, verify JWT) |
+| `src/auth/login.ts`         | Login flows (cloud + panel)                |
+| `src/auth/config.ts`        | Auth config management (~/.husar/)         |
+| `src/types/config.ts`       | Configuration type definitions             |
+
+---
+
+## Configuration
+
+The CLI uses `husar.json` configuration file managed by `config-maker`.
+
+### Config File Structure
+
+```json
+{
+  "host": "https://your-husar-instance.com",
+  "adminToken": "your-admin-token",
+  "adminTokenEnv": "HUSAR_ADMIN_TOKEN",
+  "contentApiKey": "your-content-api-key",
+  "hostEnvironmentVariable": "HUSAR_HOST",
+  "authenticationEnvironmentVariable": "HUSAR_API_KEY",
+  "overrideHost": false
+}
+```
+
+### Config Properties
+
+| Property                            | Type    | Description                                 |
+| ----------------------------------- | ------- | ------------------------------------------- |
+| `host`                              | string  | Base URL of the Husar CMS instance          |
+| `adminToken`                        | string  | Admin API token (legacy, use adminTokenEnv) |
+| `adminTokenEnv`                     | string  | Env var name containing admin token         |
+| `contentApiKey`                     | string  | Content API key for read-only access        |
+| `hostEnvironmentVariable`           | string  | Env var name for host (optional)            |
+| `authenticationEnvironmentVariable` | string  | Env var name for auth token (optional)      |
+| `overrideHost`                      | boolean | Whether to override host from env           |
+
+**Note:** The `adminTokenEnv` field is preferred over `adminToken`. When set, the CLI reads the admin token from the specified environment variable (e.g., `HUSAR_ADMIN_TOKEN`). This allows `husar.json` to be safely committed to version control.
+
+### Environment Variables
+
+- `HUSAR_HOST` / `NEXT_PUBLIC_HUSAR_HOST` / `VITE_HUSAR_HOST` - Host URL fallbacks
+- `HUSAR_API_KEY` - Default auth environment variable
+- `HUSAR_MCP_HOST` - MCP-specific host override
+- `HUSAR_MCP_ADMIN_TOKEN` - MCP-specific admin token
+- `MCP_PARSER_TIMEOUT_MS` - Parser timeout (default: 30000ms)
+
+---
+
+## CLI Commands
+
+### `husar.ai generate [folderPath]`
+
+Generates the `cms/` folder structure with Zeus GraphQL client and helper files.
+
+**Usage:**
+
+```bash
+husar.ai generate           # Generate in current directory
+husar.ai generate ./src     # Generate in ./src/cms/
+```
+
+**Generated Files:**
+
+```
+cms/
+├── zeus/
+│   ├── index.ts   # Zeus GraphQL client
+│   └── const.ts   # Constants and types
+├── host.ts        # Host configuration and getCmsHost()
+├── ssr.ts         # SSR client: husarClient setup
+└── react.ts       # React components: Shape, View, Model
+```
+
+**Prerequisites:**
+
+- `husar.json` with valid `host` configured
+- Optionally set `hostEnvironmentVariable` and `authenticationEnvironmentVariable`
+
+---
+
+### `husar.ai copy <inputFile> <name>`
+
+Parse HTML/JSX file using AI and upsert into CMS as model or shape.
+
+**Usage:**
+
+```bash
+husar.ai copy ./components/Hero.tsx hero_section
+husar.ai copy ./components/ContactForm.tsx contact_form --type model
+husar.ai copy ./pages/About.html about_page --type shape
+```
+
+**Options:**
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-t, --type <type>` | `shape` | Target type: `model` or `shape` |
+
+**Prerequisites:**
+
+- `husar.json` with valid `host` and `adminToken`
+
+**Supported File Types:**
+
+- `.tsx`, `.jsx` - React/JSX components
+- `.ts`, `.js` - TypeScript/JavaScript files
+- `.html` - HTML files
+
+---
+
+### `husar.ai mcp`
+
+Starts the MCP (Model Context Protocol) server for AI IDE integration.
+
+**Usage:**
+
+```bash
+husar.ai mcp
+```
+
+**Integration with IDEs:**
+
+For Claude Desktop, add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "husar": {
+      "command": "npx",
+      "args": ["husar.ai", "mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+For VS Code with Continue.dev or similar:
+
+```json
+{
+  "mcpServers": {
+    "husar": {
+      "command": "husar.ai",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+---
+
+### `husar.ai create [projectName]`
+
+Create a new project with Husar CMS integration. This is the recommended onboarding flow for new users.
+
+**Usage:**
+
+```bash
+husar.ai create                    # Interactive project creation
+husar.ai create my-app             # Create with specified name
+husar.ai create my-app -f vite     # Use Vite instead of Next.js
+husar.ai create --skip-install     # Skip npm install after scaffolding
+```
+
+**Options:**
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-f, --framework <framework>` | `nextjs` | Framework: `nextjs` or `vite` |
+| `--skip-install` | `false` | Skip package installation |
+
+**Flow:**
+
+1. Choose connection method (manual URL or cloud login)
+2. If cloud login: Authenticate via browser → Select project from list
+3. Panel CMS login: Authenticate with SUPERADMIN credentials via browser
+4. Framework CLI runs (create-next-app or create-vite)
+5. Husar configuration added (`husar.json`, `.env.local`, `opencode.jsonc`)
+6. Husar packages installed (`@husar.ai/ssr`, `@husar.ai/render`)
+7. CMS client generated (`cms/` folder)
+
+**Generated Configuration:**
+
+```
+project/
+├── husar.json          # CMS config (committal, no secrets)
+├── .env.local          # Secrets (NOT committed)
+└── opencode.jsonc      # MCP integration for AI IDEs
+```
+
+**husar.json (safe to commit):**
+
+```json
+{
+  "host": "https://your-instance.husar.ai",
+  "hostEnvironmentVariable": "NEXT_PUBLIC_HUSAR_HOST",
+  "authenticationEnvironmentVariable": "HUSAR_API_KEY",
+  "adminTokenEnv": "HUSAR_ADMIN_TOKEN",
+  "overrideHost": false
+}
+```
+
+**.env.local (secrets - NOT committed):**
+
+```env
+NEXT_PUBLIC_HUSAR_HOST=https://your-instance.husar.ai
+HUSAR_API_KEY=
+HUSAR_ADMIN_TOKEN=your-admin-token
+```
+
+---
+
+### `husar.ai login`
+
+Log in to Husar.ai cloud via browser authentication.
+
+**Usage:**
+
+```bash
+husar.ai login
+```
+
+**Flow:**
+
+1. Opens browser to `husar.ai/app/cli-auth`
+2. User authenticates (login or create account)
+3. JWT token is returned and saved to `~/.husar/config.json`
+
+**Note:** Cloud login is optional. You can also use manual URL entry in the `create` command.
+
+---
+
+### `husar.ai logout`
+
+Log out and clear stored credentials.
+
+**Usage:**
+
+```bash
+husar.ai logout
+```
+
+**Clears:**
+
+- Cloud JWT token
+- Cached project authentications
+- All data in `~/.husar/config.json`
+
+---
+
+### `husar.ai whoami`
+
+Display current logged-in user and connected projects.
+
+**Usage:**
+
+```bash
+husar.ai whoami
+```
+
+**Output:**
+
+```
+👤 Logged in as: user@example.com
+
+📦 Connected projects:
+   • my-project
+     Host: https://my-project.husar.ai
+
+📁 Config: ~/.husar/config.json
+```
+
+---
+
+## MCP Server Tools
+
+The MCP server exposes tools for AI assistants to interact with Husar CMS.
+
+### Core Tools
+
+#### `husar_copy`
+
+Parse HTML/JSX file and upsert into CMS.
+
+**Input Schema:**
+
+```typescript
+{
+  path: string;           // File path (absolute or relative to workspace)
+  type?: "model" | "shape"; // Target type (default: "shape")
+  name?: string;          // CMS name (default: filename, no dashes)
+  workspaceRoot?: string; // Location of husar.json in monorepo
+}
+```
+
+**Example:**
+
+```json
+{
+  "path": "packages/app/src/components/Hero.tsx",
+  "type": "shape",
+  "name": "hero_component"
+}
+```
+
+---
+
+#### `husar_generate`
+
+Generate cms/ folder structure.
+
+**Input Schema:**
+
+```typescript
+{
+  folderPath?: string;    // Target folder (default: "./src")
+  workspaceRoot?: string; // Location of husar.json
+}
+```
+
+**Output:**
+
+```json
+{
+  "status": "ok",
+  "folder": "/absolute/path/to/cms"
+}
+```
+
+---
+
+### GraphQL Admin API Tools
+
+#### `husar_graphql_query`
+
+Run a read-only GraphQL query against Admin API.
+
+**Input Schema:**
+
+```typescript
+{
+  query: string;           // GraphQL query string
+  variables?: object;      // Query variables
+  endpointPath?: string;   // Endpoint path (default: "api/graphql")
+  workspaceRoot?: string;
+}
+```
+
+**Example:**
+
+```json
+{
+  "query": "query { admin { models { name } } }",
+  "variables": {}
+}
+```
+
+---
+
+#### `husar_graphql_schema`
+
+Fetch GraphQL schema (introspection JSON) from Admin API.
+
+**Input Schema:**
+
+```typescript
+{
+  endpointPath?: string;   // Default: "api/graphql"
+  workspaceRoot?: string;
+}
+```
+
+---
+
+#### `husar_graphql_schema_sdl`
+
+Fetch Admin GraphQL schema as human-readable SDL.
+
+**Input Schema:**
+
+```typescript
+{
+  endpointPath?: string;   // Default: "api/graphql"
+  workspaceRoot?: string;
+}
+```
+
+**Output:** GraphQL SDL string
+
+---
+
+### GraphQL Content API Tools
+
+#### `husar_content_graphql_query`
+
+Run a read-only GraphQL query against Content API.
+
+**Input Schema:**
+
+```typescript
+{
+  query: string;           // GraphQL query string
+  variables?: object;      // Query variables
+  endpointPath?: string;   // Default: "content/graphql"
+  apiKey?: string;         // Content API key (or use apiKeyEnv)
+  apiKeyEnv?: string;      // Env var name containing API key
+  workspaceRoot?: string;
+}
+```
+
+---
+
+#### `husar_content_graphql_schema`
+
+Fetch GraphQL schema (introspection) from Content API.
+
+**Input Schema:**
+
+```typescript
+{
+  endpointPath?: string;   // Default: "content/graphql"
+  apiKey?: string;
+  apiKeyEnv?: string;
+  workspaceRoot?: string;
+}
+```
+
+---
+
+#### `husar_content_graphql_schema_sdl`
+
+Fetch Content GraphQL schema as SDL.
+
+**Input Schema:**
+
+```typescript
+{
+  endpointPath?: string;   // Default: "content/graphql"
+  apiKey?: string;
+  apiKeyEnv?: string;
+  workspaceRoot?: string;
+}
+```
+
+---
+
+### AI Query Suggestion Tools
+
+#### `husar_graphql_suggest_query`
+
+Generate a GraphQL query suggestion from SDL and task description.
+
+**Input Schema:**
+
+```typescript
+{
+  sdl: string;             // GraphQL schema SDL
+  task: string;            // Task description (e.g., "list posts by tag")
+  rootType?: string;       // Root type (default: "Query")
+}
+```
+
+**Output:**
+
+```json
+{
+  "query": "query GeneratedQuery($tag: String!) { posts(tag: $tag) { nodes { id title } } }",
+  "variables": { "tag": null },
+  "pickedField": "posts",
+  "rootType": "Query",
+  "candidates": [{ "name": "posts", "type": "PostConnection" }]
+}
+```
+
+---
+
+#### `husar_graphql_run_suggestion`
+
+Generate a query from SDL + task and execute it on Admin API.
+
+**Input Schema:**
+
+```typescript
+{
+  sdl: string;             // GraphQL schema SDL
+  task: string;            // Task to execute
+  variables?: object;      // Override variables
+  endpointPath?: string;   // Default: "api/graphql"
+  workspaceRoot?: string;
+}
+```
+
+**Output:**
+
+```json
+{
+  "query": "...",
+  "variables": { ... },
+  "result": { ... }
+}
+```
+
+---
+
+#### `husar_content_graphql_run_suggestion`
+
+Generate a query from SDL + task and execute it on Content API.
+
+**Input Schema:**
+
+```typescript
+{
+  sdl: string;
+  task: string;
+  variables?: object;
+  endpointPath?: string;   // Default: "content/graphql"
+  apiKey?: string;
+  apiKeyEnv?: string;
+  workspaceRoot?: string;
+}
+```
+
+---
+
+### Admin ORM Tools
+
+The MCP server also exposes ORM tools from `@husar.ai/genai` for CMS operations.
+
+#### Model Tools
+
+| Tool                   | Description                            |
+| ---------------------- | -------------------------------------- |
+| `model.model`          | Return full model configuration        |
+| `model.previewFields`  | Return expanded fields for model       |
+| `model.fieldSet`       | Return admin page fieldset             |
+| `model.upsert`         | Create or update a model document      |
+| `model.remove`         | Remove a model entry                   |
+| `model.list`           | List model entries                     |
+| `model.listPaginated`  | List model entries (paginated)         |
+| `model.one`            | Get one model entry                    |
+| `model.listById`       | Get entries by IDs                     |
+| `model.getWithContent` | Get model definition + types + content |
+
+#### View Tools
+
+| Tool                  | Description                           |
+| --------------------- | ------------------------------------- |
+| `view.model`          | Return full view configuration        |
+| `view.previewFields`  | Return expanded fields for view       |
+| `view.fieldSet`       | Return admin page fieldset            |
+| `view.upsert`         | Create or update a view entry         |
+| `view.remove`         | Remove a view entry                   |
+| `view.list`           | List view entries                     |
+| `view.one`            | Get one view entry                    |
+| `view.getWithContent` | Get view definition + types + content |
+
+#### Shape Tools
+
+| Tool                      | Description                     |
+| ------------------------- | ------------------------------- |
+| `shape.model`             | Return full shape configuration |
+| `shape.previewFields`     | Return expanded fields          |
+| `shape.fieldSet`          | Return admin page fieldset      |
+| `shape.getWithDefinition` | Get shape definition + types    |
+
+#### Form Tools
+
+| Tool                    | Description                    |
+| ----------------------- | ------------------------------ |
+| `form.model`            | Return full form configuration |
+| `form.previewFields`    | Return expanded fields         |
+| `form.fieldSet`         | Return admin page fieldset     |
+| `form.upsert`           | Create or update a form entry  |
+| `form.remove`           | Remove a form entry            |
+| `form.list`             | List form entries              |
+| `form.one`              | Get one form entry             |
+| `form.submitResponse`   | Submit a form response         |
+| `form.responses`        | List form responses            |
+| `form.response`         | Get a form response by ID      |
+| `form.removeResponse`   | Remove a form response         |
+| `form.responseFieldSet` | Get form response fieldset     |
+
+#### Definition Management Tools
+
+| Tool           | Description                       |
+| -------------- | --------------------------------- |
+| `upsertModel`  | Create or update model definition |
+| `removeModel`  | Remove model definition           |
+| `upsertView`   | Create or update view definition  |
+| `removeView`   | Remove view definition            |
+| `upsertShape`  | Create or update shape definition |
+| `removeShape`  | Remove shape definition           |
+| `upsertForm`   | Create or update form definition  |
+| `removeForm`   | Remove form definition            |
+| `listModels`   | List all model definitions        |
+| `listViews`    | List all view definitions         |
+| `listShapes`   | List all shape definitions        |
+| `graphQLTypes` | Get generated GraphQL SDL schema  |
+
+#### Content & Media Tools
+
+| Tool                | Description                           |
+| ------------------- | ------------------------------------- |
+| `uploadFile`        | Get signed S3 PUT URL for file upload |
+| `generateContent`   | Generate content using AI             |
+| `generateImage`     | Generate an image                     |
+| `translateDocument` | Translate a document                  |
+| `translateView`     | Translate a view                      |
+| `translateForm`     | Translate a form                      |
+
+#### Link & Param Tools
+
+| Tool                        | Description                      |
+| --------------------------- | -------------------------------- |
+| `upsertParam`               | Create or update root param      |
+| `removeParam`               | Remove root param                |
+| `upsertLink`                | Create or update internal link   |
+| `removeLink`                | Remove internal link             |
+| `links`                     | List internal links              |
+| `removeModelWithDocuments`  | Remove model with all documents  |
+| `removeDocumentsWithParams` | Remove documents matching params |
+
+#### Style Tools
+
+| Tool                     | Description                       |
+| ------------------------ | --------------------------------- |
+| `style.tailwind.css.get` | Fetch current Tailwind CSS source |
+| `style.tailwind.css.set` | Set Tailwind CSS source content   |
+
+#### Specialized Agent Tools
+
+| Tool             | Description                               |
+| ---------------- | ----------------------------------------- |
+| `husarViewAgent` | Create/modify views from natural language |
+
+---
+
+## Relationship with Other Packages
+
+```
+@husar.ai/cli
+├── uses @husar.ai/ssr
+│   └── generateZeus() - Creates typed GraphQL client
+│   └── husarClient() - SSR client factory
+│
+├── uses @husar.ai/genai
+│   └── createOrmToolDefinitions() - Admin ORM tools
+│   └── getOrmToolSpecs() - Tool specifications
+│
+└── uses @husar.ai/render (generated code references)
+    └── HusarComponents() - React component factory
+```
+
+---
+
+## Troubleshooting
+
+### "Host is not configured"
+
+**Cause:** Missing `host` in `husar.json`
+
+**Solution:**
+
+1. Run `husar.ai generate` to create config interactively
+2. Or create `husar.json` manually with `host` property
+
+### "Admin token is not configured"
+
+**Cause:** Missing `adminToken` in `husar.json`
+
+**Solution:**
+
+1. Get admin token from Husar CMS dashboard
+2. Add to `husar.json`: `"adminToken": "your-token"`
+
+### "Missing apiKey"
+
+**Cause:** Content API operations require an API key
+
+**Solution:**
+
+1. Add `contentApiKey` to `husar.json`
+2. Or pass `apiKey` directly to MCP tool
+3. Or set env var and use `apiKeyEnv` parameter
+
+### MCP Server Not Connecting
+
+**Cause:** Configuration or path issues
+
+**Solutions:**
+
+1. Ensure `husar.json` exists in the workspace root
+2. Check `cwd` in MCP config points to project root
+3. For monorepos, use `workspaceRoot` parameter
+4. Check stderr for error messages: `husar.ai mcp 2>&1`
+
+### Parser Timeout
+
+**Cause:** AI parsing taking too long
+
+**Solutions:**
+
+1. Set `MCP_PARSER_TIMEOUT_MS` env var (default: 30000)
+2. For MCP, internal timeout is configurable via code
+
+### "Failed to get upload URL"
+
+**Cause:** Authentication or network issues
+
+**Solutions:**
+
+1. Verify `adminToken` is valid and not expired
+2. Check `host` URL is correct and accessible
+3. Ensure the Husar instance is running
+
+### Generated Code Import Errors
+
+**Cause:** Missing dependencies in target project
+
+**Solutions:**
+
+1. Install required packages:
+   ```bash
+   npm install @husar.ai/ssr @husar.ai/render
+   ```
+2. Ensure TypeScript paths are configured if using `@/` imports
+
+---
+
+## Development Notes
+
+### Building
+
+```bash
+npm run build    # Compile with tspc
+npm run watch    # Watch mode
+```
+
+### Testing
+
+```bash
+npm test         # Run tests with node --test
+```
+
+### Running Locally
+
+```bash
+# Direct execution
+npx tsx src/cli.ts generate ./test-output
+
+# After build
+node dist/cli.js mcp
+```
+
+### MCP Server Debugging
+
+The MCP server redirects console output to stderr to prevent interference with JSON-RPC communication. View logs via:
+
+```bash
+husar.ai mcp 2>husar-mcp.log
+```
+
+---
+
+## CMS Field Types Reference
+
+When using ORM tools, these are the available field types:
+
+| Type          | Description                |
+| ------------- | -------------------------- |
+| `STRING`      | Simple text field          |
+| `TITLE`       | Title/heading field        |
+| `NUMBER`      | Numeric value              |
+| `BOOLEAN`     | True/false toggle          |
+| `DATE`        | Date/datetime              |
+| `IMAGE_URL`   | URL to image               |
+| `CONTENT`     | Rich text/HTML content     |
+| `IMAGE`       | Image with metadata        |
+| `VIDEO`       | Video file                 |
+| `FILE`        | Generic file               |
+| `SHAPE`       | Nested shape reference     |
+| `RELATION`    | Reference to another model |
+| `SELECT`      | Dropdown selection         |
+| `OBJECT`      | Nested object structure    |
+| `OBJECT_TABS` | Tabbed object structure    |
+
+### Form Field Types
+
+| Type         | Description      |
+| ------------ | ---------------- |
+| `TEXT`       | Text display     |
+| `STRING`     | Text input       |
+| `BOOLEAN`    | Checkbox         |
+| `CONTENT`    | Rich text editor |
+| `STEP`       | Form step/wizard |
+| `INPUT`      | Generic input    |
+| `GROUP`      | Field grouping   |
+| `PORTAL`     | Portal container |
+| `SUBMIT`     | Submit button    |
+| `RADIO_TEXT` | Radio with text  |
+| `BUTTON`     | Action button    |
+| `VARIABLE`   | Variable field   |
+| `DISPLAY`    | Display only     |