@getfrontline/cli 1.0.0

package/dist/skills/schema-design/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: schema-design
+description: >
+    Complete guide for designing table and object schemas with the Frontline CLI.
+    Covers choosing the right field type, metadata configuration, when to use
+    select vs relation, naming conventions, and common schema patterns.
+    Use as a reference before creating or extending any table or object.
+allowed-tools: Bash(frontline:*)
+---
+
+# Schema Design Guide
+
+This skill covers how to think about and build effective schemas using the
+Frontline CLI. Read this before creating or modifying fields on any table or object.
+
+## Resource Selection: Table vs Object
+
+| Type       | Goal                                    | Command         |
+| ---------- | --------------------------------------- | --------------- |
+| **Table**  | Simple spreadsheets, flat data          | `table create`  |
+| **Object** | Business entities, record types, pipeln | `object create` |
+
+```bash
+# Example: Create a new custom object
+frontline object create <name> --data '{
+  "displayName": "My Object",
+  "columns": [
+    { "name": "Title", "type": "string", "metadata": { "format": "text" } }
+  ]
+}'
+```
+
+## Field Type Decision Tree
+
+```
+What kind of data?
+│
+├─ Free text → string
+│   ├─ Email address    → metadata: { "format": "email" }
+│   ├─ URL / website    → metadata: { "format": "url" }
+│   ├─ Phone number     → metadata: { "format": "phone" }
+│   └─ General text     → metadata: { "format": "text" }
+│
+├─ Number → number
+│   ├─ Money            → metadata: { "format": "currency", "currency": "USD", "decimals": 2 }
+│   ├─ Percentage       → metadata: { "format": "percent" }
+│   ├─ Integer count    → metadata: { "format": "integer" }
+│   └─ Decimal          → metadata: { "format": "decimal", "decimals": 2 }
+│
+├─ Yes/No → boolean
+│   └─ metadata: {}
+│
+├─ Date or time → date / dateOnly
+│   ├─ With time + timezone → date, metadata: { "timezone": "America/New_York" }
+│   └─ Date only (no time)  → dateOnly, metadata: {}
+│
+├─ Pick from a fixed list → select
+│   ├─ Pick one    → metadata: { "mode": "singleSelect" }
+│   └─ Pick many   → metadata: { "mode": "multiSelect" }
+│
+├─ Link to another entity → relation
+│   ├─ One-to-one  → metadata: { "mode": "single" }
+│   └─ One-to-many → metadata: { "mode": "multi" }
+│
+└─ File attachment → file
+    └─ metadata: { "showPreview": true }
+```
+
+## Field Constraints
+
+You can set constraints on fields during creation or update:
+
+| Constraint | Description                                   | Example            |
+| ---------- | --------------------------------------------- | ------------------ |
+| `required` | Field must have a value in every record       | `"required": true` |
+| `unique`   | Field value must be unique across all records | `"unique": true`   |
+
+```bash
+# Make a field required and unique
+frontline object field update <object> <field-id> --data '{"required": true, "unique": true}'
+
+# Remove the required constraint
+frontline object field update <object> <field-id> --data '{"required": false}'
+```
+
+## Select vs Relation: When to Use Which
+
+| Use **select** when...                       | Use **relation** when...                     |
+| -------------------------------------------- | -------------------------------------------- |
+| Options are simple labels (Status, Priority) | Values are full records in another table     |
+| List is short and rarely changes             | List grows organically (contacts, companies) |
+| No extra data attached to each option        | Each value has its own fields and metadata   |
+| You want colored badges in the UI            | You need to navigate to the linked record    |
+| Example: Stage, Lead Source, Priority        | Example: Company, Assigned User, Contact     |
+
+## Complete Field Type Reference
+
+### string
+
+```bash
+# Plain text (default)
+--data '{ "name": "Notes", "type": "string", "metadata": { "format": "text" } }'
+
+# Email — enables validation and mailto links
+--data '{ "name": "Email", "type": "string", "metadata": { "format": "email" } }'
+
+# URL — renders as clickable link
+--data '{ "name": "Website", "type": "string", "metadata": { "format": "url" } }'
+
+# Phone — formats and enables click-to-call
+--data '{ "name": "Phone", "type": "string", "metadata": { "format": "phone_number" } }'
+```
+
+### number
+
+```bash
+# Currency — shows $ symbol, 2 decimal places
+--data '{ "name": "Revenue", "type": "number", "metadata": { "format": "currency", "currency": "USD", "decimals": 2 } }'
+
+# Percentage — shows % symbol
+--data '{ "name": "Win Rate", "type": "number", "metadata": { "format": "percent" } }'
+
+# Integer — no decimals
+--data '{ "name": "Headcount", "type": "number", "metadata": { "format": "integer" } }'
+
+# Decimal — custom precision
+--data '{ "name": "Weight", "type": "number", "metadata": { "format": "decimal", "decimals": 3 } }'
+```
+
+### boolean
+
+```bash
+--data '{ "name": "Is Active", "type": "boolean", "metadata": {} }'
+```
+
+### date / dateOnly
+
+```bash
+# Full datetime with timezone
+--data '{ "name": "Meeting Time", "type": "date", "metadata": { "timezone": "UTC" } }'
+
+# Date only (no time component)
+--data '{ "name": "Start Date", "type": "dateOnly", "metadata": {} }'
+```
+
+### select (single / multi)
+
+```bash
+# Single-select (pick one)
+--data '{ "name": "Priority", "type": "select", "metadata": { "mode": "singleSelect" } }'
+
+# Multi-select (pick many)
+--data '{ "name": "Tags", "type": "select", "metadata": { "mode": "multiSelect" } }'
+```
+
+After creating, add options:
+
+```bash
+frontline object option create <obj> <field-id> --data '{ "name": "High", "color": "Magenta" }'
+frontline object option create <obj> <field-id> --data '{ "name": "Medium", "color": "Amber" }'
+frontline object option create <obj> <field-id> --data '{ "name": "Low", "color": "Gray" }'
+```
+
+### Available Option Colors
+
+`Terracotta`, `Amber`, `Lime`, `Emerald`, `Lavender`, `Sky`, `Magenta`,
+`Bright Red`, `Teal`, `Gray`, `Brown`, `Orange`, `Yellow`, `Green`,
+`Blue`, `Purple`, `Pink`, `Red`
+
+## Common Schema Patterns
+
+### 1. Status Pipeline
+
+A single-select field with ordered stages:
+
+```bash
+frontline object field create sor__deals --data '{
+  "name": "Stage",
+  "type": "select",
+  "metadata": { "mode": "singleSelect" }
+}'
+# Then add stages in order:
+frontline object option create sor__deals <field-id> --data '{"name": "Lead", "color": "Gray"}'
+frontline object option create sor__deals <field-id> --data '{"name": "Qualified", "color": "Sky"}'
+frontline object option create sor__deals <field-id> --data '{"name": "Proposal", "color": "Amber"}'
+frontline object option create sor__deals <field-id> --data '{"name": "Won", "color": "Emerald"}'
+frontline object option create sor__deals <field-id> --data '{"name": "Lost", "color": "Red"}'
+```
+
+### 2. Contact Info Set
+
+Standard contact fields for a People-like object:
+
+```bash
+frontline object field create <obj> --data '{"name":"Email","type":"string","metadata":{"format":"email"}}'
+frontline object field create <obj> --data '{"name":"Phone","type":"string","metadata":{"format":"phone"}}'
+frontline object field create <obj> --data '{"name":"Website","type":"string","metadata":{"format":"url"}}'
+frontline object field create <obj> --data '{"name":"Address","type":"string","metadata":{"format":"text"}}'
+```
+
+### 3. Financial Tracking
+
+```bash
+frontline object field create <obj> --data '{"name":"Amount","type":"number","metadata":{"format":"currency","currency":"USD","decimals":2}}'
+frontline object field create <obj> --data '{"name":"Probability","type":"number","metadata":{"format":"percent"}}'
+frontline object field create <obj> --data '{"name":"Close Date","type":"dateOnly","metadata":{}}'
+```
+
+### 4. Categorization with Multi-Select
+
+```bash
+frontline object field create <obj> --data '{
+  "name": "Industries",
+  "type": "select",
+  "metadata": { "mode": "multiSelect" }
+}'
+frontline object option create <obj> <field-id> --data '{"name":"SaaS","color":"Sky"}'
+frontline object option create <obj> <field-id> --data '{"name":"E-commerce","color":"Purple"}'
+frontline object option create <obj> <field-id> --data '{"name":"Healthcare","color":"Emerald"}'
+frontline object option create <obj> <field-id> --data '{"name":"Fintech","color":"Amber"}'
+```
+
+## Naming Conventions
+
+| Do ✅                       | Don't ❌                  |
+| --------------------------- | ------------------------- |
+| `First Name`                | `firstName`, `first_name` |
+| `Email`                     | `email_address`           |
+| `Primary Location`          | `primary-location`        |
+| `Deal Value`                | `dealValue`               |
+| Title Case, space-separated | camelCase or snake_case   |
+
+Field names are **display names** shown in the UI. Use natural, readable names.
+
+## Workflow: Extending an Existing Object
+
+```bash
+# 1. Check what fields already exist
+frontline object field list sor__companies
+
+# 2. Check schema for relations
+frontline object schema sor__companies
+
+# 3. Add new fields — only add what's missing
+frontline object field create sor__companies --data '{
+  "name": "Annual Revenue",
+  "type": "number",
+  "metadata": { "format": "currency", "currency": "USD", "decimals": 0 }
+}'
+
+# 4. Add a categorization field
+frontline object field create sor__companies --data '{
+  "name": "Industry",
+  "type": "select",
+  "metadata": { "mode": "singleSelect" }
+}'
+# Add options
+frontline object option create sor__companies <field-id> --data '{"name":"Technology","color":"Sky"}'
+frontline object option create sor__companies <field-id> --data '{"name":"Finance","color":"Amber"}'
+
+# 5. Verify the final schema
+frontline object field list sor__companies
+```

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "@getfrontline/cli",
+    "version": "1.0.0",
+    "description": "Frontline CLI — Public API (agents, workflows, billing, tables, objects) + Max chat/admin REST from your terminal",
+    "private": false,
+    "type": "commonjs",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "bin": {
+        "frontline": "./dist/index.js",
+        "max": "./dist/max.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "node ./scripts/clean.mjs && tsc -p tsconfig.json && node ./scripts/addShebang.mjs && node ./scripts/copyStatic.mjs",
+        "dev:frontline": "ts-node src/index.ts",
+        "dev:max": "ts-node src/max.ts",
+        "postinstall": "node dist/scripts/postinstall.js || true",
+        "pack": "npm pack --dry-run",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "frontline",
+        "cli",
+        "api",
+        "max"
+    ],
+    "license": "MIT",
+    "dependencies": {
+        "chalk": "^4.1.2",
+        "commander": "^13.1.0",
+        "conf": "^10.2.0",
+        "ora": "^5.4.1",
+        "terminal-image": "^3.1.1"
+    },
+    "devDependencies": {
+        "@types/js-yaml": "^4.0.9",
+        "@types/node": "^22.0.0",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.7.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}