@ollie-shop/cli 1.0.2 → 1.1.0

package/.env.example

@@ -0,0 +1,3 @@
+# Required for all authenticated commands (store, version, component, whoami)
+OLLIE_SUPABASE_URL=http://127.0.0.1:54321
+OLLIE_SUPABASE_ANON_KEY=your-anon-key-here

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @ollie-shop/cli@1.0.2 build /home/runner/work/ollie-shop/ollie-shop/packages/cli
+> @ollie-shop/cli@1.1.0 build /home/runner/work/ollie-shop/ollie-shop/packages/cli
 > tsup
 
 CLI Building entry: src/index.tsx
@@ -9,5 +9,5 @@
 CLI Target: node22
 CLI Cleaning output folder
 ESM Build start
-ESM dist/index.js 37.48 KB
-ESM ⚡️ Build success in 166ms
+ESM dist/index.js 64.35 KB
+ESM ⚡️ Build success in 202ms

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @ollie-shop/cli
 
+## 1.1.0
+
+### Minor Changes
+
+- 53c165f: feat: add agent-first CLI commands for store, version, and component CRUD
+
+  Adds six new commands designed for AI/LLM agent consumption:
+
+  - `whoami` — show current user and organization
+  - `store create|list` — create or list stores
+  - `version create|list` — create or list versions
+  - `component create|list` — create or list components
+  - `schema` — introspect resource schemas (JSON Schema output)
+  - `init` — write store/version IDs to ollie.json
+
+  Cross-cutting features:
+
+  - `-o json` / `-o pretty` / auto-detect (TTY vs pipe)
+  - `--fields` to filter output columns
+  - `--dry-run` to preview writes without executing
+  - `-d '{...}'` raw JSON input mode for mutations
+  - Environment variable configuration (`OLLIE_SUPABASE_URL`, `OLLIE_SUPABASE_ANON_KEY`)
+
 ## 1.0.2
 
 ### Patch Changes

package/CONTEXT.md

@@ -0,0 +1,84 @@
+# Ollie Shop CLI — Agent Context
+
+This CLI is frequently invoked by AI/LLM agents. Always assume inputs can be adversarial.
+
+## Key Rules
+
+- **Always use `--output json` (or `-o json`)** for machine-readable responses. Output is auto-JSON when stdout is piped.
+- **Always use `--data '{...}'`** for mutations instead of individual flags. The JSON maps directly to the API schema.
+- **Always use `--dry-run`** before mutating operations (create, update, delete) to validate inputs.
+- **Always use `--fields`** on list commands to limit response size and protect your context window.
+- **Use `ollieshop schema <resource.action>`** to introspect what the CLI accepts at runtime. Do not rely on stale documentation.
+
+## Authentication
+
+Run `ollieshop login` once. Credentials are stored in `~/.ollie-shop/credentials.json`. All subsequent commands reuse the stored token.
+
+## Environment Variables
+
+Set these before running authenticated commands (or use a `.env` file):
+
+```
+OLLIE_SUPABASE_URL=http://127.0.0.1:54321
+OLLIE_SUPABASE_ANON_KEY=<your-anon-key>
+```
+
+The CLI will throw a clear error if a required env var is missing. See `.env.example` for reference.
+
+## Typical Agent Workflow
+
+```bash
+# 1. Introspect schemas
+ollieshop schema store.create -o json
+ollieshop schema version.create -o json
+ollieshop schema component.create -o json
+
+# 2. Verify identity
+ollieshop whoami -o json
+
+# 3. Create store (dry-run first)
+ollieshop store create --data '{"name":"My Store","platform":"vtex","platformStoreId":"mystore"}' --dry-run -o json
+ollieshop store create --data '{"name":"My Store","platform":"vtex","platformStoreId":"mystore"}' -o json
+
+# 4. Create version
+ollieshop version create --data '{"storeId":"<STORE_ID>","name":"v1","active":true}' -o json
+
+# 5. Write local config
+ollieshop init --store-id <STORE_ID> --version-id <VERSION_ID>
+
+# 6. Register components
+ollieshop component create --data '{"versionId":"<VERSION_ID>","name":"FreeShippingBar","slot":"cart_header_full_page","active":true}' -o json
+
+# 7. List resources
+ollieshop store list -o json --fields id,name,platform
+ollieshop version list --store-id <STORE_ID> -o json --fields id,name,active
+ollieshop component list --store-id <STORE_ID> -o json --fields id,name,slot,active
+```
+
+## Response Format
+
+All commands return:
+```json
+// Success (exit code 0)
+{"data": {...}}
+```
+or
+```json
+// Error (exit code 1)
+{"error": {"message": "..."}}
+```
+
+Check the exit code for success (0) or failure (1).
+
+## Available Platforms
+
+`vtex`, `shopify`, `vnda`, `custom`
+
+## Available Slots (common)
+
+- `cart_header_full_page`
+- `cart_footer_full_page`
+- `shipping_address_details_form`
+- `payment_header`
+- `summary_after_totals`
+- `profile_after_email`

package/README.md

