primitive-admin 1.0.0

package/README.md

@@ -0,0 +1,495 @@
+# primitive-admin CLI
+
+Command-line interface for administering Primitive applications. This CLI provides full control over your Primitive apps, including user management, integrations, prompts, workflows, and configuration sync.
+
+## Installation
+
+```bash
+npm install -g primitive-admin
+```
+
+### Development Setup
+
+From the **worklet root directory**:
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the CLI
+pnpm run cli:build
+
+# Link globally for system-wide access
+npm link
+```
+
+Or from the **cli directory** directly:
+
+```bash
+cd cli
+
+# Build
+npx tsc
+
+# Link globally
+npm link
+```
+
+### Rebuilding After Changes
+
+If you modify CLI source files, rebuild before testing:
+
+```bash
+# From cli directory
+cd cli && npx tsc
+
+# Or from worklet root
+pnpm run cli:build
+```
+
+The globally linked `primitive` command uses the compiled files in `cli/dist/`, so changes to source files in `cli/src/` won't take effect until you rebuild.
+
+## Quick Start
+
+```bash
+# Login via browser OAuth
+primitive login
+
+# Set your working app context
+primitive use "My App"
+
+# List users in the current app
+primitive users list
+
+# View help for any command
+primitive --help
+primitive apps --help
+```
+
+## Authentication
+
+The CLI uses browser-based OAuth for authentication. When you run `primitive login`, it opens your browser to authenticate via Google OAuth and stores credentials locally.
+
+```bash
+# Login to the default server
+primitive login
+
+# Login to a custom server
+primitive login --server https://api.example.com
+
+# View current session
+primitive whoami
+
+# Get access token for scripting
+primitive token
+
+# Logout
+primitive logout
+```
+
+Credentials are stored in `~/.primitive/credentials.json` with mode 0600.
+
+## App Context
+
+Most commands require an app ID. You can specify it in two ways:
+
+1. **Flag**: `primitive users list --app 01HXYZ...`
+2. **Context**: Set once with `primitive use`, then omit from commands
+
+Commands that only need an app ID (like `list`) also accept it as a positional argument:
+```bash
+primitive users list 01HXYZ...
+```
+
+Commands with other required arguments use only `--app` for the app ID:
+```bash
+primitive workflows get <workflow-id> --app 01HXYZ...
+```
+
+```bash
+# Interactive app selection
+primitive use
+
+# Set by name or ID
+primitive use "My App"
+primitive use 01HXYZ...
+
+# View current context
+primitive context
+
+# Clear context
+primitive context clear
+```
+
+## Commands
+
+### Apps
+
+Manage applications (requires admin access).
+
+```bash
+primitive apps list                    # List all accessible apps
+primitive apps create "My App"         # Create a new app
+primitive apps get <app-id>            # Get app details
+primitive apps update <app-id> [opts]  # Update app settings
+primitive apps delete <app-id>         # Delete an app
+```
+
+**Update options:**
+- `--name <name>` - App display name
+- `--mode <mode>` - Access mode: public, invite-only, waitlist
+- `--base-url <url>` - Application base URL
+- `--waitlist` / `--no-waitlist` - Enable/disable waitlist
+- `--google-oauth` / `--no-google-oauth` - Enable/disable Google OAuth
+- `--passkey` / `--no-passkey` - Enable/disable passkey auth
+- `--magic-link` / `--no-magic-link` - Enable/disable magic link auth
+
+### Users
+
+Manage users within an app.
+
+```bash
+primitive users list [app-id]                           # List users
+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
+```
+
+### Waitlist
+
+Manage waitlist entries for apps in waitlist mode.
+
+```bash
+primitive waitlist list [app-id]                 # List waitlist entries
+primitive waitlist invite [app-id] <waitlist-id> # Invite from waitlist
+primitive waitlist bulk-invite [app-id] -n 10    # Bulk invite
+primitive waitlist remove [app-id] <waitlist-id> # Remove from waitlist
+```
+
+### Integrations
+
+Manage HTTP integrations (external API connections).
+
+```bash
+primitive integrations list [app-id]              # List integrations
+primitive integrations create [app-id] [options]  # Create integration
+primitive integrations get <integration-id>       # Get details
+primitive integrations update <id> [options]      # Update integration
+primitive integrations delete <id>                # Soft delete
+primitive integrations test <id>                  # Test connection
+primitive integrations logs <id>                  # View invocation logs
+```
+
+**Create options:**
+- `--from-file <path>` - Load from TOML file
+- `--key <key>` - Integration key (identifier)
+- `--name <name>` - Display name
+- `--base-url <url>` - Base URL for API calls
+- `--timeout <ms>` - Request timeout in milliseconds
+
+**Secrets management:**
+```bash
+primitive integrations secrets list <integration-id>
+primitive integrations secrets add <id> --data '{"apiKey":"..."}'
+primitive integrations secrets archive <id> <secret-id>
+```
+
+### Prompts
+
+Manage LLM prompt configurations.
+
+```bash
+primitive prompts list [app-id]             # List prompts
+primitive prompts create [app-id] [options] # Create prompt
+primitive prompts get <prompt-id>           # Get details
+primitive prompts update <id> [options]     # Update prompt
+primitive prompts delete <id>               # Soft delete
+primitive prompts execute <id> --vars '{}'  # Execute prompt
+primitive prompts preview <id> --vars '{}'  # Preview rendered template
+```
+
+**Create options:**
+- `--from-file <path>` - Load from TOML file
+- `--key <key>` - Prompt key (identifier)
+- `--name <name>` - Display name
+- `--provider <provider>` - LLM provider (openrouter, gemini)
+- `--model <model>` - Model name
+- `--system-prompt <text>` - System prompt
+- `--user-template <text>` - User prompt template
+
+**Configs (prompt variations):**
+```bash
+primitive prompts configs list <prompt-id>
+primitive prompts configs create <prompt-id> [options]
+primitive prompts configs activate <prompt-id> <config-id>
+primitive prompts configs duplicate <prompt-id> <config-id>
+```
+
+### Workflows
+
+Manage multi-step workflow definitions.
+
+```bash
+primitive workflows list [app-id]                  # List workflows
+primitive workflows create [app-id] --from-file wf.toml  # Create workflow
+primitive workflows get <workflow-id>              # Get details
+primitive workflows update <id> [options]          # Update metadata
+primitive workflows draft update <id> --from-file wf.toml  # Update draft
+primitive workflows publish <id>                   # Publish draft
+primitive workflows preview <id> --input '{}'      # Preview execution
+```
+
+**Run management:**
+```bash
+primitive workflows runs list <workflow-id>
+primitive workflows runs status <workflow-id> <run-id>
+```
+
+### 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
+```
+
+**Options:**
+- `--window-days <n>` - Time window (default: 30)
+- `--limit <n>` - Result limit for top-users
+
+### Admins (Super-Admin Only)
+
+Manage the admin directory.
+
+```bash
+primitive admins list                              # List all admins
+primitive admins search <email>                    # Search by email
+primitive admins invite <email>                    # Create invitation
+primitive admins update <admin-id> [options]       # Update settings
+primitive admins disable <admin-id>                # Disable account
+primitive admins enable <admin-id>                 # Enable account
+primitive admins invitations list                  # List invitations
+primitive admins invitations delete <invitation-id>
+```
+
+### Catalog (Super-Admin Only)
+
+Manage the global prompt and integration catalog.
+
+```bash
+# Prompt catalog
+primitive catalog prompts list
+primitive catalog prompts create --from-file prompt.toml
+primitive catalog prompts get <catalog-id>
+primitive catalog prompts update <catalog-id> [options]
+primitive catalog prompts delete <catalog-id>
+
+# Integration catalog
+primitive catalog integrations list
+primitive catalog integrations create --from-file integration.toml
+primitive catalog integrations get <catalog-id>
+primitive catalog integrations update <catalog-id> [options]
+primitive catalog integrations delete <catalog-id>
+```
+
+### Sync (TOML Configuration)
+
+Sync app configuration to/from TOML files for version control.
+
+```bash
+primitive sync init [app-id] --dir ./config    # Initialize config directory
+primitive sync pull [app-id] --dir ./config    # Pull remote config to local
+primitive sync push [app-id] --dir ./config    # Push local config to remote
+primitive sync diff [app-id] --dir ./config    # Show differences
+```
+
+**Options:**
+- `--dir <path>` - Config directory (default: ./config)
+- `--dry-run` - Show changes without applying (push only)
+- `--force` - Overwrite remote changes (push only)
+
+## TOML Configuration Format
+
+The sync commands use TOML files for configuration. Here's the directory structure:
+
+```
+config/
+  .primitive-sync.json     # Sync state (auto-generated)
+  app.toml                 # App settings
+  integrations/
+    weather-api.toml       # Integration configs
+  prompts/
+    summarizer.toml        # Prompt configs with all variations
+  workflows/
+    process-doc.toml       # Workflow definitions
+```
+
+### Example: app.toml
+
+```toml
+[app]
+name = "My Application"
+mode = "invite-only"
+waitlistEnabled = false
+baseUrl = "https://myapp.com"
+
+[auth]
+googleOAuthEnabled = true
+passkeyEnabled = true
+magicLinkEnabled = false
+
+[cors]
+mode = "custom"
+allowedOrigins = ["https://myapp.com"]
+allowCredentials = true
+```
+
+### Example: integrations/weather-api.toml
+
+```toml
+[integration]
+key = "weather-api"
+displayName = "Weather API"
+description = "OpenWeatherMap integration"
+status = "active"
+timeoutMs = 30000
+
+[requestConfig]
+baseUrl = "https://api.openweathermap.org/data/2.5"
+allowedMethods = ["GET"]
+allowedPaths = ["/weather", "/forecast"]
+```
+
+### Example: prompts/summarizer.toml
+
+```toml
+[prompt]
+key = "summarizer"
+displayName = "Text Summarizer"
+description = "Summarizes input text"
+status = "active"
+
+[[configs]]
+name = "default"
+provider = "openrouter"
+model = "google/gemini-2.0-flash-001"
+temperature = "0.7"
+maxTokens = 500
+systemPrompt = "You are a helpful assistant."
+userPromptTemplate = "Summarize: {{ input.text }}"
+
+[[configs]]
+name = "concise"
+provider = "openrouter"
+model = "google/gemini-2.0-flash-001"
+temperature = "0.3"
+maxTokens = 200
+systemPrompt = "You create very brief summaries."
+userPromptTemplate = "Brief summary:\n{{ input.text }}"
+```
+
+## Output Formats
+
+All list/get commands support `--json` for machine-readable output:
+
+```bash
+# Human-readable table
+primitive apps list
+
+# JSON output for scripting
+primitive apps list --json | jq '.[0].appId'
+```
+
+## Exit Codes
+
+- `0` - Success
+- `1` - General error
+- `2` - Authentication error (try `primitive login`)
+
+## Environment Variables
+
+- `PRIMITIVE_SERVER_URL` - Server URL for login (defaults to `https://primitiveapi.com`)
+
+**Server URL priority:**
+1. `--server` flag (highest priority)
+2. `PRIMITIVE_SERVER_URL` environment variable
+3. Default: `https://primitiveapi.com`
+
+## Development
+
+```bash
+# Run without building (uses tsx)
+pnpm run cli:dev -- login
+
+# Type check
+pnpm run cli:typecheck
+
+# Build
+pnpm run cli:build
+```
+
+## Testing
+
+The CLI includes both unit tests and integration tests.
+
+### Unit Tests
+
+Unit tests run without requiring a server connection:
+
+```bash
+# Run all unit tests
+pnpm run cli:test:unit
+```
+
+### Integration Tests
+
+Integration tests require a running server and valid admin credentials:
+
+```bash
+# Set required environment variables
+export TEST_HTTP_URL=https://localhost:8787
+export TEST_ADMIN_JWT=your-admin-jwt-token
+export TEST_APP_ID=01HXYZ...  # Optional: for app-scoped tests
+
+# Run integration tests
+pnpm run cli:test:integration
+```
+
+### All Tests
+
+```bash
+# Run all CLI tests
+pnpm run cli:test
+```
+
+### Test Structure
+
+```
+cli/tests/
+  unit/
+    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
+```
+
+## Troubleshooting
+
+### "Not logged in" error
+Run `primitive login` to authenticate.
+
+### "No app specified" error
+Either pass an app ID as an argument, use `--app <id>`, or set context with `primitive use`.
+
+### Token expired
+The CLI automatically refreshes tokens. If issues persist, try `primitive logout` then `primitive login`.
+
+### Connection errors
+Verify your server URL with `primitive whoami` and check network connectivity.

