@elaraai/e3-cloud-cli 0.0.0-stage → 1.0.90

package/LICENSE.md

@@ -0,0 +1,54 @@
+# Business Source License 1.1
+
+Copyright (c) 2025 Elara AI Pty Ltd
+
+## License
+
+**Licensor:** Elara AI Pty Ltd
+
+**Licensed Work:** @elaraai/e3-cloud-cli
+
+**Change Date:** Four years from the date of each release
+
+**Change License:** AGPL-3.0
+
+## Terms
+
+The Licensed Work is provided under the terms of the Business Source License 1.1 as detailed below.
+
+### Grant of Rights
+
+The Licensor grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work.
+
+### Production Use Limitation
+
+**"Production Use"** means any use by or on behalf of a for-profit entity, other than for evaluation, testing, or development purposes.
+
+Production Use requires a separate commercial license from the Licensor.
+
+### Change Date
+
+On the Change Date (four years after each release), the Licensed Work will be made available under the Change License (AGPL-3.0).
+
+### No Warranty
+
+THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. THE LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
+### Package-Specific Licenses
+
+Individual packages within this repository may have different licensing terms. See the LICENSE.md file in each package directory for details.
+
+## Commercial Licensing
+
+To obtain a commercial license for Production Use, contact:
+
+**Email:** support@elara.ai
+**Website:** https://elaraai.com
+
+## Governing Law
+
+This license is governed by the laws of New South Wales, Australia.
+
+---
+
+*Elara AI Pty Ltd*

package/README.md

