farseer-cli 1.0.0

package/README.md

@@ -0,0 +1,741 @@
+# Farseer CLI
+
+Command-line tool for managing Farseer Apps and scripts. Includes AI assistant integration via MCP (Model Context Protocol).
+
+[![npm version](https://img.shields.io/npm/v/farseer-cli.svg)](https://www.npmjs.com/package/farseer-cli)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+## Features
+
+- **Bidirectional Sync** - Pull/push scripts and apps between local folder and Farseer instances
+- **AI Assistant Integration** - Native MCP support for Claude, Cursor, and other AI tools
+- **App Management** - Create, configure, and run Farseer apps from CLI
+- **Model Inspection** - Explore dimensions, variables, and formulas
+- **Multiple Auth Methods** - Browser OAuth (JWT) and API key authentication
+- **Local Development** - Run apps locally with automatic credential injection
+
+---
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Quick Start](#quick-start)
+3. [MCP Setup (AI Assistants)](#mcp-setup-ai-assistants)
+4. [Authentication](#authentication)
+5. [Commands Reference](#commands-reference)
+6. [App Management](#app-management)
+7. [Model Inspection](#model-inspection)
+8. [MCP Tools & Resources](#mcp-tools--resources)
+9. [File Structure](#file-structure)
+10. [Configuration](#configuration)
+11. [Troubleshooting](#troubleshooting)
+
+---
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g farseer-cli
+```
+
+Verify installation:
+
+```bash
+farseer --version
+```
+
+### Local Installation (for CI/CD)
+
+```bash
+npm install farseer-cli
+npx farseer --version
+```
+
+---
+
+## Quick Start
+
+### 1. Login
+
+```bash
+farseer login
+```
+
+This opens your browser for OAuth authentication. After successful login, your credentials are saved locally.
+
+### 2. Select Tenant
+
+```bash
+farseer checkout my-tenant
+```
+
+This sets `my-tenant` as your default tenant and automatically pulls all scripts and apps.
+
+### 3. Install Dependencies
+
+```bash
+farseer install
+```
+
+Installs npm packages required for local script execution.
+
+### 4. List Apps
+
+```bash
+farseer app list
+```
+
+### 5. Run an App
+
+```bash
+farseer run "My Import App"
+```
+
+---
+
+## MCP Setup (AI Assistants)
+
+Enable AI assistants (Claude, Cursor) to directly interact with Farseer.
+
+### Claude Desktop
+
+Add to config file:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "farseer": {
+      "command": "farseer",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop.
+
+### Cursor
+
+Add to `.cursor/mcp_config.json` (project) or `~/.cursor/mcp_config.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "farseer": {
+      "command": "farseer",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+Add to `~/.claude/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "farseer": {
+      "command": "farseer",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+Once configured, you can ask the AI assistant things like:
+- *"List my Farseer apps"*
+- *"Pull latest scripts from my-tenant"*
+- *"Create an import script for Sales Amount variable"*
+
+See [MCP Tools & Resources](#mcp-tools--resources) for full list of available tools.
+
+---
+
+## Authentication
+
+Farseer CLI supports two authentication methods:
+
+### Browser Login (JWT) - Recommended
+
+```bash
+# Default realm (master)
+farseer login
+
+# Specific realm (e.g., acme, corp)
+farseer login --realm acme
+```
+
+Opens Keycloak login in browser. Features:
+- Automatic token refresh
+- Access to all tenants you have permissions for
+- Full functionality (scripts + apps)
+
+### API Key Login
+
+```bash
+farseer login --api-key
+```
+
+Interactive prompt for tenant, organisation, and API key. Useful for:
+- CI/CD environments
+- Headless servers
+- Service accounts
+
+**Note:** API keys can only sync files. For app management, use browser login.
+
+### Check Authentication Status
+
+```bash
+farseer whoami
+```
+
+Output:
+```
+Authentication Status
+
+User Token:
+  ✓ Valid JWT token
+  Email: john@example.com
+  Expires: 2025-01-28 10:00:00
+
+Configured Tenants:
+  ✓ my-tenant (API key)
+```
+
+### Logout
+
+```bash
+# Clear JWT token
+farseer logout
+
+# Remove specific tenant credentials
+farseer logout my-tenant
+
+# Remove all credentials
+farseer logout --all
+```
+
+---
+
+## Commands Reference
+
+### Tenant Management
+
+#### `farseer checkout [org] <tenant>`
+
+Set default tenant. Automatically pulls files and apps.
+
+```bash
+# When organisation = tenant name
+farseer checkout my-tenant
+
+# When organisation differs from tenant
+farseer checkout my-org my-tenant
+
+# Skip automatic pull
+farseer checkout my-tenant --no-pull
+
+# Show current checkout
+farseer checkout
+```
+
+### Sync Operations
+
+All sync commands use the checked-out tenant by default. You can specify a different tenant as argument.
+
+#### `farseer pull [tenant]`
+
+Download scripts and apps from Farseer instance.
+
+```bash
+# Pull for checked-out tenant
+farseer pull
+
+# Pull for specific tenant
+farseer pull other-tenant
+
+# Download all files (not just .ts/.js)
+farseer pull --all
+```
+
+**What it does:**
+1. Fetches all files from `Files/` folder on instance
+2. Downloads app configurations
+3. Saves to `apps/<tenant>/files/` and `apps/<tenant>/apps/`
+4. Creates `package.json` if missing
+5. Updates sync tracking file
+
+#### `farseer push [tenant]`
+
+Upload local changes to Farseer instance.
+
+```bash
+# Push changes
+farseer push
+
+# Force push (ignore remote changes)
+farseer push --force
+```
+
+**What it does:**
+1. Checks for unpulled remote changes (fails if found, unless `--force`)
+2. Shows diff and asks for confirmation
+3. Uploads/updates/deletes files on instance
+4. Uploads/updates app configurations
+
+#### `farseer status [tenant]`
+
+Compare local files with remote instance.
+
+```bash
+# Check script files
+farseer status
+
+# Check all files
+farseer status --all
+```
+
+Output:
+```
+Comparing local with remote...
+
+Modified locally:
+  M Scripts/import-sales.ts
+
+Modified on remote:
+  M Scripts/sync-actuals.ts
+
+Only local (new):
+  + Scripts/new-script.ts
+
+Only on remote:
+  - Data/old-file.xlsx
+```
+
+#### `farseer diff [tenant] [file]`
+
+Show file differences.
+
+```bash
+# Diff all changed files
+farseer diff
+
+# Diff specific file
+farseer diff Scripts/import-sales.ts
+
+# Show only remote version
+farseer diff Scripts/import-sales.ts --remote
+```
+
+#### `farseer files list [tenant]`
+
+List files on remote instance.
+
+```bash
+# List script files only
+farseer files list
+
+# List all files
+farseer files list --all
+```
+
+---
+
+## App Management
+
+App names with spaces don't need quotes when tenant is checked out.
+
+### `farseer app list [tenant]`
+
+List all apps.
+
+```bash
+# Simple list
+farseer app list
+
+# With details (entrypoint, scripts, arguments)
+farseer app list --details
+```
+
+### `farseer app show <name>`
+
+Show app details.
+
+```bash
+farseer app show My Import App
+```
+
+Output:
+```json
+{
+  "name": "My Import App",
+  "description": "Imports sales data",
+  "entrypoint": "import-sales.ts",
+  "scripts": ["import-sales.ts", "helpers.ts"],
+  "arguments": [
+    { "name": "Year", "defaultValue": "2025" },
+    { "name": "Version", "defaultValue": "Plan" }
+  ]
+}
+```
+
+### `farseer app create <name>`
+
+Create new app.
+
+```bash
+farseer app create My New App
+```
+
+Creates JSON file in `apps/<tenant>/apps/`. Use `push` to upload to instance.
+
+### `farseer app configure <name>`
+
+Configure app settings.
+
+```bash
+# Set entrypoint and scripts
+farseer app configure My App --entrypoint index.ts --scripts "index.ts,helpers.ts"
+
+# Add argument
+farseer app configure My App --add-arg "Year=2025"
+
+# Set description
+farseer app configure My App --description "Imports data"
+```
+
+### `farseer app delete <name>`
+
+Delete app (requires `--force`).
+
+```bash
+farseer app delete My App --force
+```
+
+### `farseer run <app>`
+
+Run app locally with injected credentials.
+
+```bash
+# Run app
+farseer run My Import App
+
+# Override argument
+farseer run My Import App --arg "Year=2026"
+
+# Multiple arguments
+farseer run My Import App --arg "Year=2026" --arg "Version=Forecast"
+```
+
+**Prerequisites:**
+- Run `farseer install` first
+- Credentials configured (`farseer login`)
+
+### `farseer install [tenant]`
+
+Install npm dependencies for local development.
+
+```bash
+farseer install
+```
+
+---
+
+## Model Inspection
+
+Explore your Farseer data model from the command line.
+
+### `farseer model [tenant]`
+
+```bash
+# Show model overview
+farseer model
+
+# List all variables
+farseer model --variables
+
+# List dimension tables
+farseer model --tables
+
+# Show variable details
+farseer model --variable "Sales Amount"
+```
+
+Output for `--variable`:
+```
+Variable: Sales Amount
+
+Dimensions:
+  - Product
+  - Region
+  - Month
+  - Year
+  - Version
+
+Roll-up Type: SUM
+Number Format: #,##0.00
+Formula: (none - data variable)
+```
+
+---
+
+## MCP Tools & Resources
+
+Farseer CLI implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). For setup instructions, see [MCP Setup](#mcp-setup-ai-assistants).
+
+### Available Tools
+
+Once configured, AI assistants have access to:
+
+**Authentication:**
+- `farseer_whoami` - Check authentication status
+- `farseer_checkout` - Set default tenant
+- `farseer_checkout_clear` - Clear default tenant
+
+**Sync Operations:**
+- `farseer_pull` - Pull scripts and apps from remote
+- `farseer_push` - Push local changes to remote
+- `farseer_status` - Compare local vs remote state
+- `farseer_diff` - Show file differences
+- `farseer_list_files` - List remote files
+
+**App Management:**
+- `farseer_list_apps` - List all apps
+- `farseer_get_app` - Get app details
+- `farseer_create_app` - Create new app
+- `farseer_configure_app` - Configure app
+- `farseer_delete_app` - Delete app
+- `farseer_run_app` - Run app locally
+
+**Model Inspection:**
+- `farseer_export_model` - Export full model structure
+- `farseer_list_tables` - List dimension tables
+- `farseer_list_variables` - List variables
+- `farseer_get_table` - Get table details
+- `farseer_get_variable` - Get variable details
+
+### Documentation Resources
+
+AI assistants can read comprehensive documentation:
+- How Farseer Works (Dimensions, Variables, Formulas)
+- CLI Guide
+- API Reference (farseer-client)
+- New App Template
+- Troubleshooting
+- Import Workflows
+- Arquero Patterns
+- Query & Formulas
+- Model Export
+
+### Workflow Prompts
+
+Guided workflows for common tasks:
+- **setup_new_tenant** - Setup new tenant from scratch
+- **create_new_app** - Create new app with guidance
+- **understand_model** - Explore data model
+- **write_import_script** - Write import script
+- **copy_app** - Copy and modify existing app
+- **debug_sync_issues** - Troubleshoot sync problems
+
+### Example Conversations
+
+**List apps:**
+> "Show me all my Farseer apps"
+
+**Create import script:**
+> "Create a new import script for Sales Amount variable that reads from CSV"
+
+The AI will:
+1. Check what dimensions Sales Amount has
+2. Create TypeScript import script
+3. Push script to Farseer
+4. Create and configure app
+
+**Debug issues:**
+> "Pull latest changes and show me what's different"
+
+---
+
+## File Structure
+
+```
+apps/
+└── my-tenant/
+    ├── package.json            # Auto-generated dependencies
+    ├── .farseer-sync.json      # Sync tracking
+    ├── files/                  # Maps to Files/ folder on instance
+    │   ├── Scripts/
+    │   │   ├── import-sales.ts
+    │   │   └── helpers/
+    │   │       └── utils.ts
+    │   └── Data/
+    │       └── config.json
+    └── apps/                   # App configurations (JSON)
+        ├── Import Sales.json
+        └── Sync Actuals.json
+```
+
+### App JSON Format
+
+```json
+{
+  "name": "My Import App",
+  "description": "Imports sales data",
+  "entrypoint": "import-sales.ts",
+  "scripts": ["import-sales.ts", "helpers.ts"],
+  "arguments": [
+    { "name": "Year", "defaultValue": "2025" },
+    { "name": "Version", "defaultValue": "Plan" }
+  ],
+  "_remote": {
+    "id": 123,
+    "reference": "123"
+  }
+}
+```
+
+**Important:**
+- For **new apps**: Don't add `_remote` - CLI adds it after first push
+- For **existing apps**: `_remote` links local JSON to remote app
+- Never edit `_remote` manually
+
+---
+
+## Configuration
+
+### Config File Location
+
+`~/.farseer/config.json`
+
+### Config Structure
+
+```json
+{
+  "credentials": {
+    "my-tenant": {
+      "type": "apiKey",
+      "tenantId": "my-tenant",
+      "apiKey": "sk_xxx123",
+      "basePath": "https://my-org.farseer.io/api/v3"
+    }
+  },
+  "userAuth": {
+    "accessToken": "...",
+    "refreshToken": "...",
+    "expiresAt": "2025-01-28T10:00:00Z",
+    "realm": "master"
+  },
+  "currentCheckout": {
+    "tenant": "my-tenant",
+    "organisation": "my-org"
+  }
+}
+```
+
+### Managing Credentials
+
+```bash
+# Set API key
+farseer config set my-tenant --api-key sk_xxx123
+
+# Set with custom organisation
+farseer config set my-tenant --api-key sk_xxx123 --org my-org
+
+# List configured tenants
+farseer config list
+
+# Show credentials (masked)
+farseer config show my-tenant
+
+# Test connection
+farseer config test my-tenant
+
+# Remove credentials
+farseer config remove my-tenant
+```
+
+---
+
+## Troubleshooting
+
+### "No credentials found for tenant"
+
+```bash
+# Login with browser
+farseer login
+
+# Or set API key
+farseer config set my-tenant --api-key sk_xxx123
+```
+
+### "No tenant specified"
+
+```bash
+# Set default tenant
+farseer checkout my-tenant
+```
+
+### "Token expired"
+
+JWT tokens auto-refresh. If refresh fails:
+
+```bash
+farseer login
+```
+
+### "Remote has changes that are not synced locally"
+
+Someone edited files on Farseer UI. Pull first:
+
+```bash
+farseer pull
+farseer push
+```
+
+### "Cannot find module 'farseer-client'"
+
+```bash
+farseer install
+```
+
+### "Entry point needs to be defined"
+
+```bash
+farseer app configure "My App" --entrypoint index.ts
+```
+
+### Login Issues with Different Realm
+
+```bash
+# Try specific realm
+farseer login --realm acme
+farseer login --realm corp
+```
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- Access to Farseer instance
+
+---
+
+## License
+
+ISC
+
+---
+
+## Links
+
+- [Farseer Platform](https://farseer.io)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [Claude Desktop](https://claude.ai/download)
+- [Cursor](https://cursor.sh)

package/dist/commands/app.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerAppCommand(program: Command): void;