@openengio/cli 0.33.0 → 0.36.0

package/README.md

@@ -1,5 +1,31 @@
 # @openengio/cli
 
+## Link review and impact
+
+`openeng links status <object> --project <id> --ref <ref>` prints the stable head, tracked
+links, review and bounds states, clearing attribution and aggregate bounds. Review is `cleared`,
+`suspect`, `unreviewed`, `not-visible` or `too-many-links`; a significant upstream change makes
+a cleared link suspect. Bounds independently answer `in`, `out`, `none`, `no-value`,
+`unit-mismatch` or `not-visible`. Aggregates carry coverage and hidden or missing counts.
+Numeric bounds include their units. Text output from `objects-sdk readObject` also shows
+property values with units, using one additional catalogue read; `--json` retains the wire result.
+
+`openeng links clear <link> --version <v> --project <id> --ref <ref>` clears after review.
+For 1 to 100 links, list the ids and repeat `--version` once per link in matching order, for
+example `openeng links clear <link1> <link2> --version <v1> --version <v2> --project <id>
+--ref <ref>`. Each opaque upstream version comes from status and is a precondition; the clear is
+atomic. `upstream-changed` requires reading and reviewing again; `upstream-not-readable` requires
+upstream read access. Clearing records the person and time and leaves bounds unchanged. The edge's
+write rule governs clearing, with no organisation setting. User, run-apply, client and service
+tokens are admitted; run-explore and run-types are refused at admission. There is no object-agent
+clearing tool. An unknown outcome exits 5; recover by correlation before repeating a clear.
+
+`openeng branches impact <ref> --base <base> --project <id>` prints review, bounds and aggregate
+changes against the merge base, plus downstream reach to depth three and hidden counts. Both heads
+are pinned. Added and removed states identify new and deleted links; `head-moved` and `over-bound`
+refuse without partial output. All three commands support `--json` for the complete answer and
+print refusals by name.
+
 `openeng` is the platform's command-line client. It signs a person in through the browser, stores the
 session, and calls the platform's host. It runs on Node 22 and has no argument-parser dependency
 (`node:util`'s `parseArgs` serves because every command takes the same few flags).
@@ -57,6 +83,10 @@ The installed package contains the bundled command and the skill. It carries no
 | `openeng attachment add <object> <property> <file> --project <id> --ref <ref>` | stages, saves and prints the descriptor | four |
 | `openeng attachment get <object> <property> [--out <path>] --project <id> --ref <ref>` | downloads and prints the written path | one |
 | `openeng attachment list <object> --project <id> --ref <ref>` | prints attachment properties and descriptors | two |
+| `openeng hosted-app publish <bundle> --project <id> --key <app key>` | publishes the bundle file as the next version of the project's hosted app under the key, creating the app when the project has none; prints the version, its SHA-256 and size, and the one-wall warning for an app that holds the one-wall permission | three to four |
+| `openeng hosted-app list --project <id>` | lists the project's hosted apps | one |
+| `openeng hosted-app versions <app key> --project <id>` | lists the app's versions, newest first | two |
+| `openeng hosted-app revoke <app key \| app id \| version id> --project <id>` | revokes one version (an argument starting `hav_`) or the whole app by its key or an `app_` id; the next call under any launch of it is refused | one for an id, or two for an app key |
 | `openeng rules add` | adds a project or organisation branch rule | one |
 | `openeng rules list` | lists the selected project's or organisation's rules | one |
 | `openeng rules remove` | removes a rule by identifier | one |
@@ -75,6 +105,15 @@ Attachments are top-level properties declared with kind `attachment`. Accepted f
 `image` (PNG, JPEG, WebP, GIF), `pdf`, `step` (STEP), `mesh` (STL) and `text` (plain text and the
 admitted text-file extensions). Each body is limited to 26,214,400 bytes (25 MiB).
 
+The hosted-app commands take `--project`, and `publish` also takes `--key`, an app key: lower-case
+letters, digits and hyphens, at most 63 characters. The parser refuses any other value (exit 2), so
+the flag cannot carry a token. `publish` reads the bundle file whole; the host bounds it at 4 MiB.
+A refused publish, such as one by a person who may not publish into the project, prints the host's
+refusal and exits 4. An app that holds the one-wall permission makes `publish` print the one-wall
+warning after the version line, and `--json` carries `oneWall` and `warning` beside the version. A publisher who may not read the
+organisation's one-wall permissions still publishes: the command adds one line saying this account
+cannot read whether the app may send data out of the browser, and `--json` carries `"oneWall": "unknown"`.
+
 All three attachment commands require explicit `--project` and `--ref` and an attached organisation.
 `add` uses the local file's basename, stages it, reads the object and catalogue, then saves; it prints
 the descriptor only after a succeeded save. `add` and `list` use the catalogue's latest version of
@@ -352,7 +391,7 @@ for, built when the process starts from those entries (`OBJECTS_ROUTE_ENTRIES`,
 Every command takes `--json`, which prints one JSON value on standard output in place of text.
 The flags a command reads, named in its usage above, are `--project`, `--pattern`, `--consequence`,
 `--rule-id`, `--name`, `--change-set`, `--revision`, `--from`, `--size`, `--idempotency-key`,
-`--rail-groups`, and, for
+`--rail-groups`, `--key` (for `openeng hosted-app publish`), and, for
 `openeng connector create`, `--system`, `--stack`, `--company`, `--team`, `--owner` and `--label`; a
 command that needs one it was not given refuses before any call (exit 2).