@thatopen/services 0.0.4 → 0.0.5

package/src/cli/templates/shared/AGENTS.md

@@ -1,30 +1,8 @@
-# Working on this That Open Platform project — Agent Guide
-
-You're an AI assistant helping build/extend this project (a BIM app or cloud component) on the
-That Open Platform. Read this first.
-
-## Rules (always apply)
-1. **All business logic lives in a BIM component** (`src/bim-components/`). `setups/` only wire;
-   `ui-components/` only render; `main.ts` only boots. New logic → a new (or existing) component.
-2. **Check engine components first** — `@thatopen/components` (`OBC`) / `@thatopen/components-front`
-   (`OBF`) — before building anything custom.
-3. **Propose a short plan and get the user's OK** before changing files.
-
-## Where the full build guides live
-The complete, up-to-date guides ship with the library. Read them from the installed package:
-- `node_modules/@thatopen/services/AGENTS.md` — the router; **start here**
-- `node_modules/@thatopen/services/docs/` — detailed guides (app wiring, layout, connecting logic
-  to UI, building BIM/UI components, cloud components, publishing, icons, colors, …)
-- `node_modules/@thatopen/services/CONTEXT.md` — library API reference (`PlatformClient` vs
-  `EngineServicesClient`, permissions)
-
-## Beta libraries
-If you scaffold **another** app, first ask the user whether they have **beta access** and want the
-latest features/progress. If yes, use `thatopen create <name> -t bim-beta` — it scaffolds on the
-private `@thatopen-platform/*-beta` packages (the line the platform runs). Founding members have
-permanent beta access; the beta packages are private, so the user's beta token must be configured
-for `npm install`.
-
-## This project
-- `CONTEXT.md` (this folder) — the context for *this specific* project.
-- `package.json` scripts — `npm run dev` (preview), `npm run login`, `npm run publish`.
+# That Open Platform — Agent Guide
+
+Read these two files before doing anything else:
+
+1. `node_modules/@thatopen/services/resources/AGENTS.md` — rules, hard constraints, and the full navigation table for the That Open Platform. Always current for the installed library version.
+2. `README.md` (this folder) — what this specific project is, its commands, architecture, and patterns.
+
+If `node_modules/` doesn't exist yet, run `npm install` first or ask the user to do it.

package/src/cli/templates/shared/CLAUDE.md

@@ -1 +1 @@
-See [AGENTS.md](./AGENTS.md) for how to work on this project, the rules to follow, and where the full That Open Platform build guides live.
+See [AGENTS.md](./AGENTS.md).

package/AGENTS.md