@@ -1,3 +1,434 @@
-# Temporary Holding Version
+# @elaraai/e3-cloud-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLI tool for e3 cloud management.
+
+## Installation
+
+```bash
+npm install -g @elaraai/e3-cloud-cli
+```
+
+The version is the @elaraai lockstep: use the CLI of the e3 release your
+deployment runs.
+
+## Usage
+
+### Prerequisites
+
+Login using the e3 CLI first (credentials are shared):
+
+```bash
+e3 auth login https://e3.example.com
+```
+
+### Commands
+
+#### Check current identity
+
+```bash
+# Use first stored credential
+e3-cloud whoami
+
+# Or specify server explicitly
+e3-cloud whoami https://e3.example.com
+```
+
+Output:
+```
+sub: abc123-def456
+email: alice@example.com
+name: Alice Smith
+admin: true
+```
+
+#### List repository users
+
+```bash
+e3-cloud user list https://e3.example.com/repos/my-repo
+```
+
+Output:
+```
+USER ID             EMAIL                         ROLE                            ADDED
+abc123-def456       alice@example.com             owner                           2025-01-29T10:00:00
+xyz789-uvw012       bob@example.com               user: Rostering, Finance        2025-01-30T14:30:00
+(not signed in)     dana@example.com              user: Rostering                 2025-01-31T09:15:00
+```
+
+People added who have not signed in yet are listed too: their roles are given at their first sign-in.
+
+#### Add a person to a repository, or change their role
+
+A repository has owners and users. A user holds business roles, each granting apps (every page of each, or some), and reaches only what those pages bind.
+
+```bash
+# Add a user holding business roles (the repository's, or the built-in 'All apps')
+e3-cloud user add https://e3.example.com/repos/my-repo charlie@example.com --roles 'Rostering,Finance'
+
+# A user holding no role yet
+e3-cloud user add https://e3.example.com/repos/my-repo charlie@example.com
+
+# Add as owner
+e3-cloud user add https://e3.example.com/repos/my-repo charlie@example.com --role owner
+```
+
+Someone who has never signed in can be added with roles: they are invited, and get the roles at their first sign-in. Adding them again changes the roles they will get.
+
+#### Business roles
+
+```bash
+# List a repository's roles, and what each grants (owner or admin)
+e3-cloud role list https://e3.example.com/repos/my-repo
+
+# Write a role whole: every page of an app (workspace/app), or some (workspace/app:page,page)
+e3-cloud role set https://e3.example.com/repos/my-repo Rostering --grant production/workforce:shifts,roster --grant production/reports
+
+# Show one, and remove one no one holds
+e3-cloud role show https://e3.example.com/repos/my-repo Rostering
+e3-cloud role rm https://e3.example.com/repos/my-repo Rostering
+```
+
+#### Remove a user from a repository
+
+```bash
+# Someone with access, or the invitation of someone not signed in yet
+e3-cloud user remove https://e3.example.com/repos/my-repo charlie@example.com
+```
+
+#### Set a workspace schedule
+
+```bash
+# Run daily at 2 AM, forcing specific tasks
+e3-cloud schedule set https://e3.example.com/repos/acme/workspaces/main \
+  --cron "0 2 * * *" \
+  --force-tasks "input-orders,load-products" \
+  --description "Nightly data refresh"
+
+# Force tasks matching a regex (resolves against deployed task list)
+e3-cloud schedule set https://e3.example.com/repos/acme/workspaces/main \
+  --cron "0 2 * * *" \
+  --force-regex "input.*" \
+  --description "Nightly data refresh"
+
+# Set with explicit timezone
+e3-cloud schedule set https://e3.example.com/repos/acme/workspaces/main \
+  --cron "0 14 * * 1-5" \
+  --force-tasks "load-orders" \
+  --timezone "America/New_York" \
+  --description "Weekday 2 PM ET refresh"
+
+# Disable without removing
+e3-cloud schedule set https://e3.example.com/repos/acme/workspaces/main \
+  --enabled false
+```
+
+#### View a workspace schedule
+
+```bash
+e3-cloud schedule get https://e3.example.com/repos/acme/workspaces/main
+```
+
+#### Remove a workspace schedule
+
+```bash
+e3-cloud schedule remove https://e3.example.com/repos/acme/workspaces/main
+```
+
+#### List all schedules for a repository
+
+```bash
+e3-cloud schedule list https://e3.example.com/repos/acme
+```
+
+#### Set compute size for a task
+
+```bash
+# Set a single task to the medium container size
+e3-cloud compute set https://e3.example.com/repos/acme/workspaces/main "my-task" --size medium
+
+# Set all tasks matching a regex pattern
+e3-cloud compute set https://e3.example.com/repos/acme/workspaces/main "load_.*" --size large --regex
+
+# Reset a task back to serverless
+e3-cloud compute set https://e3.example.com/repos/acme/workspaces/main "my-task" --size serverless
+```
+
+Valid sizes: `serverless` (default, a serverless function), `small` (2 vCPU / 8 GB), `medium` (4 vCPU / 16 GB), `large` (8 vCPU / 32 GB), `xlarge` (16 vCPU / 64 GB).
+
+#### View compute size for a task
+
+```bash
+e3-cloud compute get https://e3.example.com/repos/acme/workspaces/main "my-task"
+```
+
+#### List all compute configs for a workspace
+
+```bash
+e3-cloud compute list https://e3.example.com/repos/acme/workspaces/main
+```
+
+#### Remove compute config for a task
+
+```bash
+# Remove a single task config (reverts to serverless)
+e3-cloud compute remove https://e3.example.com/repos/acme/workspaces/main "my-task"
+
+# Remove by regex pattern
+e3-cloud compute remove https://e3.example.com/repos/acme/workspaces/main "load_.*" --regex
+```
+
+#### Set timeout for a task
+
+```bash
+# Set timeout in minutes
+e3-cloud timeout set https://e3.example.com/repos/acme/workspaces/main "my-task" --timeout 120
+
+# Set timeout in hours
+e3-cloud timeout set https://e3.example.com/repos/acme/workspaces/main "my-task" --timeout 2h
+
+# Set timeout in days
+e3-cloud timeout set https://e3.example.com/repos/acme/workspaces/main "my-task" --timeout 1d
+
+# Set timeout for multiple tasks by regex
+e3-cloud timeout set https://e3.example.com/repos/acme/workspaces/main "load_.*" --timeout 4h --regex
+```
+
+Valid range: 1 minute to 30 days (43200 minutes). Accepts: minutes (e.g., `120`), hours (e.g., `2h`), days (e.g., `1d`).
+
+#### View timeout for a task
+
+```bash
+e3-cloud timeout get https://e3.example.com/repos/acme/workspaces/main "my-task"
+```
+
+#### List all timeout configs for a workspace
+
+```bash
+e3-cloud timeout list https://e3.example.com/repos/acme/workspaces/main
+```
+
+#### Remove timeout config for a task
+
+```bash
+# Remove a single task timeout (reverts to default)
+e3-cloud timeout remove https://e3.example.com/repos/acme/workspaces/main "my-task"
+
+# Remove by regex pattern
+e3-cloud timeout remove https://e3.example.com/repos/acme/workspaces/main "load_.*" --regex
+```
+
+#### Manage repo secrets
+
+Per-repo credentials for tasks (SQL passwords, API keys). **Write-only**:
+values can be set and deleted but never read back — `list` shows names and
+modification times only. Task code reads them at runtime with
+`Env.get("NAME")` (east-node-std); only the NAME appears in East IR, and the
+platform injects the value into the runner's environment at execution time.
+Rotation takes effect on the next task run without invalidating caches.
+
+```bash
+# Set a secret — value from stdin (keeps it out of shell history) or --value
+printf %s "$PG_PASSWORD" | e3-cloud secrets set https://e3.example.com/repos/acme PG_PASSWORD
+
+# Names + last-modified only; values are never shown
+e3-cloud secrets list https://e3.example.com/repos/acme
+
+# Delete
+e3-cloud secrets rm https://e3.example.com/repos/acme PG_PASSWORD
+```
+
+Names must be uppercase env-var shaped (`[A-Z_][A-Z0-9_]*`); runtime/platform
+names (`PATH`, `LD_*`, `NODE_*`, `AWS_*`, `E3_*`, …) are reserved. `list` can
+lag a set/rm by a few seconds; task-time injection is not affected.
+
+#### Record history, rollback & backups
+
+Managing `e3.record` state, the system of record. The
+durable audit index records who/what/when for every committed mutation and
+**survives compaction and GC**; rollback/restore append audited
+`$rollback`/`$restore` commits (history is never rewritten; downstream tasks
+re-run; a keyed retry after a rollback is answered, not applied twice) and are
+refused, with the reason, past a migration or across a type change; a backup
+names the record's state, which the platform keeps while the backup exists —
+through compaction and garbage collection. Base mutations stay on the e3 CLI
+(`e3 mutate` / `e3 history` / `e3 compact` — compaction now takes an automatic
+safety backup first). Rollback, restore and backup management need the repo
+owner (or platform admin) role.
+
+```bash
+# Records in a workspace, with head commit + backup counts
+e3-cloud records list https://e3.example.com/repos/acme main
+
+# Durable audit, newest first (page with --before from the 'More:' line)
+e3-cloud records history https://e3.example.com/repos/acme main orders
+
+# Value at a version (East literal to stdout, the first 100 rows of a large
+# record; -o writes the whole value as beast2, downloaded by segments)
+e3-cloud records show https://e3.example.com/repos/acme main orders <commit>
+
+# Roll back to a historical commit (appends $rollback; confirmation prompt)
+e3-cloud records rollback https://e3.example.com/repos/acme main orders <commit>
+
+# Backups: take, list, restore, download the value (a beast2 file) for offline keeping, delete
+e3-cloud records backup    https://e3.example.com/repos/acme main orders --note "before cutover"
+e3-cloud records backups   https://e3.example.com/repos/acme main orders
+e3-cloud records restore   https://e3.example.com/repos/acme main orders <backupId>
+e3-cloud records backup-pull https://e3.example.com/repos/acme main orders <backupId> -o orders.beast2
+e3-cloud records backup-rm https://e3.example.com/repos/acme main orders <backupId>
+```
+
+#### Feedback
+
+Notes users send about a part of a workspace's pages, numbered `FB-<n>` per
+workspace. A note is named `12` or `FB-12`.
+
+```bash
+# Turn a workspace's feedback on or off (owner or admin); its notes are kept when off
+e3-cloud feedback enable https://e3.example.com/repos/my-repo/workspaces/main
+e3-cloud feedback disable https://e3.example.com/repos/my-repo/workspaces/main
+
+# The workspace's open notes, newest first, with its counts (owner or admin);
+# page with --cursor from the 'More:' line; --mine lists your own instead
+e3-cloud feedback list https://e3.example.com/repos/my-repo/workspaces/main
+e3-cloud feedback list https://e3.example.com/repos/my-repo/workspaces/main --status closed --limit 50
+e3-cloud feedback list https://e3.example.com/repos/my-repo/workspaces/main --mine
+
+# One note whole: who sent it when, the page, the part, the datasets behind the
+# view; --screenshot saves its screenshot (owner or admin, or its sender)
+e3-cloud feedback show https://e3.example.com/repos/my-repo/workspaces/main FB-12 --screenshot fb-12.webp
+
+# Close and reopen (owner or admin)
+e3-cloud feedback close https://e3.example.com/repos/my-repo/workspaces/main 12
+e3-cloud feedback reopen https://e3.example.com/repos/my-repo/workspaces/main 12
+```
+
+#### Apps
+
+Pages and menus built with `@elaraai/e3-cloud-ui`, each its own deployable in
+a workspace. `build` makes a bundle of an app's source: the app, and
+the package it was built against. The source's default export is the app
+(`export default App('ops', { … })`); it is bundled with esbuild (TSX under
+the nearest tsconfig.json, east-ui's JSX without one) and built by the
+project's own `@elaraai/e3-cloud-ui`.
+
+```bash
+# Build an app into a bundle (default dist/<app>.app)
+e3-cloud app build src/apps/ops.tsx -o dist/ops.app
+
+# Deploy (owner or admin): the bundle's package is imported first when the
+# repository lacks its version; then the app is checked against it and, when
+# the workspace runs it, is live at once. A refusal prints every problem and
+# exits non-zero; --dry-run checks and changes nothing
+e3-cloud app deploy https://e3.example.com/repos/my-repo staging dist/ops.app --dry-run
+e3-cloud app deploy https://e3.example.com/repos/my-repo staging dist/ops.app
+
+# Several apps built against one package, together; or straight from source
+e3-cloud app deploy https://e3.example.com/repos/my-repo staging dist/ops.app dist/exec.app
+e3-cloud app deploy https://e3.example.com/repos/my-repo staging --from-source src/apps/ops.tsx
+
+# Stage a bundle built with the platform's next e3, for the platform deploy that moves to it
+e3-cloud app deploy https://e3.example.com/repos/my-repo production dist/ops.app --for-platform 1.0.86
+
+# What is deployed: every workspace's apps, or one's; an app's kept versions (owner or admin)
+e3-cloud app list https://e3.example.com/repos/my-repo
+e3-cloud app list https://e3.example.com/repos/my-repo staging
+e3-cloud app versions https://e3.example.com/repos/my-repo staging ops
+
+# Every app of the deployment, and which needs a bundle built with the platform's e3 (admin)
+e3-cloud app list-all https://e3.example.com
+
+# Remove an app and its versions (owner or admin)
+e3-cloud app remove https://e3.example.com/repos/my-repo staging ops
+
+# An admin's override of a workspace's protection: warns first, and its history records it as forced
+e3-cloud app deploy https://e3.example.com/repos/my-repo production dist/ops.app --force
+e3-cloud app remove https://e3.example.com/repos/my-repo production ops --force
+```
+
+A protected workspace, one with a staging (below, Staging), refuses an app
+deploy (a dry run, and a bundle for the next e3, too) and an app's removal:
+it changes only by a release from its staging. Only an admin forces one past
+it, with `--force`.
+
+A deploy whose package the workspace does not run deploys the package first,
+as a deploy job that keeps the inputs people set and starts no run; the
+CLI waits for the job, and the apps go live as it completes.
+
+**Developing an app** is done in the cloud, not locally: deploy each change
+to a workspace of your own, a staging say (`--from-source` builds and
+deploys in one step; `--dry-run` checks it against the workspace's package
+and changes nothing), and open the app in the console there. A protected
+workspace refuses a deploy: develop against its staging, and release.
+
+```bash
+e3-cloud app deploy https://e3.example.com/repos/my-repo staging --from-source src/apps/ops.tsx --dry-run
+e3-cloud app deploy https://e3.example.com/repos/my-repo staging --from-source src/apps/ops.tsx
+```
+
+#### Staging
+
+A workspace's staging is where changes are tried before they reach the
+workspace people use. Adding one **protects** that workspace, as a protected
+branch is protected: its package and apps then change only by a release from
+its staging, or a rollback. One staging to a workspace, and no staging has one
+of its own.
+
+```bash
+# What adding it would do, and nothing more; then add it: a copy of production as it is now, data included
+e3-cloud staging add https://e3.example.com/repos/acme production staging --plan
+e3-cloud staging add https://e3.example.com/repos/acme production staging
+
+# A workspace there: as it stands, or replaced whole by the copy (never unasked)
+e3-cloud staging add https://e3.example.com/repos/acme production uat --as-is
+e3-cloud staging add https://e3.example.com/repos/acme production uat --replace
+
+# Each staging, and what it protects
+e3-cloud staging list https://e3.example.com/repos/acme
+
+# Stop it (admins alone): production is unprotected, nothing is deleted, its history records who stopped it
+e3-cloud staging stop https://e3.example.com/repos/acme production
+```
+
+A protected workspace refuses, naming its staging, e3's deploy (`e3 workspace
+deploy`), an app deploy or removal (unless an admin forces it), a copy onto it,
+and its removal or its staging's. What people do with its data goes on:
+inputs set, records changed, runs, schedules.
+
+#### Releases, rollback and history
+
+```bash
+# The plan, and nothing more: package, apps, the next e3's bundles, records, inputs, carry, checks, forced changes it undoes
+e3-cloud release https://e3.example.com/repos/acme staging production --plan
+
+# Release staging to production: the plan is printed first, then the release
+# runs; one that deploys its package waits for its deploy job
+e3-cloud release https://e3.example.com/repos/acme staging production \
+  --carry inputs/mappings records/notes
+
+# Remove production's apps that staging lacks (else the release is refused)
+e3-cloud release https://e3.example.com/repos/acme staging production --remove-apps
+
+# A workspace's history, newest first, each entry's id beneath it
+e3-cloud history https://e3.example.com/repos/acme production
+
+# Roll back: to the newest entry that differs from what production runs, or to one named
+e3-cloud rollback https://e3.example.com/repos/acme production --plan
+e3-cloud rollback https://e3.example.com/repos/acme production 2026-10-12T14:02:11.000Z#…
+```
+
+A release (owner or admin) gives the target exactly the package and app
+versions the source runs, by hash, with the bundles it has staged for the
+platform's next e3. Only the target's staging releases to it, and a release
+that would change nothing is refused. The target keeps the inputs people set
+in it and migrates its records as a deploy does; `--carry` copies inputs, and
+records new in the release, from the source by reference. No dataflow run
+starts. A refused plan prints its problems and exits 1, changing nothing; the
+plan names any change an admin forced onto the target since its last release,
+which the release undoes. A rollback releases an entry of the history again,
+its package and apps exactly; a record migrated forward may refuse to go back,
+and the plan says so. A rollback stays open on a protected workspace.
+
+## License
+
+[BSL 1.1](./LICENSE.md). Production use needs a commercial license from Elara
+AI Pty Ltd. Each release becomes AGPL-3.0 four years after it is released.

package/dist/src/app-source.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import type { AppBundle } from '@elaraai/e3-cloud-ui/types';
+/**
+ * Builds the app a source file's default export defines into a bundle.
+ *
+ * @param file - The source: a module whose default export is `App(...)`
+ * @returns The bundle: the app, and its package's zip
+ * @throws {Error} When the source does not bundle or run, its default export
+ *   is no app, the project has no `@elaraai/e3-cloud-ui`, or the build refuses
+ *   the app (`AppBuildError`, naming each problem)
+ */
+export declare function buildAppFromSource(file: string): Promise<AppBundle>;
+//# sourceMappingURL=app-source.d.ts.map

package/dist/src/app-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-source.d.ts","sourceRoot":"","sources":["../../src/app-source.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmBH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AA4E5D;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CASzE"}

package/dist/src/app-source.js

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Builds an app from its source: `e3-cloud app build` and `app deploy
+ * --from-source`, as e3's CLI loads a package for `e3 workspace deploy
+ * --from-source`. esbuild bundles the entry (multi-file TypeScript and TSX,
+ * with the nearest tsconfig.json), leaving every `@elaraai/*` import to the
+ * project's own packages; the bundle is imported from under the project's
+ * `node_modules`, and its default export must be an app (`App(...)` of
+ * `@elaraai/e3-cloud-ui`). The app is built by the project's own
+ * `@elaraai/e3-cloud-ui`, the one its source imports, so the app, its pages
+ * and its package are of the modules the build reads them with.
+ */
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, parse, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** Whether a tsconfig.json is in a directory or one above it. */
+function hasTsconfig(from) {
+    for (let dir = from;; dir = dirname(dir)) {
+        if (existsSync(join(dir, 'tsconfig.json')))
+            return true;
+        if (dir === parse(dir).root)
+            return false;
+    }
+}
+/**
+ * The source's entry, resolved, and the project's `@elaraai/e3-cloud-ui`.
+ *
+ * @throws {Error} When the source does not exist, or its project has no `@elaraai/e3-cloud-ui`
+ */
+function resolveSource(file, entry = '@elaraai/e3-cloud-ui') {
+    const path = resolve(file);
+    if (!existsSync(path))
+        throw new Error(`${file} does not exist`);
+    try {
+        return { path, cloudUiEntry: createRequire(path).resolve(entry) };
+    }
+    catch {
+        throw new Error(`${file}'s project has no ${entry}: an app is built with the version its source imports (npm install @elaraai/e3-cloud-ui)`);
+    }
+}
+/** esbuild's options for a source: one ES module, every `@elaraai/*` import left to the project. */
+function bundleOptions(path) {
+    return {
+        entryPoints: [path],
+        bundle: true,
+        platform: 'node',
+        format: 'esm',
+        write: false,
+        external: ['@elaraai/*'],
+        logLevel: 'silent',
+        // Without a tsconfig.json to say so, TSX is east-ui's
+        ...(!hasTsconfig(dirname(path)) && { jsx: 'automatic', jsxImportSource: '@elaraai/east-ui' }),
+    };
+}
+/**
+ * Builds the app a bundle of its source defines: the bundle is imported from
+ * under the project's `node_modules`, and its default export built by the
+ * project's `@elaraai/e3-cloud-ui`.
+ */
+async function buildBundled(file, path, cloudUiEntry, code) {
+    // Under the project's node_modules, so its @elaraai/* imports resolve to the project's packages
+    const cache = join(dirname(path), 'node_modules', '.cache', 'e3-cloud');
+    mkdirSync(cache, { recursive: true });
+    const bundle = join(cache, `app-${process.pid}-${Date.now()}.mjs`);
+    let exported;
+    try {
+        writeFileSync(bundle, code);
+        const module = await import(`${pathToFileURL(bundle).href}?t=${Date.now()}`);
+        exported = module.default;
+    }
+    catch (err) {
+        throw new Error(`${file} did not run: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        try {
+            unlinkSync(bundle);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+    if (typeof exported !== 'object' || exported === null || exported.kind !== 'app') {
+        throw new Error(`${file}'s default export must be an app:\n\n  export default App('ops', { package, title, home, menu, pages });\n`);
+    }
+    const ui = await import(pathToFileURL(cloudUiEntry).href);
+    return ui.buildApp(exported);
+}
+/**
+ * Builds the app a source file's default export defines into a bundle.
+ *
+ * @param file - The source: a module whose default export is `App(...)`
+ * @returns The bundle: the app, and its package's zip
+ * @throws {Error} When the source does not bundle or run, its default export
+ *   is no app, the project has no `@elaraai/e3-cloud-ui`, or the build refuses
+ *   the app (`AppBuildError`, naming each problem)
+ */
+export async function buildAppFromSource(file) {
+    const { path, cloudUiEntry } = resolveSource(file);
+    const esbuild = await import('esbuild');
+    const result = await esbuild.build(bundleOptions(path)).catch((err) => {
+        throw new Error(`${file} does not bundle: ${err instanceof Error ? err.message : String(err)}`);
+    });
+    const code = result.outputFiles?.[0]?.text;
+    if (code === undefined)
+        throw new Error(`esbuild produced no output for ${file}`);
+    return buildBundled(file, path, cloudUiEntry, code);
+}
+//# sourceMappingURL=app-source.js.map

package/dist/src/app-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-source.js","sourceRoot":"","sources":["../../src/app-source.ts"],"names":[],"mappings":"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"}

package/dist/src/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AAEA;;;GAGG"}