spine-framework 0.4.2 → 0.4.4

package/.framework/src/lib/branding.ts

@@ -0,0 +1,128 @@
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Instance branding resolved from spine.config.json — app name, logo, favicon, document title"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load the optional branding block from /spine.config.json once per session, merge it over Spine defaults, and apply favicon/title to the document"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/hooks/useBranding.ts,spine.config.json,.framework/index.html"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineBranding resolved object; applyBrandingToDocument performs DOM mutation" errors="fetch or parse failures fall back to DEFAULT_BRANDING" side_effects="HTTP GET /spine.config.json (single cached request); document.title and link[rel=icon] mutation"]
+// CIL[DOC-MICRO logic_summary="Module-level cache plus single inflight fetch; resolveBranding fills missing keys with defaults; applyBrandingToDocument sets document.title and swaps the favicon link href" notable_decisions="Branding lives in instance-owned spine.config.json so framework upgrades can never overwrite app branding; index.html keeps the Spine default and the runtime swap handles app-branded instances"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework developers"]
+// CIL[DOC-NOTE type="contract" content="branding is a top-level sibling of registration in spine.config.json. All keys optional; absent block yields DEFAULT_BRANDING so bare framework installs stay Spine-branded."]
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:spinebranding:interface" type="interface" identity="SpineBranding" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Resolved instance branding shape"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type for the branding block after defaults are applied"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineBranding object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="app_name drives headings and logo alt; title drives document.title and wordmark text; logo_url and favicon_url are public/ asset paths" notable_decisions="title falls back to app_name, then to 'Spine Framework' when no branding block exists"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export interface SpineBranding {
+  app_name: string
+  title: string
+  logo_url: string
+  favicon_url: string
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:spinebranding:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:default_branding:constant" type="constant" identity="DEFAULT_BRANDING" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Spine Framework default branding used when spine.config.json has no branding block"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide the fallback brand so the framework is self-branded out of the box"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts,.framework/index.html"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineBranding constant" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Matches the static values in .framework/index.html (title 'Spine Framework', favicon /spine-logo.svg)" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export const DEFAULT_BRANDING: SpineBranding = {
+  app_name: 'Spine',
+  title: 'Spine Framework',
+  logo_url: '/spine-logo.svg',
+  favicon_url: '/spine-logo.svg',
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:default_branding:constant"]
+
+let cached: SpineBranding | null = null
+let inflight: Promise<SpineBranding> | null = null
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:resolvebranding:function" type="function" identity="resolveBranding" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Merge a raw branding block over defaults"]
+// CIL[DOC-RESPONSIBILITY responsibility="Produce a complete SpineBranding from a possibly partial branding config value"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts"]
+// CIL[DOC-CONTRACT inputs="raw: unknown (config.branding)" outputs="SpineBranding" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Each key falls back independently; title falls back to the resolved app_name so app-branded instances get a sane tab title without duplicating config" notable_decisions="non-string values treated as absent"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+function resolveBranding(raw: unknown): SpineBranding {
+  const b = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+  const appName = typeof b.app_name === 'string' && b.app_name ? b.app_name : DEFAULT_BRANDING.app_name
+  const configuredTitle = typeof b.title === 'string' && b.title ? b.title : null
+  return {
+    app_name: appName,
+    title: configuredTitle ?? (b.app_name ? appName : DEFAULT_BRANDING.title),
+    logo_url: typeof b.logo_url === 'string' && b.logo_url ? b.logo_url : DEFAULT_BRANDING.logo_url,
+    favicon_url:
+      typeof b.favicon_url === 'string' && b.favicon_url ? b.favicon_url : DEFAULT_BRANDING.favicon_url,
+  }
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:resolvebranding:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:loadbranding:function" type="function" identity="loadBranding" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Fetch and cache the instance branding from /spine.config.json"]
+// CIL[DOC-RESPONSIBILITY responsibility="Perform a single fetch per session and memoize the resolved branding"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts,.framework/src/hooks/useBranding.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Promise<SpineBranding>" errors="network/parse failures resolve to DEFAULT_BRANDING" side_effects="one HTTP GET /spine.config.json per session"]
+// CIL[DOC-MICRO logic_summary="Returns cached value if present; otherwise shares one inflight promise across callers; any failure caches defaults so a missing config never retries per component" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export function loadBranding(): Promise<SpineBranding> {
+  if (cached) return Promise.resolve(cached)
+  if (!inflight) {
+    inflight = fetch('/spine.config.json')
+      .then(res => (res.ok ? res.json() : null))
+      .then(config => {
+        cached = resolveBranding(config?.branding)
+        return cached
+      })
+      .catch(() => {
+        cached = DEFAULT_BRANDING
+        return cached
+      })
+  }
+  return inflight
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:loadbranding:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:getcachedbranding:function" type="function" identity="getCachedBranding" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Synchronous read of resolved branding, or defaults before the fetch lands"]
+// CIL[DOC-RESPONSIBILITY responsibility="Give render paths a branding value without awaiting"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="SpineBranding" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="cached ?? DEFAULT_BRANDING" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export function getCachedBranding(): SpineBranding {
+  return cached ?? DEFAULT_BRANDING
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:getcachedbranding:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/lib/branding.ts:applybrandingtodocument:function" type="function" identity="applyBrandingToDocument" parent="~/.framework/src/lib/branding.ts"]
+// CIL[DOC-MACRO purpose="Apply resolved branding to document.title and the favicon link"]
+// CIL[DOC-RESPONSIBILITY responsibility="Swap the framework-shipped favicon/title for instance branding at runtime"]
+// CIL[DOC-CONTEXT module="framework-api" layer="lib" related_files=".framework/src/lib/branding.ts,.framework/index.html"]
+// CIL[DOC-CONTRACT inputs="branding: SpineBranding" outputs="void" errors="none" side_effects="sets document.title; rewrites or creates link[rel~=icon] in document.head"]
+// CIL[DOC-MICRO logic_summary="Idempotent DOM mutation — safe to call on every branding state change from every consumer" notable_decisions="runtime swap keeps .framework/index.html a static framework-owned file that upgrades can replace freely"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+export function applyBrandingToDocument(branding: SpineBranding): void {
+  if (branding.title) document.title = branding.title
+  if (!branding.favicon_url) return
+  let link = document.querySelector<HTMLLinkElement>('link[rel~="icon"]')
+  if (!link) {
+    link = document.createElement('link')
+    link.rel = 'icon'
+    document.head.appendChild(link)
+  }
+  link.href = branding.favicon_url
+}
+// CIL[END stable_id="~/.framework/src/lib/branding.ts:applybrandingtodocument:function"]