@@ -1,86 +0,0 @@
-# Building on the That Open Platform — Agent Guide
-
-You are an AI assistant helping a user build a **BIM app** or **cloud component** on the
-That Open Platform using **`@thatopen/services`** (the `thatopen` CLI + client library).
-
-**Read this file first.** It states the rules you must follow, then routes you to the one
-detailed doc for whatever you're doing. Open only the doc you need — don't load everything.
-
-> This guide is tool-agnostic: it works with any AI (Claude, Codex, your own). All docs it
-> references ship inside the `@thatopen/services` package under `docs/`.
-
----
-
-## How to work
-
-- 🚩 **BEFORE creating anything, ask the user about beta access — this is important.** Ask:
-  *"Do you have That Open beta access? It gives you the latest libraries, features and progress —
-  and it's what the platform currently runs. Do you want to use it?"* **If yes, scaffold with the
-  `bim-beta` template** (`thatopen create <name> -t bim-beta`). Founding members have **permanent** beta
-  access, so for them the answer is almost always yes. Using the matching library line avoids
-  runtime errors against the platform. (Beta packages are private — the user needs their beta
-  access token configured in npm, or `npm install` will fail.) See
-  [docs/scaffolding.md](./docs/scaffolding.md).
-- **New app or component?** The **first step is always the CLI** (`thatopen create`) — never
-  hand-write the scaffold. See [docs/cli-setup.md](./docs/cli-setup.md) then
-  [docs/scaffolding.md](./docs/scaffolding.md).
-- **The scaffold is already a complete, working viewer** (model loading, spatial tree, properties).
-  **Run it first** (`npm run dev`) to see it work, *then* extend it — don't rebuild a viewer from scratch.
-- **Propose a short plan and get the user's OK** before changing files. If scope is unclear, ask.
-- Prefer existing engine functionality over custom code (see rule 2).
-
-## Hard rules (always apply)
-
-1. **All business logic lives in a BIM component** (`src/bim-components/`).
-   `setups/` only wire; `ui-components/` only render; `main.ts` only boots. Logic that doesn't
-   fit an existing component → create a new one. Never put logic in a setup, template, or `main.ts`.
-2. **Check engine components first** — `@thatopen/components` (`OBC`) and
-   `@thatopen/components-front` (`OBF`) — before building anything custom.
-3. **Platform built-ins** (`AppManager`, `ViewportsManager`, `UIManager`, …) come from
-   `@thatopen/services` and are available after `client.setup()`. Don't reinvent them.
-
----
-
-## What are you doing? → open the right doc
-
-### Set up & ship
-| Goal | Doc |
-|---|---|
-| Install the CLI + authenticate | [docs/cli-setup.md](./docs/cli-setup.md) |
-| Scaffold a new app / component | [docs/scaffolding.md](./docs/scaffolding.md) |
-| Preview the app inside the platform | [docs/previewing.md](./docs/previewing.md) |
-| Publish an app or component | [docs/publishing.md](./docs/publishing.md) |
-
-### Structure & wire an app
-| Goal | Doc |
-|---|---|
-| Project structure, architecture rules, component tiers | [docs/app-architecture.md](./docs/app-architecture.md) |
-| Boot / `app.ts` / `main.ts` / `client.setup()` | [docs/app-wiring.md](./docs/app-wiring.md) |
-| Configure layout, add/reorganize grid sections | [docs/app-layout.md](./docs/app-layout.md) |
-| Connect component logic to the UI | [docs/connect-logic-to-ui.md](./docs/connect-logic-to-ui.md) |
-| Update a grid element's state at runtime | [docs/update-grid-elements.md](./docs/update-grid-elements.md) |
-| Access the backend client / project data | [docs/access-backend-data.md](./docs/access-backend-data.md) |
-| Register and use icons | [docs/using-icons.md](./docs/using-icons.md) |
-| Declare and use colors | [docs/using-colors.md](./docs/using-colors.md) |
-
-### Build a custom BIM component
-Start at [docs/bim-components/overview.md](./docs/bim-components/overview.md) — conventions,
-lifecycle (setup/cleanup), exposing events, observable/element collections, per-frame updates,
-saving/restoring state, user-driven object creation.
-
-### Build a UI component
-Start at [docs/ui-components/overview.md](./docs/ui-components/overview.md) — rendering patterns,
-section layout, data tables, inline forms, confirmation dialogs, display text, async actions.
-
-### Cloud components & automations
-[docs/cloud-components.md](./docs/cloud-components.md) — build / run locally / publish a cloud
-component, the execution globals, and event-triggered automations.
-
----
-
-## Reference (also shipped in this package)
-
-- **Library API** — `PlatformClient` vs `EngineServicesClient`, the permissions contract, and the
-  full method surface → [CONTEXT.md](./CONTEXT.md)
-- **Built-in components API** — config interfaces, method signatures, `@example` blocks →
-  `src/built-in/index.ts` (in the installed package, `node_modules/@thatopen/services/`)

package/CONTEXT.md

