@fluid-app/fluid-cli-portal 0.1.61 → 0.1.63

package/templates/base/skills/fluid-portal-authoring/references/widgets-and-runtime.md

@@ -0,0 +1,57 @@
+# Widgets and runtime choices
+
+## Built-in widgets
+
+Use the current portal schema and builder catalog for the complete built-in
+widget set and each widget's props. Do not maintain category, type, or prop
+lists in this guide. An unregistered type renders no widget.
+
+## Company widget package
+
+Use a company widget package for Remote DOM UI authored in a portal project.
+Author it under `src/widgets/` and register it in `src/widgets.config.ts`.
+Packages can use serializable props, declared host portal functions, and
+approved public HTTP access. `fluid portal deploy` publishes these widget
+artifacts.
+
+## Standalone Droplet widget package
+
+Use the standalone widget project and `fluid widget publish` for a package
+associated with an existing Droplet. Do not mix its
+`fluid.widget.config.ts` layout with the company widget package layout.
+
+## Server application
+
+Use a Mist application or another server component for secrets, OAuth,
+webhooks, private APIs, background work, and other server behavior. Remote DOM
+workers receive no host cookies, storage, API client, or credentials. Do not
+invent an embed URL or iframe contract. Use only routes and integration
+contracts supplied by the application.
+
+## Network access
+
+Widget network access requires the declared `networkAccess` capability and an
+author-approved placement grant. The builder shows a warning when the widget
+is added and keeps a customization banner visible while the capability is
+present. The grant is bound to the exact package and capability versions. A
+change invalidates the grant and requires approval again. In the CLI, `--yes`
+does not approve this capability; a non-interactive push needs
+`--allow-network-widgets`.
+
+Granted requests use native fetch from the worker origin. Fluid does not add
+credentials, cookies, tokens, or headers. The widget's own `RequestInit`
+values, including credential mode, remain in effect.
+
+The runtime reference owns the exact blocked-destination and ambient-API
+contract. Native fetch redirects and DNS results are not revalidated, so
+approval is a package trust decision. Any portal data exposed to the widget can
+be sent to an external service, and worker isolation does not protect the
+browser reputation of `*.fluid.app`.
+
+## Theme behavior
+
+Built-in and third-party widgets should follow the active theme. Prefer
+semantic colors, typography, spacing, radii, borders, focus, and chart tokens.
+For widget property schemas, use `colorSelect` so authors choose a semantic
+token. The legacy `color` field is deprecated. Do not add arbitrary colors or
+styling properties when the theme engine already expresses the intended role.

package/templates/base/skills/fluid-portal-authoring/references/workflows.md

@@ -0,0 +1,56 @@
+# Preview, synchronization, and deployment
+
+## Local preview
+
+Use `pnpm dev`, which runs `fluid portal dev`. The CLI reads the local portal
+resources, pulls when `portal/` is missing, and installs its Vite integration.
+Do not replace it with bare Vite for portal definition work.
+
+When `VITE_API_URL` is unset, development resolves the signed-in company and
+proxies `/api` to its tenant portal host. The override changes routing, not
+authentication. Localhost does not have the HttpOnly member handoff cookie, so
+authenticated screens can return HTTP 401.
+
+Preview can skip malformed JSON. It preserves unresolved navigation entries
+without attaching a screen ID. It selects the profile marked `default: true`,
+or the first profile when none is marked default, and does not reproduce every
+production permission decision.
+
+## Pull, push, and versions
+
+Use the installed command reference for the complete command tree, arguments,
+options, and defaults. Pull reads the remote working definition, push writes
+the working definition, and version activation changes the live definition.
+Treat those as separate effects even when one command can combine phases.
+
+`--yes` does not approve a newly network-enabled widget. Use interactive
+approval or add `--allow-network-widgets` after package review.
+
+Push writes screens and themes, then navigations, then profiles. A failed phase
+skips later phases. Successful resources can advance their sync snapshot, so
+fix the reported phase and rerun instead of assuming the entire operation was
+rolled back.
+
+## Deployment boundaries
+
+- `pnpm build` creates portal application assets in `dist/`.
+- `.github/workflows/deploy.yml` uploads those assets to the configured CDN.
+- `fluid portal deploy` builds and publishes company widget artifacts from
+  `src/widgets.config.ts`.
+- `fluid widget publish` publishes a standalone Droplet widget package.
+
+Portal deploy does not push portal JSON, activate a portal version, publish
+standalone widgets, or upload the portal application bundle.
+
+Read the generated workflow and its adjacent environment template for the
+complete deployment-variable contract. Do not copy that list into this skill.
+
+## Recovery
+
+- Authentication failure: correct the selected profile or token and retry.
+- Invalid JSON or reference: fix the named local resource and validate again.
+- Remote drift: preserve local edits, pull, reapply the intended diff, and
+  push again.
+- Failed activation: inspect remote version state before creating another
+  version.
+- Another machine: use `fluid portal clone <app-name>`, then pull.

package/templates/starter/.env.example

@@ -5,7 +5,16 @@
 # portal-member handoff session.
 # VITE_API_URL=
 
+# Optional: production asset base used by Vite builds.
+# The included deployment workflow sets this from CDN_HOSTNAME.
+# VITE_ASSET_BASE=
+
+# Optional: override the API base used by Fluid CLI commands.
+# FLUID_API_BASE=
+
 # Optional: override the Fluid CLI auth token for this project.
 # Takes effect when running `pnpm pull`, `pnpm push`, etc.
 # Alternatively, set the "profile" field in .fluidrc (committed to the repo).
+# FLUID_API_TOKEN=
+# Legacy token name retained for compatibility:
 # FLUID_TOKEN=

package/templates/starter/README.md.template

@@ -1,18 +1,12 @@
 # {{projectName}}
 
-A Fluid portal shell built with `@fluid-app/portal-sdk` and the Fluid portal CLI.
+A Fluid portal shell, local portal-definition workspace, and optional company
+Remote DOM widget package.
 
-This starter is designed for the Fluid OS definition workflow: pull the portal definition into local JSON, edit `portal/`, push the working/draft definition back to Fluid OS, then create and activate a version when it should go live.
+## Start development
 
-## What's included
-
-- **Portal shell** — Vite builds the hosted SDK shell assets.
-- **Portal definition sync** — `pnpm pull` and `pnpm push` manage local Fluid OS JSON under `portal/`.
-- **Deployment workflow** — GitHub Actions can build and upload the hosted shell assets in `dist/`.
-- **Widget authoring support** — `pnpm widget:create <name>` scaffolds company-owned portal widgets.
-- **AI authoring kit** — generated `AGENTS.md`, `CLAUDE.md`, `.agents/skills/...`, and `.claude/skills/...` files explain the supported portal and widget workflows.
-
-## Quick start
+Requirements: Node.js, pnpm, and a Fluid CLI login or API token for remote
+portal operations.
 
 ```bash
 pnpm install
@@ -20,178 +14,114 @@ pnpm pull
 pnpm dev
 ```
 
