@stndrds/cli 1.0.0-alpha.258 → 1.0.0-alpha.259

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stndrds/cli",
-  "version": "1.0.0-alpha.258",
+  "version": "1.0.0-alpha.259",
   "description": "CLI tool to interact with Standards API",
   "type": "module",
   "bin": {
@@ -10,9 +10,12 @@
     "dist"
   ],
   "dependencies": {
+    "@clack/prompts": "^1.7.0",
     "chalk": "^5.4.1",
     "cli-table3": "^0.6.5",
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "esbuild": "^0.25.0",
+    "@stndrds/schema": "1.0.0-alpha.259"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/dist/assets/schema-builder-reference.md

@@ -1,513 +0,0 @@
-# Standards Schema Builder — Reference
-
-## Overview
-
-Standards uses a fluent builder API to define your data schema in TypeScript.
-All objects and attributes declared in code are **system** (immutable at runtime).
-Users can extend your schema at runtime by adding custom attributes via the UI.
-
-## Importing
-
-```typescript
-import {
-  object,
-  text, richtext,
-  number, currency,
-  checkbox,
-  date,
-  phone,
-  select, multiselect, status,
-  relation,
-  user,
-  file, document,
-  location,
-  formula, rollup,
-} from "@stndrds/schema";
-```
-
-## `object()` — Define an Object (table)
-
-```typescript
-const DEAL = object({ name: "deals", label: "Deal" })
-  .pluralLabel("Deals")
-  .description("Sales opportunities")
-  .icon("briefcase")
-  .order(10)                              // sidebar display order
-  .labelExpression("{{ name }}")         // REQUIRED — how records display
-  .attribute(text({ name: "name", label: "Name" }).required())
-  .attribute(number({ name: "amount", label: "Amount" }))
-  .build();
-```
-
-Object names must be **kebab-case** (e.g. `"deals"`, `"order-items"`). Max 63 characters.
-
-The `.build()` call is required at the end. The returned value is the `ObjectDefinition`.
-
-### `.sealed()` — Prevent custom attributes
-
-Marks this object as closed: `standards diff` will error if any user-created
-custom attribute is found in the DB that is not listed in `.tolerate()`.
-
-```typescript
-object({ name: "invoice", label: "Invoice" })
-  .sealed()
-  .labelExpression("{{ ref }}")
-  .attribute(number({ name: "amount", label: "Amount" }))
-  .build();
-```
-
-### `.tolerate(["name"])` — Acknowledge known custom attributes
-
-On a **sealed** object: these names won't cause a CI failure.
-On an **extensible** object: purely documentary.
-
-```typescript
-object({ name: "invoice", label: "Invoice" })
-  .sealed()
-  .tolerate(["legacy_ref", "old_notes"])
-  .labelExpression("{{ ref }}")
-  .attribute(number({ name: "amount", label: "Amount" }))
-  .build();
-```
-
-### `.labelExpression()` — Display template (REQUIRED)
-
-Every object must declare a label expression. Uses `{{ attribute }}` syntax.
-Pipes are supported: `{{ name | UPPER }}`, `{{ name | capitalize }}`, `{{ name | trim }}`, `{{ name | LOWER }}`.
-
-```typescript
-.labelExpression("{{ firstName }} {{ lastName }}")
-.labelExpression("{{ name | UPPER }}")
-.labelExpression("{{ ref }} — {{ title }}")
-```
-
-### Other object methods
-
-| Method | Purpose |
-|---|---|
-| `.pluralLabel("Deals")` | Plural form shown in collections |
-| `.description("...")` | Shown in admin UI tooltips |
-| `.icon("briefcase")` | Icon name from `@stndrds/constants` |
-| `.order(10)` | Sidebar sort order (lower = first) |
-
----
-
-## Attribute Types
-
-All attribute builders accept `{ name, label }` as first argument.
-`name` must be **camelCase** or **snake_case**, unique within the object.
-
-### `text()` — Plain text
-
-```typescript
-text({ name: "name", label: "Name" })
-  .required()
-  .minLength(1)
-  .maxLength(255)
-  .pattern("^[A-Z].*")     // custom regex
-  .email()                  // shortcut: validates as email
-  .url()                    // shortcut: validates as URL
-  .slug()                   // shortcut: validates as slug (a-z0-9-)
-  .placeholder("Enter name...")
-```
-
-Use `.multiline()` for longer plain text:
-
-```typescript
-text({ name: "notes", label: "Notes" })
-  .multiline()
-  .optional()
-  .placeholder("Add notes...")
-```
-
-### `richtext()` — Rich text (Tiptap editor)
-
-```typescript
-richtext({ name: "description", label: "Description" }).required()
-```
-
-### `number()` — Numeric value
-
-```typescript
-number({ name: "amount", label: "Amount" })
-  .decimal(2)       // decimal with 2 places (default unit="decimal")
-  .integer()        // whole numbers only (unit="integer", decimals=0)
-  .percentage()     // percentage display (unit="percentage")
-  .min(0)
-  .max(100)
-  .required()
-```
-
-Use `.renderAs("rating")` for rating UI backed by a number:
-
-```typescript
-number({ name: "score", label: "Score" })
-  .renderAs("rating")
-  .max(5)
-```
-
-### `currency()` — Monetary amount with currency code
-
-```typescript
-currency({ name: "price", label: "Price" })
-  .defaultCurrency("EUR")
-  .allowedCurrencies(["EUR", "USD", "GBP"])
-  .allowNegative()
-  .required()
-```
-
-### `checkbox()` — Boolean toggle
-
-```typescript
-checkbox({ name: "isVerified", label: "Verified" })
-  .defaultValue(false)
-```
-
-### `date()` — Date picker
-
-```typescript
-date({ name: "closeDate", label: "Close Date" })
-  .format("short")          // "short" | "long" | "full" | "relative"
-  .minDate("2024-01-01")
-  .maxDate("2030-12-31")
-  .required()
-```
-
-### `phone()` — Phone number with country code
-
-```typescript
-phone({ name: "mobile", label: "Mobile" })
-  .defaultCountry("FRA")    // ISO 3166-1 alpha-3 country code
-  .required()
-```
-
-### `select()` — Single-choice dropdown
-
-```typescript
-select({ name: "status", label: "Status" })
-  .options([
-    { label: "Lead",   value: "lead",   color: "blue" },
-    { label: "Client", value: "client", color: "green" },
-  ])
-  .required()
-```
-
-Options shape: `{ label: string, value: string, color?: string, description?: string }`.
-Colors: `"gray"` | `"red"` | `"orange"` | `"yellow"` | `"green"` | `"blue"` | `"purple"`.
-
-Use `.option({ ... })` to append a single option instead of replacing all.
-
-### `multiselect()` — Multi-choice dropdown
-
-Same API as `select()`, but the value is an array of selected option values.
-
-```typescript
-multiselect({ name: "tags", label: "Tags" })
-  .options([
-    { label: "Urgent",  value: "urgent",  color: "red" },
-    { label: "Pending", value: "pending", color: "orange" },
-  ])
-```
-
-### `status()` — Status with workflow groups
-
-Like `select()` but options support a `group` field for visual grouping.
-
-```typescript
-status({ name: "stage", label: "Stage" })
-  .options([
-    { label: "To Do",       value: "todo",        color: "gray",  group: "idle" },
-    { label: "In Progress", value: "in_progress", color: "blue",  group: "in_progress" },
-    { label: "Done",        value: "done",        color: "green", group: "finished" },
-  ])
-  .required()
-```
-
-Option groups: `"idle"` | `"in_progress"` | `"finished"`. The `group` field is optional.
-
-### `user()` — User reference
-
-```typescript
-user({ name: "owner", label: "Owner" })
-  .multiple()                 // allow multiple actors
-  .types(["user", "agent"])   // allow users, agents, or both
-  .required()
-```
-
-### `file()` — File upload
-
-```typescript
-file({ name: "attachment", label: "Attachment" })
-  .multiple()                                // allow multiple files
-  .maxFiles(5)
-  .maxSize(10 * 1024 * 1024)                 // 10 MB in bytes
-  .allowedTypes(["image/png", "image/jpeg", "application/pdf"])
-  .required()
-```
-
-### `document()` — Structured document with slots and edge properties
-
-Documents wrap files with agent-compatible processing and edge-level metadata.
-
-```typescript
-document({ name: "contracts", label: "Contracts" })
-  .slots([{ name: "file", label: "File", acceptedMimeTypes: ["application/pdf"] }])
-  .qualifyWith(
-    date({ name: "signedDate", label: "Signed Date" }),
-    select({ name: "status", label: "Status" }).options([
-      { label: "Pending",   value: "pending",   color: "orange" },
-      { label: "Validated", value: "validated", color: "green" },
-    ])
-  )
-```
-
-For multi-sided documents (e.g. identity card), define slots:
-
-```typescript
-document({ name: "identityDoc", label: "Identity Document" })
-  .slots([
-    {
-      name: "recto",
-      label: "Front",
-      required: true,
-      acceptedMimeTypes: ["image/*", "application/pdf"],
-      maxSizeBytes: 10 * 1024 * 1024,
-    },
-    {
-      name: "verso",
-      label: "Back",
-      required: false,
-      acceptedMimeTypes: ["image/*", "application/pdf"],
-      maxSizeBytes: 10 * 1024 * 1024,
-    },
-  ])
-```
-
-### `location()` — Address / geographic location
-
-```typescript
-location({ name: "address", label: "Address" })
-  .granularity("full")         // "full" | "address" | "city" | "state" | "country"
-  .defaultCountry("FRA")
-  .allowedCountries(["FRA", "BEL", "CHE"])
-  .required()
-```
-
-### `relation()` — Record reference (single or many)
-
-```typescript
-// Single relation (default cardinality: "one")
-relation({ name: "company", label: "Company" })
-  .to("companies")
-  .required()
-
-// Multi relation
-relation({ name: "contacts", label: "Contacts" })
-  .to("contacts")
-  .many()
-
-// Polymorphic (multiple targets)
-relation({ name: "linked", label: "Linked" })
-  .to("companies")
-  .to("contacts")
-  .many()
-
-// Universal (link to any object)
-relation({ name: "reference", label: "Reference" })
-  .toAny()
-  .many()
-```
-
-**Qualified relations** — add metadata on each edge:
-
-```typescript
-relation({ name: "shareholders", label: "Shareholders" })
-  .to("contacts")
-  .many()
-  .qualifyWith(
-    select({ name: "role", label: "Role" }).options([
-      { label: "Founder", value: "founder", color: "blue" },
-      { label: "Investor", value: "investor", color: "green" },
-    ]).required(),
-    number({ name: "shares", label: "Shares %" }).min(0).max(100),
-  )
-```
-
-**Bilateral relations** — automatically sync the reverse side:
-
-```typescript
-relation({ name: "relationships", label: "Relationships" })
-  .to("contacts")
-  .many()
-  .bilateral({ object: "contacts", attribute: "relationships" })
-  .qualifyWith(
-    select({ name: "type", label: "Type" }).options([...]).required()
-  )
-```
-
-Multi-relation constraints:
-
-```typescript
-.maxItems(10)  // maximum number of linked records
-```
-
-### `formula()` — Computed read-only value
-
-Formula attributes cannot be required (they are always read-only).
-
-```typescript
-formula({ name: "total", label: "Total" })
-  .expression("price * quantity")
-  .returns("number")   // "text" | "number" | "boolean" | "date"
-  .decimals(2)
-
-formula({ name: "fullName", label: "Full Name" })
-  .expression("CONCAT(firstName, ' ', lastName)")
-  .returns("text")
-```
-
-### `rollup()` — Aggregation from related records
-
-Rollup attributes cannot be required (they are always read-only).
-
-```typescript
-// Sum a numeric field across related records
-rollup({ name: "totalRevenue", label: "Total Revenue" })
-  .from("orders")           // name of the relation attribute on THIS object
-  .aggregate("amount")      // attribute name on the RELATED object
-  .using("sum")
-  .decimals(2)
-
-// Count related records
-rollup({ name: "orderCount", label: "Order Count" })
-  .from("orders")
-  .aggregate("id")
-  .using("count")
-```
-
-Available `.using()` functions:
-- Numeric only: `"sum"` | `"avg"`
-- Date only: `"earliest"` | `"latest"`
-- Universal: `"count"` | `"countValues"` | `"countUniqueValues"` | `"countEmpty"` | `"percentEmpty"` | `"percentNotEmpty"` | `"original"`
-
-The `"original"` function returns raw values as an array rendered as the target type.
-When using `"original"` on a select/status/multiselect, also call `.targetType()` and `.targetOptions()`:
-
-```typescript
-rollup({ name: "dealStages", label: "Deal Stages" })
-  .from("deals")
-  .aggregate("stage")
-  .using("original")
-  .targetType("status")
-  .targetOptions([
-    { label: "Open", value: "open", color: "blue" },
-    { label: "Won",  value: "won",  color: "green" },
-    { label: "Lost", value: "lost", color: "red" },
-  ])
-```
-
----
-
-## Common Attribute Options (all types)
-
-```typescript
-.required()                             // value is mandatory
-.optional()                             // value is optional (default)
-.hidden()                               // hidden from default UI views
-.description("Tooltip help text")       // shown as tooltip in UI
-.icon("star")                           // IconName from @stndrds/constants
-.placeholder("Enter a value...")        // input placeholder text
-.order(5)                               // display order within the form
-.defaultValue(...)                      // pre-fill new records
-```
-
----
-
-## Promoting a Custom Attribute
-
-When a user has created a custom attribute and you want to make it system:
-
-**Before (user-created in DB, not in code):**
-```
-drift: deal.urgence (text, label: "Urgence")
-```
-
-**After (promoted to system in code):**
-```typescript
-const DEAL = object({ name: "deals", label: "Deal" })
-  .labelExpression("{{ name }}")
-  .attribute(text({ name: "name", label: "Name" }).required())
-  .attribute(text({ name: "urgence", label: "Urgence" }))  // ← add this
-  .build();
-```
-
-On next boot, the existing custom attribute is automatically promoted to system.
-
----
-
-## Tolerating a Custom Attribute (sealed objects only)
-
-When you seal an object but want to acknowledge an existing custom attribute:
-
-```typescript
-const INVOICE = object({ name: "invoice", label: "Invoice" })
-  .sealed()
-  .tolerate(["legacy_ref"])   // ← known custom attr, won't fail CI
-  .labelExpression("{{ ref }}")
-  .attribute(text({ name: "ref", label: "Reference" }).required())
-  .build();
-```
-
----
-
-## Migrations
-
-When you rename or change the type of an attribute, declare a migration.
-Versions must start at 2 and be sequential (2, 3, 4, ...).
-
-```typescript
-object({ name: "deals", label: "Deal" })
-  .migration(2, (m) => m.renameAttribute("old_name", "new_name"))
-  .migration(3, (m) => m.changeType("score", "text", "number", { transform: (v) => v }))
-  .migration(4, (m) => m.removeAttribute("deprecated_field"))
-  .labelExpression("{{ new_name }}")
-  .attribute(text({ name: "new_name", label: "Name" }).required())
-  .build();
-```
-
-Available migration operations:
-- `m.renameAttribute(from, to)` — rename an attribute
-- `m.changeType(name, fromType, toType, options?)` — change attribute type
-- `m.removeAttribute(name)` — permanently remove an attribute
-- `m.addAttribute(attribute)` — add a new attribute via migration
-- `m.updateConfig(name, config)` — patch attribute config (label, options, etc.)
-
----
-
-## Type Inference
-
-Extract TypeScript types from your schema builders for use in frontend code:
-
-```typescript
-// ✅ Correct: infer types from the builder (before .build())
-const dealBuilder = object({ name: "deals", label: "Deal" })
-  .labelExpression("{{ name }}")
-  .attribute(text({ name: "name", label: "Name" }).required())
-  .attribute(number({ name: "amount", label: "Amount" }));
-
-type DealRecord = typeof dealBuilder.$infer.record;   // full record with id, timestamps
-type DealCreate = typeof dealBuilder.$infer.create;   // input for creation
-type DealUpdate = typeof dealBuilder.$infer.update;   // input for partial update
-
-// Export the compiled definition separately
-export const DEAL = dealBuilder.build();
-```
-
-You can also use `ExtractRecord` from `@stndrds/schema`:
-
-```typescript
-import { ExtractRecord } from "@stndrds/schema";
-type DealRecord = ExtractRecord<typeof dealBuilder>;  // same as $infer.record
-```
-
-Note: `ExtractRecord` works on the **builder** (`typeof dealBuilder`), not the compiled definition (`typeof DEAL`).