spine-framework 0.3.17 → 0.3.19

package/README.md

@@ -1,129 +1,254 @@
-# Spine Framework
-
-**We're building Spine Framework in the open.** The source is visible, the roadmap is public, and we share what we learn along the way. That said, Spine Framework is not open source — commercial use requires a license. See [LICENSE.md](./LICENSE.md) for details.
-
----
-
-Spine Framework is an enterprise application framework for agentic IDEs. It gives Windsurf, Cursor, and other AI coding tools a production-ready backend to build on — multi-tenant data model, auth, roles, permissions, Netlify functions, and a CLI for installation and app management.
-
-You bring the use case. Spine Framework brings the infrastructure.
-
-## Requirements
-
-- Node.js 18+
-- A [Supabase](https://supabase.com) project
-- [Netlify CLI](https://docs.netlify.com/cli/get-started/) (`npm install -g netlify-cli`)
-
-## Getting Started
-
-### 1. Install Spine Framework
-
-In a new empty directory:
-
-```bash
-npm install spine-framework@latest
-```
-
-### 2. Initialize the project
-
-```bash
-npx spine-framework init
-```
-
-This scaffolds the project structure, writes a full `package.json`, and creates a `.env` file for your Supabase credentials.
-
-### 3. Add your Supabase credentials
-
-Edit `.env`:
-
-```
-SUPABASE_URL=https://<project>.supabase.co
-SUPABASE_ANON_KEY=<anon-key>
-SUPABASE_SERVICE_ROLE_KEY=<service-role-key>
-SUPABASE_DB_PASSWORD=<db-password>
-```
-
-Get these from **Supabase Dashboard → Your Project → Settings → API**.
-
-### 4. Run migrations
-
-```bash
-npx spine-framework migrate
-```
-
-Applies the foundation schema and seed data to your Supabase project.
-
-### 5. Install apps (optional)
-
-```bash
-npx spine-framework install-app spine-framework-portal@latest
-npx spine-framework install-app spine-framework-cortex@latest
-```
-
-### 6. Start the dev server
-
-```bash
-npm run assemble && netlify dev
-```
-
-## CLI Reference
-
-```
-npx spine-framework <command>
-
-Commands:
-  init              Scaffold a new Spine Framework project
-  migrate           Apply database migrations
-  install-app       Install a Spine Framework app from npm
-  uninstall-app     Remove an installed app
-  update-app        Update an installed app to a newer version
-  status            Show installed apps and framework version
-  migrate           Run pending migrations
-```
-
-Run `npx spine-framework <command> --help` for options on any command.
-
-## Project Structure
-
-After `init`, your project will look like this:
-
-```
-.framework/        # Framework internals (do not edit)
-  cli/             # CLI commands
-  config/          # Framework configuration
-  functions/       # Netlify function handlers
-  migrations/      # SQL migrations
-  src/             # React components and core UI
-bin/               # CLI entry point
-config/            # Vite, Tailwind, TypeScript config
-scripts/           # Assembly scripts
-custom/            # Your code lives here
-  apps/            # Custom or installed apps
-  functions/       # Custom Netlify functions
-  components/      # Custom React components
-  migrations/      # Custom SQL migrations
-  tests/           # Custom tests
-.env               # Supabase credentials (not committed)
-```
-
-## Apps
-
-Spine Framework apps are npm packages. Install them with the CLI:
-
-```bash
-npx spine-framework install-app spine-framework-portal@latest
-```
-
-Each app seeds its own roles, types, and configuration into your database and integrates with the Spine Framework navigation and permission system.
-
-## License
-
-Spine Framework is **source-available, free for internal use**. Commercial use — including SaaS, resale, managed services, and white-labeling — requires a separate commercial license.
-
-See [LICENSE.md](./LICENSE.md) for full terms.
-
-For commercial licensing: [spine-framework.com](https://spine-framework.com) · webmaster@spine-framework.com
-
----
-
-Copyright © 2026 Dahl Ventures Inc. All rights reserved.
+Spine Framework
+A complete enterprise application framework built on Supabase + Netlify + React for building scalable multi-tenant applications with extensible app ecosystems.
+
+Overview
+Spine Framework is a complete, runnable framework that provides everything you need to build enterprise applications:
+
+Multi-tenant Architecture: Support for tenant hierarchies and isolated deployments
+Role-Based Access Control: Fine-grained permissions and authorization
+App Ecosystem: Install and manage custom applications
+Real-time Features: Built-in support for real-time collaboration and notifications
+AI Integration: Native support for AI agents and intelligent workflows
+Developer Tools: Comprehensive tooling for development, testing, and deployment
+Quick Start
+Prerequisites
+Node.js 18+
+PostgreSQL database (via Supabase recommended)
+Netlify account (for deployment)
+Installation
+# Clone the framework
+git clone https://github.com/spine-framework/spine-framework.git
+cd spine-framework
+
+# Install dependencies
+npm install
+
+# Set up environment
+cp .env.example .env
+# Edit .env with your Supabase and Netlify credentials
+
+# Start development
+npm run dev
+Install Custom Apps
+# Install Cortex (CRM, Support, Community, Knowledge Base)
+npm run app-install cortex
+
+# Install Customer Portal
+npm run app-install customer-portal
+
+# List available apps
+npm run spine-framework list-apps
+Architecture
+Core Components
+Framework Core: Base functionality, authentication, and data models
+App Registry: System for managing and distributing applications
+Multi-tenant Engine: Tenant isolation and hierarchy management
+Authorization Layer: Role-based permissions and access control
+Real-time Infrastructure: WebSocket support and live updates
+AI Agent System: Integration with AI services and workflows
+App Ecosystem
+Spine Framework supports a growing ecosystem of applications:
+
+Cortex: CRM, Support, Community, and Knowledge Base
+Customer Portal: Self-service customer portal
+Custom Apps: Build your own applications using the framework
+Database Schema
+The framework uses a clean, normalized schema with:
+
+Accounts & Tenants: Multi-tenant hierarchy support
+People & Roles: User management and permissions
+Items & Threads: Flexible data modeling system
+Apps & Integrations: Extensible app registry
+AI Agents: Intelligent workflow automation
+Development
+Project Structure
+my-spine-project/
+├── src/
+│   ├── components/         # Reusable UI components
+│   ├── pages/             # Application pages
+│   ├── hooks/             # Custom React hooks
+│   ├── contexts/          # React contexts
+│   └── utils/             # Utility functions
+├── functions/             # Serverless functions
+├── migrations/            # Database migrations
+├── custom/                # Custom app extensions
+└── docs/                  # Documentation
+Building Apps
+Create custom applications using the Spine Framework:
+
+// src/apps/my-app/index.tsx
+import { AppLayout, useCurrentApp } from '@spine-framework/core'
+
+export default function MyApp() {
+  const app = useCurrentApp()
+  
+  return (
+    <AppLayout>
+      <h1>{app.name}</h1>
+      {/* Your app content */}
+    </AppLayout>
+  )
+}
+Database Extensions
+Add custom database schema:
+
+-- migrations/001_my_app.sql
+CREATE TABLE my_app_data (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  account_id UUID REFERENCES accounts(id),
+  title TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT now()
+);
+
+-- Enable RLS
+ALTER TABLE my_app_data ENABLE ROW LEVEL SECURITY;
+Configuration
+Environment Variables
+# Database
+DATABASE_URL=postgresql://...
+
+# Supabase
+SUPABASE_URL=your-project.supabase.co
+SUPABASE_ANON_KEY=your-anon-key
+SUPABASE_SERVICE_ROLE_KEY=your-service-key
+
+# Framework
+SPINE_ENV=development
+SPINE_LOG_LEVEL=info
+Framework Configuration
+// spine.config.ts
+export default {
+  database: {
+    url: process.env.DATABASE_URL,
+    poolSize: 10,
+  },
+  auth: {
+    providers: ['email', 'github', 'google'],
+    sessionTimeout: '24h',
+  },
+  apps: {
+    registry: 'https://registry.spine-framework.com',
+    autoUpdate: true,
+  },
+  ai: {
+    provider: 'openai',
+    model: 'gpt-4',
+  }
+}
+Deployment
+Development
+# Start development server
+npm run dev
+
+# Run tests
+npm test
+
+# Type checking
+npm run type-check
+Production
+# Build for production
+npm run build
+
+# Deploy to Netlify
+netlify deploy --prod
+
+# Or deploy to your preferred platform
+Database Migrations
+# Run migrations
+npx spine migrate up
+
+# Create new migration
+npx spine migrate create add_new_feature
+
+# Rollback migration
+npx spine migrate down
+Available Apps
+Official Apps
+spine-framework-cortex
+
+CRM, Support, Community, Knowledge Base
+npm install spine-framework-cortex
+spine-framework-portal
+
+Customer self-service portal
+npm install spine-framework-portal
+Installing Apps
+# Install an app
+npx spine install-app cortex
+
+# List available apps
+npx spine list-apps
+
+# Update an app
+npx spine update-app cortex
+API Reference
+Core Hooks
+// Authentication
+import { useAuth, useUser } from '@spine-framework/core'
+
+// App Management
+import { useApps, useCurrentApp } from '@spine-framework/core'
+
+// Data Management
+import { useItems, useThreads } from '@spine-framework/core'
+
+// Real-time
+import { useWebSocket } from '@spine-framework/core'
+Database Functions
+-- Get account apps
+SELECT * FROM get_account_apps(account_id, true, false);
+
+-- Get accessible accounts
+SELECT * FROM get_accessible_accounts(user_id);
+
+-- Check permissions
+SELECT * FROM has_permission(user_id, 'action', 'resource');
+Contributing
+Development Setup
+# Clone the repository
+git clone https://github.com/spine-framework/spine-framework.git
+cd spine-framework
+
+# Install dependencies
+npm install
+
+# Start development
+npm run dev
+Submitting Changes
+Fork the repository
+Create a feature branch
+Make your changes
+Add tests
+Submit a pull request
+Building Apps for Distribution
+If you want to contribute an app to the ecosystem:
+
+Create your app using the framework
+Follow the app structure guidelines
+Include comprehensive documentation
+Submit for review
+License
+This framework is licensed under the Spine Framework Internal Use License.
+
+✅ Free for internal business use
+❌ Commercial redistribution requires separate license
+📞 Contact: spine-framework.com for commercial licensing
+Support
+Documentation: docs.spine-framework.com
+Issues: GitHub Issues
+Community: Discord Server
+Commercial: Contact Us
+Version History
+v1.0.0
+Initial release
+Multi-tenant architecture
+App registry system
+Role-based access control
+Real-time features
+AI integration
+Roadmap
+v1.1: Enhanced AI capabilities
+v1.2: Advanced analytics and reporting
+v1.3: Mobile app support
+v2.0: Microservices architecture
+Spine Framework - Build enterprise applications with confidence.

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

@@ -0,0 +1,39 @@
+# 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/workflows/app-install.yaml

@@ -0,0 +1,83 @@
+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."

package/custom/README.md

@@ -0,0 +1,79 @@
+# Spine Framework Custom Workspace
+
+This directory is your extension workspace for the Spine Framework. Customize your instance here without modifying the core framework code.
+
+## Directory Structure
+
+```
+custom/
+├── apps/              # Custom apps extending Spine
+│   ├── cortex/       # AI-powered support & CRM
+│   ├── portal/       # Customer portal & courses
+│   └── your-app/     # Your custom app
+├── components/        # Shared React components
+├── functions/         # Edge functions (Netlify/Vercel)
+├── migrations/        # Database migrations
+├── npm/              # Local npm packages
+├── tests/            # Custom tests
+└── .devin/           # Devin workflows & skills
+```
+
+## Getting Started
+
+### 1. Install an App
+
+Use the Devin skill to install an app:
+```
+Install the cortex app
+```
+
+Or manually copy an app package to `custom/apps/`.
+
+### 2. Apply Seed Data
+
+Seed data defines types, roles, and configuration:
+```bash
+npm run seed -- --app=cortex
+```
+
+### 3. Start Development
+
+```bash
+npm run dev
+```
+
+## Creating Custom Apps
+
+1. Create `custom/apps/my-app/` with:
+   - `index.tsx` - App entry point
+   - `manifest.json` - App configuration
+   - `seed/types.json` - Custom types
+   - `seed/roles.json` - Custom roles
+   - `pages/` - Page components
+   - `components/` - App-specific components
+
+2. Add navigation items in `manifest.json`
+
+3. Restart the dev server
+
+## Database Migrations
+
+Place custom migrations in `custom/migrations/`:
+```
+custom/migrations/001_add_custom_table.sql
+```
+
+Migrations are applied automatically on startup.
+
+## Best Practices
+
+- **Never modify `.framework/`** - Use this `custom/` directory instead
+- **Keep apps self-contained** - Each app should have its own seed data
+- **Use the CLI** - `spine-cli` helps manage apps and migrations
+- **Test in isolation** - Apps should work standalone
+
+## Support
+
+- Framework docs: `.framework/docs/`
+- Devin skills: `custom/.devin/skills/`
+- Community: https://github.com/spine-framework/spine