@openengio/cli 0.23.3 → 0.24.3

package/README.md

@@ -12,12 +12,6 @@ Install the public npm package:
 npm install -g @openengio/cli
 ```
 
-Upgrading from `@benjaminfh/oe2`: first run the earlier package's `logout` command, so its stored
-session does not stay on this machine; then uninstall it and install `@openengio/cli`. The command
-is now `openeng`, the environment variables are
-`OPENENG_HOST`, `OPENENG_SIGN_IN_ORIGIN` and `OPENENG_SESSION_STORE`, and you sign in again once
-with `openeng login`.
-
 `openeng` has no host built in. The production host is `https://api.openeng.io`. Pass `--host
 https://api.openeng.io` to a command, or set `OPENENG_HOST=https://api.openeng.io` once to make it the
 default. An agent starts with `openeng skill`, which prints how to work with the platform.
@@ -47,7 +41,7 @@ The installed package contains the bundled command and the skill. It carries no
 | `openeng org current` | prints the organisation the stored session is attached to, or none (`{ "organisation": null }` under `--json`); sends no request | none |
 | `openeng projects list` | lists the projects the signed-in person may list | one |
 | `openeng demo seed --project <id> [--size standard\|full]` | plays a generic open-cycle gas turbine plant into a project the person may list; `standard` is the default size, and a repeat completes what is left | one listing, one catalogue read, four to publish the types when they are not yet published, then one per object and edge |
-| `openeng link <explore\|branch-diff\|project> --project <id> --ref <ref>`, `openeng link <ontology\|change-set> --ref <ref>`, `openeng link <object\|type\|proposal\|app> <identifier> --project <id> --ref <ref>`, `openeng link app-page <appKey> <pageKey> --project <id> --ref <ref>`, `openeng link app-draft <appKey> --ref <ref>`, `openeng link organisation-page <page>` | prints the address of a page of the web application: the host's web origin joined to the page's path, built for the attached organisation; `--json` answers `{ link }`; a flag the page does not read is refused (exit 2) before any call, and so is a host with no web origin configured; `openeng link --help` prints every form | one (`readWebOrigin`) |
+| `openeng link <explore\|branch-diff\|project> --project <id> --ref <ref>`, `openeng link <ontology\|change-set> --ref <ref>`, `openeng link <object\|type\|proposal\|app> <identifier> --project <id> --ref <ref>`, `openeng link app-page <appKey> <pageKey> --project <id> --ref <ref>`, `openeng link app-draft <appKey> --ref <ref>`, `openeng link organisation-page <page>` | prints the address of a page of the web application: the host's web origin joined to the page's path, built for the attached organisation; `--json` answers `{ link }`; a flag the page does not read or a ref outside `main` and `<projectId>/<branch>` is refused (exit 2) before any call; a branch must match `--project` when given. The command reads the ref and the page's object, catalogue type, app page or proposal before printing, and refuses a missing subject with no address; a host with no web origin is refused too. `openeng link --help` prints every form | one `readWebOrigin`, plus a ref read for a branch or a project page on main, plus the subject read for object, type, app, app-page or proposal; the reads run in parallel |
 | `openeng types draft open` | opens a change set on the attached organisation's namespace | one |
 | `openeng projects create --name <text>` | creates a project in the organisation the session is attached to, under a minted idempotency key | one |
 | `openeng types list --project <id>` | lists the project's published types | one |
@@ -59,12 +53,101 @@ The installed package contains the bundled command and the skill. It carries no
 | `openeng types draft validate --change-set <id> --revision <token>` | the host's violations for that revision, printed with their count; exits 4 when there is one or more and 0 when there are none, so a script can gate `accept` on the exit code | one |
 | `openeng types draft discard --change-set <id>` | discards the change set | one |
 | `openeng types draft accept --change-set <id> --revision <token>` | publishes the change set's types at the revision the person reviewed, under a minted idempotency key | one |
+| `openeng rules add` | adds a project or organisation ref rule | one |
+| `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 ref, optionally read-only | one |
+| `openeng org-refs list` | lists visible organisation refs | one |
+| `openeng org-refs delete` | deletes a writable organisation ref | one |
+| `openeng org-refs mark-read-only` | marks an organisation ref read-only | one |
+| `openeng locks set` | sets or lifts an object's lock on a project ref | one |
+| `openeng ceiling show` | reads a project's maximum agent role | one |
+| `openeng ceiling set` | sets a project's maximum agent role | one |
+| `openeng schema-update request` | records a schema update request | one |
+| `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 |
 
 An object type's `subscriptionRoles` field declares which roles it admits: owner, approver or watcher.
 Owner is limited to one; approver and watcher may have optional maxima. Without the field, only
 watchers are admitted.
 