-Open the local URL printed by Vite, usually [http://localhost:5173](http://localhost:5173).
-
-Useful commands:
-
-```bash
-pnpm dev        # Pull missing portal JSON and start the portal dev server
-pnpm build      # TypeScript build plus production bundle
-pnpm preview    # Preview dist locally
-pnpm typecheck  # TypeScript checks
-pnpm lint       # OxLint
-pnpm pull       # fluid portal pull
-pnpm push       # fluid portal push
-pnpm widget:create <name>  # scaffold a company-owned portal widget
-```
-
-When `VITE_API_URL` is unset, `fluid portal dev` resolves the signed-in
-company and proxies `/api` to its tenant BFF at
-`https://<subdomain>.portal.fluid.app`. Set `VITE_API_URL` in `.env` only when
-you need a different API host. The override changes routing, not
-authentication.
-
-Local preview always serves your local `portal/` manifest, custom pages, and
-navigation. Built-in screens that load member data also require the
-`portal_tenant_user_id` session cookie created by the production/Rails handoff.
-A direct localhost preview cannot create or read that HttpOnly tenant cookie,
-so Shop, Orders, Contacts, and other member-data screens may return HTTP 401 or
-remain in an unauthenticated state. Do not treat persistent skeletons as proof
-that authenticated data works; verify those screens through a real tenant
-handoff environment.
-
-## Project structure
-
-```text
-.
-├── AGENTS.md                                      # AI-agent guidance
-├── CLAUDE.md                                      # Bridge to AGENTS.md
-├── .agents/skills/fluid-portal-authoring/         # Portal sync workflow skill
-├── .agents/skills/fluid-widget-authoring/         # Widget authoring skill
-├── .claude/skills/fluid-portal-authoring/         # Claude-compatible copy
-├── .claude/skills/fluid-widget-authoring/         # Claude-compatible copy
-├── .github/workflows/deploy.yml                   # Hosted shell asset deployment
-├── src/
-│   ├── main.tsx                                   # createPortal bootstrap
-│   ├── index.css                                  # Tailwind and SDK globals
-│   ├── portal.config.ts                           # SDK custom-page integration
-│   ├── widgets.config.ts                          # Remote DOM widget packages
-│   └── widgets/                                   # Created by pnpm widget:create
-├── portal/                                        # Created/refreshed by fluid portal pull
-└── .portal-sync/                                  # Generated sync metadata
-```
-
-## Supported portal authoring workflow
-
-### 1. Pull remote Fluid OS definitions
-
-```bash
-pnpm pull
-```
-
-This runs `fluid portal pull` and writes `portal/` plus `.portal-sync/`.
-
-- `portal/` contains local JSON for Fluid OS resources such as screens, themes, navigations, profiles, and definition metadata.
-- `.portal-sync/` contains generated sync state for future diffs. Do not edit it by hand.
-
-Pull before editing unless you intentionally want to work from the current local JSON.
-
-### 2. Edit `portal/` JSON
-
-Make portal definition changes inside `portal/`.
-
-Guidelines:
-
-- Keep JSON valid and deterministic.
-- Preserve stable IDs, slugs, and cross-resource references unless intentionally changing them.
-- Update related files together when a resource reference changes.
-- Do not invent unsupported fields. Match the shapes produced by `pnpm pull`.
-- Keep changes small enough to review.
-
-### 3. Validate locally
-
-Run checks that match the change:
+`pnpm dev` runs `fluid portal dev`, normally at http://localhost:5173. When
+`portal/definition.json` is absent, it pulls the linked working definition
+before starting. Pass `-- --skip-pull` only when the missing local definition
+is intentional. The CLI installs portal JSON and widget-development Vite
+plugins; bare Vite does not provide the same preview.
+
+Localhost does not receive the production HttpOnly member handoff cookie.
+Authenticated screens can return HTTP 401 even when local JSON and custom pages
+render correctly.
+
+## Project map
+
+| Path | Owner and lifecycle |
+| --- | --- |
+| `.fluidrc` | Author-owned link to the remote portal definition. Change only when intentionally relinking. |
+| `.env.example` | Committed environment template. Copy values to `.env` or `.env.local`; do not put secrets in the example. |
+| `.env`, `.env.local` | Local credentials and overrides. Never commit. |
+| `.gitignore` | Source-control exclusions for local, generated, and secret files. |
+| `.oxlintrc.json` | Generated lint configuration. Change only when project lint policy changes. |
+| `package.json` | Project scripts and dependencies. Author-owned after scaffold creation. |
+| lockfile | Dependency resolution. Commit when dependency changes are intentional. |
+| `tsconfig.json`, `vite.config.ts` | TypeScript and Vite build configuration. |
+| `index.html` | Vite HTML entry and portal mount element. |
+| `README.md` | Human setup, lifecycle, and recovery guidance. |
+| `AGENTS.md`, `CLAUDE.md` | Root coding-agent guidance. `CLAUDE.md` points to the canonical `AGENTS.md`. |
+| `portal/definition.json` | Pulled or author-edited portal metadata. Its `$schema` owns valid fields. |
+| `portal/screens/` | Local screen resources. File names are screen slugs. |
+| `portal/navigations/` | Local web or mobile navigation resources. References use file slugs. |
+| `portal/profiles/` | Profile matching and navigation/theme assignments. |
+| `portal/themes/` | Complete theme resources. Partial theme configs are invalid. |
+| `.portal-sync/` | Pull/push snapshots used for drift and diff calculation. Generated; never edit or commit. |
+| `src/main.tsx` | Portal shell entry. |
+| `src/portal.config.ts` | Custom React page registration and portal shell configuration. |
+| `src/widgets.config.ts` | Company widget package registration for development and `fluid portal deploy`. |
+| `src/widgets/` | Company Remote DOM widget source when present. |
+| `src/index.css` | Portal shell styling. Use portal semantic theme tokens. |
+| `src/vite-env.d.ts` | Vite environment type declarations. |
+| `.github/workflows/deploy.yml` | CDN build and shell-asset deployment workflow. |
+| `.agents/skills/fluid-portal-authoring/` | Portal task procedures and reference guidance. |
+| `.agents/skills/fluid-widget-authoring/` | Widget task procedures and reference guidance. |
+| `.claude/skills/` | Compatibility view of the same skills. Do not maintain divergent instructions. |
+| `dist/` | Generated portal shell assets from `pnpm build`. |
+| `.fluid/widget-dist/` | Generated company widget publication artifacts. |
+| `.fluid/widget-build/`, `.fluid/tmp/` | Generated temporary widget build state. |
+| `.fluid-portal-scaffold-pending` | Transient create/clone marker used during interrupted scaffolds. |
+| `node_modules/` | Installed dependencies. Generated. |
+
+## Environment
+
+| Variable | Use |
+| --- | --- |
+| `VITE_API_URL` | Optional browser BFF override. When absent, dev resolves the signed-in company and proxies `/api` to its tenant portal host. |
+| `VITE_ASSET_BASE` | Production base URL for portal shell assets. |
+| `FLUID_API_BASE` | Optional Fluid CLI API-base override. |
+| `FLUID_API_TOKEN` | Fluid CLI token. The older `FLUID_TOKEN` name is also accepted. |
+
+## Edit, validate, and review
+
+Edit only the required resources under `portal/`. Follow each file's `$schema`.
+The file name, not the display name, is the slug used by navigation, profiles,
+and theme references. Use each resource's schema for the exact widget-tree and
+cross-reference contract.
 
 ```bash
 pnpm typecheck
 pnpm lint
 pnpm build
+pnpm exec fluid portal doctor
+git diff
 ```
 
-For visual/content changes, use local preview:
-
-```bash
-pnpm dev
-```
-
-Expected result: the portal CLI pulls the definition when `portal/` is missing, then starts the shell against the local portal JSON. Use this command instead of bare `vite` so the pull and manifest preflight run.
-
-### 4. Push local definition changes
-
-```bash
-pnpm push
-```
-
-This runs `fluid portal push`, compares local `portal/` JSON against sync state, and updates the remote working/draft definition.
-
-Push does **not** publish changes live by itself.
-
-### 5. Publish a live Fluid OS version
-
-When the pushed working/draft definition is ready for users:
-
-```bash
-pnpm exec fluid portal version create --activate
-```
+Before a remote write, run `pnpm pull` when the remote working definition may
+have changed. If local and remote changes conflict, preserve local edits, pull
+the current state, reapply the intended change, and review the new diff.
 
-Only run this when activation is intended. If publishing needs content, design, or release approval, stop and ask first.
+## Push and activate
 
-## Command boundaries
+Push validates and writes the remote working definition. It writes resource
+groups in phases; an earlier group can succeed before a later group fails. Fix
+the reported phase and rerun after checking remote and `.portal-sync/` state.
 
-Do not mix these up:
+Activation is separate. `fluid portal push --yes --activate` creates and
+activates a live version only after every push phase succeeds. Do not activate
+unless the task authorizes a live release.
 
-- `fluid portal pull` downloads the remote portal definition into `portal/`.
-- `fluid portal push` syncs local `portal/` JSON to the remote working/draft definition.
-- `fluid portal version create --activate` makes the remote working/draft definition live.
-- `pnpm build` creates hosted shell assets in `dist/`.
-- GitHub Actions deploys hosted shell assets from `dist/`.
-- `fluid portal deploy` publishes company-owned widget runtime artifacts. It does not push portal JSON and does not upload hosted shell assets.
+A network-enabled third-party widget requires interactive approval. In a
+non-interactive run, add `--allow-network-widgets`; `--yes` alone does not grant
+network access. The grant is exact to package ID, package version, and
+capability version and becomes stale when any value changes.
 
-## Widget work
+## Build and deployment boundaries
 
-Company-owned portal widgets are supported through the portal widget scaffold:
+- `pnpm build` creates portal shell assets in `dist/`.
+- `.github/workflows/deploy.yml` uploads `dist/` to GCS and invalidates Cloud
+  CDN. Configure `GCP_PROJECT`, `GCS_BUCKET`, `CDN_URL_MAP`, `CDN_HOSTNAME`,
+  `CDN_INVALIDATION_PATH`, and repository secret `GCP_SA_JSON`.
+- `fluid portal deploy` builds and publishes company widget runtime artifacts
+  from `src/widgets.config.ts` through `.fluid/widget-dist/`.
 
-```bash
-pnpm widget:create stock-ticker
-# or
-pnpm exec fluid portal widget create stock-ticker
-```
+`fluid portal deploy` does not push portal JSON, activate a portal version, or
+upload the portal shell. The GitHub workflow does not publish portal JSON or
+widget package versions.
 
-The scaffold writes widget source under `src/widgets/<name>/` and registers its package in `src/widgets.config.ts`. Portal pages remain separate in `src/portal.config.ts`. Then use the generated widget authoring skill:
+## Detailed guidance
 
+- `.agents/skills/fluid-portal-authoring/SKILL.md`
 - `.agents/skills/fluid-widget-authoring/SKILL.md`
-- `.claude/skills/fluid-widget-authoring/SKILL.md`
-
-That skill covers canonical Remote DOM packages, property schemas, theme variables, runtime CSS, validation, build, and publish workflows.
-
-## Hosted shell deployment
-
-The included GitHub Actions workflow builds the portal and uploads `dist/` to Google Cloud Storage plus Cloud CDN.
-
-1. Push to `main` or run the workflow manually.
-2. The workflow runs `pnpm build`.
-3. It syncs `dist/` to `gs://portals-cdn/{{projectName}}/assets/`.
-4. It invalidates the CDN cache for this portal's asset prefix.
-
-Setup:
-
-1. Create a GCP service account with Storage Object Admin and Compute Load Balancer Admin roles.
-2. Add the service account JSON key as a GitHub Actions secret named `GCP_SA_JSON`.
-3. Set `CDN_HOSTNAME` in `.github/workflows/deploy.yml` to your Cloud CDN load balancer domain.
-4. Update `GCP_PROJECT` and `CDN_URL_MAP` if your project differs from the defaults.
-
-## AI authoring kit
-
-Generated projects include portable guidance for AI coding tools:
-
-- `AGENTS.md` — canonical project instructions.
-- `CLAUDE.md` — plain-file bridge to `AGENTS.md`.
-- `.agents/skills/fluid-portal-authoring/SKILL.md` — portal pull/edit/push/version workflow.
-- `.agents/skills/fluid-widget-authoring/SKILL.md` — widget authoring and validation workflow.
-- `.claude/skills/...` — Claude-compatible copies generated from the same template skill files.
-
-## Learn more
-
-- Fluid Commerce Documentation: https://docs.fluidcommerce.com
-- Vite Documentation: https://vite.dev
-- React Documentation: https://react.dev
+- Installed portal API contract:
+  `node_modules/@fluid-app/portal-sdk/authoring/portal-api/api.md`
+- Installed portal command contract:
+  `node_modules/@fluid-app/fluid-cli-portal/authoring/commands.md`