spine-framework 0.3.145 → 0.4.0

package/custom/.devin/AGENT.md

@@ -1,357 +0,0 @@
-# Spine Framework — Custom Apps Agent Guide
-
-This document explains the structure, contract, and tooling for apps under `custom/apps/`. Read this before touching any app code.
-
----
-
-## Directory Layout
-
-Every app lives at `custom/apps/{slug}/` and must follow this structure:
-
-```
-custom/apps/{slug}/
-├── package.json          # npm identity + spine metadata block
-├── manifest.json         # runtime contract — the source of truth
-├── index.tsx             # default export: root React component
-├── components/           # app-level shared components (sidebar, cards, etc.)
-├── pages/                # route-mapped page components
-│   └── {section}/
-│       └── SomePage.tsx
-├── functions/            # Netlify function handlers scoped to this app
-├── hooks/                # React hooks
-├── utils/                # Pure utility functions
-├── public/               # Static assets copied to PROJECT_ROOT/public/ at assemble time
-└── seed/                 # Data seeded into the DB on install
-    ├── roles.json
-    ├── types.json
-    ├── link-types.json
-    └── (any other declared seed files)
-```
-
-No other top-level directories are allowed. `validate-app` will fail on unknown directories.
-
----
-
-## package.json — Required Shape
-
-```json
-{
-  "name": "spine-framework-{slug}",
-  "version": "X.Y.Z",
-  "private": false,
-  "description": "...",
-  "peerDependencies": {
-    "spine-framework": ">=0.1.0"
-  },
-  "files": [
-    "index.tsx",
-    "manifest.json",
-    "seed/",
-    "pages/",
-    "components/",
-    "hooks/",
-    "utils/",
-    "functions/",
-    "public/",
-    "README.md"
-  ],
-  "scripts": {
-    "validate": "npx spine-framework validate-app ."
-  },
-  "spine": {
-    "type": "app",
-    "slug": "{slug}",
-    "manifestPath": "manifest.json"
-  }
-}
-```
-
-**Rules:**
-- `"private": false` is required — apps must be publishable to npm
-- `files` must include every directory that exists in the app
-- `version` must match `manifest.json` version exactly
-- `spine.slug` must match `manifest.json` slug exactly
-- Package name convention: `spine-framework-{slug}`
-
----
-
-## manifest.json — Full Contract
-
-```json
-{
-  "name": "My App",
-  "slug": "my-app",
-  "description": "...",
-  "version": "X.Y.Z",
-  "app_type": "full",
-  "route_prefix": "/my-app",
-  "required_roles": ["role-slug"],
-  "routes": ["/", "/page"],
-  "nav_items": [
-    { "title": "Home", "path": "/", "icon": "Home", "order": 1 }
-  ],
-  "features": ["feature-a", "feature-b"],
-  "dependencies": ["items", "accounts"],
-  "entry_point": "./index.tsx",
-  "sidebar_component": "./components/MyAppSidebar.tsx",
-  "seed": [
-    { "file": "seed/roles.json",     "table": "roles",      "conflict": "app_id,slug" },
-    { "file": "seed/types.json",      "table": "types",      "conflict": "app_id,kind,slug" },
-    { "file": "seed/link-types.json", "table": "link_types", "conflict": "app_id,slug" }
-  ],
-  "registration": {
-    "enabled": true,
-    "default_role": "role-slug",
-    "redirect_path": "/my-app",
-    "account_strategy": "new"
-  }
-}
-```
-
-### Field Reference
-
-| Field | Required | Notes |
-|-------|----------|-------|
-| `name` | yes | Display name — written to `apps.name` in DB |
-| `slug` | yes | Unique identifier — written to `apps.slug` |
-| `version` | yes | Must match `package.json` version |
-| `app_type` | yes | One of: `full`, `ui`, `backend`, `data` |
-| `route_prefix` | yes | Where the app is mounted (e.g. `/cortex`, `/`, `/workspace`). Single source of truth for routing. |
-| `required_roles` | yes | Array of role slugs required to access the app |
-| `routes` | recommended | Root-relative paths the app handles — **must NOT include route_prefix** |
-| `nav_items` | recommended | Root-relative sidebar nav paths — **must NOT include route_prefix** |
-| `entry_point` | yes (full/ui) | Path to root React component (relative to app root) |
-| `sidebar_component` | yes (full/ui) | Path to sidebar component — used by AppWrapper |
-| `seed` | yes | Declares all seed files (see below) |
-| `registration` | if app supports self-registration | Controls `spine.config.json` registration entry |
-
-### `app_type` values
-
-- `full` — has UI (pages, components) and backend (functions). Requires `index.tsx`, `pages/`, `functions/`
-- `ui` — frontend only. Requires `index.tsx`, `pages/`
-- `backend` — functions only. Requires `functions/`
-- `data` — schema/seed only. No UI or functions required
-
----
-
-## Dynamic route_prefix
-
-`route_prefix` in `manifest.json` is the **single source of truth** for where an app is served. Changing it and running `update-db-app` is the only step needed to move an app to a different URL.
-
-### How it flows
-
-1. `manifest.json` declares `"route_prefix": "/cortex"` (or `/`, or anything)
-2. `install-app` / `update-db-app` writes it to `apps.route_prefix` in the DB
-3. `App.tsx` reads all app records and mounts each at `{route_prefix}/*`
-4. Inside the app, `useAppPath()` prepends the prefix to all links — no hardcoded paths
-
-### Rules for routes and nav_items
-
-Routes and nav_items must be **root-relative** — declared from the app's own root, not the full URL:
-
-```json
-// CORRECT
-"route_prefix": "/cortex",
-"routes": ["/", "/dashboard", "/crm/accounts"],
-"nav_items": [{ "title": "Dashboard", "path": "/dashboard" }]
-
-// WRONG — validate-app will reject these
-"routes": ["/cortex", "/cortex/dashboard", "/cortex/crm/accounts"],
-"nav_items": [{ "title": "Dashboard", "path": "/cortex/dashboard" }]
-```
-
-### useAppPath() hook
-
-All absolute links inside an app must use `useAppPath()` instead of hardcoded strings:
-
-```tsx
-import { useAppPath } from '@core/hooks/useAppPath'
-
-function MyComponent() {
-  const appPath = useAppPath()
-
-  return <a href={appPath('/dashboard')}>Dashboard</a>
-  // → '/cortex/dashboard' if route_prefix is /cortex
-  // → '/dashboard'        if route_prefix is /
-}
-```
-
-Use `useAppPath()` in: sidebar nav arrays, breadcrumbs, `navigate()` calls, any `<Link>` with an absolute path.
-
-### Changing an app's location
-
-```bash
-# 1. Edit manifest.json
-"route_prefix": "/"   # was "/cortex"
-
-# 2. Sync to DB (no npm, no file changes)
-npx spine-framework update-db-app cortex
-
-# 3. Rebuild and serve
-npm run assemble && netlify dev
-```
-
-That's the entire workflow. No code changes needed.
-
----
-
-## Seed Block
-
-The `seed` array in `manifest.json` declares every file to be seeded into the DB at install time. `install-app` reads this array and runs a generic upsert loop — no hardcoded file names.
-
-### Seed entry format
-
-```json
-{ "file": "seed/roles.json", "table": "roles", "conflict": "app_id,slug" }
-```
-
-| Field | Required | Notes |
-|-------|----------|-------|
-| `file` | yes | Path relative to app root |
-| `table` | yes | Supabase table name |
-| `conflict` | yes | Column(s) for `onConflict` upsert (comma-separated) |
-| `inject_app_id` | no | Default `true` — set `false` for tables without `app_id` |
-
-### Common conflict keys
-
-| Table | conflict |
-|-------|----------|
-| `roles` | `app_id,slug` |
-| `types` | `app_id,kind,slug` |
-| `link_types` | `app_id,slug` |
-| `triggers` | `app_id,name` |
-
-### Seed file format
-
-Every seed file must be a JSON array. Each object maps to one DB row. Do NOT include `id` or `app_id` — these are set by the framework at install time.
-
-```json
-[
-  {
-    "slug": "my-role",
-    "name": "My Role",
-    "description": "...",
-    "permissions": ["*"],
-    "is_system": true,
-    "is_active": true,
-    "is_protected": false
-  }
-]
-```
-
-All seed files must be idempotent — safe to run against an existing DB without creating duplicates.
-
----
-
-## registration block
-
-Controls how users self-register for this app. Written to `spine.config.json` by `install-app`.
-
-```json
-"registration": {
-  "enabled": true,
-  "default_role": "member",
-  "redirect_path": "/portal",
-  "account_strategy": "new"
-}
-```
-
-| `account_strategy` | Behavior |
-|--------------------|----------|
-| `new` | Creates a new account per registering user (customer-facing apps) |
-| `existing` | Assigns user to an existing account — requires `target_account` |
-| `choice` | User chooses at registration |
-
-If `account_strategy` is `existing`, `target_account` (account slug) is required.
-
----
-
-## CLI Commands
-
-```bash
-# Install an app from npm (first time)
-npx spine-framework install-app spine-framework-{slug}
-npx spine-framework install-app spine-framework-{slug}@next  # pre-release
-
-# Sync local manifest.json changes to the DB (no npm, no file changes)
-# Use this after changing route_prefix, nav_items, registration, etc.
-npx spine-framework update-db-app {slug}
-
-# Validate an app before publishing
-npx spine-framework validate-app custom/apps/{slug}
-# or from inside the app directory:
-npm run validate
-
-# Uninstall an app
-npx spine-framework uninstall-app spine-framework-{slug}
-
-# Update app code from npm (preserves local manifest.json)
-npx spine-framework update-app spine-framework-{slug}
-```
-
-**Key distinction:**
-- `install-app` = get/update code from npm. After first install, `manifest.json` is preserved — the developer owns it.
-- `update-db-app` = push local manifest changes to DB. No npm involved.
-
-`validate-app` checks:
-- `manifest.json` present, valid JSON, all required fields
-- `package.json` present, versions match, `"private": false`
-- Required files exist for `app_type`
-- `entry_point` and `sidebar_component` files exist (if declared)
-- `seed` block entries are valid and all declared files exist
-- `registration.account_strategy: "existing"` has `target_account`
-- No unknown directories
-- `.devin/` present → must contain `AGENTS.md` or `AGENT.md`
-- All directories in `files` array are present
-
----
-
-## Assemble
-
-`assemble-frontend.sh` and `assemble-functions.sh` pick up app files at build time:
-
-- `functions/` → assembled into the Netlify functions directory
-- `public/` → copied to `PROJECT_ROOT/public/` (Vite's publicDir)
-- `pages/`, `components/`, `hooks/`, `utils/` → assembled into `.assembled/src/{slug}/`
-
-**Important:** `public/` assets must go to `PROJECT_ROOT/public/`, not `.assembled/src/public/`. This was a known bug fixed in `spine-framework@0.3.76`.
-
----
-
-## Publishing
-
-Apps are published independently to npm, separate from `spine-framework`.
-
-```bash
-# From inside custom/apps/{slug}/
-npm version patch   # bump version (must match manifest.json!)
-# Also bump version in manifest.json to match
-npm publish --tag next --access public   # pre-release
-npm publish --tag latest --access public # stable release
-```
-
-Always publish with `--tag next` for development/testing. Promote to `--tag latest` only when stable and tested E2E in a dogfood project.
-
-Version must be kept in sync between `package.json` and `manifest.json` — `validate-app` will fail if they differ.
-
----
-
-## Current Apps
-
-| Slug | Package | Description |
-|------|---------|-------------|
-| `cortex` | `spine-framework-cortex` | Internal workspace: CRM, Support, Community, KB |
-| `portal` | `spine-framework-portal` | Customer-facing: Tickets, KB, Courses, Community |
-
----
-
-## Adding a New App
-
-1. Create `custom/apps/{slug}/` with the directory structure above
-2. Write `package.json` and `manifest.json` following the templates above
-3. Write `index.tsx` exporting the root React component
-4. Write `components/{Slug}Sidebar.tsx` and declare it as `sidebar_component`
-5. Write seed files and declare them in the `seed` block
-6. Run `npm run validate` — fix all errors before proceeding
-7. Publish with `--tag next`
-8. Test E2E: `npx spine-framework install-app spine-framework-{slug}@next`

package/custom/.devin/skills/install-app/SKILL.md

@@ -1,39 +0,0 @@
-# Install App
-
-Installs a Spine Framework app into the custom workspace.
-
-## When to Use
-
-Use this skill when you need to:
-- Install an app package (portal, cortex, or third-party) into custom/apps/
-- Configure seed data for the app
-- Set up migrations required by the app
-
-## Installation Process
-
-1. **Copy app files** from the package to `custom/apps/<app-slug>/`
-2. **Copy seed data** to `custom/apps/<app-slug>/seed/`
-3. **Copy migrations** (if any) to `custom/migrations/`
-4. **Update workspace configuration** to include the app
-
-## Critical Safeguards
-
-- **NEVER** delete existing `custom/apps/`, `custom/functions/`, or `custom/migrations/` content
-- **ALWAYS** preserve existing custom apps during installation
-- Seed data is additive - existing types/roles are not modified
-
-## Usage
-
-```
-Install the cortex app from spine-framework-cortex package
-```
-
-The skill will:
-1. Locate the package in node_modules or local path
-2. Copy app files to custom/apps/cortex/
-3. Copy seed files (types.json, roles.json, link-types.json)
-4. Report what was installed
-
-## Output
-
-Reports installed files and any conflicts that need manual resolution.

package/custom/.devin/skills/spine-workbench-discovery/SKILL.md

@@ -1,39 +0,0 @@
----
-name: spine-workbench-discovery
-description: "Promote an idea to discovery, run the Workbench Research Agent, and optionally link relevant code chunks."
-allowed-tools:
-  - mcp_call_tool
-  - read
-  - ask_user_question
----
-
-# Spine Workbench — Discovery
-
-Promote an existing Workbench idea to a `workbench_discovery` and gather related code or knowledge.
-
-## When to invoke
-
-- The user wants to start discovery on an idea.
-- They want to investigate the problem, find related code, and decide whether to approve.
-
-## Steps
-
-1. **Identify the idea**
-   - Ask for the `idea_id` if not provided.
-   - If the user gave a title instead of an ID, search with `spine_cil_search_chunks` or list relevant work items to resolve it.
-
-2. **Start discovery**
-   - Call `spine_workbench_start_discovery` with the `idea_id` and `account_id`.
-   - Capture the returned `discovery.id`.
-
-3. **Run the Research Agent (optional)**
-   - Call `spine_workbench_run_research_agent` with the `idea_id` or new `discovery_id`.
-   - Summarize the retrieved sources and recommendations.
-
-4. **Link relevant code (optional)**
-   - Use `spine_cil_search_chunks` to find CIL chunks related to the discovery topic.
-   - For the strongest matches, call `spine_workbench_link_code` with `link_type: workbench_concerns_chunk`.
-
-5. **Return the result**
-   - Show the discovery `id`, `title`, `status`, and any linked code.
-   - Suggest next step: `spine-workbench-initiative` to approve, or `spine-workbench-plan` if it is small enough to skip the initiative stage.

package/custom/.devin/skills/spine-workbench-idea/SKILL.md

@@ -1,36 +0,0 @@
----
-name: spine-workbench-idea
-description: "Capture a new idea in the Workbench and, if helpful, gather relevant context from CIL before tracking it."
-allowed-tools:
-  - mcp_call_tool
-  - read
-  - ask_user_question
----
-
-# Spine Workbench — Idea
-
-Capture a new idea as a `workbench_work_item` with `work_type: idea`.
-
-## When to invoke
-
-- The user says "I have an idea", "track this", "capture a feature request", or similar.
-- They describe something that should go through the Workbench lifecycle (idea → discovery → initiative → plan → implement).
-
-## Steps
-
-1. **Confirm the title and description**
-   - If the user only mentioned a vague concept, ask for a 1-sentence title and a short description before side effects.
-   - If the input is clear, proceed directly.
-
-2. **Optionally gather context**
-   - If the idea relates to an existing file, chunk, or feature, call `spine_cil_search_chunks` to find relevant CIL context.
-   - Summarize the top 1-3 most relevant chunks in your reasoning.
-
-3. **Track the idea**
-   - Call `spine_workbench_track_idea` with:
-     - `account_id` — ask the user if not known.
-     - `title` and `description` from the input.
-
-4. **Return the result**
-   - Show the new idea's `id`, `title`, and `status`.
-   - Suggest next step: `spine-workbench-discovery` or `spine-workbench-plan`.

package/custom/.devin/skills/spine-workbench-implement/SKILL.md

@@ -1,46 +0,0 @@
----
-name: spine-workbench-implement
-description: "Implement a Workbench work item: read context, edit code, verify with CIL, and post progress."
-allowed-tools:
-  - mcp_call_tool
-  - read
-  - edit
-  - write
-  - exec
-  - ask_user_question
----
-
-# Spine Workbench — Implement
-
-Implement the code for a Workbench work item and keep CIL in sync.
-
-## When to invoke
-
-- The user says "implement this", "build it", "fix it", or is ready to code a planned work item.
-
-## Steps
-
-1. **Identify the work item**
-   - Ask for `work_item_id` if not provided.
-
-2. **Load context**
-   - Use `spine_cil_get_context` or `spine_cil_find_context` on the most relevant chunk(s) linked to the work item.
-   - If no chunks are linked, use `spine_cil_search_chunks` first.
-
-3. **Implement the change**
-   - Edit or create the files needed.
-   - Follow the Spine Way: core-vs-custom boundary, design schema, permissions, and admin-data for runtime records.
-
-4. **Re-index changed files in CIL**
-   - After saving, call `spine_cil_reindex_chunk` with `also_embed: true` for each changed chunk.
-   - Use `spine_cil_validate_file` to confirm no drift remains.
-
-5. **Run verification**
-   - Run the relevant build, lint, typecheck, or test commands for the changed code.
-   - If verification fails, fix the issues before finishing.
-
-6. **Post progress**
-   - Call `spine_workbench_add_thread_message` with an implementation summary.
-
-7. **Return the result**
-   - Summarize the files changed, verification status, and next step (e.g., open a PR, run end-to-end tests).

package/custom/.devin/skills/spine-workbench-initiative/SKILL.md

@@ -1,28 +0,0 @@
----
-name: spine-workbench-initiative
-description: "Approve a discovery and promote it to a workbench_initiative."
-allowed-tools:
-  - mcp_call_tool
-  - read
-  - ask_user_question
----
-
-# Spine Workbench — Initiative
-
-Approve an existing `workbench_discovery` and create a linked `workbench_initiative`.
-
-## When to invoke
-
-- The user says "approve discovery", "promote to initiative", or wants to move from discovery to roadmap.
-
-## Steps
-
-1. **Identify the discovery**
-   - Ask for the `discovery_id` if not provided.
-
-2. **Approve the discovery**
-   - Call `spine_workbench_approve_discovery` with the `discovery_id` and `account_id`.
-
-3. **Return the result**
-   - Show the new initiative `id`, `title`, and `status`.
-   - Suggest next step: `spine-workbench-plan`.

package/custom/.devin/skills/spine-workbench-plan/SKILL.md

@@ -1,38 +0,0 @@
----
-name: spine-workbench-plan
-description: "Create documentation and test-plan tickets for a work item and link the code chunks it concerns."
-allowed-tools:
-  - mcp_call_tool
-  - read
-  - ask_user_question
----
-
-# Spine Workbench — Plan
-
-Create planning artifacts for a work item: docs ticket, test plan, and code links.
-
-## When to invoke
-
-- The user wants to "write a test plan", "create docs", "link code", or generally prepare a work item for implementation.
-- The work item is an idea, discovery, or initiative.
-
-## Steps
-
-1. **Identify the work item**
-   - Ask for `work_item_id` if not provided.
-   - If the user mentions the initiative/discovery/idea by title, ask for the UUID or use search.
-
-2. **Create the planning artifacts**
-   - Call `spine_workbench_create_docs_ticket` to create a `workbench_docs_ticket`.
-   - Call `spine_workbench_create_test_plan` to create a `workbench_test_plan`.
-
-3. **Link relevant code**
-   - Use `spine_cil_search_chunks` to find the most relevant chunks/files for this work item.
-   - For each strongly relevant chunk, call `spine_workbench_link_code` with `work_item_id`, `chunk_id`, and `link_type: workbench_concerns_chunk`.
-
-4. **Log progress**
-   - Call `spine_workbench_add_thread_message` with a short progress note.
-
-5. **Return the result**
-   - Show the created docs ticket, test plan, and any code links.
-   - Suggest next step: `spine-workbench-implement`.

package/custom/.devin/workflows/app-install.yaml

@@ -1,83 +0,0 @@
-name: Install App
-version: 1.0.0
-description: Install a Spine Framework app into the custom workspace
-
-triggers:
-  - type: user-prompt
-    patterns:
-      - "install app"
-      - "add app"
-      - "setup app"
-
-steps:
-  - name: Identify app package
-    action: ask-user
-    prompt: "Which app would you like to install? (e.g., cortex, portal, or package name)"
-    store: app_name
-
-  - name: Check for existing installation
-    action: shell
-    command: "test -d /Users/thistle/CascadeProjects/spine-ia/custom/apps/${app_name} && echo 'exists' || echo 'new'"
-    store: exists_status
-
-  - name: Warn about existing installation
-    condition: exists_status == "exists"
-    action: ask-user
-    prompt: "App ${app_name} already exists in custom/apps/. Overwrite? (yes/no)"
-    store: confirm_overwrite
-
-  - name: Exit on no confirmation
-    condition: exists_status == "exists" && confirm_overwrite != "yes"
-    action: exit
-    message: "Installation cancelled. Existing app preserved."
-
-  - name: Locate package
-    action: shell
-    command: |
-      if [ -d "/Users/thistle/CascadeProjects/spine-ia/custom/apps/${app_name}" ]; then
-        echo "/Users/thistle/CascadeProjects/spine-ia/custom/apps/${app_name}"
-      elif [ -d "/Users/thistle/CascadeProjects/spine-ia/custom/npm/${app_name}" ]; then
-        echo "/Users/thistle/CascadeProjects/spine-ia/custom/npm/${app_name}"
-      else
-        echo "not_found"
-      fi
-    store: package_path
-
-  - name: Report package not found
-    condition: package_path == "not_found"
-    action: exit
-    message: "Could not find app package. Expected at custom/apps/${app_name} or custom/npm/${app_name}"
-
-  - name: Install app files
-    action: shell
-    command: |
-      mkdir -p "/Users/thistle/CascadeProjects/spine-ia/custom/apps/${app_name}"
-      cp -r "${package_path}"/*/ "/Users/thistle/CascadeProjects/spine-ia/custom/apps/${app_name}/" 2>/dev/null || true
-      echo "App files copied"
-
-  - name: Install seed data
-    action: shell
-    command: |
-      if [ -d "${package_path}/seed" ]; then
-        mkdir -p "/Users/thistle/CascadeProjects/spine-ia/custom/apps/${app_name}/seed"
-        cp "${package_path}/seed/"*.json "/Users/thistle/CascadeProjects/spine-ia/custom/apps/${app_name}/seed/" 2>/dev/null || true
-        echo "Seed data copied"
-      else
-        echo "No seed data found"
-      fi
-
-  - name: Report installation
-    action: message
-    message: |
-      App ${app_name} installed successfully!
-
-      Location: custom/apps/${app_name}/
-
-      Next steps:
-      1. Review the installed files
-      2. Apply seed data: npm run seed -- --app=${app_name}
-      3. Restart the development server
-
-output:
-  success: "App ${app_name} installed to custom/apps/${app_name}/"
-  failure: "Failed to install app. Check the logs above."