+## The rules commands
+
+These commands use the Admin SDK. Choose exactly one of `--project <id>` and `--organisation`.
+The boolean `--organisation` flag takes no value and uses the session's attached organisation;
+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 ref 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.
+
+## Organisation refs, locks, agent ceilings and schema requests
+
+All these commands need an attached organisation, make one host call (plus a refresh when needed),
+and send no idempotency key. Text output is described below; `--json` always returns `{ scope, value }`
+with the full route response in `value`, including null. A host refusal uses the standard explanation
+and next step. Changing rules, refs and locks is a person's action, never a way for an agent to bypass
+protection.
+
+Creating, deleting or marking organisation refs needs `administer projects` in the attached
+organisation. Setting a ceiling needs `administer projects` on the selected project; setting
+or lifting a lock needs `lock objects` there. Requesting a schema update needs `write ref` on
+a branch's home project, or `administer projects` for an organisation ref. Rule and organisation-ref
+lists and ceiling reads need `read`. Schema-update show reads only the caller's own requests in the
+token's organisation, without requiring project read access. Each command's `--help` names its requirement.
+A branch whose name contains `/` cannot request or show a schema update today.
+
+- `openeng org-refs create --name <name> [--read-only]` calls `createOrganisationRef` and prints
+  `ref <name>  read-only` or `ref <name>  writable`. It creates from the organisation's trunk head.
+  The name is one non-reserved ref segment, such as `release-v1`; without the flag it is writable.
+- `openeng org-refs list` calls `listOrganisationRefs` and prints each ref in that form, or `no refs`.
+- `openeng org-refs delete --name <name>` calls `deleteOrganisationRef` and prints `deleted ref <name>`.
+  A read-only ref cannot be deleted.
+- `openeng org-refs mark-read-only --name <name>` calls `markOrganisationRefReadOnly` and prints the
+  ref's name and read-only state. All four organisation-ref calls have no selector.
+- `openeng locks set --project <id> --ref <ref> --object <objectId> --lock <none|merge-only|frozen>`
+  calls the Objects client's `setObjectLock` with selector `{ projectId, ref }` and input
+  `{ objectId, lock }`. It prints `object <objectId>  lock <lock>`. `none` lifts the lock;
+  the lock also applies to the object's child edges.
+- `openeng ceiling show --project <id>` calls `readAgentCeiling` and prints `ceiling <role>`.
+- `openeng ceiling set --project <id> --ceiling <contributor|maintainer>` calls `setAgentCeiling`
+  and prints `ceiling <role>`. Both ceiling calls use a project selector.
+- `openeng schema-update request --ref <ref>` calls the Branches client's `requestSchemaUpdate`
+  and prints `schema update <ref>  <state>`. It records a request; execution is separate.
+- `openeng schema-update show --ref <ref>` calls `readSchemaUpdateRequest` and prints that same
+  form, or `no request` for null. Schema calls have no selector and act in the attached organisation.
+  The ref is a project branch or a bare organisation ref name; `main` is refused by the host.
+
+Missing required flags and unknown lock or ceiling spellings refuse before any call (exit 2).
+For an uncertain outcome, rules, organisation refs, ceiling and schema requests name a read-only
+command: list the rules or organisation refs, or show the ceiling or schema request. Inspect that
+answer before acting again. The lock command instead names the same idempotent `openeng locks set`
+command with the same arguments, which sets the same lock again.
+
 ## The connector commands
 
 A connection imports an Onshape account's documents into a mirror project of its own. Every
@@ -100,11 +183,12 @@ Everyone with access to this project sees every document this Onshape account ca
 4. `openeng connector run <connection>`, by a person who holds `merge` on the mirror project.
 5. `openeng connector runs <connection>` until the run's state is `succeeded` or `failed`.
 
-### The known gap
+### Owned records
 
-The next import sets back a person's change to a mirrored property and counts it `overwritten`.
-The next import also creates a deleted mirrored object again, with a new identifier, and counts it
-`created`; links people made to the old object are gone. Mirrored objects are therefore read-only in practice until write-back exists.
+The connected system alone writes records of its owned types. A person's write is refused as
+`owned`. People put their own information in separate rows and link those rows to the mirrored
+records. The importer counts updates to mirrored properties as `overwritten`. If a mirrored
+record is absent, the importer creates it with a new identifier and counts it as `created`.
 
 ## The attached organisation
 
@@ -126,8 +210,9 @@ reach; the stored organisation decides only what the CLI prints and whether it r
   then ` · project: <id>` when `--project` or the selector's `projectId` named one, and
   ` · ref: <ref>` when the selector named one. No host call finds them.
 - **`--json`.** The one value on standard output gains the same fields as `scope`:
-  `{ "organisation": { "id", "name" }, "project"?, "ref"? }`. An object value gains a `scope` key. A
+  `{ "organisation": { "id", "name" }, "project"?, "ref"? }`. An object value normally gains a `scope` key. A
   value that is an array or null is wrapped as `{ "scope": {...}, "value": <the original> }`. A
+  rules command's success always uses that wrapper to preserve the rule's own `scope` field. A
   failure the host did not answer carries no scope. A command with no scope has no `scope` field.
 - **The hint.** Every `not-found` the host answers to a gated command prints, after the refusal,
   "not found in organisation <name>: check that you are attached to the correct organisation (openeng org
@@ -218,8 +303,9 @@ for, built when the process starts from those entries (`OBJECTS_ROUTE_ENTRIES`,
 ## 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`, `--name`, `--change-set`,
-  `--revision`, `--from`, `--size`, `--idempotency-key`, `--rail-groups`, and, for
+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
 `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).