spine-framework 0.3.144 → 0.4.0

package/.framework/tests/unit/cil-determinism.test.ts

@@ -0,0 +1,85 @@
+// CIL[BEGIN stable_id="~/.framework/tests/unit/cil-determinism.test.ts:module_header:module_header" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Unit tests for CIL deterministic identity and content hashing utilities"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide test coverage for CIL stable identity generation and content hash normalization"]
+// CIL[DOC-CONTEXT module="cil-determinism.test.ts" layer="tests" related_files=".framework/functions/_shared/cil.ts"]
+// CIL[DOC-CONTRACT inputs="vitest describe/it/expect, cil.ts computeContentHash/generateStableId/parseStableId" outputs="Passing unit test assertions" errors="AssertionError on deterministic/round-trip/hash mismatch failures" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports utilities and sets up a Vitest test module" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="test maintainers"]
+import { describe, it, expect } from 'vitest'
+import { computeContentHash, generateStableId, parseStableId } from '../../functions/_shared/cil.ts'
+// CIL[DOC-VECTOR type="context" content="purpose='Unit tests for CIL deterministic identity and content hashing utilities'; No verified external callers; imports: .framework/functions/_shared/cil.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/tests/unit/cil-determinism.test.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/cil-determinism.test.ts:describe_cil_stable_identity:block" type="block" identity="describe_cil_stable_identity" parent="none"]
+// CIL[DOC-MACRO purpose="Verify stable id generation and parsing are deterministic"]
+// CIL[DOC-RESPONSIBILITY responsibility="Assert generateStableId and parseStableId behave predictably"]
+// CIL[DOC-CONTEXT module="cil-determinism.test.ts" layer="tests" related_files=".framework/functions/_shared/cil.ts,.framework/tests/unit/cil-determinism.test.ts"]
+// CIL[DOC-CONTRACT inputs="file path, identity, and type strings; stable id strings" outputs="Stable id string; parsed stable id object" errors="AssertionError if output does not match expected deterministic id or object" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Tests deterministic stable id formatting and round-trip parsing" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+describe('CIL stable identity', () => {
+  it('generateStableId produces deterministic stable ids', () => {
+    expect(generateStableId('~/.framework/functions/auth.ts', 'getAccount', 'function'))
+      .toBe('~/.framework/functions/auth.ts:getAccount:function')
+  })
+
+  it('parseStableId round-trips stable ids', () => {
+    const id = generateStableId('~/.framework/functions/auth.ts', 'getAccount', 'function')
+    expect(parseStableId(id)).toEqual({
+      canonicalPath: '~/.framework/functions/auth.ts',
+      identity: 'getAccount',
+      type: 'function',
+    })
+  })
+})
+// CIL[DOC-VECTOR type="context" content="purpose='Verify stable id generation and parsing are deterministic'; No verified external callers; imports: .framework/functions/_shared/cil.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/tests/unit/cil-determinism.test.ts:describe_cil_stable_identity:block"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/cil-determinism.test.ts:describe_cil_content_hash:block" type="block" identity="describe_cil_content_hash" parent="none"]
+// CIL[DOC-MACRO purpose="Verify content hash is deterministic and normalizes CIL markers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Assert computeContentHash produces consistent hashes and ignores CIL markers/blank lines"]
+// CIL[DOC-CONTEXT module="cil-determinism.test.ts" layer="tests" related_files=".framework/functions/_shared/cil.ts,.framework/tests/unit/cil-determinism.test.ts"]
+// CIL[DOC-CONTRACT inputs="JavaScript function source strings" outputs="32-character hexadecimal hash string" errors="AssertionError on hash mismatch or non-hex output" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Tests hash determinism, CIL marker stripping, and sensitivity to code changes" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+describe('CIL content_hash', () => {
+  it('computeContentHash is deterministic for identical inputs', () => {
+    const h1 = computeContentHash('function foo() { return 1 }')
+    const h2 = computeContentHash('function foo() { return 1 }')
+    expect(h1).toBe(h2)
+    expect(h1).toMatch(/^[0-9a-f]{32}$/)
+  })
+
+  it('computeContentHash normalizes away CIL markers and blank lines', () => {
+    const withCil = '// CIL[BEGIN]\nfunction foo() { return 1 }\n// CIL[END]\n\n'
+    const without = 'function foo() { return 1 }'
+    expect(computeContentHash(withCil)).toBe(computeContentHash(without))
+  })
+
+  it('computeContentHash changes when code changes', () => {
+    const h1 = computeContentHash('function foo() { return 1 }')
+    const h2 = computeContentHash('function foo() { return 2 }')
+    expect(h1).not.toBe(h2)
+  })
+})
+// CIL[DOC-VECTOR type="context" content="purpose='Verify content hash is deterministic and normalizes CIL markers'; No verified external callers; imports: .framework/functions/_shared/cil.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/tests/unit/cil-determinism.test.ts:describe_cil_content_hash:block"]

