@relyio/cli 0.2.0

package/README.md

@@ -0,0 +1,589 @@
+# RelyIO CLI
+
+Command Line Interface for RelyIO - a modern content management system.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @relyio/cli
+
+# Or use with npx
+npx @relyio/cli
+```
+
+## Quick Start
+
+```bash
+# Initialize a new project
+relyio init
+
+# Log in to your account
+relyio login
+
+# Link to an existing project
+relyio link --project_id <id>
+
+# Check schema status
+relyio status
+
+# Deploy schemas
+relyio deploy
+```
+
+## Schema Definition
+
+RelyIO supports two ways to define your content schemas:
+
+### TypeScript Schemas (Recommended)
+
+Define your schemas with full type safety using the RelyIO SDK:
+
+```typescript
+// relyio/schema.ts
+import { defineSchema, defineContentType, fields } from '@relyio/sdk/schema'
+
+const blogPost = defineContentType('blogPost', {
+  displayName: 'Blog Post',
+  fields: [
+    fields.shortText('title', { config: { required: true } }),
+    fields.richText('content'),
+    fields.media('featuredImage'),
+  ],
+})
+
+export const schema = defineSchema({
+  contentTypes: { blogPost },
+})
+```
+
+### YAML Schemas
+
+Define schemas in YAML format for GitOps workflows:
+
+```yaml
+# relyio/contentTypes/blogPost.yaml
+name: blogPost
+displayName: Blog Post
+fields:
+  - name: title
+    type: shortText
+    config:
+      required: true
+  - name: content
+    type: richText
+```
+
+The CLI automatically detects which format you're using—no configuration required.
+
+## Commands
+
+### Authentication
+
+| Command  | Description                    |
+| -------- | ------------------------------ |
+| `login`  | Log in to your RelyIO account  |
+| `logout` | Log out of your RelyIO account |
+| `whoami` | Show current user info         |
+
+### Project Management
+
+| Command          | Description                              |
+| ---------------- | ---------------------------------------- |
+| `init`           | Initialize a new RelyIO project          |
+| `link`           | Link to an existing RelyIO project       |
+| `status`         | Check local schema status against remote |
+| `validate`       | Validate schemas locally                 |
+| `deploy`         | Deploy schemas to a branch environment   |
+| `diff`           | Show detailed schema differences         |
+| `generate-types` | Generate TypeScript/Python types         |
+
+### Branch Environments
+
+| Command         | Description                 |
+| --------------- | --------------------------- |
+| `branch list`   | List branch environments    |
+| `branch create` | Create a branch environment |
+| `branch delete` | Delete a branch environment |
+
+### AI
+
+| Command  | Description                                                    |
+| -------- | -------------------------------------------------------------- |
+| `ai`     | Start an interactive AI REPL session in the current project    |
+| `schema` | One-shot schema edits with the schema-architect agent          |
+| `draft`  | One-shot content drafting with the content-editor agent        |
+| `query`  | Ask a natural-language question about your content (read-only) |
+
+### Utilities
+
+| Command      | Description                          |
+| ------------ | ------------------------------------ |
+| `doctor`     | Diagnose common configuration issues |
+| `open`       | Open RelyIO URLs in your browser     |
+| `alias`      | Manage command shortcuts             |
+| `completion` | Generate shell completion scripts    |
+| `version`    | Show CLI version                     |
+
+## Command Reference
+
+### `relyio status`
+
+Check your local schema status with enhanced validation insights.
+
+```bash
+# Check status once
+relyio status
+
+# Check status for a specific branch
+relyio status -b my-branch
+
+# Watch mode - automatically update when schema files change
+relyio status --watch
+
+# Output as JSON (for CI/CD)
+relyio status --json
+
+# Verbose output with detailed validation
+relyio status --verbose
+```
+
+**Options:**
+
+- `-b, --branch <branch>` - Target branch (defaults to current Git branch)
+- `-w, --watch` - Watch for schema file changes
+- `--json` - Output as JSON for CI/CD integration
+- `-v, --verbose` - Show detailed validation insights
+
+### `relyio deploy`
+
+Deploy your schema to a branch environment.
+
+```bash
+# Deploy to current branch
+relyio deploy
+
+# Deploy to a specific branch
+relyio deploy -b development
+
+# Skip confirmation prompt
+relyio deploy --yes
+
+# Output as JSON (for CI/CD)
+relyio deploy --json
+```
+
+**Options:**
+
+- `-b, --branch <branch>` - Target branch (defaults to current Git branch)
+- `-y, --yes` - Skip confirmation prompt
+- `--skip-notes` - Skip deployment notes prompt
+- `--json` - Output result as JSON
+
+### `relyio diff`
+
+Show detailed differences between local and remote schemas.
+
+```bash
+# Show diff for current branch
+relyio diff
+
+# Show diff for a specific branch
+relyio diff -b production
+
+# Output as JSON
+relyio diff --json
+```
+
+**Options:**
+
+- `-b, --branch <branch>` - Target branch (defaults to current Git branch)
+- `--json` - Output diff as JSON
+
+### `relyio validate`
+
+Validate your local schema without connecting to the API.
+
+```bash
+# Validate schema
+relyio validate
+
+# Output as JSON
+relyio validate --json
+```
+
+**Options:**
+
+- `--json` - Output validation result as JSON
+
+### `relyio generate-types`
+
+Generate typed code from your schema.
+
+```bash
+# Generate TypeScript types
+relyio generate-types
+
+# Generate for a specific language
+relyio generate-types -l python
+
+# Generate multiple languages
+relyio generate-types --languages typescript,python
+
+# Custom output directory
+relyio generate-types -o ./src/types
+
+# Watch mode
+relyio generate-types --watch
+```
+
+**Options:**
+
+- `-l, --language <language>` - Target language (default: typescript)
+- `--languages <list>` - Comma-separated list of languages
+- `-o, --output <dir>` - Output directory (default: ./types)
+- `-c, --config <path>` - Path to codegen configuration file
+- `-b, --branch <branch>` - Generate types from a specific branch schema
+- `--naming-convention <style>` - Naming style (camelCase, PascalCase, snake_case)
+- `--include-api-types` - Generate API response wrapper types
+- `--include-helpers` - Generate utility functions
+- `--module-format <format>` - Module format (esm, commonjs, both)
+- `-w, --watch` - Watch for schema changes
+
+### `relyio ai`
+
+Open an interactive AI REPL where you can chat with RelyIO agents about
+your project. The REPL loads the active branch's schema, lets the agent
+read/write files in the project (gated by your permission mode), and
+supports slash commands like `/agent`, `/deploy`, `/undo`,
+`/diff-history`.
+
+```bash
+# Start a fresh session in the current project
+relyio ai
+
+# Pick the permission mode up front
+relyio ai --mode safe   # ask before every file mutation (default)
+relyio ai --mode trust  # remember per-tool decisions for the session
+relyio ai --mode plan   # read-only, no mutations
+relyio ai --mode auto   # run unattended (CI-friendly)
+
+# Start with a specific agent
+relyio ai --agent schema-architect
+
+# Resume the most recent session
+relyio ai --resume
+```
+
+**Options:**
+
+- `-m, --mode <mode>` — permission mode (`safe`, `trust`, `plan`, `auto`)
+- `-a, --agent <slug>` — start with a specific agent (e.g. `schema-architect`, `content-editor`)
+- `--resume` — resume the most recent local session
+
+### `relyio schema "<instruction>"`
+
+One-shot schema edits via the `schema-architect` agent. The agent reads
+the local schema, proposes edits as a unified diff, and (with
+confirmation) writes them back to disk.
+
+```bash
+# Add a field interactively
+relyio schema "add a video field to blogPost"
+
+# Target a non-default branch
+relyio schema "rename the hero component to banner" --branch staging
+
+# Apply changes without prompts (CI)
+relyio schema "add SEO fields" --no-confirm
+
+# Apply *and* deploy on success
+relyio schema "add a tags field to blogPost" --deploy
+
+# Plan-only mode — agent describes changes without writing anything
+relyio schema "review my schema for missing required fields" --dry-run
+```
+
+**Options:**
+
+- `-b, --branch <name>` — override branch detection
+- `--no-confirm` — auto-apply file changes without prompting
+- `--dry-run` — plan-only mode (no writes, no deploy)
+- `--deploy` — deploy the resolved branch on success
+
+### `relyio draft "<instruction>"`
+
+One-shot content drafting via the `content-editor` agent. The agent
+creates entries against the active dataset using the deployed schema.
+Drafts go through the same proposal flow as the AI REPL, so you can
+review every entry before applying.
+
+```bash
+# Draft 5 blog posts
+relyio draft "create 5 blog posts about AI development workflows"
+
+# Draft against a specific dataset / branch
+relyio draft "add 3 product reviews for the laptop SKU" --dataset prod
+
+# Auto-commit the drafts (CI / scripted bulk ops)
+relyio draft "translate every blog post to Spanish" --auto-commit
+```
+
+**Options:**
+
+- `-d, --dataset <name>` — dataset to draft into
+- `-b, --branch <name>` — override branch detection
+- `--no-confirm` — auto-approve incidental confirmations
+- `--auto-commit` — apply every drafted proposal without prompting
+
+> Note: drafting requires the local schema to be in sync with the
+> remote branch. If you have uncommitted schema changes, `relyio
+draft` blocks with a `schema-dirty` error and asks you to run
+> `/deploy` (in the REPL) or `relyio deploy` first.
+
+### `relyio query "<question>"`
+
+Ask a natural-language question about your content. Read-only — never
+mutates anything. Results render as a table by default, or as JSON / CSV
+/ count for piping into other tools.
+
+```bash
+# Default table view
+relyio query "all published blog posts by John, sorted by date"
+
+# Filter / sort / limit, table-rendered
+relyio query "products under \$50 with low stock" --format table
+
+# Just the count
+relyio query "how many draft entries exist" --format count
+
+# JSON for piping to jq
+relyio query "entries modified this week" --format json --limit 100
+```
+
+**Options:**
+
+- `-f, --format <fmt>` — `table` (default), `json`, `csv`, or `count`
+- `-d, --dataset <name>` — dataset to query (skips the picker)
+- `-b, --branch <name>` — override branch detection
+- `-l, --limit <n>` — max results (default 25, capped at 50)
+- `--no-confirm` — auto-approve any incidental confirmations
+
+The result table always includes the `entryUid` column so you can copy
+canonical IDs straight into follow-up commands.
+
+### `relyio doctor`
+
+Diagnose common configuration and connectivity issues.
+
+```bash
+relyio doctor
+```
+
+Checks:
+
+- Node.js version
+- Git installation
+- Authentication status
+- API connectivity
+- Project configuration
+- Schema files
+
+### `relyio open`
+
+Open RelyIO URLs in your default browser.
+
+```bash
+# Open dashboard
+relyio open dashboard
+
+# Open current project
+relyio open project
+
+# Open current branch
+relyio open branch
+
+# Open documentation
+relyio open docs
+
+# Open API docs
+relyio open api
+```
+
+### `relyio alias`
+
+Create shortcuts for frequently used commands.
+
+```bash
+# List all aliases
+relyio alias
+
+# Create an alias
+relyio alias set d deploy
+relyio alias set sw "status --watch"
+
+# Remove an alias
+relyio alias remove d
+```
+
+### `relyio completion`
+
+Generate shell completion scripts for tab completion.
+
+```bash
+# Generate for your current shell
+relyio completion
+
+# Generate for a specific shell
+relyio completion --shell zsh
+
+# Install (add to your shell config)
+# For bash:
+eval "$(relyio completion --shell bash)"
+
+# For zsh:
+eval "$(relyio completion --shell zsh)"
+
+# For fish:
+relyio completion --shell fish | source
+```
+
+## Configuration
+
+The CLI uses a three-tier configuration system:
+
+1. **Global User Configuration** - `~/.relyio/config.json`
+
+   - Stores non-secret state (project link, PAT metadata)
+   - Auth tokens themselves are kept in the OS keychain whenever
+     possible — see [Secret storage](#secret-storage) below
+
+2. **Project Link Configuration** - `.relyio-context.json`
+
+   - Stores project ID and organization ID
+   - Created when you run `relyio link` or `relyio init`
+
+3. **Local Project Configuration** - `relyio/config.yaml`
+   - Stores project-specific settings
+   - Created when you run `relyio init`
+
+## CI/CD Integration
+
+All major commands support `--json` output for easy integration with CI/CD pipelines:
+
+```bash
+# Check status in CI
+STATUS=$(relyio status --json)
+if echo "$STATUS" | jq -e '.hasChanges' > /dev/null; then
+  echo "Schema changes detected"
+  relyio deploy --yes --json
+fi
+```
+
+### Exit Codes
+
+The one-shot AI commands (`relyio schema`, `relyio draft`, `relyio
+query`) follow a stable exit-code contract so shell pipelines and CI
+jobs can branch reliably without parsing stdout:
+
+| Code  | Meaning                                                                                                             |
+| ----- | ------------------------------------------------------------------------------------------------------------------- |
+| `0`   | Success — agent finished and the user resolved everything that needed resolving.                                    |
+| `1`   | Unrecoverable error — auth missing, project not linked, network failure, agent crashed.                             |
+| `2`   | Cannot proceed — schema is dirty (run `relyio deploy`), validation failed, or `--auto-commit` had nothing to apply. |
+| `130` | User pressed `Ctrl-C` (POSIX `128 + SIGINT`).                                                                       |
+
+Other commands follow the standard `0 = ok`, `1 = error` convention.
+
+```bash
+# Example: deploy schema only if drafting succeeds
+relyio schema "add a tags field" --no-confirm
+case $? in
+  0) relyio deploy --yes ;;
+  2) echo "schema is dirty — please run 'relyio deploy' first" >&2; exit 1 ;;
+  *) echo "drafting failed" >&2; exit 1 ;;
+esac
+```
+
+## Configuration Details
+
+### Secret storage
+
+The CLI persists auth tokens (login PAT, API keys) in your operating
+system's secure credential store via [`keytar`][keytar] when available
+— Keychain on macOS, Credential Vault on Windows, libsecret on Linux.
+
+If the native module fails to load (commonly on headless Linux without
+`libsecret-1-dev`, or in Docker images without build prerequisites),
+the CLI prints a one-time stderr warning and falls back to plaintext
+storage in `~/.relyio/config.json`. Run `relyio doctor` to see which
+backend is currently active.
+
+[keytar]: https://github.com/atom/node-keytar
+
+### Override URLs
+
+| Variable                   | Default                        | Purpose                                 |
+| -------------------------- | ------------------------------ | --------------------------------------- |
+| `RELYIO_API_URL`           | `https://api.relyio.com`       | Manage API base URL                     |
+| `RELYIO_AI_GATEWAY_URL`    | `https://ai.relyio.com`        | AI gateway streaming endpoint           |
+| `RELYIO_DASHBOARD_URL`     | `https://dashboard.relyio.com` | Dashboard URL used by `relyio open`     |
+| `RELYIO_BRANCH`            | _(detected from git)_          | Force branch detection (CI containers)  |
+| `RELYIO_CLI_TEMPLATES_DIR` | _(bundled with CLI)_           | Override the `init` templates location  |
+| `DEBUG`                    | _(off)_                        | Set to `true` to enable verbose logging |
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/relyio/relyio.git
+cd relyio
+
+# Install dependencies
+pnpm install
+
+# Build the CLI
+pnpm --filter @relyio/cli build
+```
+
+### Local Testing
+
+```bash
+# Link the CLI globally
+cd packages/customer/cli
+pnpm local-test
+
+# Now you can use the CLI from anywhere
+relyio --help
+```
+
+### Running Tests
+
+```bash
+# Run tests
+pnpm --filter @relyio/cli test
+
+# Run tests in watch mode
+pnpm --filter @relyio/cli test:watch
+```
+
+## Publishing
+
+This package is published as `@relyio/cli` on npm. To publish a new version:
+
+```bash
+# Create a new changeset
+pnpm changeset
+
+# Build before publish
+pnpm --filter @relyio/cli build
+
+# Publishing (handled by CI)
+pnpm publish -r
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }