@lepsto/sdk-app 84.0.0

package/docs/recipes/federation.md

@@ -0,0 +1,285 @@
+# Recipe: Module Federation setup
+
+How to wire the Module Federation contract an App must implement (APP-004),
+and the dual-mode CSS graph that goes with it (APP-008, APP-009, APP-010).
+This page shows the *how*; for exact wording, rationale, and examples of the
+shared rules, see the referenced `FED-*` IDs in the toolkit-guide — this
+recipe does not restate them.
+
+## Expose `./App` — and nothing else
+
+Your app's federation config exposes exactly one module: a React component at
+`./App` (FED-001).
+
+```ts
+// vite.config.ts (federation mode only)
+federation({
+  name: APP_NAME,       // MUST equal the manifest `id` (FED-004)
+  filename: 'remoteEntry.js',
+  manifest: true,
+  exposes: {
+    './App': './src/federation/app-remote.tsx',
+  },
+  shared: SHARED,
+});
+```
+
+There is no `./navigation` module. FED-011 — the shell's extension-menu
+contract — is **RETIRED (2026-08)**: the shell never registers, preloads or
+calls it, there is no `subscribeNavItems` (v1 or v2) and no
+`navContractVersion` negotiation, and the menu the shell renders while your app
+is open comes from **your own** `lessly.app.yaml` — the `nav.sections` block
+(APP-011) — not from your App code, and not from a toolkit manifest.
+
+Still mapping the expose is inert, not an error — you just ship a chunk nobody
+fetches. If your app has one, the cleanup is: delete
+`src/federation/navigation.ts`, drop the `./navigation` entry from `exposes`,
+and delete any `navContractVersion` / `notify()` plumbing `./App` called. What
+the module used to feed the menu — environment lists, tool groups, live badges,
+status dots, a settings gear — belongs **in your own pages**, rendered by
+`./App` under its relative routes (FED-003). Deep links, refresh and the back
+button are unaffected: the dynamic items only ever fed the menu, never the
+router.
+
+## The menu moves to the manifest, not to a module
+
+The rows the module used to publish are now data in your App's manifest:
+
+```yaml
+# lessly.app.yaml
+nav:
+  icon: flask-conical
+  sections:
+    - id: overview
+      items:
+        - label: Dashboard
+          path: ''          # '' = your App's root
+          match: exact
+          icon: gauge
+        - label: Activity
+          path: activity
+          icon: activity
+```
+
+`path` is relative to your App's base path (`/<productSlug>/~/<id>`), so these
+are the same relative routes `./App` already renders under (FED-003). The full
+field constraints, the worked example, what happens when you ship no block, and
+how a change reaches production are in APP-011.
+
+## Shared singletons: `>=` floors, not carets, on 0.x packages
+
+`react`, `react-dom`, `react-router`, and `@lessly/ui` MUST be declared as
+shared singletons, never bundled (FED-005), pinned via `@module-federation/vite`
+at exactly `1.16.12` (FED-006):
+
+```ts
+const SHARED = {
+  react: { singleton: true, strictVersion: false, requiredVersion: '^19' },
+  'react-dom': { singleton: true, strictVersion: false, requiredVersion: '^19' },
+  'react-router': { singleton: true, strictVersion: false, requiredVersion: '^7.18' },
+  // 0.x singletons use a `>=` floor, NOT a caret: `^0.x` resolves to `<0.(x+1).0`,
+  // so a routine shell ui/icon bump would fail Module Federation version negotiation.
+  '@lessly/ui': { singleton: true, strictVersion: false, requiredVersion: '>=0.1.0' },
+};
+```
+
+`@lessly/ui` is pre-1.0. A caret range on a 0.x package (`^0.1.0`) resolves to
+`<0.2.0`, so the next time the shell bumps `@lessly/ui`'s minor version, MF
+version negotiation fails and your remote won't load under the shell. Use a
+`>=` floor for every 0.x shared singleton instead — it only guarantees a
+minimum, so it survives minor bumps upstream. Any other 0.x singleton you add
+(e.g. an icon package) follows the same rule.
+
+## Dual build: standalone + federation, merged into one `dist/`
+
+The build MUST produce one merged dual-mode `dist/` covering both standalone
+and federation artifacts (FED-007): a standalone build (plain SPA, `base: '/'`)
+and a federation build (`base: '/~/<id>/'`, emits `remoteEntry.js` +
+`mf-manifest.json`), merged so both coexist:
+
+```jsonc
+// package.json scripts
+{
+  "build": "tsc -b && pnpm build:standalone && pnpm build:federation && pnpm build:merge",
+  "build:standalone": "vite build",
+  "build:federation": "vite build --mode federation",
+  "build:merge": "node scripts/merge-federation-dist.mjs"
+}
+```
+
+```ts
+// vite.config.ts
+export default defineConfig(({ mode }) => {
+  const isFederation = mode === 'federation';
+  return {
+    base: isFederation ? `/~/${APP_NAME}/` : '/',
+    build: {
+      outDir: isFederation ? 'dist-federation' : 'dist',
+      emptyOutDir: true,
+    },
+    // ...
+  };
+});
+```
+
+The merge step copies `dist-federation/*` into `dist/`, keeping the
+**standalone** `index.html` (not the federation one) and failing loudly on any
+filename collision with differing content, then removes `dist-federation/`.
+The result: one `dist/` that serves the standalone SPA at `/` and the
+federation remote entry + assets at `/~/<id>/`.
+
+## Absolute asset base in federation mode
+
+The asset base in federation mode is the absolute path `/~/<id>/` — not a
+relative path, and `<id>` MUST match the manifest `id` and the MF `name`
+(FED-004). Getting this wrong breaks asset resolution once the shell mounts
+your remote at that path.
+
+## Styles: two entries, one vocabulary
+
+Federation mode and standalone mode enter the CSS graph through **different**
+stylesheets, and that split is the whole point. Standalone is your app's own
+page, so it owns the base layer, the fonts and the full kit stylesheet.
+Federation mounts your subtree inside the shell's already-painted page, so the
+federation entry must add nothing global (APP-008), must take its scales from
+the shell's preset (APP-009), and must park its utilities in
+`layer(remote-utilities)` (APP-010).
+
+Four files, ready to copy.
+
+```css
+/* src/index.federation.css — the federation entry, imported by ./App.
+   Utilities only: no preflight, no fonts, no base layer, no @theme, and no
+   tailwindcss/theme.css at all. */
+
+/* Layer order first, so positions are fixed before Tailwind emits its own.
+   Mirrors the shell's declaration in lessly-workspace:apps/web/src/index.css. */
+@layer theme, base, components, remote-utilities, utilities;
+
+@config '../tailwind.config.ts';
+@import 'tailwindcss/utilities.css' layer(remote-utilities);
+@import '@lessly/ui/styles-federated.css';
+
+/* Tailwind must scan the kit's compiled output, or the classes @lessly/ui
+   components use are never generated. */
+@source '../node_modules/@lessly/ui/dist/index.js';
+
+/* ...and must NOT scan your tests: a utility class named as a test fixture is
+   just a string to Tailwind, and would be compiled into the shipped sheet. */
+@source not '../src/**/*.test.ts';
+@source not '../src/**/*.test.tsx';
+```
+
+```css
+/* src/index.css — the standalone entry, imported by src/main.tsx. Your app
+   owns the page here: full tailwindcss (preflight included), the fonts, the
+   full kit stylesheet, and the base layer. Same @config as the federation
+   entry — one vocabulary on both (APP-009). */
+@config '../tailwind.config.ts';
+@import 'tailwindcss';
+@import url('https://fonts.googleapis.com/css2?family=Inter');
+@import '@lessly/ui/styles.css';
+@import './base.css';
+
+/* Same reason as in the federation entry: Tailwind generates utilities per
+   entry, and neither entry's scan reaches node_modules on its own. */
+@source '../node_modules/@lessly/ui/dist/index.js';
+```
+
+```css
+/* src/base.css — the global base layer. Imported by the STANDALONE entry
+   ONLY; it must never be reachable from src/index.federation.css. */
+@layer base {
+  * { @apply border-border-subtle; }
+  body { @apply bg-bg-primary text-text-primary; font-family: var(--font-sans); }
+}
+```
+
+```ts
+// tailwind.config.ts — the single source of scale vocabulary, for both entries
+import { lesslyPreset } from '@lessly/ui/tailwind-preset';
+
+export default {
+  presets: [lesslyPreset],
+  content: ['./index.html', './src/**/*.{ts,tsx}'],
+};
+```
+
+Wire them up:
+
+```tsx
+// src/federation/app-remote.tsx
+import '../index.federation.css';
+```
+
+```tsx
+// src/main.tsx
+import './index.css';
+```
+
+### Three things that are easy to get wrong
+
+**`theme.css` is optional, and it is not a token bridge.** There is no
+`src/theme.css` in the layout above, and an app with no tokens of its own does
+not need one. The kit's tokens come from `@lessly/ui/styles-federated.css` in
+federation and `@lessly/ui/styles.css` in standalone; re-declaring them locally
+is a hand-copied set that drifts from the kit silently, and an `@theme` block
+restating the kit's scales is exactly what APP-009 forbids.
+
+Add `src/theme.css` only for tokens **your app owns and the kit does not** —
+`--hover-bg` and the like — and then it holds **variable declarations only**.
+Both entries import it, so a `@layer base { body { … } }` block in it is
+reachable from the federation entry and will re-font the shell's chrome after
+first paint. That exact block is what shipped the production font jump; it
+belongs in `src/base.css`, standalone-only.
+
+**The sanctioned federated export, not a hand-rolled filter.**
+`@lessly/ui/styles-federated.css` is `styles.css` minus the `@font-face` blocks
+and the `@layer base` — tokens, `--color-*` aliases, `.link`, the `.motion-*`
+helpers and the compiled tw-animate-css layer are all still there. A prebuild
+script that reads the kit's stylesheet out of `node_modules` and strips the
+forbidden blocks itself breaks on any restructure of a file you don't own.
+Depend on `@lessly/ui` at `^4.0.0`, the range the shell runs.
+
+**`layer(remote-utilities)` only after the shell declares the order.** The
+shell already ships `@layer theme, base, components, remote-utilities,
+utilities;` (`lessly-workspace:apps/web/src/index.css`). Adopt the layer
+against a shell that hasn't, and `remote-utilities` becomes the last-declared —
+and therefore highest-priority — layer, so every one of your utilities beats
+every shell utility. Verify the shell first; adopting early is a regression,
+not a head start.
+
+### Guard it
+
+A CSS regression here is invisible in a standalone build — it only shows once
+your app is composed into a live shell. Keep a standing test over the **built**
+federation CSS (`dist-federation/`), not over the entry's import list, since an
+imported stylesheet can carry what the entry looks clean of. What it must
+assert, and the two shapes it must not confuse:
+
+```bash
+# No fonts, and no base-layer BLOCK. Note the `{`: `@layer base, components;`
+# is a harmless order declaration and must not trip the guard.
+grep -REn "@font-face|@layer[[:space:]]+base[[:space:]]*\{" dist-federation/
+
+# A global rule is a violation only if it declares more than custom properties:
+# styles-federated.css's `*, ::before, ::after { --tw-*: … }` is legal.
+grep -REn "(^|[,}])[[:space:]]*(html|body|\*)[^{]*\{" dist-federation/
+grep -R -- "-webkit-text-size-adjust" dist-federation/ && echo "preflight leaked"
+
+# Utilities in the app's own layer, never the shell's.
+grep -REn "@layer[[:space:]]+utilities[[:space:]]*\{" dist-federation/ \
+  && echo "APP-010 — utilities still in the shell's layer"
+```
+
+## Fast Refresh under a local shell
+
+When developing your remote composed under a local shell (`vite --mode
+federation`), point `reactRefreshHost` at the shell's dev origin so React Fast
+Refresh works through the federation boundary:
+
+```ts
+react(isFederation ? { reactRefreshHost: shellDevOrigin } : {})
+```
+
+See `recipes/local-dev.md` for how to run this composed setup end to end.

package/docs/recipes/local-dev.md

@@ -0,0 +1,111 @@
+# Recipe: running an App locally
+
+How to run an App standalone and, when needed, composed under a local shell.
+Auth stays ambient in both modes (APP-005) — you never implement login or
+token handling yourself.
+
+## Standalone: `pnpm dev`
+
+```sh
+pnpm dev
+```
+
+This starts the app on its own, outside any shell, proxied through
+`@lessly/app-dev`'s local dev server. Platform API calls made through your
+`sdk` (created with `createLesslyApp`, see `recipes/sdk-usage.md`) are
+forwarded through a bearer proxy at exactly this path:
+
+```
+/lessly-api
+```
+
+`@lessly/app-dev` attaches your locally stored bearer token to everything it
+proxies through `/lessly-api`, so your SDK client just talks to that path in
+dev — it never sees or handles the token itself.
+
+So in dev you pass `baseUrl: '/lessly-api'` — a page-relative `baseUrl` is
+supported and resolved against the current document (browser-only); see
+`recipes/sdk-usage.md`.
+
+### Device-code login
+
+The first time you run `pnpm dev` (or once your local session expires),
+`@lessly/app-dev` walks you through a device-code login: it prints a
+verification URL and a short code, opens your browser, and polls until you
+approve. Once approved, it stores the resulting bearer token locally and the
+`/lessly-api` proxy starts attaching it automatically. You don't write any of
+this — it's ambient, per APP-005: an App MUST NOT implement its own login,
+token handling, or refresh.
+
+### `.env.local`
+
+Set which product your local session targets:
+
+```sh
+# .env.local
+VITE_PRODUCT_ID=prod_123
+```
+
+Vite does not load `.env.example` — copy it to `.env.local` and edit the
+value. `.env.local` is per-developer and untracked; don't commit it.
+
+### The stub `user` prop
+
+In dev-standalone, the `user` prop your app receives is a **stub**:
+`{ id: <from the local dev JWT>, displayName: 'Dev User' }`. It is not a real
+session — it exists only so you have *something* to render while developing
+outside a shell. Per APP-005, don't build any behavior on `user` beyond
+display (a name badge, an avatar fallback). The real, shell-authenticated
+user only arrives once your app is composed via federation, through the
+`./App` props — code that branches on `user` for anything beyond display will
+work in dev-standalone and misbehave once composed under a real shell.
+
+## Composed: running under a local shell
+
+To see your app the way it will actually render — composed under the shell,
+receiving real federation props — run:
+
+```sh
+pnpm dev:shell
+```
+
+This builds/serves your remote in federation mode (`vite --mode federation`,
+see `recipes/federation.md`) and points it at a local or staging shell for
+Fast Refresh (`reactRefreshHost`).
+
+### Pointing a staging shell at your local remote
+
+To make a **staging** shell load your app from your local dev server instead
+of its deployed remote, set this in the shell's browser `localStorage`
+(**staging only** — this override does not exist in production):
+
+```
+localStorage['lessly:dev-remote'] = "<slug>=<origin>"
+```
+
+`<slug>` is your app's manifest `id`; `<origin>` is your local dev server's
+origin (e.g. `http://localhost:5173`). For example:
+
+```js
+localStorage['lessly:dev-remote'] = 'my-app=http://localhost:5173';
+```
+
+Reload the staging shell after setting this — it reads the override at
+startup and fetches your remote entry from `<origin>` instead of the deployed
+one for the app matching `<slug>`. Remove the key (or clear `localStorage`) to
+go back to the deployed remote.
+
+## Keeping your local setup current
+
+Update the SDK and `@lessly/app-dev` with the `@latest` form, never `npm
+update`:
+
+```sh
+npm i @lessly/sdk-app@latest
+npm i @lessly/app-dev@latest
+```
+
+`@lessly/sdk-app` and `@lessly/app-dev` are pre-1.0 and pinned with caret
+ranges, so `npm update` never crosses a minor version — and since the SDK
+bumps its minor version whenever the platform ships a new tool, `npm update`
+would never actually deliver those updates (see APP-007).

package/docs/recipes/sdk-usage.md

@@ -0,0 +1,194 @@
+# Recipe: calling the platform API
+
+How to reach Lessly platform data from an App. The normative rule is APP-001
+(all platform data access goes through `@lessly/sdk-app`) and APP-006 (prefer
+the generated option factories) — this page shows the *how*.
+
+## Create the client
+
+Create one client with `createLesslyApp` and call operations through the
+Proxy namespace tree:
+
+```ts
+import { createLesslyApp } from '@lessly/sdk-app';
+
+const sdk = createLesslyApp({
+  baseUrl: 'https://api.lessly.dev',
+  productId: 'prod_123',
+  // getCsrfToken defaults to reading the `lessly_csrf` cookie; override for SSR/tests.
+});
+
+const connectors = await sdk.organization.connectors.list({ productId: 'prod_123' });
+await sdk.organization.product.create({ name: 'Acme' });
+```
+
+> The exact namespaces you see depend on the live catalog — see
+> [Namespaces and subpath imports](#namespaces-and-subpath-imports). The calls
+> above use `organization`; substitute the namespace/resource you need.
+
+### `baseUrl`: absolute or page-relative
+
+`baseUrl` may be either form:
+
+- **Absolute** — `'https://api.lessly.dev'`. Works anywhere, including SSR and
+  tests.
+- **Page-relative** — `'/lessly-api'`, the path `pnpm dev` proxies through
+  (see `recipes/local-dev.md`). It is resolved against the current document via
+  `globalThis.location`, so it is **browser-only**: outside a browser the SDK
+  throws a named error (`@lessly/sdk-app: relative baseUrl "/lessly-api" cannot
+  be resolved outside a browser`) instead of an opaque `Invalid URL`. Tests and
+  SSR must pass an absolute base.
+
+```ts
+const sdk = createLesslyApp({
+  baseUrl: import.meta.env.DEV ? '/lessly-api' : 'https://api.lessly.dev',
+  productId: 'prod_123',
+});
+```
+
+`productId` is the active product — read it from your `./App` props or the
+`X-Product-Id` header (see APP-005), never decoded from a token.
+
+## Handle errors with `LesslyApiError`
+
+Every failed call throws a typed `LesslyApiError` with `status`, `code`, and
+`body`. Branch on `code` (stable) rather than `status` alone when you need to
+distinguish platform-defined failure reasons:
+
+```ts
+import { LesslyApiError } from '@lessly/sdk-app';
+
+try {
+  await sdk.organization.product.create({ name: 'Acme' });
+} catch (err) {
+  if (err instanceof LesslyApiError) {
+    if (err.status === 409) {
+      // err.code / err.body carry the platform's structured reason
+    }
+  }
+  throw err;
+}
+```
+
+### Missing CSRF cookie
+
+Mutating calls (`POST`, `PUT`, `PATCH`, `DELETE`) require the `lessly_csrf`
+cookie. If it is absent, the SDK throws before any network call:
+`LesslyApiError` with `status: 0` and `code: 'csrf_cookie_missing'`. There is no
+retry and no hidden token refresh — re-establish the session, or supply
+`getCsrfToken` for SSR/tests. Read-only calls are unaffected.
+
+## Prefer the generated query/mutation option factories
+
+Each namespace subpath (`@lessly/sdk-app/<namespace>`) ships framework-agnostic
+query/mutation **option factories** — plain objects, not hooks — usable with
+any TanStack Query adapter (React, Solid, Vue, Svelte). You pass the `sdk`
+instance explicitly:
+
+```ts
+// React example — works the same with any @tanstack/*-query adapter.
+import { useQuery, useMutation } from '@tanstack/react-query';
+import {
+  organizationConnectorsListQueryOptions,
+  organizationProductCreateMutationOptions,
+} from '@lessly/sdk-app/organization';
+
+function Connectors() {
+  const { data } = useQuery(organizationConnectorsListQueryOptions(sdk, { productId: 'prod_123' }));
+  const create = useMutation(organizationProductCreateMutationOptions(sdk));
+  // create.mutate({ name: 'Acme' })
+}
+```
+
+The factories return `{ queryKey, queryFn }` (and `{ mutationKey, mutationFn }`),
+so they also work directly with `queryClient.ensureQueryData(...)` and friends
+— useful for prefetching outside a component, e.g. in a route loader:
+
+```ts
+await queryClient.ensureQueryData(organizationConnectorsListQueryOptions(sdk, { productId: 'prod_123' }));
+```
+
+Prefer these factories over hand-rolling calls against `sdk.<namespace>...`
+directly (APP-006): they keep query keys, request shapes, and cache
+invalidation consistent with the published API surface, and stay in sync with
+it automatically when you run `npm i @lessly/sdk-app@latest`.
+
+## Namespaces and subpath imports
+
+The SDK is organized by namespace (currently `organization` and `playground`).
+Call operations off `sdk.<namespace>.<resource>.<action>(...)`, and import that
+namespace's option factories from the matching subpath,
+`@lessly/sdk-app/<namespace>` — not the package root. This keeps each App's
+bundle limited to the namespaces it actually uses.
+
+Some operations belong to the namespace itself rather than to a resource under
+it — listing the organizations you can see, for example, has no entity to hang
+off. Those are called directly on the namespace, `sdk.<namespace>.<action>(...)`,
+and their query keys drop the resource segment to match. Both forms are
+generated from the live catalog; check `client.gen.ts` (or your editor's
+autocomplete) for which shape a given operation takes.
+
+The available namespaces track the live catalog and **grow as platform
+extensions migrate to `@lessly-platform/tools`** — a namespace appears here only once its
+tools carry a REST binding. Run `npm i @lessly/sdk-app@latest` to pick up newly
+migrated namespaces. To see exactly what a given version exposes, check its
+subpaths in `package.json` `exports`, or the `manifest.gen.ts` namespace list.
+
+## Streaming (`*Connect` factories)
+
+Some catalog tools are ws-bound: instead of a request/response pair they carry
+a `ws` binding, and the generator emits a `<toolId>Connect` factory for them
+next to the option factories. That factory is the **only** sanctioned way to
+stream from an App (APP-001) — it derives `ws(s)://` from your `baseUrl`, opens
+the socket, and hands back a small handle:
+
+```ts
+import { createLesslyApp } from '@lessly/sdk-app';
+import { playgroundWsEchoConnect } from '@lessly/sdk-app/playground';
+
+const sdk = createLesslyApp({ baseUrl: 'https://api.lessly.dev', productId: 'prod_123' });
+
+const stream = playgroundWsEchoConnect(sdk, { room: 'lobby' });
+const off = stream.onMessage((frame) => console.log(frame));
+stream.onClose(({ code, reason, wasClean }) => console.log('closed', code, reason, wasClean));
+stream.send('hello');       // queued until the socket is OPEN, then flushed in order
+// later
+off();
+stream.close(1000, 'done');
+```
+
+What the handle does and does not do:
+
+- **Session cookies ride the upgrade.** No CSRF token and no product header are
+  sent — a browser `WebSocket` cannot set headers at all, and the gateway
+  authenticates the upgrade from the session.
+- **Frames are raw.** `onMessage` delivers `MessageEvent.data` exactly as it
+  arrived (`string`, `ArrayBuffer` or `Blob`); the SDK never parses it. Framing
+  is protocol-specific and is documented by the tool's own description.
+- **No reconnection.** A dropped connection surfaces once, through `onClose`
+  with the close code (`1006` for an abnormal drop). Whether and how to
+  reconnect is the App's decision — the SDK will not retry behind your back.
+- **Params are placed like a GET.** `:token` segments are filled from the input,
+  everything else becomes a query parameter.
+
+The `*Connect` factory is the App-facing surface, and the only one APP-001
+sanctions. The lower-level pieces it is built on — `sdk.openStream(binding, …)`
+and the `connectStream` runtime — are the SDK's own primitive: they are exported
+so the generated code can use them and so tests can substitute a socket, not so
+that App code can address a route by hand. Call the factory.
+
+Streaming needs a browser: outside one (SSR, node tests) there is no
+`WebSocket`, and the SDK says so by name rather than failing opaquely. Pass
+`options.WebSocket` to supply an implementation in tests.
+
+## What not to do
+
+- Don't open a `WebSocket` to a platform host, and don't hand-build a
+  `ws(s)://` URL from `baseUrl` (APP-001) — use the generated `*Connect`
+  factory. A tool without a `ws` binding has no sanctioned stream.
+- Don't `fetch` a platform host directly, and don't use any other HTTP client
+  for platform data (APP-001) — always go through `sdk` or the generated
+  factories.
+- Don't hand-roll request paths against the client when a
+  `*QueryOptions`/`*MutationOptions` factory already exists for that operation
+  (APP-006).