package/.framework/src/pages/NoAppPage.tsx

@@ -10,6 +10,7 @@
 
 import React from 'react'
 import { useAuth } from '../contexts/AuthContext'
+import { useBranding } from '../hooks/useBranding'
 // CIL[END stable_id="~/.framework/src/pages/NoAppPage.tsx:module_header:module_header"]
 
 // CIL[BEGIN stable_id="~/.framework/src/pages/NoAppPage.tsx:noapppage:component" type="component" identity="NoAppPage" parent="~/.framework/src/pages/NoAppPage.tsx"]
@@ -22,12 +23,13 @@ import { useAuth } from '../contexts/AuthContext'
 // CIL[DOC-STABILITY stability="experimental"]
 export function NoAppPage() {
   const { logout } = useAuth()
+  const branding = useBranding()
 
   return (
     <div className="min-h-screen flex items-center justify-center bg-slate-50 px-4">
       <div className="max-w-md w-full text-center space-y-6">
         <div className="mx-auto flex items-center justify-center">
-          <img src="/spine-logo.svg" alt="Spine Framework" className="h-14 w-auto" />
+          <img src={branding.logo_url} alt={branding.app_name} className="h-14 w-auto" />
         </div>
         <div className="space-y-2">
           <h1 className="text-2xl font-semibold text-slate-900">No apps yet</h1>

package/.framework/src/pages/SetupPage.tsx

@@ -10,6 +10,7 @@
 
 import React from 'react'
 import { Link } from 'react-router-dom'
+import { useBranding } from '../hooks/useBranding'
 // CIL[DOC-VECTOR type="context" content="purpose='Declare module-level imports for the Setup page'; No verified external callers; imports: none"]
 // 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"]
@@ -28,15 +29,17 @@ import { Link } from 'react-router-dom'
 // CIL[DOC-STABILITY stable]
 
 export function SetupPage() {
+  const branding = useBranding()
+
   return (
     <div className="min-h-screen flex items-center justify-center bg-slate-50 py-12 px-4 sm:px-6 lg:px-8">
       <div className="max-w-lg w-full space-y-8">
         <div className="text-center">
           <div className="mx-auto flex items-center justify-center">
-            <img src="/spine-logo.svg" alt="Spine Framework" className="h-14 w-auto" />
+            <img src={branding.logo_url} alt={branding.app_name} className="h-14 w-auto" />
           </div>
           <h2 className="mt-6 text-3xl font-extrabold text-slate-900">
-            Welcome to Spine
+            Welcome to {branding.app_name}
           </h2>
           <p className="mt-2 text-sm text-slate-600">
             Your project is running but no apps are installed yet.

package/.framework/src/pages/auth/AuthConfirmPage.tsx

@@ -17,6 +17,7 @@ import {
   finalizeRegistration,
   readPendingRegistration,
 } from '../../lib/registration'
+import { useBranding } from '../../hooks/useBranding'
 // CIL[DOC-VECTOR type="context" content="purpose='Defines the AuthConfirmPage React component for confirming email signup and password reset tokens.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/components/ui/LoadingSpinner.tsx"]
 // 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"]
@@ -59,6 +60,7 @@ export function AuthConfirmPage() {
   const [searchParams] = useSearchParams()
   const navigate = useNavigate()
   const { refreshUser } = useAuth()
+  const branding = useBranding()
 
   const tokenHash = searchParams.get('token_hash')
   const type = searchParams.get('type') as 'signup' | 'recovery' | string | null
@@ -275,7 +277,7 @@ export function AuthConfirmPage() {
       <div className="max-w-md w-full space-y-8">
         <div>
           <div className="mx-auto flex items-center justify-center">
-            <img src="/spine-logo.svg" alt="Spine Framework" className="h-14 w-auto" />
+            <img src={branding.logo_url} alt={branding.app_name} className="h-14 w-auto" />
           </div>
           <h2 className="mt-6 text-center text-3xl font-extrabold text-slate-900">
             Set a new password

package/.framework/src/pages/auth/ForgotPasswordPage.tsx

@@ -13,6 +13,7 @@ import { Link } from 'react-router-dom'
 import { supabase } from '../../lib/supabase'
 import { LoadingSpinner } from '../../components/ui/LoadingSpinner'
 import { TurnstileWidget, turnstileEnabled } from '../../components/auth/TurnstileWidget'
+import { useBranding } from '../../hooks/useBranding'
 
 // CIL[DOC-VECTOR type="context" content="purpose='Provides imports and entry-point metadata for the ForgotPasswordPage component.'; No verified external callers; imports: .framework/src/lib/supabase.ts,.framework/src/components/ui/LoadingSpinner.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -36,6 +37,7 @@ export function ForgotPasswordPage() {
   const [isLoading, setIsLoading] = useState(false)
   const [submitted, setSubmitted] = useState(false)
   const [error, setError] = useState('')
+  const branding = useBranding()
 
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault()
@@ -91,7 +93,7 @@ export function ForgotPasswordPage() {
       <div className="max-w-md w-full space-y-8">
         <div>
           <div className="mx-auto flex items-center justify-center">
-            <img src="/spine-logo.svg" alt="Spine Framework" className="h-14 w-auto" />
+            <img src={branding.logo_url} alt={branding.app_name} className="h-14 w-auto" />
           </div>
           <h2 className="mt-6 text-center text-3xl font-extrabold text-slate-900">
             Reset your password

package/.framework/src/pages/auth/LoginPage.tsx

@@ -13,6 +13,7 @@ import { Link, useNavigate } from 'react-router-dom'
 import { useAuth } from '../../contexts/AuthContext'
 import { LoadingSpinner } from '../../components/ui/LoadingSpinner'
 import { TurnstileWidget, turnstileEnabled } from '../../components/auth/TurnstileWidget'
+import { useBranding } from '../../hooks/useBranding'
 
 // CIL[DOC-VECTOR type="context" content="purpose='Module header for the LoginPage component: imports, dependencies, and module-level context.'; No verified external callers; imports: .framework/src/contexts/AuthContext.tsx,.framework/src/components/ui/LoadingSpinner.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -37,6 +38,7 @@ export function LoginPage() {
   const [isLoading, setIsLoading] = useState(false)
   
   const { login } = useAuth()
+  const branding = useBranding()
   const navigate = useNavigate()
 
   const handleSubmit = async (e: React.FormEvent) => {
@@ -74,10 +76,10 @@ export function LoginPage() {
       <div className="max-w-md w-full space-y-8">
         <div>
           <div className="mx-auto flex items-center justify-center">
-            <img src="/spine-logo.svg" alt="Spine Framework" className="h-14 w-auto" />
+            <img src={branding.logo_url} alt={branding.app_name} className="h-14 w-auto" />
           </div>
           <h2 className="mt-6 text-center text-3xl font-extrabold text-slate-900">
-            Sign in to Spine
+            Sign in to {branding.app_name}
           </h2>
           <p className="mt-2 text-center text-sm text-slate-600">
             Or{' '}

package/.framework/src/pages/auth/RegisterPage.tsx

@@ -23,6 +23,7 @@ import {
   PendingRegistrationIntent,
 } from '../../lib/registration'
 import { TurnstileWidget, turnstileEnabled } from '../../components/auth/TurnstileWidget'
+import { useBranding } from '../../hooks/useBranding'
 // CIL[DOC-NOTE type="change" content="Batch4b: POST invites calls go through apiFetch (authenticated); pending-registration intent helpers imported for confirm-email resume"]
 // CIL[END stable_id="~/.framework/src/pages/auth/RegisterPage.tsx:module_header:module_header"]
 // CIL[BEGIN stable_id="~/.framework/src/pages/auth/RegisterPage.tsx:usetype:type" type="type" identity="UseType" parent="~/.framework/src/pages/auth/RegisterPage.tsx"]
@@ -270,6 +271,7 @@ export function RegisterPage() {
   const [searchParams] = useSearchParams()
   const navigate = useNavigate()
   const { user, refreshUser, logout } = useAuth()
+  const branding = useBranding()
   const inviteToken = searchParams.get('t')
   const resumeRequested = searchParams.get('resume') === '1'
 
@@ -652,7 +654,7 @@ export function RegisterPage() {
       <div className="max-w-md w-full space-y-8">
         <div>
           <div className="mx-auto flex items-center justify-center">
-            <img src="/spine-logo.svg" alt="Spine Framework" className="h-14 w-auto" />
+            <img src={branding.logo_url} alt={branding.app_name} className="h-14 w-auto" />
           </div>
           <h2 className="mt-6 text-center text-3xl font-extrabold text-slate-900">
             {isInvite ? 'Complete your registration' : 'Create your account'}

package/.framework/templates/project.json

@@ -4,6 +4,7 @@
     ".framework/functions",
     ".framework/migrations",
     ".framework/public",
+    ".framework/schemas",
     ".framework/scripts",
     ".framework/seeds",
     ".framework/src",

package/.framework/tests/unit/agent-runner.test.ts

@@ -1370,7 +1370,7 @@ describe('executeToolAction — cil_chunk_lookup code content search', () => {
 describe('executeToolAction — escalate_to_human', () => {
   beforeEach(() => vi.clearAllMocks())
 
-  function mockEscalationFlow(opts: { escalationStatus?: string } = {}) {
+  function mockEscalationFlow(opts: { escalationStatus?: string; owner?: string } = {}) {
     const updates: { table: string; payload: any }[] = []
     vi.mocked(adminDb.from).mockImplementation((table: string) => {
       const q: any = {
@@ -1381,7 +1381,7 @@ describe('executeToolAction — escalate_to_human', () => {
         update: vi.fn((payload: any) => { updates.push({ table, payload }); return q }),
         single: vi.fn(() => {
           if (table === 'threads' && q._cols === 'data') {
-            return Promise.resolve({ data: { data: { escalation_status: opts.escalationStatus } }, error: null })
+            return Promise.resolve({ data: { data: { owner: opts.owner, escalation_status: opts.escalationStatus } }, error: null })
           }
           if (table === 'threads' && q._cols === 'target_type, target_id') {
             return Promise.resolve({ data: { target_type: 'items', target_id: 'item-1' }, error: null })
@@ -1419,7 +1419,7 @@ describe('executeToolAction — escalate_to_human', () => {
     expect(res).toEqual({ escalated: true, already_escalated: false, reason: 'no relevant docs' })
     expect(updates).toContainEqual({
       table: 'threads',
-      payload: { data: { escalation_status: 'pending' } }
+      payload: { data: { owner: 'human' } }
     })
     expect(updates).toContainEqual({
       table: 'items',
@@ -1440,6 +1440,20 @@ describe('executeToolAction — escalate_to_human', () => {
     expect(res.already_escalated).toBe(true)
     expect(updates).toHaveLength(0)
   })
+
+  it('dedupes when the thread is already human-owned', async () => {
+    const updates = mockEscalationFlow({ owner: 'human' })
+
+    const res = await executeToolAction(
+      { handler: 'escalate_to_human' },
+      { reason: 'still stuck' },
+      makeCtx(),
+      { threadId: THREAD_ID, config: escConfig }
+    )
+
+    expect(res.already_escalated).toBe(true)
+    expect(updates).toHaveLength(0)
+  })
 })
 // CIL[DOC-VECTOR type="context" content="purpose='Test executeToolAction escalate_to_human handler'; No verified external callers; imports: .framework/functions/_shared/middleware.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/audit.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/outcomes.ts,.framework/functions/admin-data.ts,.framework/functions/integration-outbound.ts,.framework/functions/_shared/agent-runner.ts,.framework/functions/_shared/cil.ts,.framework/functions/_shared/pipeline-runner.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]