spine-framework 0.3.145 → 0.4.0

package/.env.example

@@ -0,0 +1,76 @@
+# ── Branding ──────────────────────────────────────────────────────
+# App name shown in UI, page title, localStorage keys, webhook headers
+VITE_APP_NAME=Spine
+
+# Environment badge shown in the UI (dev, staging, prod)
+VITE_ENVIRONMENT=dev
+
+# ── Supabase (frontend — public keys only) ───────────────────────
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key
+
+# ── Supabase (backend — Netlify Functions) ───────────────────────
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
+# Functions build user-scoped PostgREST clients with the anon key.
+SUPABASE_ANON_KEY=your-anon-key
+
+# ── Migrations / CLI ─────────────────────────────────────────────
+# Postgres password used by `spine-framework migrate` and `install-app`
+# (connects directly to db.<project-ref>.supabase.co:5432).
+# Get from: Supabase Dashboard → Project Settings → Database.
+SUPABASE_DB_PASSWORD=
+
+# ── App URLs ─────────────────────────────────────────────────────
+# Base URL for invite links and auth redirects; also the allowlist
+# origin for client-supplied base_url params.
+APP_BASE_URL=http://localhost:8888
+
+# ── Database Schema (advanced / multi-instance) ────────────────
+# Default installs run in the public schema. Only set these
+# if you intentionally deploy the deprecated namespaced installer
+# (see SETUP.md "Advanced: multi-instance" section).
+# VITE_DB_SCHEMA=
+# DB_SCHEMA=
+
+# ── CORS / Security ─────────────────────────────────────────────
+# Your production site URL (used for CORS Allow-Origin header).
+# Netlify auto-sets URL; override with SITE_URL if using a custom domain.
+# SITE_URL=https://your-custom-domain.com
+
+# Cloudflare Turnstile site key (public — safe to ship to the browser).
+# When set, the Register/Login/ForgotPassword pages render a Turnstile
+# widget and pass its token to Supabase Auth. Pair it with the secret key
+# configured in Supabase Dashboard → Authentication → Bot and Abuse
+# Protection. Use one Turnstile site covering both your prod domain and
+# `localhost` so the same key works in local dev.
+# VITE_TURNSTILE_SITE_KEY=
+
+# Netlify API credentials used by the security admin function to push
+# banned IPs into the site's edge Firewall Traffic Rules. Create a
+# Personal Access Token in Netlify → User Settings → Applications.
+# Leave unset to skip the edge layer (Supabase ban + internal blocklist
+# still apply).
+# NETLIFY_ACCESS_TOKEN=
+# NETLIFY_SITE_ID=
+
+# Shared secret required in the `x-internal-secret` header for any request
+# to be treated as a cron/trigger machine principal (x-cron-id/x-trigger-id
+# headers). Generate with `openssl rand -hex 32`. Leave unset to disable
+# these header-based principals entirely (default; nothing sets them today).
+# INTERNAL_INVOKE_SECRET=
+
+# Shared secret for the system-cron scheduler endpoint (?api_key= or
+# ?scheduler_key= query param). Generate with `openssl rand -hex 32`.
+# SCHEDULER_API_KEY=
+
+# ── AI (optional) ───────────────────────────────────────────────
+# Required for AI-powered workflow actions (ai_prompt action type)
+# OPENAI_API_KEY=sk-...
+
+# ── Email (optional) ────────────────────────────────────────────
+# Provider: 'resend', 'sendgrid', or 'webhook' (default)
+# EMAIL_PROVIDER=resend
+# EMAIL_API_KEY=re_...
+# EMAIL_FROM=noreply@yourdomain.com
+# EMAIL_WEBHOOK_URL=https://hook.us1.make.com/your-scenario-id

package/.framework/.spine-manifest.json

@@ -0,0 +1,19 @@
+{
+  "version": "2.0.0",
+  "description": "Spine v2 Core Platform Manifest",
+  "integrity": {
+    "src": "sha256-$(find src -type f -name '*.tsx' -o -name '*.ts' -o -name '*.css' | LC_ALL=C sort | xargs cat | sha256sum | cut -d' ' -f1)",
+    "functions": "sha256-$(find functions -type f -name '*.ts' | LC_ALL=C sort | xargs cat | sha256sum | cut -d' ' -f1)"
+  },
+  "lastModified": "2026-04-09T00:00:00Z",
+  "paths": {
+    "src": "./src",
+    "functions": "./functions",
+    "public": "./public"
+  },
+  "rules": {
+    "customPrefix": "custom_",
+    "readOnly": true,
+    "integrityCheck": true
+  }
+}

