@oddington/cli 0.1.20 → 0.1.23

package/README.md

@@ -22,6 +22,129 @@ Run `os --help` or add `--help` to any command for the full command list.
 Commands print readable output by default. Add `--json` when another program
 will consume the result.
 
+## Local apps
+
+From anywhere inside the app’s Git worktree, run:
+
+```sh
+os app launch <name>
+```
+
+Launch reads exactly `apps/<name>/app.json`, checks current membership in its
+declared workspace, runs the colocated package’s fixed `npm run build`, and
+opens its confined public interface in your ordinary browser. Prepare the app’s
+documented dependencies separately; launch never installs them. Git, npm and
+the required Node version must be available. Missing declarations, dependencies,
+build output or membership stop launch with setup guidance.
+
+Each `routines` mapping must declare `routine`, `input`, and ordered public
+`steps`; `result` is optional. A mapping containing only `routine` is invalid.
+For example:
+
+```json
+{
+  "name": "accounting",
+  "workspace": "sample",
+  "interface": { "root": "dist/interface" },
+  "repositories": ["general"],
+  "routines": {
+    "reconcile": {
+      "routine": "reconcile-records",
+      "input": {
+        "type": "object",
+        "properties": {
+          "includeArchived": { "type": "boolean" },
+          "limit": { "type": "integer", "minimum": 1, "maximum": 100 }
+        },
+        "additionalProperties": false
+      },
+      "result": {
+        "type": "object",
+        "properties": { "processed": { "type": "integer" } },
+        "required": ["processed"],
+        "additionalProperties": false
+      },
+      "steps": [
+        { "id": "read" },
+        {
+          "id": "write",
+          "summary": {
+            "type": "object",
+            "properties": { "changed": { "type": "integer" } },
+            "required": ["changed"],
+            "additionalProperties": false
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+Contracts use a closed V0 value-schema grammar. Each schema has a `type` of
+`object`, `array`, `boolean`, `string`, `integer`, `number`, or `file`, with only
+the fields supported by that type. Objects declare `properties` and
+`additionalProperties: false`; optional `required` lists contain unique declared
+property names. Property names start with a lowercase letter and contain only
+letters and numbers. Arrays declare `items` and `maxItems` from 1 to 64. Strings
+may declare `maxLength` from 0 to 4,096 and otherwise have a 4,096-character limit.
+Numbers may declare inclusive `minimum` and `maximum`; numbers must be finite,
+and integers and their bounds must be safe integers. A `file` value is a complete
+shared File descriptor, never a bare ID or operating-system path.
+
+Schemas nest at most eight nodes deep, and an operation's input, result and step
+summaries share a budget of 64 object properties. Encoded input and result each
+fit within 16 KiB of UTF-8 JSON. Declare one to 64 ordered steps with unique
+lowercase letter or number IDs separated by single hyphens. Each step has only
+`id` and an optional `summary` schema. Omitting a summary or result schema permits
+no corresponding value. Values are not coerced, schemas have no defaults, and
+an optional property stays absent rather than accepting `null`.
+
+Declare a closed empty object for input with no properties; an app without
+routine operations may use `"routines": {}`. Unsupported schema or process-control
+fields stop launch before build or hosting. Validation grants no routine or File
+authority, and opening the interface does not require local routine code.
+
+The command prints the clean assigned IPv4 loopback URL and owns the host until
+Ctrl-C or termination. No root, workspace, command or port override is accepted;
+`os app run` is unsupported. Browser authority is separate, origin-scoped and
+bounded to ten minutes or the retained access session’s earlier expiry window.
+Local sign-out leaves CLI sign-in intact. Removing CLI storage alone leaves an
+established app session intact; every protected request still checks upstream
+identity and workspace access. Host shutdown ends it immediately. An opener
+failure stops the host without printing a bootstrap secret.
+
+Launch supplies authenticated context and unchanged interface assets. The SDK's
+typed `app.routines.<key>.availability()` assesses only a retained declared
+binding, without starting code or creating a run. It reports ordered public
+step IDs when available, or `authority_unavailable` / `execution_unavailable`
+without steps. Customer-owned module augmentation supplies the property types;
+it grants no authority.
+
+Local readiness requires the mapped `routines/<routine>/run.ts` and owning
+`routines/package.json` inside this worktree, Node native TypeScript stripping,
+`"type": "module"`, a satisfied npm `engines.node` range, and an installed
+`@oddington/sdk` that resolves without import. The assessment never imports
+routine code, runs package scripts, installs dependencies or accepts browser
+path/runtime overrides. Missing code still permits app launch. Availability
+is fresh assessment, not a reservation or guarantee of later execution.
+Hosted bindings report execution unavailable without local fallback.
+`app.routines.<key>.run(input)` starts only that mapped installed routine as a
+fixed Node child. Its private `appRun.current()` input is immutable; declared
+steps and finish await host acceptance. Success requires accepted finish and
+zero exit. Shared effects publish immediately, without a preparation selector.
+Supplied File inputs reject execution unavailable before capability issuance;
+File-use transfer and local Data/Files adapters remain unsupported.
+
+The host owns children across refresh and tab closure. Exact-origin browser
+state permits `recover()` without a run selector while the host/session remains
+authorized. `events()` reconnects in order; `cancel()` resolves after child
+termination and capability revocation. Host stop, local sign-out, expiry or
+authority loss ends active execution. At most four runs occupy authorization,
+execution or cleanup slots; event retention is bounded to 256 events / 1 MiB
+per run, with ten minutes of terminal grace and at most 16 terminal streams.
+Cancellation or later failure does not undo confirmed shared effects.
+
 ## Connections
 
 A connection gives a workspace controlled access to GitHub, Gmail, Airtable,
@@ -269,12 +392,19 @@ reference. Connections can still contact their providers. A failed child cannot
 publish. Inspect the files and bounded Git diff, then publish from the original
 root. With several ready runs, select one using `--run`.
 
-The SDK's `data.repository(name)` collection and selection calls also work in
+The SDK's `data.repository(name)` collection, selection and search calls also work in
 this mode, using only installed repository grants and the exact committed
 checkout version captured for the run. Dirty and untracked files are ignored;
 an OS cache outside the checkout reuses derived data without remote access.
-Accepted record effects advance later selections to their exact proposed
-version. A run that only reads or validates creates no prepared-run directory
+Accepted record effects advance later selections and searches to their exact
+proposed version. Validation and another publisher leave the captured view
+unchanged; replaying an older publication cannot rewind it. For example,
+`general.records.search('acme overdue', { collections: ['invoices'], limit: 20 })`
+returns bounded full Records with guards usable in Changes, or empty matches
+with the searched version. Missing/incomplete search data fails retryably with
+`unavailable`, and a dead parent has no hosted fallback. Ordinary immediate
+`os routine run` continues to deliver search through the hosted service.
+A run that only reads or validates creates no prepared-run directory
 and reports completion without a publish instruction. Authentication and named
 provider connections retain their normal network and authority requirements;
 preparation does not promise offline execution and may contact OS or providers.