diff --git a/README.md b/README.md index 639f67c..7ba3363 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,21 @@ It provides: Cloudflare Workers with D1 is the primary deployment target. Node.js with SQLite or PostgreSQL is also supported. +## Quick start from a Lexicon prefix + +```bash +pnpx @atmo-dev/contrail init my-appview \ + --prefix community.lexicon.calendar. \ + --namespace com.example.calendar +cd my-appview +pnpx @atmo-dev/contrail dev +``` + +`--prefix` selects the source record Lexicons to import; `--namespace` sets the +separate XRPC namespace for the generated AppView methods. See the +[prefix setup guide](docs/01-getting-started.md#initialize-from-your-lexicon-prefix) +for choosing a prefix, generated files, and import options. + ## Documentation 1. [Get started locally](docs/01-getting-started.md) diff --git a/docs/01-getting-started.md b/docs/01-getting-started.md index c7e64ea..bc6582b 100644 --- a/docs/01-getting-started.md +++ b/docs/01-getting-started.md @@ -2,7 +2,9 @@ Run a local AppView for a public AT Protocol collection with Node.js 22.13 or newer. -Create a project from a verified Lexicon namespace: +## Initialize from your Lexicon prefix + +Pass the prefix to `contrail init`: ```bash pnpx @atmo-dev/contrail init my-appview \ @@ -11,12 +13,32 @@ pnpx @atmo-dev/contrail init my-appview \ cd my-appview ``` -Contrail queries `https://lex.atmo.tools`, selects record Lexicons under the +Replace `community.lexicon.calendar.` with your source Lexicon prefix. The value +is matched as a literal NSID prefix, so include the trailing `.` when you mean a +namespace boundary. For example, this prefix selects record Lexicons such as +`community.lexicon.calendar.event` and +`community.lexicon.calendar.rsvp`. + +The two namespace options serve different purposes: + +- `--prefix` selects the record Lexicons Contrail imports. +- `--namespace` sets the generated AppView XRPC method namespace. It is optional, + defaults to `com.example`, and does not need to match the imported prefix. + +Omit `my-appview` to initialize the current directory. Contrail refuses to +replace an existing config or pinned import. + +### What initialization creates + +Contrail queries `https://lex.atmo.tools`, selects record Lexicons matching the prefix, pins their complete dependency graph under `lexicons/pinned/`, and -creates `contrail.config.ts`. String fields become equality filters and sort -options; datetime fields become range filters and chronological sort options. -Arrays, unions, numeric fields, and other unsupported shapes are reported rather -than configured incorrectly. +creates `contrail.config.ts`. Every imported schema is recorded with its CID and +authority in `lexicons/pinned.lock`; commit the pinned schemas and lock alongside +the config. + +String fields become equality filters and sort options; datetime fields become +range filters and chronological sort options. Arrays, unions, numeric fields, +and other unsupported shapes are reported rather than configured incorrectly. When a strongRef or AT URI could point at another imported collection, an interactive terminal asks whether to add forward hydration and an inverse @@ -24,17 +46,32 @@ relation. The schema does not encode its target, so non-interactive runs leave ambiguous references unconfigured. Use `--no-interactive` to request that behavior explicitly. -The import requires complete verification and catalog indexing. Use +### Import options + +| Option | Purpose | Default | +|---|---|---| +| `--prefix ` | Import verified record Lexicons matching this NSID prefix | none (uses the offline starter) | +| `--namespace ` | Namespace for generated AppView XRPC methods | `com.example` | +| `--lexicon-api ` | Use another Lexicon registry | `https://lex.atmo.tools` | +| `--timeout ` | Readiness and dependency lookup budget | `60` | +| `--allow-partial` | Accept incomplete prefix verification or catalog indexing | off | +| `--no-interactive` | Skip reference and inverse-relation questions | off | + +The default import requires complete verification and catalog indexing. Use `--allow-partial` only when you deliberately accept that some prefix documents -may be absent; required dependencies must always resolve. Every imported schema -is recorded with its CID and authority in `lexicons/pinned.lock`. +may be absent; required dependencies must always resolve. -For an offline example config with no registry request, omit `--prefix`: +## Offline starter + +For an example config with no registry request, omit `--prefix`: ```bash pnpx @atmo-dev/contrail init my-appview +cd my-appview ``` +## Run the local AppView + Then run: ```bash diff --git a/docs/03-configure-and-query.md b/docs/03-configure-and-query.md index a5d3bae..56c27b7 100644 --- a/docs/03-configure-and-query.md +++ b/docs/03-configure-and-query.md @@ -51,6 +51,13 @@ This produces the following client parameters: Dotted fields become camel case: `subject.uri` becomes `subjectUri`. Every list method also supports `actor` (a DID or handle), `sort`, `order`, `limit`, `cursor`, and `profiles`. +A reference hydrates the current indexed target record identified by the URI in +`field`. If that field comes from a strongRef, Contrail does not retrieve the +historical record version named by the strongRef's CID. Lexicons also do not +usually identify a reference's target collection or desired inverse relation; +configure those semantics explicitly. Prefix initialization prompts for these +choices on a TTY and otherwise leaves them unconfigured. + ## Query from the client After changing the config, re-run `contrail connect` in your app. The generated Atcute client now knows the new parameters and response types: @@ -79,3 +86,18 @@ Every record has `uri`, `cid`, and its original record body in `value`. Hydrated Pass the returned opaque `cursor` into the same query to get the next page. `limit` defaults to 50 and may be 1–200. Full-text `search` works with D1 and PostgreSQL. The zero-config local SQLite AppView does not provide full-text search. + +## Lexicon source files + +Contrail resolves checked-in Lexicon documents in this order: + +1. `lexicons/custom/` — application-owned schemas; +2. `lexicons/pinned/` — verified, CID-pinned schemas created by prefix + initialization; and +3. `lexicons/pulled/` — mutable schemas fetched by `contrail lexicons all`. + +The first document for an NSID wins. Remote pull generation does not request an +NSID already supplied by `custom` or `pinned`, and cleaning pulled output does +not replace either directory. Keep `lexicons/pinned.lock` with the pinned files; +it records the registry snapshot, verification state, source CID, authority, +and role of each imported document. diff --git a/packages/contrail/README.md b/packages/contrail/README.md index b58d992..115e13b 100644 --- a/packages/contrail/README.md +++ b/packages/contrail/README.md @@ -176,14 +176,24 @@ cd my-appview contrail dev ``` -Prefix initialization uses `https://lex.atmo.tools` by default. It requires a -stable, fully verified and indexed catalog snapshot, pins each root and -transitive dependency by CID under `lexicons/pinned/`, writes provenance to -`lexicons/pinned.lock`, and generates equality/range fields which are safe on -all supported databases. Use `--lexicon-api` for a different registry, -`--timeout` to change the 60-second readiness budget, or `--allow-partial` to -explicitly accept incomplete prefix discovery. Missing required dependencies -always fail. +The prefix is matched literally against source Lexicon NSIDs. Include a trailing +`.` to select a namespace boundary. `--namespace` is independent: it controls +the generated AppView XRPC method IDs and defaults to `com.example`. + +| Init option | Purpose | +|---|---| +| `--prefix ` | Import verified record Lexicons matching an NSID prefix | +| `--namespace ` | Set the generated AppView XRPC namespace | +| `--lexicon-api ` | Select a registry (default: `https://lex.atmo.tools`) | +| `--timeout ` | Set the readiness/dependency budget (default: `60`) | +| `--allow-partial` | Explicitly accept incomplete prefix discovery | +| `--no-interactive` | Leave ambiguous references unconfigured | + +Prefix initialization requires a stable, fully verified and indexed catalog +snapshot, pins each root and transitive dependency by CID under +`lexicons/pinned/`, writes provenance to `lexicons/pinned.lock`, and generates +equality/range fields which are safe on all supported databases. Missing +required dependencies always fail, including with `--allow-partial`. In an interactive terminal, reference-shaped fields can be connected to an imported target collection and optionally exposed as inverse relations. These