package/dist/bin/primitive.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerAuthCommands } from "../src/commands/auth.js";
+import { registerAppsCommands } from "../src/commands/apps.js";
+import { registerUsersCommands } from "../src/commands/users.js";
+import { registerWaitlistCommands } from "../src/commands/waitlist.js";
+import { registerIntegrationsCommands } from "../src/commands/integrations.js";
+import { registerPromptsCommands } from "../src/commands/prompts.js";
+import { registerWorkflowsCommands } from "../src/commands/workflows.js";
+import { registerAdminsCommands } from "../src/commands/admins.js";
+import { registerCatalogCommands } from "../src/commands/catalog.js";
+import { registerAnalyticsCommands } from "../src/commands/analytics.js";
+import { registerSyncCommands } from "../src/commands/sync.js";
+import { error } from "../src/lib/output.js";
+import { ApiError } from "../src/lib/api-client.js";
+const program = new Command();
+program
+    .name("primitive")
+    .description(`CLI for administering Primitive applications.
+
+Manage apps, users, integrations, prompts, workflows, and more from the command line.
+Supports TOML-based configuration sync for version-controlled app settings.`)
+    .version("1.0.0")
+    .addHelpText("after", `
+Examples:
+  $ primitive login                    # Authenticate via browser OAuth
+  $ primitive use "My App"             # Set working app context
+  $ primitive users list               # List users (uses current app)
+  $ primitive integrations list --json # JSON output for scripting
+  $ primitive sync pull --dir ./config # Export config to TOML files
+
+Authentication:
+  Credentials are stored in ~/.primitive/credentials.json
+
+App Context:
+  Set with 'primitive use <app>' to avoid passing --app to every command.
+  Most commands accept --app flag to override the current context.
+
+Documentation:
+  See https://github.com/anthropics/primitive for full documentation.
+`);
+// Register all command groups
+registerAuthCommands(program);
+registerAppsCommands(program);
+registerUsersCommands(program);
+registerWaitlistCommands(program);
+registerIntegrationsCommands(program);
+registerPromptsCommands(program);
+registerWorkflowsCommands(program);
+registerAdminsCommands(program);
+registerCatalogCommands(program);
+registerAnalyticsCommands(program);
+registerSyncCommands(program);
+// Global error handler
+program.hook("preAction", () => {
+    // Reset API client state before each command
+});
+// Parse and execute
+program.parseAsync(process.argv).catch((err) => {
+    if (err instanceof ApiError) {
+        error(err.message);
+        if (err.statusCode === 401) {
+            error("Try running 'primitive login' to authenticate.");
+        }
+        process.exit(err.statusCode === 401 ? 2 : 1);
+    }
+    else {
+        error(err.message || "An unexpected error occurred");
+        process.exit(1);
+    }
+});
+//# sourceMappingURL=primitive.js.map

package/dist/bin/primitive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive.js","sourceRoot":"","sources":["../../bin/primitive.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,EAAE,4BAA4B,EAAE,MAAM,iCAAiC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,WAAW,CAAC;KACjB,WAAW,CAAC;;;4EAG6D,CAAC;KAC1E,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,OAAO,EAAE;;;;;;;;;;;;;;;;;CAiBvB,CAAC,CAAC;AAEH,8BAA8B;AAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAClC,4BAA4B,CAAC,OAAO,CAAC,CAAC;AACtC,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACjC,yBAAyB,CAAC,OAAO,CAAC,CAAC;AACnC,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACjC,yBAAyB,CAAC,OAAO,CAAC,CAAC;AACnC,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAE9B,uBAAuB;AACvB,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;IAC7B,6CAA6C;AAC/C,CAAC,CAAC,CAAC;AAEH,oBAAoB;AACpB,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IAC7C,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;QAC5B,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACnB,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;YAC3B,KAAK,CAAC,gDAAgD,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,GAAG,CAAC,OAAO,IAAI,8BAA8B,CAAC,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC"}