package/.framework/tests/unit/core-isolation.test.ts

@@ -0,0 +1,153 @@
+// CIL[BEGIN stable_id="~/.framework/tests/unit/core-isolation.test.ts:module_header:module_header" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Test setup and imports for core isolation tests"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure test environment for core isolation"]
+// CIL[DOC-CONTEXT module="tests/unit/core-isolation" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/webhook-registry.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="test imports" errors="none" side_effects="Imports vitest and core modules"]
+// CIL[DOC-MICRO logic_summary="Imports vitest, db, webhook-registry, app-manifest, and middleware" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developers"]
+import { describe, it, expect, beforeAll } from 'vitest'
+import { adminDb } from '../../functions/_shared/db'
+import { resolveHandler, lookupHandler } from '../../functions/_shared/webhook-registry'
+import { loadManifest, discoverManifests } from '../../functions/_shared/app-manifest'
+import { createHandler } from '../../functions/_shared/middleware'
+// CIL[DOC-VECTOR type="context" content="purpose='Test setup and imports for core isolation tests'; No verified external callers; imports: .framework/functions/_shared/db.ts,.framework/functions/_shared/webhook-registry.ts,.framework/functions/_shared/app-manifest.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/tests/unit/core-isolation.test.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/core-isolation.test.ts:describe_CoreIsolation:block" type="block" identity="describe_CoreIsolation" parent="none"]
+// CIL[DOC-MACRO purpose="Test core functionality works without custom code"]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify core independence from custom code"]
+// CIL[DOC-CONTEXT module="tests/unit/core-isolation" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/webhook-registry.ts,.framework/tests/unit/core-isolation.test.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="test assertions" errors="none" side_effects="Tests core modules"]
+// CIL[DOC-MICRO logic_summary="Tests webhook registry, app manifests, DB access, handler creation, and permissions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+describe('Core Isolation', () => {
+  describe('Webhook Registry', () => {
+    it('should have empty registry when no custom handlers registered', async () => {
+      const handlers = await lookupHandler('non-existent-handler')
+      expect(handlers).toBeNull()
+    })
+
+    it('should fail gracefully when resolving unknown handler', async () => {
+      const handler = await resolveHandler('unknown-handler')
+      expect(handler).toBeNull()
+    })
+
+    it('should not depend on custom_webhook-handlers.ts', async () => {
+      const registry = await import('../../functions/_shared/webhook-registry')
+      expect(registry.resolveHandler).toBeDefined()
+      expect(registry.lookupHandler).toBeDefined()
+      expect(registry.loadHandler).toBeDefined()
+    })
+  })
+
+  describe('App Manifest System', () => {
+    it('should discover manifests without error', () => {
+      const manifests = discoverManifests()
+      expect(Array.isArray(manifests)).toBe(true)
+    })
+
+    it('should handle missing manifest gracefully', () => {
+      const manifest = loadManifest('non/existent/manifest.json')
+      expect(manifest).toBeNull()
+    })
+
+    it('should load valid manifest if exists', () => {
+      const manifest = loadManifest('custom/apps/cortex/manifest.json')
+      if (manifest) {
+        expect(manifest.slug).toBeDefined()
+        expect(manifest.name).toBeDefined()
+        expect(Array.isArray(manifest.required_roles)).toBe(true)
+      }
+    })
+  })
+
+  // Live-DB probes — only meaningful when real credentials are configured
+  // (`.env.test` in the monorepo). The setup file stubs a placeholder URL for
+  // unit runs; hitting it would produce a fetch error, so gate on the stub.
+  const LIVE_DB =
+    !!process.env.SUPABASE_URL && !process.env.SUPABASE_URL.includes('test.supabase.co')
+
+  describe.runIf(LIVE_DB)('Database Access', () => {
+    it('should connect to database without custom code', async () => {
+      const { data, error } = await adminDb.from('accounts').select('id').limit(1)
+      expect(error).toBeNull()
+    })
+
+    it('should query apps without custom dependencies', async () => {
+      const { data, error } = await adminDb
+        .from('apps')
+        .select('slug, name, is_active')
+        .limit(1)
+      
+      expect(error).toBeNull()
+      expect(Array.isArray(data) || data === null).toBe(true)
+    })
+  })
+
+  describe('Handler Creation', () => {
+    it('should create handler without custom imports', () => {
+      const handler = createHandler(async (event, ctx) => {
+        return { status: 'ok' }
+      })
+
+      expect(handler).toBeDefined()
+      expect(typeof handler).toBe('function')
+    })
+  })
+
+  describe('Permission System', () => {
+    it('should check permissions without custom code', async () => {
+      const { isSystemAdmin } = await import('../../functions/_shared/permissions')
+
+      const memberCtx = { principal: { id: 'test-user', account_id: 'test-account', roles: [] } }
+      const adminCtx = { principal: { id: 'admin-user', account_id: 'test-account', roles: [{ slug: 'system_admin' }] } }
+
+      expect(isSystemAdmin(memberCtx as any)).toBe(false)
+      expect(isSystemAdmin(adminCtx as any)).toBe(true)
+    })
+  })
+})
+// CIL[DOC-VECTOR type="context" content="purpose='Test core functionality works without custom code'; No verified external callers; imports: .framework/functions/_shared/db.ts,.framework/functions/_shared/webhook-registry.ts,.framework/functions/_shared/app-manifest.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/tests/unit/core-isolation.test.ts:describe_CoreIsolation:block"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/core-isolation.test.ts:describe_NoCoreCustomImports:block" type="block" identity="describe_NoCoreCustomImports" parent="none"]
+// CIL[DOC-MACRO purpose="Test core files don't import custom code"]
+// CIL[DOC-RESPONSIBILITY responsibility="Verify static import boundaries"]
+// CIL[DOC-CONTEXT module="tests/unit/core-isolation" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/webhook-registry.ts,.framework/tests/unit/core-isolation.test.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="test assertions" errors="none" side_effects="Conceptual test only"]
+// CIL[DOC-MICRO logic_summary="Documents expected clean files without actual file reading" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+describe('No Core→Custom Imports', () => {
+  it('should verify no static imports from custom/', async () => {
+    const expectedCleanFiles = [
+      '.framework/functions/integration-routes.ts',
+      '.framework/functions/apps.ts',
+      '.framework/src/hooks/useApps.ts'
+    ]
+    
+    expectedCleanFiles.forEach(file => {
+      expect(file).toContain('.framework/')
+    })
+  })
+})
+// CIL[DOC-VECTOR type="context" content="purpose='Test core files don't import custom code'; No verified external callers; imports: .framework/functions/_shared/db.ts,.framework/functions/_shared/webhook-registry.ts,.framework/functions/_shared/app-manifest.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/tests/unit/core-isolation.test.ts:describe_NoCoreCustomImports:block"]

