showpane 0.4.1 → 0.4.2

package/bundle/toolchain/skills/portal-dev/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: portal-dev
+description: |
+  Start the local development server for Showpane. Quick way to preview portals during development.
+  Trigger phrases: "portal dev", "start dev server", "run showpane locally", "start the server". (showpane)
+allowed-tools: [Bash, Read]
+---
+
+## Preamble (run first)
+
+This skill uses a simplified preamble — no version check or learnings loading needed for starting a dev server.
+
+```bash
+# Read config
+CONFIG="$HOME/.showpane/config.json"
+if [ ! -f "$CONFIG" ]; then
+  echo "Showpane not configured. Run /portal setup first."
+  exit 1
+fi
+APP_PATH=$(python3 -c "import json; d=json.load(open('$CONFIG')); print(d.get('app_path',''))" 2>/dev/null)
+APP_PATH="${SHOWPANE_APP_PATH:-$APP_PATH}"
+if [ -z "$APP_PATH" ] || [ ! -d "$APP_PATH" ]; then
+  echo "App path not found: $APP_PATH"
+  echo "Run /portal setup to reconfigure."
+  exit 1
+fi
+echo "APP_PATH: $APP_PATH"
+
+# Predictive next-skill suggestion
+if [ -f "$HOME/.showpane/timeline.jsonl" ]; then
+  _RECENT=$(grep '"event":"completed"' "$HOME/.showpane/timeline.jsonl" 2>/dev/null | tail -3 | grep -o '"skill":"[^"]*"' | sed 's/"skill":"//;s/"//' | tr '\n' ',' | sed 's/,$//')
+  [ -n "$_RECENT" ] && echo "RECENT_SKILLS: $_RECENT"
+fi
+
+# Search relevant learnings
+LEARN_FILE="$HOME/.showpane/learnings.jsonl"
+if [ -f "$LEARN_FILE" ]; then
+  _LEARN_COUNT=$(wc -l < "$LEARN_FILE" 2>/dev/null | tr -d ' ')
+  echo "LEARNINGS: $_LEARN_COUNT entries"
+  if [ "$_LEARN_COUNT" -gt 0 ] 2>/dev/null; then
+    echo "RECENT_LEARNINGS:"
+    tail -5 "$LEARN_FILE" 2>/dev/null
+  fi
+fi
+
+# Track skill execution
+SHOWPANE_TIMELINE="$HOME/.showpane/timeline.jsonl"
+mkdir -p "$(dirname "$SHOWPANE_TIMELINE")"
+echo '{"skill":"portal-dev","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$SHOWPANE_TIMELINE" 2>/dev/null
+```
+
+If RECENT_SKILLS is shown, suggest the likely next skill:
+- After portal-create → suggest /portal-preview
+- After portal-preview → suggest /portal-deploy or /portal-share
+- After portal-deploy → suggest /portal-status or /portal-verify
+- After portal-setup → suggest /portal-create
+- After portal-credentials → suggest /portal-share
+- After portal-update → suggest /portal-deploy
+
+If RECENT_LEARNINGS is shown, review them before proceeding. Past learnings may contain
+relevant warnings or tips for this operation. Apply them where relevant but don't
+mention them unless they directly affect the current task.
+
+## Steps
+
+### Step 1: Check if port 3000 is already in use
+
+```bash
+lsof -i :3000 -sTCP:LISTEN -t 2>/dev/null
+```
+
+If a process is listening on port 3000:
+
+1. Check if it's already a Showpane/Next.js dev server:
+   ```bash
+   lsof -i :3000 -sTCP:LISTEN 2>/dev/null | head -5
+   ```
+
+2. If it's already the Showpane dev server, inform the user:
+   > "Dev server is already running at http://localhost:3000. No action needed."
+   >
+   > Useful links:
+   > - Login page: http://localhost:3000/client
+   > - Example portal: http://localhost:3000/client/example
+
+3. If it's a different process, warn the user:
+   > "Port 3000 is in use by another process (PID: <pid>). Options:"
+   > - Kill it: `kill <pid>` then re-run `/portal dev`
+   > - Use a different port: `cd $APP_PATH && PORT=3001 npm run dev`
+
+   Ask the user how to proceed. Do not kill processes without explicit permission.
+
+### Step 2: Verify dependencies
+
+Check that node_modules exists and the Prisma client is generated:
+
+```bash
+if [ ! -d "$APP_PATH/node_modules" ]; then
+  echo "Installing dependencies..."
+  cd "$APP_PATH" && npm install
+elif [ ! -d "$APP_PATH/node_modules/.prisma" ]; then
+  echo "Generating Prisma client..."
+  cd "$APP_PATH" && npx prisma generate
+fi
+```
+
+If `npm install` is needed, wait for it to complete before starting the dev server.
+
+### Step 3: Source environment variables
+
+The dev server needs DATABASE_URL and other env vars:
+
+```bash
+if [ -f "$APP_PATH/.env" ]; then
+  echo "Loading .env from $APP_PATH"
+else
+  echo "WARNING: No .env file found at $APP_PATH/.env"
+  echo "The dev server may fail without DATABASE_URL and AUTH_SECRET."
+  echo "Create $APP_PATH/.env with at minimum:"
+  echo "  DATABASE_URL=postgresql://postgres:postgres@localhost:5432/showpane"
+  echo "  AUTH_SECRET=<any-random-string>"
+fi
+```
+
+### Step 4: Check database connectivity
+
+Before starting the dev server, verify the database is reachable. The app will fail to load pages that query the database if the connection is broken.
+
+```bash
+if [ -f "$APP_PATH/.env" ]; then
+  set -a && source "$APP_PATH/.env" && set +a
+fi
+if [ -n "$DATABASE_URL" ]; then
+  cd "$APP_PATH" && npx prisma db execute --stdin <<< "SELECT 1" 2>/dev/null
+  if [ $? -ne 0 ]; then
+    echo "WARNING: Database connection failed. Check DATABASE_URL in $APP_PATH/.env"
+    echo "The dev server will start but portal pages may not load correctly."
+  fi
+else
+  echo "WARNING: DATABASE_URL not set in $APP_PATH/.env"
+fi
+```
+
+This is a non-blocking check. If the database is down, the dev server still starts — it just won't be able to serve authenticated portal pages. Static pages and the example portal (which uses hardcoded data) will still work.
+
+### Step 5: Check for pending migrations
+
+```bash
+cd "$APP_PATH" && npx prisma migrate status 2>&1 | grep -q "pending"
+```
+
+If there are pending migrations, inform the user:
+
+> "There are pending database migrations. Run `cd $APP_PATH && npx prisma migrate dev` to apply them, or they will be applied automatically when you next run `/portal deploy`."
+
+This is informational only — do not block the dev server start.
+
+### Step 6: Start the dev server
+
+Run the dev server in the background so it doesn't block the terminal:
+
+```bash
+cd "$APP_PATH" && npm run dev
+```
+
+Use the Bash tool's `run_in_background` parameter to start it without blocking. The user will see the output when Next.js finishes compiling.
+
+If the `npm run dev` script is not defined in package.json, fall back to:
+
+```bash
+cd "$APP_PATH" && npx next dev
+```
+
+The dev server typically takes 3-10 seconds to start depending on the project size and machine speed.
+
+### Step 7: List existing portals
+
+After starting, discover which portals exist so the user has useful links:
+
+```bash
+ls -d "$APP_PATH/src/app/(portal)/client"/*/ 2>/dev/null | while read dir; do
+  slug=$(basename "$dir")
+  echo "$slug"
+done
+```
+
+### Step 8: Confirm startup and show links
+
+Present a clean summary:
+
+```
+Dev server starting at http://localhost:3000
+
+  Login page:      http://localhost:3000/client
+  Example portal:  http://localhost:3000/client/example
+```
+
+If the user has created portals, also list them:
+
+```
+  Your portals:
+    - http://localhost:3000/client/acme-health
+    - http://localhost:3000/client/beta-corp
+```
+
+Then show tips:
+
+```
+Tips:
+  - Create a portal:   /portal create <slug>
+  - Edit a portal:     /portal update <slug>
+  - View all portals:  /portal list
+  - Hot reload is ON:  edits to portal files appear instantly
+  - Stop the server:   Ctrl+C in the terminal, or kill the process
+```
+
+## Error Handling
+
+### Port conflict resolution
+If port 3000 is occupied by a non-Showpane process:
+- Show the PID and process name
+- Offer two options: kill the process (with explicit permission) or use PORT=3001
+- If using an alternate port, update all the links shown to the user
+
+### npm run dev fails immediately
+Common causes:
+- **Missing .env**: Next.js may require certain env vars at build time. Check for required vars.
+- **Port already in use**: Covered in Step 1 but can race if something starts between the check and the dev server launch.
+- **Node version mismatch**: Showpane requires Node.js 18+. Check with `node --version`.
+- **Corrupted node_modules**: Suggest `rm -rf $APP_PATH/node_modules && cd $APP_PATH && npm install`.
+
+### Database-related page errors
+If the dev server starts but portal pages show errors:
+- Check the terminal output for Prisma errors
+- Verify DATABASE_URL is correct and the database server is running
+- Run `cd $APP_PATH && npx prisma migrate dev` to ensure the schema is up to date
+- Run `cd $APP_PATH && npx prisma generate` to regenerate the Prisma client if the schema changed
+- If using Docker for the database, ensure the database container is running: `docker compose ps`
+- Check that the database user has the correct permissions for the showpane database
+
+## Working with the Dev Server
+
+### Hot reload behavior
+
+The Next.js dev server watches all files under `src/` for changes. When you edit a portal's client component file, the browser automatically updates without a full page reload. This means:
+
+- Editing tab content: reflected instantly in the browser
+- Adding a new tab: reflected instantly
+- Changing PortalShell props: reflected instantly
+- Adding a new portal directory: requires navigating to the new URL manually (hot reload only works on already-loaded pages)
+- Changing `prisma/schema.prisma`: requires restarting the dev server after running `npx prisma generate`
+
+### Accessing portals during development
+
+Portals in development can be accessed in two ways:
+
+1. **Direct URL**: Navigate to `http://localhost:3000/client/<slug>` — this bypasses authentication during local development if the portal doesn't have credentials set yet
+2. **Login page**: Navigate to `http://localhost:3000/client` — use this to test the full authentication flow with credentials created via `/portal credentials`
+
+The example portal at `/client/example` always works without authentication and is a useful reference while building new portals.
+
+### Stopping the dev server
+
+The dev server can be stopped in several ways:
+- `Ctrl+C` in the terminal where it's running
+- `kill <pid>` using the PID shown during startup
+- Running `lsof -i :3000 -sTCP:LISTEN -t | xargs kill` to find and kill whatever is on port 3000
+
+### Using a different port
+
+If port 3000 is reserved for another project, set the PORT environment variable:
+
+```bash
+cd "$APP_PATH" && PORT=3001 npm run dev
+```
+
+When using a non-standard port, all portal URLs change accordingly (e.g., `http://localhost:3001/client/<slug>`).
+
+## Completion
+
+As a final step, log skill completion:
+
+```bash
+echo '{"skill":"portal-dev","event":"completed","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$HOME/.showpane/timeline.jsonl" 2>/dev/null
+```
+
+## Conventions
+
+- Never kill processes on port 3000 without explicit user permission
+- Use the simplified preamble — dev server startup should be fast, not a health check
+- If dependencies are missing, install them automatically (no need to ask)
+- Show useful links after startup (login page, example portal, user's portals)
+- The dev server uses Next.js hot reload — edits to portal files are reflected immediately without restarting
+- If .env is missing, warn but still try to start (the server will show its own error)
+- Keep the output minimal and scannable — the user wants to get to work, not read documentation
+- Database and migration checks are informational, not blocking — let the dev server start regardless
+- This is the most commonly run skill — optimize for speed and minimal friction
+- When the dev server is already running, do not restart it — just confirm it is running and show the links
+- If the user is starting their work session, suggest `/portal dev` followed by `/portal create` or `/portal update` as the natural workflow
+- The dev server process belongs to the user's terminal session — do not try to daemonize it or manage it as a background service
+- If the user closes their terminal, the dev server stops — this is expected behavior for a development workflow

package/bundle/toolchain/skills/portal-list/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: portal-list
+description: |
+  List all client portals in the organization. Use when asked to "list portals",
+  "show portals", "what portals do I have", "my portals", or "all portals". (showpane)
+allowed-tools: [Bash, Read, Glob, Grep]
+---
+
+## Preamble (run first)
+
+Before doing anything else, execute this block in a Bash tool call:
+
+```bash
+CONFIG="$HOME/.showpane/config.json"
+if [ ! -f "$CONFIG" ]; then
+  echo "Showpane not configured. Run /portal setup first."
+  exit 1
+fi
+APP_PATH=$(cat "$CONFIG" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('app_path',''))" 2>/dev/null)
+DEPLOY_MODE=$(cat "$CONFIG" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('deploy_mode','docker'))" 2>/dev/null)
+ORG_SLUG=$(cat "$CONFIG" | python3 -c "import sys,json; d=json.loads(sys.stdin.read()); print(d.get('orgSlug','') or d.get('org_slug',''))" 2>/dev/null)
+APP_PATH="${SHOWPANE_APP_PATH:-$APP_PATH}"
+if [ -f "$APP_PATH/.env" ]; then set -a && source "$APP_PATH/.env" && set +a; fi
+DATABASE_URL="${DATABASE_URL:-}"
+if [ ! -d "$APP_PATH/node_modules/.prisma" ]; then
+  echo "App dependencies not installed. Run: cd $APP_PATH && npm install"
+  exit 1
+fi
+SKILL_DIR="${SHOWPANE_TOOLCHAIN_DIR:-$HOME/.showpane/current}"
+SKILL_VERSION=$(cat "$SKILL_DIR/VERSION" 2>/dev/null || echo "unknown")
+echo "SHOWPANE: v$SKILL_VERSION | MODE: $DEPLOY_MODE | APP: $APP_PATH"
+LEARN_FILE="$HOME/.showpane/learnings.jsonl"
+[ -f "$LEARN_FILE" ] && echo "LEARNINGS: $(wc -l < "$LEARN_FILE" | tr -d ' ') loaded" || echo "LEARNINGS: 0"
+
+# Predictive next-skill suggestion
+if [ -f "$HOME/.showpane/timeline.jsonl" ]; then
+  _RECENT=$(grep '"event":"completed"' "$HOME/.showpane/timeline.jsonl" 2>/dev/null | tail -3 | grep -o '"skill":"[^"]*"' | sed 's/"skill":"//;s/"//' | tr '\n' ',' | sed 's/,$//')
+  [ -n "$_RECENT" ] && echo "RECENT_SKILLS: $_RECENT"
+fi
+
+# Search relevant learnings
+LEARN_FILE="$HOME/.showpane/learnings.jsonl"
+if [ -f "$LEARN_FILE" ]; then
+  _LEARN_COUNT=$(wc -l < "$LEARN_FILE" 2>/dev/null | tr -d ' ')
+  echo "LEARNINGS: $_LEARN_COUNT entries"
+  if [ "$_LEARN_COUNT" -gt 0 ] 2>/dev/null; then
+    echo "RECENT_LEARNINGS:"
+    tail -5 "$LEARN_FILE" 2>/dev/null
+  fi
+fi
+
+# Track skill execution
+SHOWPANE_TIMELINE="$HOME/.showpane/timeline.jsonl"
+mkdir -p "$(dirname "$SHOWPANE_TIMELINE")"
+echo '{"skill":"portal-list","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$SHOWPANE_TIMELINE" 2>/dev/null
+```
+
+If RECENT_SKILLS is shown, suggest the likely next skill:
+- After portal-create → suggest /portal-preview
+- After portal-preview → suggest /portal-deploy or /portal-share
+- After portal-deploy → suggest /portal-status or /portal-verify
+- After portal-setup → suggest /portal-create
+- After portal-credentials → suggest /portal-share
+- After portal-update → suggest /portal-deploy
+
+If RECENT_LEARNINGS is shown, review them before proceeding. Past learnings may contain
+relevant warnings or tips for this operation. Apply them where relevant but don't
+mention them unless they directly affect the current task.
+
+## Overview
+
+This skill retrieves all portals belonging to the current organization and displays them as a formatted table in the terminal. It is the quickest way to see what portals exist, their status, and when they were last updated. It is also a good starting point before running other portal-specific skills -- users often run `/portal list` to find a slug before using `/portal analytics`, `/portal share`, or `/portal preview`.
+
+## Steps
+
+### Step 1: Query all portals
+
+Run the list script:
+
+```bash
+cd $APP_PATH && NODE_PATH="$APP_PATH/node_modules" npx tsx --tsconfig $APP_PATH/tsconfig.json $SKILL_DIR/bin/list-portals.ts --org-id <org_id>
+```
+
+Use the `ORG_SLUG` from the preamble output to determine the `org_id`. The script resolves the org slug to an ID internally if needed.
+
+Expected success response:
+
+```json
+{
+  "ok": true,
+  "orgName": "Demo Company",
+  "portals": [
+    {
+      "slug": "whzan",
+      "companyName": "Whzan Digital Health",
+      "isActive": true,
+      "lastUpdated": "2026-04-02T10:00:00Z",
+      "hasCredentials": true,
+      "tabCount": 4
+    },
+    {
+      "slug": "acme",
+      "companyName": "Acme Corp",
+      "isActive": true,
+      "lastUpdated": "2026-04-05T14:22:00Z",
+      "hasCredentials": true,
+      "tabCount": 3
+    }
+  ],
+  "total": 2
+}
+```
+
+If the script exits with a non-zero code, read stderr. Common errors:
+
+- `org_not_found`: The organization slug from config does not exist in the database. The user may need to re-run `/portal setup`.
+- `database_error`: Connection issue. Check that DATABASE_URL is correct and the database is accessible.
+
+### Step 2: Format as an ASCII table
+
+Present the portal list in a clean, scannable format:
+
+```
+PORTALS (Demo Company)
+════════════════════════════════════════
+  Slug        Company              Status    Last Updated
+  ─────────── ──────────────────── ───────── ────────────
+  whzan       Whzan Digital Health Active    2 Apr 2026
+  acme        Acme Corp            Active    5 Apr 2026
+  example     Example Portal       Active    6 Apr 2026
+════════════════════════════════════════
+  3 portals total
+```
+
+Column definitions:
+
+- **Slug**: The URL-safe identifier used in the portal path (`/client/<slug>`).
+- **Company**: The client company name displayed in the portal header.
+- **Status**: "Active" for portals with `isActive: true`. "Inactive" for deactivated portals. Inactive portals should be displayed in the table but noted as such.
+- **Last Updated**: The date the portal content or configuration was last modified. Format as `DD Mon YYYY`.
+
+### Step 3: Handle empty state
+
+If the organization has zero portals, do not show an empty table. Instead, display:
+
+```
+PORTALS (Demo Company)
+════════════════════════════════════════
+  No portals yet.
+  
+  Create your first portal: /portal create <slug>
+════════════════════════════════════════
+```
+
+This guides new users toward the next action. If the user ran `/portal onboard`, they would have gone through this already, but many users will discover the CLI skill-by-skill.
+
+### Step 4: Add contextual hints
+
+After the table, provide brief contextual guidance based on what the list reveals:
+
+- **All portals active, credentials set**: No additional notes needed. The list is self-explanatory.
+- **Portal without credentials**: Append a note: "Portal 'example' has no credentials. Run /portal credentials example to set up access."
+- **Inactive portals present**: "1 inactive portal not shown. Use --all to include inactive portals." (The `--all` flag can be passed to `list-portals.ts`.)
+- **Large number of portals (10+)**: Consider grouping or paginating. For now, just show all of them -- the terminal handles scrolling.
+
+Keep hints to one line each. Do not over-explain.
+
+## Filtering and Sorting
+
+The default sort order is by `lastUpdated` descending (most recently updated first). This puts the portals the user is actively working on at the top.
+
+If the user asks to filter (e.g., "show only active portals" or "portals updated this week"), apply the filter before formatting. Common filters:
+
+- `--active-only` (default): Only show portals with `isActive: true`.
+- `--all`: Include inactive/deactivated portals.
+- `--updated-since <date>`: Only portals updated after the given date.
+
+Pass these flags through to the `list-portals.ts` script if the user requests them.
+
+## Conventions
+
+- Always show the organization name in the header so the user has context about which org they are viewing.
+- Format dates as `DD Mon YYYY` (e.g., "2 Apr 2026"). Do not show times in the list view -- they add clutter without value at this level.
+- Right-pad string columns for alignment. The table should look clean even with varying slug and company name lengths.
+- Use double-line box drawing (`═`) for outer borders and single-line (`─`) for the header separator.
+- If the response includes `tabCount`, do not show it in the default table. It is available for other skills (like `/portal status`) but too detailed for a list view.
+- The footer line ("3 portals total") should always be present, even for a single portal ("1 portal total").
+
+## Error Handling
+
+- If the preamble fails, stop and display the error. Do not attempt to query the database.
+- If the database query fails, show the error from stderr and suggest checking the connection: "Database query failed. Verify your DATABASE_URL is correct and the database is running."
+- If the org is not found, suggest re-running `/portal setup` to reconfigure.
+
+## Data Freshness
+
+The list data comes directly from the database at query time. It reflects the current state of all portals, including any changes made moments ago. There is no caching layer. If the user just created a portal with `/portal create`, it will appear in the list immediately.
+
+The `lastUpdated` timestamp reflects when the portal's database record was last modified. This includes credential changes, status changes, and metadata updates. It does NOT reflect when the portal's React source files were last edited -- file changes are tracked by git, not the database.
+
+## Multi-Organization Support
+
+In v1, Showpane supports a single organization per installation. The `org_id` parameter is always derived from the config. Future versions may support multiple organizations, at which point the list skill would accept an `--org` flag to filter.
+
+If the user asks about portals in a different organization, explain: "Showpane is configured for organization '<orgSlug>'. To work with a different org, update your config: edit ~/.showpane/config.json and change the orgSlug value, or set it via environment variable."
+
+## Output as Input
+
+The list output is designed to be scannable and to feed into other skills. When a user sees the list and asks to do something with a specific portal (e.g., "show analytics for whzan"), the slug is immediately available from the list.
+
+If the user follows up with an action after seeing the list, carry the context forward. Do not ask them to re-specify the slug if they just referenced it from the list output.
+
+## Learnings Integration
+
+The list skill does not write learnings. It is a read-only query. However, if learnings indicate that the user has a preferred portal or frequently works with a specific client, you can highlight that portal in the output (e.g., bold the slug or add a note like "recently active").
+
+## Portal Lifecycle States
+
+Portals have two states in the database:
+
+- **Active** (`isActive: true`): The portal is accessible to clients. It appears in the default list view. This is the normal operating state.
+- **Inactive** (`isActive: false`): The portal has been deactivated via `/portal delete`. It is hidden from the default list view but still exists in the database. Page files may or may not still be in the repository.
+
+There is no "draft" or "pending" state. A portal is either active or inactive. When `/portal create` runs, the portal is immediately active. If the user wants to prepare a portal before making it accessible, they should create it and set up credentials last -- the portal page exists but is behind the login gate.
+
+## Response Format Details
+
+The `list-portals.ts` script returns JSON with these fields per portal:
+
+- `slug` (string): URL identifier, 2-50 characters, lowercase alphanumeric and hyphens.
+- `companyName` (string): Display name of the client company.
+- `isActive` (boolean): Current status.
+- `lastUpdated` (ISO 8601 string): Last modification timestamp.
+- `hasCredentials` (boolean): Whether the portal has a username/password configured.
+- `tabCount` (number): How many tabs the portal has. Not shown in list view but used by status dashboard.
+- `createdAt` (ISO 8601 string): When the portal was first created.
+
+All fields are guaranteed to be present. None are nullable.
+
+## Completion
+
+As a final step, log skill completion:
+
+```bash
+echo '{"skill":"portal-list","event":"completed","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> "$HOME/.showpane/timeline.jsonl" 2>/dev/null
+```
+
+## Related Skills
+
+- `/portal status` -- richer view with health scores and activity data
+- `/portal analytics` -- deep dive into a specific portal's engagement
+- `/portal create` -- create a new portal
+- `/portal delete` -- deactivate a portal from this list