@openengio/cli 0.33.0 → 0.37.0

package/README.md

@@ -1,5 +1,32 @@
 # @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. The admitted actor classes are
+person (a `user` token), `agent:apply` (an apply run token), `app:client` (a `client` token) and
+service (a `service` token); `agent:explore` and `agent: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).
@@ -33,6 +60,8 @@ The installed package contains the bundled command and the skill. It carries no
 |---|---|---|
 | `openeng login [--no-open]` | binds a loopback listener, opens the browser at the sign-in address (or prints it with `--no-open`), redeems the returned code once and stores the session | one (`redeem`) |
 | `openeng logout` | refreshes first when the access token has expired, calls `logout`, deletes the stored session whatever the host answered | one, two with an expired token |
+| `openeng session status` | reads server-stored channel, mode and sign-in time | one |
+| `openeng session human` | confirms human mode once for this session | challenge, poll, retry; one when already human |
 | `openeng whoami` | prints the principal, host, store and expiry of the stored session, and the client's protocol version (`protocolVersion` under `--json`); never a token | none |
 | `openeng org list` | lists the organisations the signed-in person holds a live grant in; needs no attachment | one |
 | `openeng org attach <id>` | attaches the session to the organisation, and stores the access token the host answers with the organisation's identifier and name, beside the session and under the same host key; needs no attachment | one |
@@ -57,7 +86,12 @@ 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 reduced isolation warning for an app that holds the reduced isolation 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 update` | changes a rule's settings in place | one, plus step-up when needed |
 | `openeng rules list` | lists the selected project's or organisation's rules | one |
 | `openeng rules remove` | removes a rule by identifier | one |
 | `openeng org-refs create` | creates an organisation branch or baseline, optionally read-only | one |
@@ -71,10 +105,23 @@ The installed package contains the bundled command and the skill. It carries no
 | `openeng schema-update show` | reads the latest visible request, or no request | one |
 | `openeng skill [<topic> \| playbook <name>]` | prints the main skill and lists topics, or prints one bundled topic; needs no host and no session | none |
 
