@elaraai/e3-cloud-codex-plugin 0.0.0-stage → 1.0.90-alpha.0

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@elaraai/e3-cloud-codex-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.90-alpha.0",
+  "description": "e3 cloud - apps for hosted e3 workspaces with @elaraai/e3-cloud-ui, the e3-cloud CLI and @elaraai/e3-cloud-client: skills, example search and the search-first hooks",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "author": {
+    "name": "Elara AI",
+    "email": "support@elara.ai",
+    "url": "https://elaraai.com"
+  },
+  "homepage": "https://github.com/elaraai/plugins",
+  "keywords": [
+    "e3",
+    "e3-cloud",
+    "east",
+    "elara",
+    "apps",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    ".codex-plugin",
+    ".build",
+    "hooks",
+    "skills",
+    ".mcp.json",
+    "index.json"
+  ]
+}

package/skills/e3-cloud-cli/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: e3-cloud-cli
+description: "The e3-cloud CLI — run an e3 cloud deployment from the shell. Use when: (1) Signing in (`e3 auth login` to a server, whose credentials e3-cloud shares) and checking who you are (`e3-cloud whoami`), (2) Building and deploying apps — `e3-cloud app build`, `app deploy` (UI-only, or with its package, `--dry-run`, several together, `--from-source`), `app list`, `app versions`, `app remove` (an app is developed in the cloud: deployed to a workspace of one's own and opened there), (3) Staging an app for the platform's next e3 (`app deploy --for-platform VERSION`, `app list-all`), (4) Staging and releases — `e3-cloud staging add|stop|list` (a staging protects the workspace it releases to: it then changes only by a release from it, or a rollback; `--force` on `app deploy` and `app remove` is an admin's override), `e3 workspace copy` for the rehearsal, `e3-cloud release URL FROM TO` with `--plan`, `--carry` and `--remove-apps`,… See the detailed scope below."
+---
+
+## Detailed skill scope
+
+The e3-cloud CLI — run an e3 cloud deployment from the shell. Use when: (1) Signing in (`e3 auth login` to a server, whose credentials e3-cloud shares) and checking who you are (`e3-cloud whoami`), (2) Building and deploying apps — `e3-cloud app build`, `app deploy` (UI-only, or with its package, `--dry-run`, several together, `--from-source`), `app list`, `app versions`, `app remove` (an app is developed in the cloud: deployed to a workspace of one's own and opened there), (3) Staging an app for the platform's next e3 (`app deploy --for-platform VERSION`, `app list-all`), (4) Staging and releases — `e3-cloud staging add|stop|list` (a staging protects the workspace it releases to: it then changes only by a release from it, or a rollback; `--force` on `app deploy` and `app remove` is an admin's override), `e3 workspace copy` for the rehearsal, `e3-cloud release URL FROM TO` with `--plan`, `--carry` and `--remove-apps`, `e3-cloud history`, `e3-cloud rollback`, (5) A repository's people and business roles — `e3-cloud user list|add|remove` (`--role owner`, or a user with `--roles 'Rostering,Finance'`), `e3-cloud role list|show|set|rm` (`--grant WORKSPACE/APP[:page,page]`), and for admins `user list-all|disable|enable|invitations|uninvite`, (6) Secrets (`e3-cloud secrets set|list|rm`), schedules (`schedule set|get|list|remove`), each task's compute size and timeout (`compute`, `timeout`), people's workspace settings (`settings`), (7) Records' history, rollback and backups (`e3-cloud records …`) and feedback (`e3-cloud feedback …`).
+
+# e3-cloud — the e3 cloud CLI (@elaraai/e3-cloud-cli)
+
+`e3-cloud` runs the parts of an e3 cloud deployment that e3's own CLI does not:
+apps, releases, users and roles, secrets, schedules, task configs, records'
+history and backups, and feedback. e3's CLI (`e3`, `@elaraai/e3-cli`) still
+does what it does against any server: repositories, packages, workspaces,
+datasets, dataflow runs and copies. Both sign in with `e3 auth login` and share its
+credentials (`~/.e3/credentials.json`).
+
+A command names what it acts on by URL: a server (`https://e3.example.com`),
+a repository (`…/repos/acme`), or a workspace (`…/repos/acme/workspaces/production`),
+as its help says.
+
+## Before writing code — search the example index
+
+Every command has an entry in the plugin's index, with the client calls and
+the app library's. Before scripting a deployment or answering how a command
+works:
+
+1. Call `search_e3_cloud_examples` with what
+   you are about to do (`release staging to production`, `give a user a role`).
+   Summaries come back first.
+2. Fetch the one or two that match with
+   `get_e3_cloud_example`.
+3. Do not read `node_modules/@elaraai/**` instead: the index holds the same
+   commands, exact and far cheaper, and `e3-cloud <command> --help` the rest.
+
+Nothing is injected for you; the search is the step.
+
+## Quick Start
+
+```bash
+npm install -g @elaraai/e3-cloud-cli @elaraai/e3-cli
+e3 auth login https://e3.example.com
+e3-cloud whoami https://e3.example.com
+
+# An app: build its bundle, check it, deploy it
+e3-cloud app build src/apps/ops.tsx
+e3-cloud app deploy https://e3.example.com/repos/acme staging dist/ops.app --dry-run
+e3-cloud app deploy https://e3.example.com/repos/acme staging dist/ops.app
+
+# Staging: a copy of production where changes are tried; production is protected from then on
+e3-cloud staging add https://e3.example.com/repos/acme production staging
+
+# A release: the plan first, then exactly what staging runs, production's data kept
+e3-cloud release https://e3.example.com/repos/acme staging production --plan
+e3-cloud release https://e3.example.com/repos/acme staging production
+```
+
+## Apps
+
+- `app build <source>` writes the bundle (`dist/<app>.app`): the app and the
+  package it was built against. A refusal names each problem.
+- `app deploy <repo-url> <workspace> [bundles…]` imports the bundle's package
+  when the repository lacks it, checks every app against it, and deploys: at
+  once when the workspace runs that package (UI only); else the package deploys
+  first, keeping the inputs people set, and the apps go live as it completes
+  (the CLI waits). `--dry-run` checks and changes nothing; `--from-source`
+  builds sources instead of bundles; several apps deploy together or not at all.
+- An app is developed in the cloud, not locally: deploy it to a workspace
+  of your own (`--from-source` after each change, `--dry-run` to check
+  only) and open it in the console. Develop against a staging, never the
+  protected workspace it releases to.
+- `app deploy` and `app remove` to a protected workspace are refused, naming
+  its staging; an admin alone forces one with `--force`, which warns first and
+  which the workspace's history records as forced.
+- `app deploy … --for-platform <version>` stages a bundle built with the
+  platform's next e3; `app list-all` (admins) lists every app and which needs
+  one.
+
+## Staging
+
+A workspace's staging is where changes are tried before they reach the
+workspace people use, which it then **protects**, as a protected branch is
+protected: its package and apps change only by a release from its staging, or
+a rollback. One staging to a workspace; no staging has one of its own.
+
+- `staging add <repo-url> <live> <name>` prints what it would do, then adds it:
+  a copy of the live workspace as it is now, data included. `--plan` stops at
+  the plan; a workspace of the name is used `--as-is`, or replaced whole only
+  with `--replace`.
+- `staging list <repo-url>` names each staging and what it protects;
+  `staging stop <repo-url> <live>` (admins alone) unprotects it, deleting
+  nothing.
+- A protected workspace refuses e3's `workspace deploy`, an app deploy or
+  removal, a copy onto it, and its removal or its staging's. Its data goes on:
+  inputs, records, runs and schedules.
+
+## Releases
+
+A release gives the target exactly the package and app versions the source
+runs, by hash, with the bundles it has staged for the next e3. Only the
+target's staging releases to it. The target keeps the inputs people set in it,
+migrates its records, and runs next by hand or on its schedule. Owners and
+admins release.
+
+- `e3 workspace copy <repo-url> production staging` makes staging production
+  as it is now, apps included: the rehearsal's first step before each change.
+- `release <repo-url> <from> <to>` prints the plan first, then releases;
+  `--plan` stops at the plan. A refused plan prints why and exits 1, changing
+  nothing; one that would change nothing is refused. The plan names any change
+  an admin forced onto the target since its last release, which it undoes. `--carry <path…>` copies inputs, and records new in the release,
+  from the source by reference; `--remove-apps` removes the target's apps the
+  source lacks.
+- `history <repo-url> <workspace>` lists each release, deploy, app deploy,
+  copy and rollback, with its id; `rollback <repo-url> <workspace> [<id>]`
+  releases an entry again, its package and apps exactly.
+
+## Traps
+
+- A release deploys the source's package by its version: re-importing a
+  package under the same version since the source deployed it refuses the
+  release (deploy the source again).
+- A rollback past a record migration is refused: e3's deploy never migrates a
+  record back. A rollback stays open on a protected workspace.
+- Sign in with `e3 auth login <server>`: there is no `e3 login`.
+- `secrets set` reads the value from stdin unless `--value` is given; the
+  next run reads the new value.
+- The version is the @elaraai lockstep: use the CLI of the release your
+  deployment runs.

package/skills/e3-cloud-client/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: e3-cloud-client
+description: "@elaraai/e3-cloud-client — drive an e3 cloud deployment from TypeScript. Use when: (1) Calling a deployment from code with a token (`whoami`, `RequestOptions`, `ApiError`), (2) Managing a repository's people and business roles (`repoUsers`, `addUser`, `removeUser`, `repoInvitations`, `listRoles`, `putRole`, `myAccess`), (3) Deploying apps from code — `appUpload`, `appDeploy` / `appsDeploy` and `appDeployWait`, `appList`, `appGet`, `appVersions`, `appRemove` — and reading a refusal (`appProblemsText`), (4) Staging, releasing and rolling back — `addStaging` / `stopStaging` (a staging protects the workspace it releases to), `releaseWorkspace`, `rollbackWorkspace` (a plan first, `releasePlanRefusalLines`), `workspaceHistory`, `getRepositoryReleaseSettings`, (5) Secrets, schedules and task configs (`putSecret`, `listSecrets`, `setSchedule`, `setCompute`, `setTimeout`), (6) Records' history and backups (`recordAudit`, `createRecordBackup`, `restoreRecordBackup`) and feedback (`listFeedback`, `closeFeedback`)."
+---
+
+# @elaraai/e3-cloud-client
+
+The e3 cloud API's client: every call takes the deployment's origin
+(`https://e3.example.com`) and request options holding a token, and
+throws `ApiError` on a refusal, its `code` naming it. Values are East values in
+BEAST2 on the wire, typed by `@elaraai/e3-cloud-types`, so a role or a
+response is a variant (`variant('owner', null)`, `response.type`). e3's own
+routes (repositories, packages, workspaces, datasets, runs) are
+`@elaraai/e3-api-client`'s.
+
+## Before writing code — search the example index
+
+Every call has an entry in the plugin's index. Before writing code against a
+deployment:
+
+1. Call `search_e3_cloud_examples` with what
+   you are about to do (`deploy an app from code`, `release with a plan`).
+   Summaries come back first.
+2. Fetch the one or two that match with
+   `get_e3_cloud_example` and pattern your code
+   on them.
+3. Do not read `node_modules/@elaraai/**` or reason from `.d.ts` signatures:
+   the index holds the same calls, exact and far cheaper.
+
+Nothing is injected for you; the search is the step.
+
+## Quick Start
+
+```typescript
+import { variant } from '@elaraai/east';
+import { ApiError, addUser, whoami } from '@elaraai/e3-cloud-client';
+
+const url = 'https://e3.example.com';
+const options = { token: process.env.E3_TOKEN! };
+
+const me = await whoami(url, options);
+try {
+  await addUser(url, 'acme', { email: 'ada@example.com', role: variant('user', { roles: ['All apps'] }) }, options);
+} catch (err) {
+  if (err instanceof ApiError) console.error(err.code);   // forbidden, not_found, …
+  else throw err;
+}
+```
+
+## Apps and releases
+
+- An app deploy uploads the app object (`appUpload`, with
+  `@elaraai/e3-cloud-ui`'s `encodeAppObject`), then deploys it
+  (`appDeploy`). It answers `refused` with every problem, `checked` for a dry
+  run, `live`, `staged`, or `deploying` naming the deploy job its package runs
+  in, which `appDeployWait` waits for.
+- A staging (`addStaging(url, repo, live, { name, start, plan })`, `start`
+  `variant('copy', null)` or `variant('as_is', null)`) protects the workspace
+  it releases to: its package and apps then change only by a release from it,
+  or a rollback; an app deploy or removal there throws `workspace_protected`
+  unless an admin passes `force`. `stopStaging` (admins) lifts it.
+- A release (`releaseWorkspace(url, repo, target, { from, carry, removeApps, plan })`,
+  `from` the target's staging) answers `planned`, `refused` (its problems and
+  checks in the plan, `nothing_to_release` among them), `released` (its apps
+  switched) or `releasing` (the job `appDeployWait` waits for). Ask for the
+  plan first and show it; `releasePlanRefusalLines` says why a plan refuses,
+  and its `undoes` lists forced changes it undoes. `rollbackWorkspace` takes
+  an entry of `workspaceHistory`.
+
+## Traps
+
+- The URL is the deployment's origin, not `…/api`: the client adds the path.
+- A refusal of a release or an app deploy is an answer (`refused`), not a
+  throw; a request the server cannot take at all throws `ApiError`.
+- The version is the @elaraai lockstep: use the client of the release the
+  deployment runs.

package/skills/e3-cloud-ui/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: e3-cloud-ui
+description: "Apps for e3 cloud — a solution's pages and menu, deployed to a workspace apart from its package and drawn natively by the e3-cloud web app. Use when: (1) Writing an app's pages with Page(name, meta, thunk) — the thunk returning the body, an East.function returning UIComponentType whose one argument is the page's params — or Page.task(name, uiTask, meta) for a ui() task's output, (2) Linking pages with PageLink (to, params) and Nav.go / Nav.back, (3) Declaring the sidebar with Menu.group and the app with App(name, { package, title, logo, home, menu, pages }), (4) Building the bundle an app deploy uploads with buildApp / exportApp, and reading a refusal (AppBuildError) or a deploy's problems, (5) Checking an app against a package with checkApp (@elaraai/e3-cloud-ui/check), (6) Reading an app's East types (AppType, PageType, AppBundleType — @elaraai/e3-cloud-ui/types), (7) Deploying with the e3-cloud CLI: app build, app deploy (UI-only, or with its package), app list / versions / remove."
+---
+
+# e3-cloud-ui — apps for e3 cloud
+
+An **app** is a solution's pages and menu. It is deployed to one workspace of a
+hosted e3, apart from the package, and the e3-cloud web app draws it natively:
+each app is a sidebar section, each page a URL, its crumbs its parents. Apps
+share a workspace's data, functions and records; staging and production each
+have their own.
+
+Read `README.md` for the author's guide; this file is the short form.
+
+## Before writing code — search the example index
+
+Every e3 cloud API has an example in the plugin's index: the page bodies of
+`@elaraai/e3-cloud-ui`, and the hand-written entries for `App`, `Page`,
+`Page.task`, `Menu`, `buildApp` and `checkApp`. A page's body is East and
+e3-ui code, whose examples are the East plugin's. Before writing or changing
+an app:
+
+1. Call `search_e3_cloud_examples` for the
+   part of the app you are about to write. Summaries come back first: id,
+   description and keywords, a few hundred bytes each.
+2. Fetch the one or two that match with
+   `get_e3_cloud_example` and pattern your code
+   on them.
+3. For what a body does with data and components (`Data.bind`, `Func.bind`,
+   `Record.bind`, east-ui's components), search East's index too, with the
+   East plugin's `search_east_examples` (package `e3-ui` or `east-ui`).
+4. Do not read `node_modules/@elaraai/**` or `*.examples.tsx` files
+   wholesale, and do not reason from `.d.ts` signatures: the index holds the
+   same code, exact and far cheaper.
+
+Nothing is injected for you; the search is the step.
+
+## Write a page
+
+```tsx
+import { East, NullType } from '@elaraai/east';
+import { Reactive, Stat, Slider, UIComponentType, VStack } from '@elaraai/east-ui';
+import { Data } from '@elaraai/e3-ui';
+import { App, Menu, Nav, Page, PageLink } from '@elaraai/e3-cloud-ui';
+
+const overview = Page('overview', { title: 'Overview', icon: 'gauge-high' },
+  () => East.function([], UIComponentType, _$ => (
+    <Reactive>{$ => {
+      const t = $.let(Data.bind(target));
+      return (
+        <VStack>
+          <Stat label="Target" value={East.print(t.read())} />
+          <Slider value={t.read()} onChangeEnd={t.write} />
+          <PageLink to={line} params={{ site: 'North', line: 'L4' }}>North L4</PageLink>
+        </VStack>
+      );
+    }}</Reactive>
+  )));
+```
+
+- The body is a **thunk**, `() => East.function(…)`: pages link both ways, so
+  bodies are built when the app builds.
+- The function's **one argument is the page's params** (or none). Never write
+  the type separately: TypeScript takes it from the function.
+- Bind data exactly as a `ui()` body does: `Data.bind`, `Data.bindPaged`,
+  `Func.bind`, `Record.bind`. Pass the defs, never names.
+- `meta.parent` makes the crumbs and lights the menu item.
+- Bind event handlers once: `const go = $.const(East.function([], NullType, $ => { $(Nav.go(line, key)); }))`.
+
+## Declare the app
+
+```ts
+export default App('ops', {
+  package: acme, title: 'Acme Operations', home: overview,
+  menu: [Menu.group('Analyse', [overview, lines])],
+  pages: [overview, lines, line],
+});
+```
+
+`home` and menu pages take no params. `pages` lists every page.
+
+## Build and deploy
+
+```
+e3-cloud app build src/apps/ops.tsx -o dist/ops.app
+e3-cloud app deploy <repo-url> <workspace> dist/ops.app [--dry-run]
+e3-cloud app deploy <repo-url> <workspace> --from-source src/apps/ops.tsx [--dry-run]
+```
+
+An app is developed in the cloud, not locally: deploy it to a workspace of
+your own (never a protected one: develop against its staging) and open it in
+the console. `--dry-run` checks it against the workspace's package and changes
+nothing; a deploy prints every problem when it is refused.
+
+`buildApp` refuses an app that doesn't fit its own package (`AppBuildError`,
+one line per problem). A deploy is UI-only when the workspace runs the bundle's
+package, else it deploys the package too; both are refused unless every app
+on the workspace fits.
+
+## Traps
+
+- A body written without the thunk can only link to pages defined above it.
+- A page that writes a task's output or a record through `Data.bind` is
+  refused: write inputs; change records through their mutations.
+- `Page.task` needs a task in the `ui` role (`ui()`), and its output shows only
+  after the workspace's next dataflow run.
+- The version is the @elaraai lockstep: use the same version as east and e3.