primitive-admin 1.1.0-alpha.3 → 1.1.0-alpha.31

package/README.md

@@ -150,12 +150,13 @@ Manage users within an app.
 
 ```bash
 primitive users list [app-id]                           # List users
+primitive users create <email> [--role admin|member]    # Create/add user by email
 primitive users invite [app-id] <email> [--role admin]  # Invite user
 primitive users remove [app-id] <user-id>               # Remove user
 primitive users set-role [app-id] <user-id> <role>      # Change role
 primitive users transfer-owner [app-id] <new-owner-id>  # Transfer ownership
-primitive users invitations list [app-id]               # List pending invitations
-primitive users invitations delete [app-id] <inv-id>    # Delete invitation
+primitive users mint-jwt <user-id> [--role <role>]      # Mint test JWT (dev/test only)
+primitive users invitations [app-id]                    # List pending invitations
 ```
 
 ### Waitlist
@@ -197,6 +198,26 @@ primitive integrations secrets add <id> --data '{"apiKey":"..."}'
 primitive integrations secrets archive <id> <secret-id>
 ```
 
+### Secrets
+
+Manage encrypted app secrets (API keys, tokens, credentials). Values are encrypted at rest and never displayed after creation.
+
+```bash
+primitive secrets list [--app <app-id>]                            # List secrets (values never shown)
+primitive secrets set <KEY> --value <value> [--summary <text>]     # Create or update a secret
+primitive secrets delete <KEY>                                      # Delete a secret
+```
+
+**Examples:**
+```bash
+primitive secrets set OPENAI_API_KEY --value "sk-..." --summary "Production key"
+primitive secrets set STRIPE_SECRET --value "sk_live_..."
+primitive secrets list --json
+primitive secrets delete STRIPE_SECRET
+```
+
+Keys must be uppercase letters, digits, and underscores (e.g., `OPENAI_API_KEY`). Max 100 secrets per app, 2 KB per value. The `set` command is an upsert — it creates or updates automatically. Use `{{secrets.KEY}}` in workflows and `secrets.KEY` in CEL rules.
+
 ### Prompts
 
 Manage LLM prompt configurations.
@@ -248,6 +269,20 @@ primitive workflows runs list <workflow-id>
 primitive workflows runs status <workflow-id> <run-id>
 ```
 