+Create the object first, then stage and save its attachment. Creation with a file is refused
+as `invalid-properties` with `attachment-requires-object` at each offending property.
+
 Attachments are top-level properties declared with kind `attachment`. Accepted file classes are
 `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 reduced isolation permission makes `publish` print the
+reduced isolation warning after the version line (the lead, a blank line, then the detail), and `--json` carries `oneWall` and `warning`
+beside the version. A publisher who may not read the organisation's reduced isolation 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
@@ -125,32 +172,48 @@ The boolean `--organisation` flag takes no value and uses the session's attached
 its calls have no selector. Both flags together, or neither, refuse before a host call (exit 2).
 The project forms are:
 
-- `openeng rules add --project <id> --pattern <pattern> --consequence <merge-only|locked-rows-only>`
-  prints the rule's identifier, pattern and consequence. Repeating the same content returns the
-  existing rule, including when the pattern differs only in letter case.
-- `openeng rules list --project <id>` prints each visible rule's identifier, pattern and
-  consequence, or `no rules` when there are none.
-- `openeng rules remove --project <id> --rule-id <id>` prints the removed rule's identifier.
-  An absent or unreadable identifier, or one from another project, answers `not-found`.
-
-Each command makes one host call, or two if the session first needs refreshing, and sends no
-idempotency key. Under `--json`, each success answers `{ scope, value }`: `scope` is the CLI's
-organisation and, for project forms, project; `value` holds the full rule for add, an array of rules for list, and
-`{ ruleId }` for remove. Organisation forms call `addOrganisationRule`, `listOrganisationRules`
-and `removeOrganisationRule` with the same inputs. Their full rule has `scope: "organisation"`
-and `projectId: null`; project rules keep `scope: "project"`. That scope stays inside `value`.
-Missing flags or a consequence other than the two spellings above refuse before any host call (exit 2).
-The host validates the pattern.
-
-A project rule's pattern is `main` or a branch or baseline under that project's identifier, exactly or ending
-in `/*` to match the prefix. A matching `merge-only` rule requires changes through a branch and
-merge. A `locked-rows-only` rule binds merge-only row locks while leaving unlocked rows direct.
-Adding or removing rules needs a person's `administer projects` capability on the selected
-project, or in the attached organisation for `--organisation`; both are audited. Listing needs
-`read`. Each command's `--help` has a capability line. A `not-permitted` refusal carries no
-capability; read that help line to find what the person needs. A change takes effect on the next
-request. A `protected` write refusal means to use the branch and review workflow.
-Agents must ask a person to manage rules.
+- `openeng rules add --project <id> --extent <ref|rows> --pattern <pattern> [settings]` adds a rule.
+- `openeng rules update --project <id> --rule-id <id> [settings]` changes settings in place.
+- `openeng rules list --project <id>` prints visible identifiers, patterns and consequences.
+- `openeng rules remove --project <id> --rule-id <id>` removes one rule by identifier.
+
+Both add and update take these settings flags:
+
+| flag | value |
+|---|---|
+| `--consequence` | `open`, `merge-only`, `locked-rows-only` |
+| `--require-proposal` | `true` or `false` |
+| `--required-approvals` | integer 0 to 10 |
+| `--approver-min-role` | `contributor`, `maintainer`, `owner` or `null` |
+| `--restrict-deletions` | `true` or `false`; true only for a project `ref` rule |
+| `--approvers` | JSON array of person identifiers; `[]` clears the list |
+| `--bypass` | JSON array of member objects; `[]` clears the list |
+
+Bypass objects use `kind: "role"` with `roleKey`, `kind: "person"` with `personId`,
+`kind: "service"` with `serviceIdentityId`, or `kind: "client"` with `clientId`.
+An add defaults omitted settings to merge-only, a proposal, one approval, minimum Maintainer,
+no named approvers, Owner/Maintainer bypass, and deletion restriction for project `ref` rules
+only. An update keeps omitted settings and replaces each supplied list. It cannot change pattern
+or extent. Every update, stronger or weaker, asks an agent-mode session for confirmation.
+
+A project `ref` pattern is `<project>/` and a glob; `rows` may also name `main`. Organisation rules
+use `ref` with `main` or a glob over one organisation ref. In a glob `*` stops at `/`, `**` is any
+characters, `/` included, `?` is one character other than `/`, and `[]` is a set with ranges and no
+negation: `^` and `!` are refused. `**` has no zero-directory form: `<project>/**/x` does not match `<project>/x`.
+Matching is case-insensitive, and a glob is at most 255 characters.
+A `rows` rule binds only its project's rows; `ref` binds every row on the matching ref.
+The host answers `invalid-rule-pattern`, `invalid-rule-setting` or `unknown-rule-member` when
+pattern, settings or membership do not fit. An absent or other owner's rule answers `not-found`.
+A repeated rule add returns the existing rule without changing it. Changing a rule’s consequence
+to one another rule on that pattern already has is refused `duplicate-rule`; the rule stays unchanged.
+
+Commands make one host call, plus refresh or step-up calls when needed, and send no idempotency
+key. Under `--json`, success answers `{ scope, value }`, with the full rule for add/update,
+an array of full rules for list, and `{ ruleId }` for remove. Organisation forms use
+`--organisation` and the corresponding organisation rule route; their rules have
+`scope: "organisation"` and `projectId: null` inside `value`.
+Changing rules needs a person's `administer projects` authority on the owner and writes an audit
+record with settings before and after. Listing needs `read`. Agents must ask a person to manage rules.
 
 ## Organisation branches and baselines, locks, agent ceilings and schema requests
 
@@ -212,7 +275,7 @@ Everyone with access to this project sees every document this Onshape account ca
 | `openeng connector create --system onshape --stack <stack> --name <text> [--company <id>] [--team <id> \| --owner <id>] [--label <text>]` | creates the connection, its mirror project and its service identity, then drafts the connector's types as a change set in the same request; `--name` names the mirror project; `--stack` is the Onshape stack label, the host-name label joined to the suffix, as in `cad`; `--team` or `--owner` limits the import to that team's or owner's documents, and with neither the company's documents are imported, and `--company` is then required and must be the company's own identifier, not a user's, or the command is refused (exit 2) before any call; `--team` with `--owner` is refused (exit 2) before any call. The answer says whether the types were drafted, and if not, which rule stopped it; the connection exists either way | `administer projects` and `administer service identities` in the organisation, which the `owner` role holds |
 | `openeng connector set-credential <connection>` | asks for the Onshape access key and secret key at a terminal prompt with nothing echoed, has the host check them against Onshape, and stores them; no flag or environment variable carries a key, and with no terminal it refuses before any call. Backspace deletes a character, a paste of both keys with a line ending between them fills both prompts, and Control-C or Control-D cancels with a refusal that says no keys were set. Setting it again replaces the stored credential. It prints the Onshape account the key belongs to and the time it was set | `administer projects` in the organisation |
 | `openeng connector draft-types <connection>` | drafts the connector's types as a change set for a person to review, or answers that they are already approved or that a change set is open; use it for a connection whose drafting failed at create, and after a connector update | `administer types` in the organisation, and read on the mirror project |
-| `openeng connector run <connection>` | starts an import run and prints its identifier once its row has committed; the run refuses while the connector's types are not approved | `merge` on the mirror project |
+| `openeng connector run <connection>` | starts an import run and prints its identifier once its row has committed; the run refuses while the connector's types are not approved | `write ref` on the mirror project |
 | `openeng connector runs <connection>` | lists the connection's runs, newest first: state, start and finish times, whether it was complete, the counts (created, updated, unchanged, withdrawn, carried, overwritten) and, for a failed run, its failure kind and fixed text | read on the mirror project |
 | `openeng connector revoke <connection>` | revokes the connection: its running runs end as failed and its service identity can no longer act | `administer projects` and `administer service identities` in the organisation |
 
@@ -227,7 +290,7 @@ Everyone with access to this project sees every document this Onshape account ca
    --change-set <id> --project <mirror project id>` and accepts it with `openeng types draft accept
    --change-set <id> --revision <token>`. The change set identifier is in `create`'s answer, or in
    `openeng types draft current`. Until it is accepted, a run refuses with `types-not-approved`.