package/.framework/cli/commands/agents.ts

@@ -1,41 +1,64 @@
-// CIL[BEGIN chunk_id="agents_module_header_1784183721" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Preamble and imports for agents"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provides imports and top-level types/constants used by the rest of the module"]
-// CIL[DOC-CONTEXT module=".framework/cli/commands/agents" layer="cli" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="imports, types, constants" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports external dependencies and declares shared types or constants" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-
-
-
+/**
+ * @module   agents
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module provides command-line interface (CLI) commands for managing agents within the system. It serves as a bridge between user input and the underlying agent functionalities, facilitating operations such as running agents and interacting with the admin database. INVARIANT: The commands must be executed within a valid CLI context to ensure proper functionality.
+ *
+ * @seeAlso context.ts (provides CLI context management).
+ * @seeAlso _shared/index.ts (contains shared functions for agent operations).
+ *
+ * @cil-generated
+ */
+
+
+
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/agents.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/cli/commands/agents.ts"]
+// CIL[DOC-AUDIENCE audience="both"]
+// CIL[DOC-MACRO purpose="Top-level module imports for the agents CLI command set."]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the external dependencies used by the agents CLI commands."]
+// CIL[DOC-CONTEXT module="agents" layer="shared-core" related_files=".framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Command type and shared helper functions for the agents command module" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports the Commander Command type, CLI context utilities, and shared agent functions." notable_decisions="Uses explicit .ts extensions on relative imports."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stable]
 import type { Command } from 'commander'
 import { buildCliContext, printResult, handleError } from '../context.ts'
 import { runAgent, adminDb } from '../../functions/_shared/index.ts'
 
 
-// CIL[END chunk_id="agents_module_header_1784183721"]
-// CIL[BEGIN chunk_id="agents_registeragentcommands_1784183721" type="function" identity="registerAgentCommands" parent="none"]
-// CIL[DOC-MACRO purpose="Implement the registerAgentCommands helper function"]
-// CIL[DOC-RESPONSIBILITY responsibility="Owns the registerAgentCommands computation and return value"]
-// CIL[DOC-CONTEXT module=".framework/cli/commands/agents" layer="cli" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="void" errors="Error" side_effects="logs to console, queries database, builds CLI context"]
-// CIL[DOC-MICRO logic_summary="Computes and returns void" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+
+// CIL[DOC-VECTOR type="context" content="purpose='Top-level module imports for the agents CLI command set.'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/agents.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/agents.ts:registerAgentCommands:function" type="function" identity="registerAgentCommands" parent="~/.framework/cli/commands/agents.ts"]
+// CIL[DOC-MACRO purpose="Register agent and thread subcommands with a Commander program."]
+// CIL[DOC-RESPONSIBILITY responsibility="Attach 'agents run', 'threads list', and 'threads get' command handlers to the program."]
+// CIL[DOC-CONTEXT module="agents" layer="shared-core" related_files=".framework/cli/commands/agents.ts,.framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-CONTRACT inputs="program: Commander Command" outputs="none (mutates the program)" errors="throws Error for database or runtime failures, handled by handleError" side_effects="registers CLI commands, queries the admin database, prints to stdout"]
+// CIL[DOC-MICRO logic_summary="Creates the 'agents' command group and attaches run/list/get actions, builds CLI context, calls runAgent and adminDb queries, and prints results." notable_decisions="Uses async action handlers; supports optional account scoping and JSON output."]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY internal]
+/**
+ * Registers commands for interacting with AI agents, including sending messages and managing agent threads. This module facilitates user interaction with agent functionalities through a command-line interface.
+ *
+ * @macro       Command registration handler for AI agent operations.
+ * @micro       Defines nested commands for running agents and managing threads, utilizing asynchronous actions to handle user input.
+ * @inputSpec
+ *   program: Command (required) — The command program instance to register agent commands with.
+ * @outputSpec  none
+ * @sideEffects none
+ * @stability   internal
+ * @calls       buildCliContext, runAgent, adminDb.from, printResult, handleError
+ * @errorHandling catches and handles errors during command execution.
+ * @cil-generated
+ */
 export function registerAgentCommands(program: Command) {
   const agents = program
     .command('agents')
@@ -147,5 +170,10 @@ export function registerAgentCommands(program: Command) {
       }
     })
 }
