@oddington/cli 0.1.37 → 0.1.39

package/README.md

@@ -45,80 +45,31 @@ From anywhere inside the app’s Git worktree, run:
 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
+Launch reads exactly `apps/<name>/app.json`, resolves one member workspace from
+the worktree's stable source identity, 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:
+The declaration contains only stable app scope. 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
-          }
-        }
-      ]
-    }
-  }
+  "routines": ["reconcile-records"]
 }
 ```
 
-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.
+Definitions are discovered by exported ID in confined `routines/*/routine.ts`,
+independently of directory names. `os app build <name>` and launch use the same
+preparation, generate the ignored `.os/app.d.ts` and `app-descriptor.json` pair,
+then build fixed `dist/index.html`. Types infer input/defaults, result and step
+detail from the definition. Browser assets embed only the safe structural
+descriptor, never access declarations, source imports or live availability.
+Unsupported input or invalid generation fails preparation without exposing a
+partial pair. An app without routine operations uses `"routines": []`.
 
 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;
@@ -140,44 +91,28 @@ The SDK retries renewal independently of Data reads. Confirmed renewal denial an
 shutdown end 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` inside this
-worktree. Modern routines also require their private ESM package manifest,
-the shared frozen Bun workspace lock, Bun 1.3.14, compatible Node, the exact
-root authoring SDK 0.1.17 and the selected installed runtime graph. Launch uses
-the same OS-owned executable-unit builder as deployment. Legacy routines keep
-their existing module-root, Node TypeScript stripping and SDK requirements
-until a selected manifest explicitly cuts them over. 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 a local browser Files adapter remain unsupported. Local
-Data uses the exact published index; warm reads make no synchronous hosted or
-CLI-store calls and neither initiate nor await browser-session renewal.
-
-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. Successful credential rotation preserves admitted Data and routine
-work and the same bounded run ownership. Other tabs confirm and adopt the stored
-winner silently; an old credential cannot start new requests or erase that
-winner. `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.
+Launch supplies authenticated context and unchanged interface assets.
+`app.listRoutines()` preserves declaration order, including unavailable entries.
+`app.routines[id].describe()` combines structural metadata with current readiness
+and read-only connection availability; starts recheck current source and complete
+authority. Defaulted `run()` and authorized OS File descriptors use the same
+local runner as CLI. There is no app-specific child lifecycle.
+
+Run handles expose `current()`, connected `watch()`, retained `step(id)` and
+explicit `publish()`. Successful local execution reports `not_needed`, `ready`,
+`published` or publication `failed`; it never publishes automatically. Publication
+uses the existing guarded publisher and preserves confirmed receipts. Routine
+`runs.list()` returns at most 20 recent summaries; `runs.get(id)` opens retained
+facts under newly checked authority. Older Runs are not pruned. History and step
+detail survive refresh; interrupted execution has no restart recovery.
+
+The host owns live work across refresh and tab closure. Credential renewal
+preserves the logical session; replaced contexts invalidate old handles. Host
+stop, sign-out, expiry or authority loss ends active work. At most four starts
+occupy authorization/execution/cleanup slots. No browser command, path, workspace,
+connection setting, replay cursor or cancellation API is exposed. Local Data
+continues to use its exact published index. Browser File creation remains a
+separate unsupported local adapter; existing authorized Files may be Run input.
 
 ## Connections