@fluid-app/fluid-cli-portal 0.1.31 → 0.1.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-portal",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Fluid CLI plugin for building portal applications",
   "files": [
     "dist",
@@ -32,7 +32,7 @@
     "p-limit": "^7.3.0",
     "prompts": "^2.4.2",
     "tsx": "^4.21.0",
-    "@fluid-app/fluid-cli": "0.1.11"
+    "@fluid-app/fluid-cli": "0.1.12"
   },
   "devDependencies": {
     "@swc/core": "^1.15.18",
@@ -44,8 +44,8 @@
     "tsdown": "^0.21.0",
     "typescript": "^5",
     "vite": "^6.0.0",
-    "@fluid-app/fluidos-api-client": "0.1.0",
-    "@fluid-app/typescript-config": "0.0.0"
+    "@fluid-app/typescript-config": "0.0.0",
+    "@fluid-app/fluidos-api-client": "0.1.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/templates/base/.gitignore.template

@@ -0,0 +1,27 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# Editor directories
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Portal sync metadata (generated by fluid portal pull/push)
+.portal-sync/
+
+# Logs
+*.log
+pnpm-debug.log*

package/templates/base/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+Guidance for AI coding tools working in this generated Fluid portal project.
+
+This project is primarily authored through the Fluid OS portal definition sync workflow. Author portal structure, routes, and content through pulled Fluid OS JSON under `portal/` unless a human explicitly asks for a different architecture.
+
+## Source of truth
+
+- Use `.agents/skills/fluid-portal-authoring/SKILL.md` for portal definition work.
+- Use `.agents/skills/fluid-widget-authoring/SKILL.md` for company widget creation with `pnpm widget:create`, widget manifests, property schemas, runtime CSS, validation, build, and publish work.
+- `.claude/skills/...` contains the same generated skills for Claude-compatible tools.
+
+## Portal workflow
+
+1. Run `pnpm pull` to sync the remote Fluid OS definition into `portal/`.
+2. Edit the pulled JSON under `portal/`.
+3. Validate locally with `pnpm typecheck`, `pnpm lint`, and `pnpm build` when applicable.
+4. Run `pnpm push` to sync local `portal/` JSON back to the remote working/draft definition.
+5. Run `pnpm exec fluid portal version create --activate` only when the pushed definition should become live.
+
+Do not edit `.portal-sync/` by hand. It is generated sync metadata.
+
+## Command boundaries
+
+- `pnpm pull` / `fluid portal pull`: downloads the portal definition into `portal/`.
+- `pnpm push` / `fluid portal push`: updates the remote working/draft definition from local JSON.
+- `fluid portal version create --activate`: publishes the remote working/draft definition as the live version.
+- `pnpm build`: builds the hosted portal shell assets into `dist/`.
+- `fluid portal deploy`: publishes company-owned widget runtime artifacts, not portal JSON and not shell assets.
+
+## Quality bar
+
+- Keep portal JSON valid and references consistent.
+- Preserve stable IDs and slugs unless the change intentionally renames them.
+- Keep the portal shell thin; do not fork SDK internals into this app.
+- For widget changes, use `pnpm widget:create <name>` / `fluid portal widget create <name>` and follow the copied `fluid-widget-authoring` skill before editing manifests or schemas.

package/templates/base/skills/fluid-portal-authoring/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: fluid-portal-authoring
+description: Use when modifying this generated Fluid portal project through the supported pull/edit/push/version workflow, including portal/ JSON, themes, navigations, screens, profiles, local validation, and distinguishing portal definition sync from widget artifact deployment.
+---
+
+# Fluid Portal Authoring
+
+Use this skill before changing a generated Fluid portal project.
+
+## Supported authoring model
+
+This template is a Fluid portal shell plus a local copy of the Fluid OS portal definition.
+The supported workflow is:
+
+1. Pull the remote portal definition into `portal/`.
+2. Edit the pulled JSON files locally.
+3. Validate and preview locally.
+4. Push the JSON changes back to the remote working/draft definition.
+5. Create and activate a version when the pushed definition should go live.
+
+In generated portal projects, routes, portal structure, screens, themes, profiles, and definition metadata are owned by Fluid OS JSON under `portal/` after pull.
+
+## Important files and directories
+
+- `src/main.tsx`: portal shell bootstrap. Keep this small.
+- `src/portal.config.ts`: portal SDK integration and widget/package exports when present.
+- `src/index.css`: app-level CSS imports and global styles.
+- `portal/`: pulled Fluid OS definition JSON. This is the primary editing surface for portal content.
+- `.portal-sync/`: generated sync metadata used by pull/push diffing. Do not edit by hand.
+- `.fluidrc`: generated CLI profile binding for this portal project.
+- `.agents/skills/fluid-widget-authoring/SKILL.md`: widget authoring guidance when this portal owns widget packages or widget manifests.
+
+## Pull before editing
+
+Run:
+
+```bash
+pnpm pull
+```
+
+Expected result:
+
+- `portal/` contains local JSON for Fluid OS resources such as screens, themes, navigations, profiles, and definition metadata.
+- `.portal-sync/` contains sync state used to compute future diffs.
+- `.fluidrc` pins the CLI profile when the project was created with a profile.
+
+Pull before making changes unless you intentionally want to overwrite local work. If local JSON and remote state may both have changed, inspect the diff before pushing.
+
+## Edit pulled portal JSON
+
+Work inside `portal/` for portal definition changes.
+
+Guidelines:
+
+- Keep JSON valid and deterministic.
+- Preserve stable IDs, slugs, and cross-resource references unless intentionally changing them.
+- Update references together. If a navigation item points to a screen/theme/profile slug or ID, make sure the target exists in `portal/`.
+- Prefer small, reviewable edits. One portal content change per PR is easier to validate.
+- Do not hand-edit `.portal-sync/`; it is sync metadata, not source content.
+- Do not invent unsupported fields. Match the shapes produced by `pnpm pull`.
+
+## Validate locally
+
+Run the checks that match the change:
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm build
+```
+
+For portal JSON changes, also run a push dry run or validation command if available in your CLI version. If a command reports broken cross-references, fix the JSON references before pushing.
+
+Use local preview for visual/content changes:
+
+```bash
+pnpm dev
+```
+
+Expected result: the portal shell starts and can load the local pulled portal definition for preview where supported by the SDK/tooling.
+
+## Push definition changes
+
+Run:
+
+```bash
+pnpm push
+```
+
+What push does:
+
+- Reads local `portal/` JSON.
+- Compares it against `.portal-sync/` state.
+- Shows or applies a diff to the remote working/draft Fluid OS definition.
+- Updates the remote draft/working state.
+
+What push does not do:
+
+- It does not create a live Fluid OS version by itself.
+- It does not upload hosted portal shell assets from `dist/`.
+- It does not publish widget runtime artifacts.
+
+After a successful push, inspect the remote portal definition if possible and run the app locally or against the target environment.
+
+## Publish a live portal version
+
+After pushing and verifying the working/draft definition, create and activate a version when the change should become live:
+
+```bash
+pnpm exec fluid portal version create --activate
+```
+
+Use this only when the pushed definition is ready for users. If activation should be coordinated with a release or content review, stop and ask the project owner before running it.
+
+## Distinguish the three deploy/sync paths
+
+Do not mix these up:
+
+- `pnpm push` / `fluid portal push`: syncs `portal/` JSON to the remote working/draft Fluid OS definition.
+- `fluid portal version create --activate`: snapshots the remote working/draft definition and makes it live.
+- GitHub Actions or hosting deployment: uploads the built portal shell assets from `dist/`.
+- `fluid portal deploy`: publishes company-owned widget runtime artifacts. It is not the portal JSON push command and it is not the hosted shell asset deployment.
+
+## Widget work inside a portal project
+
+Company-owned portal widgets are still supported. Use the widget scaffold command, then follow the copied `fluid-widget-authoring` skill for detailed manifest, property schema, theme token, validation, build, and publish rules.
+
+```bash
+pnpm widget:create my-widget
+# or
+pnpm exec fluid portal widget create my-widget
+```
+
+Short version:
+
+- Keep widget code under the scaffolded `src/widgets/<name>/` directory.
+- Keep widget metadata serializable.
+- Keep `defaultProps` aligned with property schema defaults.
+- Use semantic theme tokens.
+- Import runtime CSS from the widget build graph.
+- Validate/build widget artifacts before publishing them.
+
+## Preflight checklist
+
+Before considering portal work complete:
+
+- [ ] Pulled the latest remote definition or intentionally worked from current local JSON.
+- [ ] Edited only supported files for the change.
+- [ ] Preserved JSON validity and cross-resource references.
+- [ ] Kept portal structure, routes, and content changes in pulled Fluid OS JSON under `portal/`.
+- [ ] Ran typecheck/lint/build or the closest available checks.
+- [ ] Ran push only when the local `portal/` diff was understood.
+- [ ] Created/activated a version only when the definition should go live.

package/templates/base/src/main.tsx

@@ -1,5 +1,5 @@
 import { createPortal } from "@fluid-app/portal-sdk";
-import { customPages, customWidgets } from "./portal.config";
+import { customWidgets } from "./portal.config";
 import "./index.css";
 
-createPortal({ customPages, customWidgets });
+createPortal({ customWidgets });

package/templates/base/src/portal.config.ts

@@ -1,40 +1,14 @@
-/**
- * Portal Configuration
- *
- * Register custom page components and widget plugins here.
- *
- * - customPages: rendered by AppShell when a navigation slug matches
- * - customWidgets: registered as plugin widgets in the builder and SDK
- *
- * Navigation structure is defined in navigation.config.ts and synced
- * to the Fluid OS API on `fluid deploy`.
- */
-
-import type { ComponentType } from "react";
 import type { WidgetManifest } from "@fluid-app/portal-sdk";
-import { DashboardScreen } from "./screens/Dashboard";
 
 /**
- * Custom page components keyed by navigation slug.
+ * Portal SDK integration point.
  *
- * When AppShell resolves a navigation item, it checks this map first.
- * If a matching slug is found here, the custom component is rendered
- * instead of the default system screen or placeholder.
- */
-export const customPages: Record<string, ComponentType> = {
-  dashboard: DashboardScreen,
-  // Add more custom screens here:
-  // "example-form": ExampleFormScreen,
-};
-
-/**
- * Custom widget plugins.
+ * Portal screens, themes, navigations, and profiles are authored through
+ * the Fluid OS definition sync workflow: `pnpm pull`, edit `portal/`,
+ * then `pnpm push`. Keep portal structure, routes, and content in the
+ * pulled Fluid OS JSON files.
  *
- * Each manifest registers a widget in both the builder palette
- * and the SDK runtime. Add manifests here after scaffolding
- * with `fluid widget create <name>`.
+ * Keep this file for widget manifests or source widget packages that need
+ * to be available to the SDK preview/runtime.
  */
-export const customWidgets: WidgetManifest[] = [
-  // Import and add widget manifests here:
-  // stockTicker,
-];
+export const customWidgets: WidgetManifest[] = [];