+**Workflow TOML push-time validation (issue #685):** Every command that
+pushes a workflow TOML (`workflows create --from-file`,
+`workflows draft update --from-file`, `workflows configs create --from-file`,
+`workflows configs update --from-file`, and `primitive sync push`) runs the
+file through `cli/src/lib/workflow-toml-validator.ts` before sending it to
+the server. The validator rejects any step with a top-level field outside
+the universal-and-consumed allowlist — most commonly catching the footgun
+where `[steps.<id>.request]` is written under `[[steps]]` (TOML places the
+sub-table under `steps[N][<id>]`, not the intended `steps[N].request`, so
+the runtime silently runs the step with an empty `request` block). The
+correct form for the most-recent step is `[steps.request]`. When adding a
+new step kind that consumes a new top-level field, add the field name to
+`ALLOWLISTED_FIELDS` in that file.
+
 ### Tokens
 
 Manage long-lived API access tokens for headless/server authentication.
@@ -267,12 +302,13 @@ primitive tokens revoke <token-id> [app-id]                           # Revoke t
 
 ### Databases
 
-Manage online databases, permissions, and group permissions.
+Manage online databases and permissions. `list` returns databases the user has direct access to; group-shared databases are listed via `primitive groups databases`.
 
 ```bash
-primitive databases list [app-id]                     # List databases
+primitive databases list [app-id]                     # List databases (direct access)
 primitive databases create <title> [app-id]           # Create database
 primitive databases get <database-id> [app-id]        # Get details
+primitive databases update <database-id> [options]    # Update title or type
 primitive databases delete <database-id> [app-id]     # Delete database
 ```
 
@@ -283,14 +319,68 @@ primitive databases permissions grant <database-id> --user-id <uid> --permission
 primitive databases permissions revoke <database-id> <user-id> [app-id]
 ```
 
-**Group permissions:**
+Permission values: `owner` (set at creation), `manager`
+
+**Metadata:**
+```bash
+primitive databases metadata update <database-id> --data '{"key":"value"}'  # Merge-update metadata
+```
+
+**Operations:**
 ```bash
-primitive databases group-permissions list <database-id> [app-id]
-primitive databases group-permissions grant <database-id> --group-type <type> --group-id <id> --permission <perm> [app-id]
-primitive databases group-permissions revoke <database-id> <group-type> <group-id> [app-id]
+primitive databases operations list <database-id> [app-id]                     # List registered operations
+primitive databases operations execute <database-id> <op-name> --params '{}'   # Execute operation
+primitive databases operations execute <database-id> <op-name> --token <jwt>   # Execute as specific user
 ```
 
-Permission values: `owner`, `read-write`, `reader`
+The `--token` flag lets you execute an operation as a specific user using a test JWT from `users mint-jwt`. Useful for testing access rules.
+
+**Records (schema introspection):**
+```bash
+primitive databases records models <database-id> [app-id]            # List model names
+primitive databases records describe <database-id> <model> [app-id]  # Show inferred schema
+```
+
+**Indexes:**
+```bash
+primitive databases indexes list <database-id> [--model <name>]       # List indexes
+primitive databases indexes create <database-id> <model> <field> [options]  # Create index
+primitive databases indexes drop <database-id> <model> <field>        # Drop index
+```
+
+**Export / Import:**
+```bash
+primitive databases export [app-id] <database-id> --output <dir>      # Export records, indexes, constraints
+primitive databases import [app-id] <path> --overwrite --dry-run      # Import from export directory
+```
+
+Export creates a directory with `metadata.json`, `records.jsonl`, `indexes.json`, and `constraints.json`. Import restores records and indexes into a new or existing database. Database type config (operations, triggers, access rules) is managed separately via `primitive sync` — run `sync push` on the target app before importing.
+
+### Documents
+
+Manage document ownership, group permissions, and export/import.
+
+```bash
+primitive documents transfer-owner [app-id] <document-id> <new-owner-id>  # Transfer ownership
+```
+
+**Group permissions on documents:**
+```bash
+primitive documents group-permissions list <document-id>
+primitive documents group-permissions grant <document-id> --group-type <type> --group-id <id> --permission <perm>
+primitive documents group-permissions revoke <document-id> <group-type> <group-id>
+```
+
+Permission values: `read-write`, `reader`
+
+**Export / Import:**
+```bash
+primitive documents export [app-id] <document-id> --output <dir>         # Export Yjs state, blobs, permissions, aliases
+primitive documents export-all [app-id] --user-id <id> --owned-only      # Export all docs for a user
+primitive documents import [app-id] <path> --overwrite --aliases overwrite|skip --dry-run  # Import from export
+```
+
+Export creates a directory per document with `metadata.json`, `document.yjs` (Yjs state), `permissions.json` (for reference), and `blobs/` (attachments). Permissions are exported for reference but not restored during import — the importing admin is the new owner and manages sharing in the target app. Document IDs are preserved across import. User-scoped aliases can be restored with `--aliases overwrite` (update existing) or `--aliases skip` (keep existing, default).
 
 ### Groups
 
@@ -317,20 +407,46 @@ primitive groups members set-role <group-type> <group-id> <user-id> <role> [app-
 primitive groups memberships <user-id> [app-id]          # List user's group memberships
 ```
 
+**Group resource access:**
+```bash
+primitive groups documents <group-type> <group-id>       # List documents a group can access
+```
+
+Group permissions on documents are managed via `primitive documents group-permissions` (see [Documents](#documents) above).
+
 ### Analytics
 
 View usage analytics for an app.
 
 ```bash
-primitive analytics overview [app-id]              # Activity overview
-primitive analytics top-users [app-id]             # Most active users
-primitive analytics user [app-id] <user-ulid>      # User activity details
-primitive analytics integrations [app-id]          # Integration metrics
+# Overview & active users
+primitive analytics overview [app-id]                  # DAU / WAU / MAU + growth
+primitive analytics daily-active [app-id]              # Daily active users time series
+primitive analytics rolling-active [app-id]            # Rolling active users (28 points)
+primitive analytics cohort-retention [app-id]          # Weekly cohort retention matrix
+
+# Users
+primitive analytics top-users [app-id]                 # Most active users
+primitive analytics user-search [app-id] --query <q>   # Search by email or ULID
+primitive analytics user-detail <user-ulid> [app-id]   # User activity breakdown
+primitive analytics user-snapshot <user-ulid> [app-id] # Latest context snapshot
+
+# Events
+primitive analytics events [app-id]                    # Paginated event feed
+primitive analytics events-grouped [app-id]            # Events grouped by dimension
+
+# Features
+primitive analytics integrations [app-id]              # Integration usage metrics
+primitive analytics workflows [app-id]                 # Top workflows by runs
+primitive analytics prompts [app-id]                   # Top prompts by executions
 ```
 
-**Options:**
-- `--window-days <n>` - Time window (default: 30)
-- `--limit <n>` - Result limit for top-users
+**Common options:**
+- `--window-days <n>` - Time window in days (default varies per command)
+- `--limit <n>` - Result limit (top-users, workflows, prompts)
+- `--group-by <dim>` - Dimension for events-grouped (action, feature, route, country, deviceType, plan, day)
+- `--page <n>` - Page number for events feed (0-based)
+- `--json` - Output raw JSON
 
 ### Admins (Super-Admin Only)
 
@@ -475,6 +591,35 @@ primitive apps list
 primitive apps list --json | jq '.[0].appId'
 ```
 
+### Stdout vs. stderr
+
+The CLI follows the same convention as `git`, `kubectl`, `aws`, and `gh`:
+
+- **stdout** carries the *data* the command produced — JSON documents under
+  `--json`, tabular listings (`apps list`), raw values (`primitive token`),
+  and the primary `label: value` fields a `get` / `show` / `describe` command
+  emits (e.g. `primitive integrations get <id>`).
+- **stderr** carries *diagnostics* — status text (`✓ Created…`,
+  `i Waiting for completion...`), warnings (`!` markers), progress lines, and
+  the `key: value` summaries shown *after* a side-effecting command runs
+  (e.g. the `Webhook ID: …` confirmation printed by `webhooks create`).
+
+This means `primitive <cmd> --json | jq` always works, regardless of any
+status / warning / progress text the command may print along the way.
+It also means `primitive integrations get <id> > out.txt` writes the
+integration's fields to `out.txt` while the status diagnostics still appear
+on the terminal via stderr.
+
+Conversely, redirecting stderr (`primitive <cmd> 2>/dev/null`) silences
+diagnostics — including success checkmarks like `✓ Pushed 3 changes` — so
+prefer `2>&1 >file.txt` if you want the full transcript.
+
+For contributors writing new commands, the output helpers in
+`cli/src/lib/output.ts` make the data-vs-diagnostic split explicit: use
+`json()` and `result(label, value)` for data the caller asked for, and
+`success()` / `info()` / `warn()` / `keyValue()` / `divider()` / `heading()`
+for diagnostics about what the command did.
+
 ## Exit Codes
 
 - `0` - Success
@@ -545,11 +690,13 @@ cli/tests/
     config.test.ts    # Credentials and config management
     output.test.ts    # Output formatting functions
   integration/
-    api-client.test.ts  # API client HTTP tests
-    commands.test.ts    # CLI command tests
-    tokens.test.ts      # Token lifecycle tests
-    databases.test.ts   # Database CRUD, permissions, group permissions tests
-    groups.test.ts      # Group CRUD, members, memberships tests
+    api-client.test.ts      # API client HTTP tests
+    commands.test.ts        # CLI command tests
+    tokens.test.ts          # Token lifecycle tests
+    databases.test.ts       # Database CRUD, permissions, group permissions tests
+    documents.test.ts       # Document group permissions, group resource listing tests
+    groups.test.ts          # Group CRUD, members, memberships tests
+    classroom-e2e.test.ts   # End-to-end classroom app workflow (types, rules, operations, access)
 ```
 
 ## Troubleshooting

package/assets/skill/skills/primitive-platform/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: primitive-platform
+description: >
+  Expert guide for building applications on the Primitive platform. MUST be used whenever the user
+  is writing code that uses js-bao, js-bao-wss-client, primitive-app components, or any Primitive
+  platform feature (documents, databases, workflows, prompts, integrations, blobs, authentication,
+  users/groups). Also trigger whenever about to run any `primitive` CLI command (e.g., primitive sync, primitive integrations, primitive apps, primitive env) to ensure Step 0 CLI verification is performed first. After writing or modifying code that touches Primitive
+  APIs, this skill cross-references the implementation against official guides and automatically
+  corrects common mistakes. Use this skill even if the user doesn't explicitly ask for it —
+  any Primitive-related code should be validated against current best practices.
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep, Agent
+---
+
+# Primitive Platform Development Guide
+
+You are an expert on the Primitive platform. Your job is to help developers write correct,
+idiomatic Primitive code by leveraging the CLI's built-in guide system and enforcing best practices.
+
+**The CLI guides are the single source of truth.** Never hardcode or memorize guide content —
+always fetch the latest from the CLI.
+
+## Step 0: Verify CLI Configuration
+
+The Primitive CLI is **project-scoped**. Each project has a `.primitive/config.json` (committed to
+the repo) that defines named environments (`dev`, `prod`, `staging`, …), where each environment
+binds an `apiUrl` and (optionally) an `appId`. Per-environment auth tokens live in
+`.primitive/credentials.json` (gitignored). There is no global "currently active app" — the active
+environment determines the server *and* the app.
+
+**Before running any CLI commands**, your *first* check is whether the project is in project mode:
+
+```bash
+ls .primitive/config.json   # exists at project root or any ancestor?
+```
+
+The two branches below are not equivalent — pick the one that matches reality and follow it.
+
+### Branch A — `.primitive/config.json` exists (project mode)
+
+The active environment is resolved in this order:
+1. `--env <name>` flag on the command
+2. `PRIMITIVE_ENV` environment variable
+3. `defaultEnvironment` in `.primitive/config.json`
+4. The sole environment, if exactly one is defined
+
+Confirm you're targeting the correct environment:
+
+1. **Read the CLI header.** Every command prints `Env | App | Server` at the top of its output —
+   verify these match the project's intended target.
+2. **Inspect the project config:**
+
+   ```bash
+   primitive env list           # All environments (default marked with *)
+   primitive env show           # Details for the currently-resolved env
+   primitive whoami             # Authenticated user + resolved server/app
+   ```
+
+**To switch environments** for a one-off command, pass `--env <name>`. To change the project
+default, run `primitive env use <name>`. To switch the *app* an env points at, edit the env's
+`appId` in `.primitive/config.json` (or re-run `primitive env add`). `primitive use <app>` is a
+no-op when the active env already pins an `appId`.
+
+### Branch B — no `.primitive/config.json` (project mode NOT set up)
+
+In this branch the CLI silently falls back to global state in `~/.primitive/credentials.json`
+(legacy mode). Commands will run against whatever app/server happens to be globally active —
+which the agent didn't set and the user may have forgotten about. **This is a footgun.** Do not
+proceed silently.
+
+**Surface the gap to the user before running mutating commands.** Say something like:
+
+> "This project doesn't have a `.primitive/config.json`, so the CLI will use your global state
+> (`<server>` / `<app from `whoami`>`). I'd recommend setting up project-scoped config with
+> `primitive env add <name> --api-url <url> [--app-id <id>]` so this project pins its own
+> environment. Want me to set that up, or proceed against global state for now?"
+
+`primitive env add` is additive — it only writes an entry to `.primitive/config.json` (creating
+the file if needed). It does not touch source code, create apps on the server, or install
+dependencies, so it's safe to run in any existing project.
+
+Do not rely on `.env` files like `PRIMITIVE_API_URL` to control CLI targeting — those are not
+read by the CLI in project mode, and the project config is the source of truth.
+
+**Why this matters:** If the CLI is pointed at the wrong environment (e.g., prod instead of dev),
+commands like `primitive sync push` will modify the wrong server. Silent fallback to global state
+makes this exact mistake easy to commit. Always verify — and surface — before running mutating
+operations.
+
+## Step 1: Discover Available Guides
+
+Before writing or reviewing any Primitive code, run:
+
+```bash
+primitive guides list
+```
+
+This returns the full list of available guide topics with descriptions, keywords, and use cases.
+Use this output to determine which guides are relevant to the current task.
+
+## Step 2: Fetch the Relevant Guides
+
+For each relevant topic identified in Step 1, fetch the full guide:
+
+```bash
+primitive guides get <topic>
+```
+
+**Always fetch guide(s) BEFORE writing code.** If multiple features are involved, fetch multiple
+guides. The guides contain:
+- Complete API documentation with method signatures
+- Working code examples (TypeScript/JavaScript)
+- Common patterns and anti-patterns
+- Configuration examples (TOML files for `primitive sync`)
+- Decision frameworks for architecture choices
+
+**Do not guess or assume API patterns.** If you're unsure about a method signature, parameter,
+or pattern, fetch the guide. The guides are comprehensive and authoritative.
+
+## Step 3: Write Code Following Guide Patterns
+
+When writing Primitive code:
+
+1. **Follow the patterns from the fetched guides exactly** — method names, argument order, lifecycle patterns
+2. **Use `primitive sync`** for all backend configuration (workflows, prompts, integrations, databases)
+3. **Configuration lives in TOML files** in version control, pushed via `primitive sync push`
+4. **Run `pnpm codegen`** after creating or modifying js-bao models
+
+## Step 4: Post-Code Review (Automatic)
+
+After writing or modifying Primitive-related code, **automatically perform this review**:
+
+### 4a. Identify What Was Written
+Determine which Primitive features the new/modified code touches by scanning for:
+- Import statements from `js-bao`, `js-bao-wss-client`, or `primitive-app`
+- Primitive API calls (documents.open, databases.connect, workflows, etc.)
+- Model definitions, schemas, queries
+- Configuration files (TOML for sync)
+
+### 4b. Fetch and Cross-Reference
+Run `primitive guides list` to identify which guides cover the features used, then fetch each one:
+```bash
+primitive guides get <topic>
+```
+
+Compare the written code against the guide content:
+- **API usage patterns** — Are methods called correctly with proper arguments?
+- **Lifecycle management** — Are documents opened before queries? Is auth checked first?
+- **Access control** — Are CEL expressions or permissions configured properly?
+- **Anti-patterns** — Does the code do anything the guide explicitly warns against?
+- **Missing steps** — Does the code need `pnpm codegen`, `primitive sync push`, or other follow-up?
+
+### 4c. Report and Fix
+If issues are found:
+1. **Explain the issue** — cite the specific guide section that applies
+2. **Show the fix** — provide corrected code
+3. **Apply the fix** — edit the file directly (don't just suggest, actually fix it)
+4. **Note any CLI commands needed** — e.g., `pnpm codegen` or `primitive sync push`
+
+If no issues are found, briefly confirm the code follows best practices.
+
+## CLI Quick Reference
+
+Remind users of these essential commands when relevant:
+
+```bash
+# Verify current configuration (DO THIS FIRST)
+primitive env list                 # List environments in .primitive/config.json (default marked *)
+primitive env show                 # Details for the currently-resolved env (api URL, app ID)
+primitive whoami                   # Authenticated user + resolved server/app
+
+# Switching environments
+primitive env use <name>           # Change the project's default environment
+primitive --env <name> <command>   # One-off override for a single command
+PRIMITIVE_ENV=<name> <command>     # Override via env var (useful in scripts/CI)
+
+# Setup — existing project (most common: adopting Primitive in an existing repo)
+npm install -g primitive-admin                          # Install CLI
+primitive env add dev --api-url <url> --app-id <id>     # Add env to .primitive/config.json
+primitive env add prod --api-url <url> --app-id <id>    # (creates the file if missing)
+primitive login                                         # Authenticate (tokens stored per-env)
+
+# Setup — brand-new project (greenfield only)
+primitive init my-new-app                               # Scaffolds template, creates a new app
+                                                        # on the server, runs pnpm install.
+                                                        # Do NOT run inside an existing repo.
+
+# Guides (the most important commands for development)
+primitive guides list              # See all available guides with topics and descriptions
+primitive guides get <topic>       # Read detailed guide for a specific topic
+
+# Configuration as Code
+primitive sync init --dir ./config # Initialize config directory
+primitive sync pull --dir ./config # Pull config from server
+primitive sync push --dir ./config # Push config to server
+primitive sync diff --dir ./config # Preview changes before push
+
+# Common operations
+primitive apps list                # List apps on the active env's server
+primitive apps create "Name"       # Create an app (does NOT auto-bind to an env;
+                                   # edit .primitive/config.json or use `env add` to bind)
+```
+
+## When the User is Starting a New Feature
+
+If the user describes a new feature they want to build:
+
+1. **Verify CLI configuration** per Step 0 — confirm the active environment in
+   `.primitive/config.json` (and its bound `apiUrl` / `appId`) match the project's intended target
+   before running any commands
+2. **Run `primitive guides list`** to discover available topics
+3. **Identify which guides are relevant** to their feature from the list output
+4. **Fetch those guides** with `primitive guides get <topic>`
+5. **Recommend a data modeling approach** based on the guide content. If requirements are unclear or ambiguous, **ask the user clarifying questions before proceeding** — it's much easier to get the data model right upfront than to migrate later
+6. **Outline the implementation steps** referencing specific patterns from the guides
+7. **Write the code** following the patterns exactly
+8. **Review automatically** per Step 4 above
+
+## When the User Asks "How Do I...?"
+
+For any question about Primitive platform capabilities:
+
+1. **Run `primitive guides list`** to find the relevant topic
+2. **Fetch the guide**: `primitive guides get <topic>`
+3. **Answer from the guide content** — don't guess or make up APIs
+4. **Include working code examples** from the guide
+5. **Point the user to the guide** for further reading: "You can see more examples by running `primitive guides get <topic>`"