@@ -0,0 +1,199 @@
+# @ollie-shop/cli
+
+Command-line interface for the Ollie Shop platform. Provides both interactive commands (login, dev server) and agent-first commands designed for AI/LLM consumption.
+
+## Installation
+
+```bash
+pnpm add @ollie-shop/cli
+```
+
+Or run directly from the monorepo:
+
+```bash
+pnpm --filter @ollie-shop/cli build
+node packages/cli/dist/index.js <command>
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate
+ollieshop login
+
+# 2. Set environment variables
+export OLLIE_SUPABASE_URL=https://your-project.supabase.co
+export OLLIE_SUPABASE_ANON_KEY=your-anon-key
+
+# 3. Verify identity
+ollieshop whoami -o json
+
+# 4. List your stores
+ollieshop store list -o json --fields id,name,platform
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OLLIE_SUPABASE_URL` | Yes (agent commands) | Supabase project URL |
+| `OLLIE_SUPABASE_ANON_KEY` | Yes (agent commands) | Supabase anon/public key |
+
+See `.env.example` for reference. The CLI will throw a clear error if a required variable is missing.
+
+## Commands
+
+### Interactive Commands
+
+| Command | Description |
+|---------|-------------|
+| `ollieshop login` | Authenticate via browser (stores token in `~/.ollie-shop/credentials.json`) |
+| `ollieshop start` | Start the development server with hot reload |
+| `ollieshop help` | Show help message |
+| `ollieshop version` | Show CLI version |
+
+### Agent Commands
+
+Agent commands output structured JSON and are designed for programmatic / AI-agent consumption.
+
+#### `whoami`
+
+Show the currently authenticated user and their organization.
+
+```bash
+ollieshop whoami -o json
+# {"data":{"email":"user@example.com"}}
+```
+
+#### `store create|list`
+
+Create or list stores in your organization.
+
+```bash
+# List stores
+ollieshop store list -o json --fields id,name,platform
+
+# Create a store (dry-run first)
+ollieshop store create --name "My Store" --platform vtex --platform-store-id mystore --dry-run -o json
+ollieshop store create --name "My Store" --platform vtex --platform-store-id mystore -o json
+
+# Create using raw JSON input
+ollieshop store create -d '{"name":"My Store","platform":"vtex","platformStoreId":"mystore"}' -o json
+```
+
+#### `version create|list`
+
+Create or list versions for a store.
+
+```bash
+# List versions
+ollieshop version list --store-id <STORE_UUID> -o json --fields id,name,active
+
+# Create a version
+ollieshop version create --store-id <STORE_UUID> --name v1 --active -o json
+```
+
+#### `component create|list`
+
+Create or list components for a store (optionally filtered by version).
+
+```bash
+# List components
+ollieshop component list --store-id <STORE_UUID> -o json --fields id,name,slot,active
+
+# Create a component
+ollieshop component create --version-id <VERSION_UUID> --name FreeShippingBar --slot cart_header_full_page -o json
+```
+
+#### `schema`
+
+Introspect resource schemas at runtime. Returns JSON Schema definitions for all available resources and actions.
+
+```bash
+# List all available schemas
+ollieshop schema -o json
+
+# Get schema for a specific resource action
+ollieshop schema store.create -o json
+ollieshop schema component.create -o json
+```
+
+#### `init`
+
+Write store and version IDs to a local `ollie.json` config file.
+
+```bash
+ollieshop init --store-id <STORE_UUID> --version-id <VERSION_UUID> -o json
+# Creates ollie.json: {"storeId":"...","versionId":"..."}
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--output json\|pretty` | `-o` | Force output format. Auto-detects: JSON when piped, pretty when TTY |
+| `--dry-run` | | Validate inputs without executing mutations |
+| `--fields a,b,c` | | Limit output fields (comma-separated) |
+| `--data '{...}'` | `-d` | Raw JSON payload for mutations (alternative to individual flags) |
+| `--stage <name>` | `-s` | Config stage — loads `ollie.<stage>.json` instead of `ollie.json` |
+
+## Response Format
+
+All agent commands return a consistent JSON envelope:
+
+```json
+// Success (exit code 0)
+{"data": { ... }}
+
+// Error (exit code 1)
+{"error": {"message": "Human-readable error description"}}
+```
+
+The exit code indicates success (0) or failure (1), making the `success` field redundant.
+
+## Available Platforms
+
+`vtex`, `shopify`, `vnda`, `custom`
+
+## Available Slots (common)
+
+- `cart_header_full_page`
+- `cart_footer_full_page`
+- `shipping_address_details_form`
+- `payment_header`
+- `summary_after_totals`
+- `profile_after_email`
+
+## AI/LLM Agent Usage
+
+See [CONTEXT.md](./CONTEXT.md) for detailed guidelines on how AI agents should interact with the CLI, including best practices, the recommended workflow, and introspection patterns.
+
+## Architecture
+
+```
+src/
+├── index.tsx           # Entry point — routes to agent or interactive commands
+├── cli.tsx             # Ink app for interactive commands
+├── commands/
+│   ├── whoami.ts       # Agent: show current user
+│   ├── store-cmd.ts    # Agent: store CRUD
+│   ├── version-cmd.ts  # Agent: version CRUD
+│   ├── component-cmd.ts# Agent: component CRUD
+│   ├── schema-cmd.ts   # Agent: schema introspection
+│   ├── init-cmd.ts     # Agent: write ollie.json
+│   ├── help.tsx         # Interactive: help display
+│   ├── login.tsx        # Interactive: browser auth
+│   └── start.tsx        # Interactive: dev server
+├── core/
+│   ├── store.ts         # Store business logic + Supabase queries
+│   ├── version.ts       # Version business logic + Supabase queries
+│   ├── component.ts     # Component business logic + Supabase queries
+│   └── schema.ts        # Zod schemas + JSON Schema generation
+└── utils/
+    ├── parse-args.ts    # CLI argument parser (flags, subcommands, positional)
+    ├── output.ts        # JSON/pretty output formatter + field filtering
+    ├── validate.ts      # UUID, required, enum, resource name validators
+    ├── supabase.ts      # Authenticated Supabase client + org resolution
+    ├── auth.ts          # Browser auth flow + credential storage
+    └── config.ts        # ollie.json config loader/saver
+```