@oddington/cli 0.1.26 → 0.1.28

package/README.md

@@ -22,6 +22,11 @@ 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.
 
+Sign-in and session operations use `https://auth.oddington.ai`. Connection
+management, repository targets, local app repository context, Dropbox authorization,
+remote File-storage configuration and Routine deployment use `https://api.oddington.ai`. These addresses are fixed; workspace
+configuration and `ODDINGTON_OS_ORIGIN` do not override them.
+
 ## Local apps
 
 From anywhere inside the app’s Git worktree, run:
@@ -324,6 +329,33 @@ and other CLI output never reveal saved credentials.
 `ODDINGTON_CONNECTION_CREDENTIAL`. Only run trusted code, and do not print or
 retain that value.
 
+## Deploy and roll back routines
+
+From the installed routine's customer Git worktree, a signed-in workspace
+member can run:
+
+```sh
+os routine deploy invoice-import
+os routine rollback invoice-import
+```
+
+Deploy reads `routines/invoice-import/routine.json` and packages the exact
+eligible current source, including eligible uncommitted changes, plus frozen
+dependencies. The declaration must match every installed access grant. OS
+builds and checks definitions, then activates only a compatible ready version;
+a failure preserves the current active version. Deployment never invokes
+business code or creates installation authority.
+
+The command reports phases, bounded diagnostics, the opaque version, source
+summary, runtime profile/features and capability names. Closing the CLI stops
+inspection while accepted OS work continues. Repeat the identical command to
+resume its deployment; source uploads and accepted seals recover lost replies.
+Rollback selects the preceding compatible retained version on OS without a
+rebuild. Both commands accept only the routine name and `--json` output option;
+they accept no commit, module, image, command, credential or version selector.
+JSON returns product facts without progress prose and uses the same exit status
+as human output.
+
 ## Publish asks and digests
 
 A signed-in workspace member can publish an initial ask whose Questions have
@@ -382,31 +414,43 @@ login. For a manual run, a signed-in workspace member uses the installed
 routine's name. OS supplies only the connections declared by its installation:
 
 ```sh
-os routine run --workspace example --name invoice-import \
-  -- node routines/invoice-import/run.ts
+os routine run invoice-import --input input.json
+os routine run invoice-import --input - --json
 ```
 
-OS resolves the active deployment, supplies temporary routine authority to the
-child, and revokes it when the process exits. A record read contains
-one authoritative commit and selected
-`{ ref, version, fields }` records in requested order. Keep versions opaque and
-save them with the reviewed records. A local checkout cannot supply this evidence.
+OS matches the current Git worktree to exactly one authenticated installed
+workspace/routine and resolves `routines/invoice-import/run.ts`. The entry exports
+an inert `defineRoutine` definition from `@oddington/sdk`. No handler deployment
+is required unless an authored item declares executable handlers. JSON input
+is validated before business work; its file/stdin path is transport, not input.
+Omitted input is `{}`. Each JSON value is bounded to 256 KiB.
 
-To inspect the same routine's work before publication, use `prepare`:
+Before execution, the command names installed connections and explains that
+local filesystem changes, model calls and provider effects happen immediately.
+Only Record, File, Ask and Digest changes stay local for review. The child
+receives temporary installed authority, which is revoked when execution ends.
+Success reports concrete nonzero counts and the stable Run reference:
 
 ```sh
-os routine prepare --workspace example --name invoice-import \
-  -- node routines/invoice-import/run.ts
 os routine publish
-os routine publish --run <prepared-run>
+os routine publish <run>
+os routine publish <run> --json
 ```
 