-
-// CIL[END chunk_id="agents_registeragentcommands_1784183721"]
+// CIL[DOC-VECTOR type="context" content="purpose='Register agent and thread subcommands with a Commander program.'; No verified external callers; imports: .framework/cli/context.ts,.framework/functions/_shared/index.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/agents.ts:registerAgentCommands:function"]

package/.framework/cli/commands/auth.ts

@@ -1,40 +1,66 @@
+/**
+ * @module   auth
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module handles authentication commands for the CLI, providing the necessary context and error handling for user authentication processes. It serves as an entry point for command execution related to user authentication, ensuring that commands are processed correctly and errors are managed effectively.
+ * 
+ * INVARIANT: The CLI must be invoked with valid authentication parameters to function correctly.
+ *
+ * @seeAlso context.js (provides context management and error handling functionality.)
+ * @seeAlso commander (used for command parsing and execution.)
+ *
+ * @cil-generated
+ */
 
 
 
 
 
-// CIL[BEGIN chunk_id="auth_module_header_1784071456" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies for auth CLI commands"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide imports for auth command registration"]
-// CIL[DOC-CONTEXT module="auth-cli" layer="cli" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="imports" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports Command type and CLI context utilities" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+
+
+// CIL[BEGIN stable_id="~/.framework/cli/commands/auth.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/cli/commands/auth.ts"]
+// CIL[DOC-MACRO purpose="Module setup and imports for auth.ts"]
+// CIL[DOC-RESPONSIBILITY responsibility="Establish the public surface and dependencies of auth.ts"]
+// CIL[DOC-CONTEXT module=".framework/cli/commands/auth.ts" layer="cli" related_files=".framework/cli/context.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports required modules for auth.ts" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-AUDIENCE audience="cli"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import type { Command } from 'commander'
 import { buildCliContext, handleError } from '../context.js'
-// CIL[END chunk_id="auth_module_header_1784071456"]
-// CIL[BEGIN chunk_id="auth_registerauthcommands_1784071456" type="function" identity="registerAuthCommands" parent="none"]
-// CIL[DOC-MACRO purpose="Register auth commands with CLI framework"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide whoami and check subcommands for auth"]
-// CIL[DOC-CONTEXT module="auth-cli" layer="cli" related_files="[\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="auth command registration" errors="CLI context errors" side_effects="outputs identity info"]
-// CIL[DOC-MICRO logic_summary="Registers whoami and check commands for identity validation" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="external_symbols_unknown"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: cli. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/src/components/ui/table-primitives.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+
+// CIL[DOC-VECTOR type="context" content="purpose='Module setup and imports for auth.ts'; No verified external callers; imports: .framework/cli/context.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/auth.ts:module_header:module_header"]
+// CIL[BEGIN stable_id="~/.framework/cli/commands/auth.ts:registerAuthCommands:function" type="function" identity="registerAuthCommands" parent="~/.framework/cli/commands/auth.ts"]
+// CIL[DOC-MACRO purpose="Implement registerAuthCommands"]
+// CIL[DOC-RESPONSIBILITY responsibility="Execute the core logic for registerAuthCommands"]
+// CIL[DOC-CONTEXT module=".framework/cli/commands/auth.ts" layer="cli" related_files=".framework/cli/commands/auth.ts,.framework/cli/context.ts"]
+// CIL[DOC-CONTRACT inputs="program: Command" outputs="result of the operation" errors="propagates dependency errors" side_effects="writes to stdout/stderr; calls process.exit"]
+// CIL[DOC-MICRO logic_summary="Processes inputs, performs work, and returns output for registerAuthCommands" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+/**
+ * Registers authentication-related commands for the CLI, enabling users to manage their identity and validate credentials. This module provides commands for displaying the current user's identity and checking credential validity.
+ *
+ * @macro       Command registration handler for authentication operations.
+ * @micro       Defines subcommands under the 'auth' command with specific actions for each.
+ * @inputSpec
+ *   program: Command (required) — the CLI program instance to register commands with.
+ * @outputSpec  none
+ * @sideEffects none
+ * @stability   internal
+ * @calls       buildCliContext, handleError
+ * @errorHandling none
+ * @cil-generated
+ */
 export function registerAuthCommands(program: Command) {
   const auth = program
     .command('auth')
@@ -92,4 +118,10 @@ export function registerAuthCommands(program: Command) {
       }
     })
 }
-// CIL[END chunk_id="auth_registerauthcommands_1784071456"]
+// CIL[DOC-VECTOR type="context" content="purpose='Implement registerAuthCommands'; No verified external callers; imports: .framework/cli/context.ts"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/cli/commands/auth.ts:registerAuthCommands:function"]