-4. `openeng connector run <connection>`, by a person who holds `merge` on the mirror project.
+4. `openeng connector run <connection>`, by a person who holds `write ref` on the mirror project.
 5. `openeng connector runs <connection>` until the run's state is `succeeded` or `failed`.
 
 ### Owned records
@@ -347,12 +410,37 @@ for, built when the process starts from those entries (`OBJECTS_ROUTE_ENTRIES`,
 - **Calls.** One host call; two when the session had expired. A streamed command holds one
   connection.
 
+## Actions held to the person's confirmation
+
+The platform holds some actions (granting a role, inviting a person, merging, deleting a branch,
+registering an application and others) to the person's own confirmation. When a command meets one,
+`openeng` prints the address of the confirm page on the host's web application, to standard output
+(standard error under `--json`), and a line on standard error saying it is waiting. It then polls
+`readStepUpProof` under the person's own token every two seconds, for as long as the pending request
+lives, and when the person has confirmed it sends the command again once, with the proof and the same
+key. The proof is never printed. If nobody confirms before the time limit, it reports that the
+action was refused because nobody
+confirmed in time and exits 4, without sending the write again. Other proof-poll refusals keep their
+actual meaning; a transport failure remains a transport failure. A host with no web application
+answers the original challenge after a line explaining why no confirmation page can be offered.
+
+`openeng session status` asks the server for `{ channel, mode, issuedAt }`, even when no organisation
+is attached. Text output names the channel, mode and sign-in time. Local `whoami` stays an identity
+read and cannot establish the session's mode.
+
+A person at the terminal can run `openeng session human` to stop further challenges for the rest
+of that CLI session. It uses the same confirm-address, poll and single-retry road, then prints the
+server's stored state in the status format. Repeating it on an already-human session is a no-op.
+A new CLI sign-in starts in agent mode. An unknown session becomes CLI/agent on ordinary action
+confirmation; its next marked action asks again. Confirming human mode on an unknown session
+classifies it and enters human mode in that one approval. Neither command stores a local mode.
+
 ## Flags and environment
 
 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).
 
@@ -441,8 +529,10 @@ built for that host. Otherwise it says the host did not read this `openeng`'s pr
 the version it read, or `none`. The catalogue explanation also prints. Under `--json`, the refusal
 carries the host's key as `host` and this client's version as `clientVersion`. The host's `versions`
 are unchanged: `versions.client` is the version the host read, or null, and `versions.host` is the
-host's version. The text also prints `Update with: npm install -g @openengio/cli@latest`, and JSON adds
-`update: "npm install -g @openengio/cli@latest"`.
+host's version. When the host is newer, the text also prints `Update with: npm install -g @openengio/cli@latest`
+and names the version series that speaks the host's protocol (`0.<protocol>.x`). When the host is older, it says
+the host has not been updated yet and prints the command that installs the `openeng` built for the host's
+protocol (`npm install -g @openengio/cli@0.<protocol>`). JSON adds that command as `update`.
 
 | exit code | meaning |
 |---|---|