-The SDK calls stay the same. Declared records appear in the matched checkout;
-exact files, captured receipts and authored items stay in a private sealed run
-under the Git directory. The command prints its inspection location and run
-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`.
+Declared records appear in the matched checkout; exact files, captured receipts,
+source/input and authored items stay in the private Run directory
+`.git/oddington-prepared/<run>` (under the worktree's actual Git directory).
+`execution.json` retains steps, optional result, redacted child output and known
+effect evidence. `complete.json` seals successful intent. Inspect these files and
+the bounded Git diff, then publish from the original root. Bare publish lists
+ready references and refuses ambiguity. A failed or cancelled Run cannot publish;
+earlier local/provider effects remain real. A successful Run with no OS changes
+retains its evidence and says “Nothing needs to be sent to OS.”
+
+`--json` emits one value on stdout; notices use stderr and child logs stay in
+Run evidence. Run output includes `runId`, `state`, `placement`, `changes`,
+`counts`, optional declared `result`, and `directory`. Publish output includes
+the same Run reference, change state, confirmed receipts, Files, items and links.
 
 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
@@ -418,15 +462,26 @@ 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
+`unavailable`, and a dead parent has no hosted fallback. Authentication and named
 provider connections retain their normal network and authority requirements;
-preparation does not promise offline execution and may contact OS or providers.
-Execution location and File storage are independent of this publication choice.
-`os routine run --local` remains a deprecated compatibility alias for
-`os routine prepare` and prints the replacement command.
+local execution may contact OS or providers.
+
+Local execution requires native Node TypeScript stripping, a module
+`routines/package.json`, a matching `engines.node`, and an installed SDK.
+Before inspection, OS pins reachable ESM/CommonJS modules, runtime packages,
+governing package metadata and literal `new URL` assets, up to 20,000 files /
+256 MiB. Unrelated routines, historical output, unused dependencies, caches and
+logs are excluded. Reachable symlinks, native addons, computed loaders/assets
+and unsupported exports refuse; execution never uses changing checkout code.
+No dependency installation or package script runs. Run state is bounded to
+64 MiB; reports and redacted output each retain at most 10 MiB. Launcher ownership
+renews every 20 seconds with a 90-second lease; execution retains the existing
+15-minute capability bound.
+
+`routine prepare`, `run --local`, executable/argv selection, routine workspace,
+name and working-root flags, and publish `--run` are retired. Remote execution,
+deployment and schedules are unavailable in this release. `os run --connection`
+remains the separate ad hoc command; app children still publish immediately.
 
 `changes.delete(record)` captures the selected `$ref` and `$version`. A mixed
 create/update/delete group prepares one guarded proposal; validation creates no
@@ -434,7 +489,7 @@ proposal or materialization. Local publication removes only declared Records,
 returns their captured identities in `deleted`, and advances subsequent run
 reads to the exact prepared version. Files and durable Source uses remain
 retained. Deleted paths are sealed as absent: recreating one before
-`os routine publish --run <prepared-run>` invalidates publication before effects.
+`os routine publish <run>` invalidates publication before effects.
 Later publication rechecks the complete group at its captured base, applies one
 exact commit and waits for its exact hosted index. Interrupted Git or index
 acknowledgements resume that same proposal and preserve the inspected identities.
@@ -442,7 +497,7 @@ acknowledgements resume that same proposal and preserve the inspected identities
 Publication checks the whole run before effects, applies exact record history,
 retains files, then publishes Asks and Digests. It preserves unrelated local
 work. Changed prepared bytes, authority or unrelated remote movement require
-repair and a new preparation; publication never rebases inspected work.
+repair and a new Run; publication never rebases inspected work.
 After interruption, repeat the same publish command with unchanged content.
 `publication.json` journals attempted operations and confirmed receipts
 separately from sealed intent. Fresh launches recover original commit, file and
@@ -489,8 +544,9 @@ or attach anything. CSV parsing hints (`csv.encoding`, `csv.delimiter`,
 `csv.headerRow`) are optional. OS derives the row count, size, digest, media type
 and verified PDF pages. Unsupported files remain preserved and downloadable.
 
-Set `workingRoot` in the SDK, `--working-root` on the file command or routine
-launcher, or `ODDINGTON_INBOX_WORKING_ROOT`. The default is the current directory:
+Member-authored files may use `workingRoot` in the SDK, `--working-root` on the
+file command, or `ODDINGTON_INBOX_WORKING_ROOT`. Named routine Runs receive
+their resolved worktree root from OS. The file command defaults to the current directory:
 
 ```sh
 os files add --workspace <workspace> --working-root <local-root> --path <relative-file-path> --json
@@ -505,6 +561,31 @@ an item containing them.
 Resolution is an explicit guarded business outcome from a handler or the
 original publishing routine.
 
+Delete an unused shared File as its signed-in creator:
+
+```sh
+os files delete --workspace <workspace> --id <file-id> --yes --json
+```
+
+`--yes` explicitly confirms removal of the original and every retained
+enrichment. Without confirmation the command refuses before authentication or
+deletion work. A Source or another independent use conflicts without changing
+the File; delete that use through its owning capability first. Read access does
+not allow deleting another member's or an installed routine's File.
+
+The command uses the published SDK and the CLI member session. Configured
+`ODDINGTON_FILES_ROOT` selects the existing managed local owner, including
+uploaded-cache cleanup. Success means physical cleanup and durable completion;
+repeating a completed command succeeds. Temporary failures remain retryable,
+and a pending File stays inaccessible. R2 cleanup removes only the exact pinned
+registered object and confirms absence; a changed identity fails with integrity.
+Human output names the workspace and File ID. JSON success is one document:
+`{"workspace":"playground","id":"<file-id>","status":"deleted"}`.
+Failures exit nonzero with the bounded Files error category.
+After interruption or a lost reply, repeat the same confirmed command and ID;
+do not create a replacement File to recover deletion. A completed retry needs
+no provider connection, but still requires current creator authority.
+
 ## Package boundary
 
 `@oddington/cli` contains the `os` executable and depends on the compatible