package/.framework/tests/unit/funnel-signals.test.ts

@@ -0,0 +1,135 @@
+// CIL[DOC-MACRO purpose="Unit tests for emitSignal dedupe_scope behavior in _shared/funnel.ts"]
+// CIL[DOC-RESPONSIBILITY responsibility="Assert the optional dedupe_scope narrows the dedupe lookup to (account_id, action_type, dedupe_scope), is stamped into the inserted row data, and that omitting it preserves the once-per-account default"]
+// CIL[DOC-CONTEXT module="funnel-signals.test" layer="test-unit" related_files=".framework/functions/_shared/funnel.ts"]
+// CIL[DOC-CONTRACT inputs="mocked adminDb + fireCreateTriggers" outputs="expect assertions on query filters and inserted payloads" errors="none" side_effects="registers vi.mock factories"]
+// CIL[DOC-AUDIENCE audience="test"]
+// CIL[DOC-STABILITY stability="stable"]
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('../../functions/_shared/db.ts', () => ({
+  adminDb: { from: vi.fn(), rpc: vi.fn() },
+}))
+vi.mock('../../functions/_shared/trigger-engine.ts', () => ({
+  fireCreateTriggers: vi.fn().mockResolvedValue(undefined),
+}))
+
+import { adminDb } from '../../functions/_shared/db.ts'
+import { emitSignal } from '../../functions/_shared/funnel.ts'
+
+function ctx(): any {
+  return { accountId: 'acct-1', principal: { id: 'p-1', type: 'human' } }
+}
+
+/**
+ * Recording query builder — captures every chain call so tests can assert
+ * which filters were applied. `terminal` is the value single/maybeSingle/
+ * then resolve with.
+ */
+function chain(calls: any[][], terminal: any): any {
+  const b: any = {}
+  const rec = (name: string) => (...args: any[]) => {
+    calls.push([name, ...args])
+    return b
+  }
+  for (const m of [
+    'select', 'eq', 'in', 'or', 'is', 'not', 'order', 'insert', 'update',
+    'delete', 'upsert', 'lt', 'gt', 'lte', 'gte', 'neq', 'contains', 'limit',
+  ]) b[m] = rec(m)
+  b.single = () => Promise.resolve(terminal)
+  b.maybeSingle = () => Promise.resolve(terminal)
+  b.then = (res: any, rej?: any) => Promise.resolve(terminal).then(res, rej)
+  return b
+}
+
+/**
+ * Wire adminDb so `types` resolves the signal type and `items` answers the
+ * dedupe lookup (first call) and the insert (second call). Returns the
+ * recorded call lists.
+ */
+function mockDb(opts: { dedupeRows?: any[] } = {}) {
+  const itemsCalls: any[][] = []
+  let itemsCallIdx = 0
+  vi.mocked(adminDb.from).mockImplementation((table: string) => {
+    if (table === 'types') {
+      return chain([], { data: { id: 'type-demo-signal' }, error: null })
+    }
+    if (table === 'items') {
+      itemsCallIdx++
+      return chain(
+        itemsCalls,
+        itemsCallIdx === 1
+          ? { data: opts.dedupeRows ?? [], error: null }
+          : { data: { id: 'sig-1', type_id: 'type-demo-signal' }, error: null }
+      )
+    }
+    return chain([], { data: null, error: null })
+  })
+  return { itemsCalls }
+}
+
+describe('emitSignal — dedupe_scope', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('narrows the dedupe lookup by data.dedupe_scope and stamps it on the row', async () => {
+    const { itemsCalls } = mockDb()
+    const created = await emitSignal(ctx(), {
+      type_slug: 'demo_signal',
+      action: 'workflow_completed',
+      dedupe_scope: 'run-1',
+      data: { source: 'demo' },
+    })
+    expect(created?.id).toBe('sig-1')
+    // The dedupe query filters on the scope marker.
+    expect(itemsCalls).toContainEqual(['eq', 'data->>dedupe_scope', 'run-1'])
+    // The inserted row carries the scope so later lookups match.
+    const insert = itemsCalls.find((c) => c[0] === 'insert')
+    expect(insert?.[1]?.data?.dedupe_scope).toBe('run-1')
+    expect(insert?.[1]?.data?.action_type).toBe('workflow_completed')
+  })
+
+  it('omits the scope filter entirely when dedupe_scope is not set', async () => {
+    const { itemsCalls } = mockDb()
+    const created = await emitSignal(ctx(), {
+      type_slug: 'demo_signal',
+      action: 'demo_started',
+      data: { source: 'demo' },
+    })
+    expect(created?.id).toBe('sig-1')
+    expect(itemsCalls.some((c) => c[0] === 'eq' && c[1] === 'data->>dedupe_scope')).toBe(false)
+    const insert = itemsCalls.find((c) => c[0] === 'insert')
+    expect(insert?.[1]?.data).not.toHaveProperty('dedupe_scope')
+  })
+
+  it('skips the insert when a scoped signal already exists for the run', async () => {
+    const { itemsCalls } = mockDb({ dedupeRows: [{ id: 'existing' }] })
+    const created = await emitSignal(ctx(), {
+      type_slug: 'demo_signal',
+      action: 'workflow_completed',
+      dedupe_scope: 'run-1',
+    })
+    expect(created).toBeNull()
+    expect(itemsCalls.some((c) => c[0] === 'insert')).toBe(false)
+  })
+
+  it('skips the dedupe lookup entirely when dedupe is false', async () => {
+    const { itemsCalls } = mockDb()
+    await emitSignal(ctx(), {
+      type_slug: 'demo_signal',
+      action: 'demo_started',
+      dedupe: false,
+    })
+    expect(itemsCalls.some((c) => c[0] === 'eq' && c[1] === 'data->>action_type')).toBe(false)
+    expect(itemsCalls.some((c) => c[0] === 'insert')).toBe(true)
+  })
+
+  it('returns null when the signal type is not installed', async () => {
+    vi.mocked(adminDb.from).mockImplementation((table: string) =>
+      chain([], table === 'types' ? { data: null, error: null } : { data: [], error: null })
+    )
+    const created = await emitSignal(ctx(), {
+      type_slug: 'demo_signal',
+      action: 'demo_started',
+    })
+    expect(created).toBeNull()
+  })
+})