@@ -1,258 +0,0 @@
-# @thatopen/services
-
-Client library and CLI for the That Open Platform — a cloud platform for building BIM (Building Information Modeling) software.
-
-## What this repo contains
-
-1. **Library** (`src/core/client.ts`) — `EngineServicesClient`, a TypeScript API client for managing files, folders, apps, cloud components, and executions on the platform.
-2. **CLI** (`src/cli/`) — The `thatopen` command-line tool for scaffolding and publishing apps and cloud components.
-3. **Built-in components** (`src/built-in/`) — Type stubs for platform-provided UI components (AppManager, ViewportManager, etc.) that are fetched and evaluated at runtime.
-
-## Project structure
-
-```
-src/
-  core/client.ts              # EngineServicesClient — the main API class
-  cli/
-    commands/create.ts        # thatopen create — scaffolds new projects
-    commands/serve.ts         # thatopen serve — dev server (esbuild watch + serve)
-    commands/login.ts         # thatopen login — authenticate with the platform
-    commands/publish.ts       # thatopen publish — build and upload to the platform
-    commands/run.ts           # thatopen run — test cloud components locally
-    commands/create-tests.ts  # thatopen create-tests — scaffolds test app + test component
-    commands/serve-tests.ts   # thatopen serve-tests — serves both test projects in parallel
-    templates/                # Template generators for scaffolded projects
-    lib/                      # CLI helper utilities (config, certificates)
-  built-in/index.ts           # Built-in component type stubs + runtime UUID constants
-  types/                      # TypeScript type definitions (items, execution, etc.)
-  index.ts                    # Library entry point (re-exports everything)
-```
-
-## Build system
-
-- **Library** builds to CommonJS (`dist/index.cjs.js`) + ESM (`dist/index.es.js`) + types (`dist/index.d.ts`) via Vite (`vite.config.mts`).
-- **CLI** builds to a single `dist/cli.js` executable via Vite (`vite.config.cli.mts`). It bundles commander, jszip, and all library code.
-- TypeScript strict mode is enabled.
-
-### Commands
-
-```bash
-npm run build          # Full build (library + CLI)
-npm run build:lib      # Library only
-npm run build:cli      # CLI only
-```
-
-### Testing
-
-```bash
-npm run test                      # Run vitest unit tests (HTTP client contract)
-npm run test:watch                # Vitest watch mode
-npm run test:ui                   # Interactive browser test page
-npm run test:cli-build-app        # Scaffold + build a test app
-npm run test:cli-build-component  # Scaffold + build a test cloud component
-npm run test:cli-run-component    # Run the test cloud component locally
-npm run test:cli-build-tests      # Build CLI + scaffold test app & test component into temp/
-npm run test:cli-serve-tests      # Serve the test app and test component's local server in parallel
-```
-
-## Two clients — components vs apps/FE
-
-This package ships two clients with overlapping but intentionally different
-surfaces. Pick the one that matches who's calling.
-
-### `EngineServicesClient`
-**For cloud components running inside the platform.** Authenticates via
-API token by default (`?accessToken=`). Supports local-server execution,
-WebSocket execution progress, built-in component runtime helpers, and the
-low-level HTTP surface. This is what you get via
-`EngineServicesClient.fromPlatformContext()` inside a component bundle.
-
-### `PlatformClient`
-**For apps, frontends, and any caller using a user JWT.** Extends
-`EngineServicesClient`; the API-token-compatible surface is inherited and
-the constructor forces `useBearer: true`. On top, it owns the JWT-only
-routes — `getProject`, `getProjectData`, `checkPermission`,
-`checkPermissionBatch` — which hit `ProjectController` in the backend
-(guarded by JWT) and are not reachable with an access token.
-
-The constructor accepts either a static JWT or a provider function
-(sync or async) that returns the current JWT. The provider is called on
-every request, so Auth0's `getAccessTokenSilently()` and similar
-refreshing sources Just Work:
-
-```ts
-import { PlatformClient } from '@thatopen/services';
-const client = new PlatformClient(
-  () => auth0.getAccessTokenSilently(),
-  'https://api.thatopen.com',
-);
-await client.getProjectData(projectId);
-```
-
-`PlatformClient.fromPlatformContext()` is available for apps running inside
-the platform iframe — it pulls the JWT from
-`window.__THATOPEN_CONTEXT__` and returns a ready-to-use client.
-
-Choose by audience:
-- Component code → `EngineServicesClient` (or `EngineServicesClient.fromPlatformContext()`).
-- App / FE / integration with a user JWT → `PlatformClient`.
-
-## Permissions contract (backend coupling)
-
-The platform API enforces **project-scoped permission checks**: whenever a
-request carries a `projectId` (URL param, query, or body), the backend
-rejects the call if the resource does not belong to that project or the
-caller lacks permission there — regardless of whether the caller has access
-to the same resource in a different project.
-
-Relevant client methods:
-
-- `executeComponent(componentId, executionParams, versionTag?)`: include
-  `projectId` in `executionParams` to scope the execution. The backend
-  validates that the component is linked to that project. Without a
-  `projectId`, the execution runs in the user's personal/ownership scope.
-- `listExecutions(componentId, projectId?)`: pass `projectId` to filter
-  executions to that project's context.
-- `checkPermission({ resourceType, action, resourceId?, projectId? })`:
-  returns `{ hasPermission, scope }`. `scope` is `'global' | 'project' |
-  'entity' | 'none'` — `global` for admin/owner bypass, `project` for a
-  role broad grant, `entity` for a per-entity override, `none` for denied.
-- `checkPermissionBatch(checks)`: evaluates a list of checks in one
-  round-trip. Useful for hydrating action visibility for many rows without
-  N+1 calls.
-
-Per-entity permission overrides (`ResourcePermission.removePermission`,
-`ResourcePermission.appliesToDescendants`) are applied automatically on the
-server side when listing project files/folders — no client change needed.
-
-
-### Publishing to npm
-
-```bash
-yarn create-version   # Build → changeset → version → publish
-```
-
-## Key concepts
-
-### Apps vs Cloud Components
-
-| | Apps | Cloud Components |
-|---|---|---|
-| **Runs in** | Browser (iframe on the platform) | Server (Node.js child process) |
-| **Item type** | `APP` | `TOOL` |
-| **Entry point** | Side effects in `main.ts` (renders UI) | `export async function main()` |
-| **Context** | `window.__THATOPEN_CONTEXT__` provides `{ appId, projectId, accessToken, apiUrl }` | Globals: `thatOpenServices`, `executionParams`, `executionContext` (`{ projectId?, executionId, toolId, toolVersion }`), `executionReporter` (`message/error/progress`). `OBC`, `THREE`, `web-ifc`, `fs` are NOT injected — import them and let the bundler include them. |
-| **Build output** | IIFE `dist/bundle.js` (all deps bundled) | IIFE `dist/bundle.js` (only `@thatopen/services` externalized) |
-| **Template** | `bim`, `default`, or `test` | `cloud` or `cloud-test` |
-
-### Authentication
-
-Two modes, controlled by `useBearer` in the constructor:
-- **Query parameter** (default): Sends `accessToken` as a URL query param. Used with platform API tokens.
-- **Bearer header** (`useBearer: true`): Sends as `Authorization: Bearer <token>`. Used with Auth0 JWTs inside platform apps.
-
-### Built-in components
-
-Built-in components are platform-hosted UI modules fetched at runtime. Usage pattern:
-
-```ts
-import { AppManager, ViewportManager } from "@thatopen/services";
-
-// Register all library globals once
-client.setBuiltInGlobals({ OBC, OBF, BUI, CUI, THREE, FRAGS });
-
-// Fetch, evaluate, and register with OBC — globals are automatically applied
-await client.initBuiltInComponent(AppManager, components);
-await client.initBuiltInComponent(ViewportManager, components);
-
-// Use via OBC component system
-const app = components.get(AppManager);
-const viewports = components.get(ViewportManager);
-```
-
-Available built-in components:
-
-| Component | Purpose |
-|-----------|---------|
-| `AppManager` | App shell — CSS grid layout with sidebar for switching layouts |
-| `ViewportManager` | Factory for 3D viewports with pre-configured world |
-| `LoadModelButton` | Button + dropdown for loading IFC / Fragments files |
-| `ViewerToolbar` | Toolbar with Show/Hide/Focus/Isolate and color palette |
-| `ModelsPanel` | Panel listing loaded models with search and load button |
-| `ModelsDropdown` | Dropdown selector listing loaded models |
-| `ClassificationsList` | Hierarchical table of IFC classification data |
-| `ClashesList` | Interactive clash detection results with highlighting |
-| `ClippingsList` | Panel listing clipping planes with controls |
-| `LengthMeasuringsList` | Panel listing length measurements with totals |
-| `AreaMeasuringsList` | Panel listing area measurements with totals |
-| `ColorsPalette` | Color picker with Highlighter style swatches |
-| `HighlightersList` | Panel listing Highlighter styles with manage actions |
-| `QtoComparisonList` | Side-by-side quantity comparison for two elements |
-| `QueriesHierarchy` | Recursive multi-level query browser |
-| `CustomViewLegend` | Color legend overlay |
-| `ScreenshotAnnotator` | Modal for annotating screenshots via MarkerJS |
-
-Full API reference with config interfaces, method signatures, and `@example` blocks: `src/built-in/index.ts`.
-
-### Configuration files
-
-- **Global**: `~/.thatopen/config.json` — `{ accessToken, apiUrl }`
-- **Local** (per project): `.thatopen` — `{ accessToken, apiUrl, appId?, componentId?, itemType? }`
-- Local config takes priority. Created by `thatopen login --local`.
-
-## API surface (EngineServicesClient)
-
-### Files
-- `listFiles(filters?)` / `getFile(id, props?)` / `createFile(data)` / `updateFile(id, data)`
-- `archiveFile(id)` / `recoverFile(id)` / `downloadFile(id, params?)` / `getFileMetadata(id, params?)`
-
-### Folders
-- `listFolders(params?)` / `getFolder(id)` / `createFolder(name, parentId?)`
-- `updateFolder(id, params)` / `archiveFolder(id)` / `recoverFolder(id)` / `downloadFolder(id)`
-
-### Components
-- `listComponents(params?)` / `getComponent(id, props?)` / `createComponent(data)` / `updateComponent(id, data)`
-- `archiveComponent(id)` / `recoverComponent(id)` / `downloadComponent(id, params?)` / `downloadComponentBundle(id, params?)`
-
-### Apps
-- `listApps(params?)` / `createApp(data)` / `archiveApp(id)`
-- `downloadApp(id, params?)` / `downloadAppBundle(id, params?)`
-
-### Execution (cloud components)
-- `executeComponent(componentId, params, versionTag?)` — triggers server-side execution, returns `{ executionId }`
-- `abortExecution(executionId)` / `listExecutions(componentId)` / `getExecution(executionId)`
-- `onExecutionProgress(executionId, callback)` — real-time WebSocket subscription
-
-### Built-in components
-- `setBuiltInGlobals(globals)` — registers globals once; subsequent `initBuiltInComponent` calls use them automatically
-- `getBuiltInComponent(name)` — fetches JS bundle by name
-- `initBuiltInComponent(component, components, globals?)` — fetches, evaluates, and registers (uses stored globals if `globals` omitted)
-
-### Hidden files
-- `createHiddenFile(file, parentId)` / `deleteHiddenFile(id)` / `getHiddenFile(id)`
-- `downloadHiddenFile(id)` / `getHiddenFilesByParent(parentId)` / `deleteHiddenFilesByParent(parentId)`
-
-### General
-- `updateItem(id, params)` / `createVersion(id, file, tag, extraProps?, metadata?)`
-- `getProjectData(projectId)` / `checkPermission(params)`
-
-## CLI commands
-
-```bash
-thatopen create <name> [--template bim|default|cloud|test|cloud-test]
-                                                        # Scaffold project + auto npm install
-                                                        # Use "." as name to scaffold in current directory
-thatopen serve [--port N]                                # Dev server (esbuild watch + serve bundle)
-thatopen login [--token T] [--api-url U] [--local]       # Authenticate
-thatopen publish [--name N] [--version-tag T] [--skip-build] [--app-id ID | --component-id ID]
-thatopen run [--params '{}'] [--skip-build]              # Test cloud component locally
-thatopen local-server [--port N] [--skip-build]          # Local execution server (API-compatible)
-thatopen create-tests [directory]                        # Scaffold test app + test component (cleans directory first)
-thatopen serve-tests [directory]                         # Serve test app + test component in parallel
-```
-
-## Dependencies
-
-- **Runtime**: `dotenv`, `socket.io-client`
-- **Peer** (optional): `@thatopen/components` ^3.3.1, `@thatopen/ui` ^3.3.3, `three` ^0.182.0
-- **CLI bundled**: `commander`, `jszip`