spine-framework 0.3.124 → 0.3.126

package/.framework/src/hooks/useApi.ts

@@ -1,52 +1,68 @@
-/**
- * @module src/hooks/useApi
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * Low-level React hooks for async API calls with loading/error state,
- * AbortController-based cancellation, and optional pagination/mutation
- * variants. These are the primitives all higher-level data hooks
- * (`useEntityList`, `useEntityRecord`) build on top of.
- *
- * **Exports:**
- * | Hook              | Purpose                                             |
- * |-------------------|-----------------------------------------------------|
- * | `useApi`          | Single async call with abort + route-change re-fetch|
- * | `usePaginatedApi` | Paginated async call with page/size controls        |
- * | `useMutation`     | Write operation (create/update/delete) with state   |
- *
- * **Abort contract:** `useApi` creates a new `AbortController` per
- * invocation. On route navigation (`location.pathname` change) or on
- * unmount, the in-flight request is aborted and state is reset. This
- * prevents stale responses from a previous route populating the next
- * route's data.
- *
- * @seeAlso src/lib/api.ts (apiFetch — passes AbortSignal through)
- * @seeAlso src/hooks/useEntityList.ts (uses useApi)
- * @seeAlso src/hooks/useEntityRecord.ts (uses useApi + useMutation)
- */
 
-import { useState, useEffect, useCallback, useRef } from 'react'
-import { useLocation } from 'react-router-dom'
 
-// ─── TYPES ───────────────────────────────────────────────────────────────────
 
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="useapi_module_header_1783740744" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React hooks and router for API functionality"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide core React dependencies for API state management"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React hooks" errors="none" side_effects="Module imports"]
+// CIL[DOC-MICRO logic_summary="Imports useState, useEffect, useCallback, useRef from React and useLocation from react-router-dom" 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: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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"]
+import { useState, useEffect, useCallback, useRef } from 'react'
+import { useLocation } from 'react-router-dom'
+// CIL[END chunk_id="useapi_module_header_1783740744"]
+// CIL[BEGIN chunk_id="useapi_apistate_1783740744" type="interface" identity="ApiState" parent="none"]
+// CIL[DOC-MACRO purpose="Define API state structure for loading, data, and error tracking"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own the core state shape for API operations"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="state interface" errors="none" side_effects="Type definition"]
+// CIL[DOC-MICRO logic_summary="Generic interface with data, loading, error, and lastFetched fields" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface ApiState<T> {
   data: T | null
   loading: boolean
   error: string | null
   lastFetched: Date | null
 }
-
-/**
- * Options for `useApi`.
- *
- * @prop immediate - If true, executes the function on mount and on route change
- * @prop onSuccess - Callback fired on successful response
- * @prop onError - Callback fired on error (with message string)
- * @prop initialData - Seed value for `data` before first fetch
- */
+// CIL[END chunk_id="useapi_apistate_1783740744"]
+// CIL[BEGIN chunk_id="useapi_useapioptions_1783740744" type="interface" identity="UseApiOptions" parent="none"]
+// CIL[DOC-MACRO purpose="Configure API hook behavior with callbacks and initial data"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define configuration options for API hook usage"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="options interface" errors="none" side_effects="Type definition"]
+// CIL[DOC-MICRO logic_summary="Options for immediate execution, success/error callbacks, initial data, and dependencies" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.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"]
 interface UseApiOptions<T> {
   immediate?: boolean
   onSuccess?: (data: T) => void
@@ -54,17 +70,21 @@ interface UseApiOptions<T> {
   initialData?: T
   deps?: any[]
 }
-
-/**
- * Return value of `useApi`.
- *
- * @prop data - Response data or null
- * @prop loading - True while the request is in flight
- * @prop error - Error message string or null
- * @prop execute - Imperatively trigger the API call (with optional params)
- * @prop reset - Cancel in-flight request and restore to initial state
- * @prop refetch - Alias for `execute()` with no params
- */
+// CIL[END chunk_id="useapi_useapioptions_1783740744"]
+// CIL[BEGIN chunk_id="useapi_useapireturn_1783740744" type="interface" identity="UseApiReturn" parent="none"]
+// CIL[DOC-MACRO purpose="Define the return value structure for useApi hook"]
+// CIL[DOC-RESPONSIBILITY responsibility="Shape the public API surface for consumers"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="return interface" errors="none" side_effects="Type definition"]
+// CIL[DOC-MICRO logic_summary="Returns state data, loading status, error, and control functions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/principal.ts, .framework/src/pages/admin/IntegrationsPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, .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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface UseApiReturn<T> {
   data: T | null
   loading: boolean
@@ -73,34 +93,21 @@ interface UseApiReturn<T> {
   reset: () => void
   refetch: () => Promise<T>
 }
-
-// ─── useApi ──────────────────────────────────────────────────────────────────
-
-/**
- * Generic async API hook with loading/error state and automatic
- * request cancellation.
- *
- * Each call to `execute` cancels any previous in-flight request via
- * `AbortController`. When `immediate: true`, the hook re-executes
- * (and aborts the prior request) whenever `location.pathname` changes.
- *
- * @param apiFunction - Async function to call; receives `{ ...params, signal }`
- * @param options - `UseApiOptions<T>` — see type for details
- * @returns `UseApiReturn<T>` — data, loading, error, execute, reset, refetch
- *
- * @inputSpec apiFunction must forward `signal` to any underlying `apiFetch`
- *   call, otherwise cancellation is a no-op.
- * @sideEffects React state mutations; aborts in-flight fetch on cleanup
- * @calledBy useEntityList.ts, useEntityRecord.ts
- *
- * @example
- * ```tsx
- * const { data, loading, execute } = useApi(
- *   async () => apiFetch('/api/items?action=list').then(r => r.json()),
- *   { immediate: true }
- * )
- * ```
- */
+// CIL[END chunk_id="useapi_useapireturn_1783740744"]
+// CIL[BEGIN chunk_id="useapi_useapi_1783740744" type="function" identity="useApi" parent="none"]
+// CIL[DOC-MACRO purpose="Core async API hook with loading state and request cancellation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage API calls, state, and automatic cleanup on navigation"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="UseApiReturn" errors="throws API errors" side_effects="React state, AbortController"]
+// CIL[DOC-MICRO logic_summary="Wraps async functions with loading state, error handling, and AbortController for cancellation" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 export function useApi<T>(
   apiFunction: (params?: any) => Promise<T>,
   options: UseApiOptions<T> = {}
@@ -127,15 +134,12 @@ export function useApi<T>(
     lastFetched: null
   })
 
-  // Stable AbortController ref — replaced on each new fetch cycle
   const abortControllerRef = useRef<AbortController | null>(null)
 
   const execute = useCallback(async (params?: any) => {
-    // Create a new AbortController for this specific request
     const abortController = new AbortController()
     const { signal } = abortController
     
-    // Cancel previous request if still running
     abortControllerRef.current?.abort()
     abortControllerRef.current = abortController
 
@@ -147,7 +151,6 @@ export function useApi<T>(
       const result = await apiFunctionRef.current({ ...params, signal })
       const duration = Date.now() - startTime
 
-      // Structured API call log for agentic IDE consumption
       console.log(JSON.stringify({
         type: 'spine_api_call',
         timestamp: new Date().toISOString(),
@@ -198,8 +201,6 @@ export function useApi<T>(
     return execute()
   }, [execute])
 
-  // Re-fetch when pathname changes (navigation) — AbortController cancels
-  // any previous in-flight request so auth state re-renders don't corrupt data
   useEffect(() => {
     if (!immediateRef.current) return
     setState({
@@ -224,9 +225,21 @@ export function useApi<T>(
     refetch
   }
 }
-
-// ─── usePaginatedApi ─────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="useapi_useapi_1783740744"]
+// CIL[BEGIN chunk_id="useapi_paginatedapistate_1783740744" type="interface" identity="PaginatedApiState" parent="none"]
+// CIL[DOC-MACRO purpose="Extend ApiState with pagination metadata for paginated responses"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define state structure for paginated API data"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="paginated state interface" errors="none" side_effects="Type definition"]
+// CIL[DOC-MICRO logic_summary="Extends ApiState with pagination fields for page, totalPages, totalItems, itemsPerPage" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 interface PaginatedApiState<T> extends ApiState<T[]> {
   pagination: {
     page: number
@@ -235,24 +248,39 @@ interface PaginatedApiState<T> extends ApiState<T[]> {
     itemsPerPage: number
   }
 }
-
-/**
- * Options for `usePaginatedApi`. Extends `UseApiOptions` with `itemsPerPage`.
- */
+// CIL[END chunk_id="useapi_paginatedapistate_1783740744"]
+// CIL[BEGIN chunk_id="useapi_usepaginatedapioptions_1783740744" type="interface" identity="UsePaginatedApiOptions" parent="none"]
+// CIL[DOC-MACRO purpose="Extend UseApiOptions with pagination-specific configuration"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define configuration options for paginated API hook"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="paginated options interface" errors="none" side_effects="Type definition"]
+// CIL[DOC-MICRO logic_summary="Extends UseApiOptions with itemsPerPage configuration" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 interface UsePaginatedApiOptions<T> extends UseApiOptions<T[]> {
   itemsPerPage?: number
 }
-
-/**
- * Return value of `usePaginatedApi`. Extends `UseApiReturn` with pagination
- * controls.
- *
- * @prop pagination - Current page, totalPages, totalItems, itemsPerPage
- * @prop setPage - Navigate to a specific page (triggers re-fetch if immediate)
- * @prop setItemsPerPage - Change page size, resets to page 1
- * @prop nextPage / prevPage - Convenience page navigation
- * @prop hasNextPage / hasPrevPage - Boundary guards
- */
+// CIL[END chunk_id="useapi_usepaginatedapioptions_1783740744"]
+// CIL[BEGIN chunk_id="useapi_usepaginatedapireturn_1783740744" type="interface" identity="UsePaginatedApiReturn" parent="none"]
+// CIL[DOC-MACRO purpose="Extend UseApiReturn with pagination navigation controls"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define return structure for paginated API hook with navigation"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="paginated return interface" errors="none" side_effects="Type definition"]
+// CIL[DOC-MICRO logic_summary="Extends UseApiReturn with pagination state and navigation functions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 interface UsePaginatedApiReturn<T> extends UseApiReturn<T[]> {
   pagination: PaginatedApiState<T>['pagination']
   setPage: (page: number) => void
@@ -262,19 +290,21 @@ interface UsePaginatedApiReturn<T> extends UseApiReturn<T[]> {
   hasNextPage: boolean
   hasPrevPage: boolean
 }
-
-/**
- * Paginated variant of `useApi`. Manages page and itemsPerPage state and
- * automatically re-fetches when either changes (if `immediate: true`).
- *
- * @param apiFunction - Must accept `{ page, itemsPerPage, ...params }` and
- *   return `{ data: T[], pagination: { page, totalPages, totalItems, itemsPerPage } }`
- * @param options - `UsePaginatedApiOptions<T>`
- * @returns `UsePaginatedApiReturn<T>`
- *
- * @sideEffects React state mutations
- * @calledBy admin list pages with server-side pagination
- */
+// CIL[END chunk_id="useapi_usepaginatedapireturn_1783740744"]
+// CIL[BEGIN chunk_id="useapi_usepaginatedapi_1783740744" type="function" identity="usePaginatedApi" parent="none"]
+// CIL[DOC-MACRO purpose="Paginated API hook with page navigation and items-per-page controls"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage paginated API state and navigation controls"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="UsePaginatedApiReturn" errors="throws API errors" side_effects="React state, pagination"]
+// CIL[DOC-MICRO logic_summary="Wraps paginated API calls with state management and navigation functions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 export function usePaginatedApi<T>(
   apiFunction: (params: { page: number; itemsPerPage: number; [key: string]: any }) => Promise<{
     data: T[]
@@ -350,7 +380,7 @@ export function usePaginatedApi<T>(
       pagination: {
         ...prev.pagination,
         itemsPerPage,
-        page: 1 // Reset to first page when changing items per page
+        page: 1
       }
     }))
   }, [])
@@ -389,7 +419,6 @@ export function usePaginatedApi<T>(
   const hasNextPage = state.pagination.page < state.pagination.totalPages
   const hasPrevPage = state.pagination.page > 1
 
-  // Auto-execute when page or itemsPerPage changes
   useEffect(() => {
     if (apiOptions.immediate) {
       execute()
@@ -412,37 +441,61 @@ export function usePaginatedApi<T>(
     hasPrevPage
   }
 }
-
-// ─── useMutation ─────────────────────────────────────────────────────────────
-
+// CIL[END chunk_id="useapi_usepaginatedapi_1783740744"]
+// CIL[BEGIN chunk_id="useapi_mutationstate_1783740744" type="interface" identity="MutationState" parent="none"]
+// CIL[DOC-MACRO purpose="Define state structure for mutation operations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own the state shape for write operations"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="mutation state interface" errors="none" side_effects="Type definition"]
+// CIL[DOC-MICRO logic_summary="Simple state interface with data, loading, and error fields for mutations" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 interface MutationState<T> {
   data: T | null
   loading: boolean
   error: string | null
 }
-
-/**
- * Options for `useMutation`.
- *
- * @prop onSuccess - Called with the result after a successful mutation
- * @prop onError - Called with the error message on failure
- * @prop onSettled - Called after success or failure (always fires)
- */
+// CIL[END chunk_id="useapi_mutationstate_1783740744"]
+// CIL[BEGIN chunk_id="useapi_usemutationoptions_1783740744" type="interface" identity="UseMutationOptions" parent="none"]
+// CIL[DOC-MACRO purpose="Define callback options for mutation lifecycle events"]
+// CIL[DOC-RESPONSIBILITY responsibility="Configure mutation hook behavior with lifecycle callbacks"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="mutation options interface" errors="none" side_effects="Type definition"]
+// CIL[DOC-MICRO logic_summary="Options for success, error, and settled callbacks with typed parameters" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 interface UseMutationOptions<T, P> {
   onSuccess?: (data: T) => void
   onError?: (error: string) => void
   onSettled?: () => void
 }
-
-/**
- * Return value of `useMutation`.
- *
- * @prop data - Result of the last successful mutation, or null
- * @prop loading - True while the mutation is in flight
- * @prop error - Error message string or null
- * @prop mutate - Trigger the mutation with typed params
- * @prop reset - Reset state to null/false/null
- */
+// CIL[END chunk_id="useapi_usemutationoptions_1783740744"]
+// CIL[BEGIN chunk_id="useapi_usemutationreturn_1783740744" type="interface" identity="UseMutationReturn" parent="none"]
+// CIL[DOC-MACRO purpose="Define return structure for mutation hook"]
+// CIL[DOC-RESPONSIBILITY responsibility="Shape the public API surface for mutation operations"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="mutation return interface" errors="none" side_effects="Type definition"]
+// CIL[DOC-MICRO logic_summary="Returns mutation state, mutate function, and reset function" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 interface UseMutationReturn<T, P> {
   data: T | null
   loading: boolean
@@ -450,26 +503,21 @@ interface UseMutationReturn<T, P> {
   mutate: (params: P) => Promise<T>
   reset: () => void
 }
-
-/**
- * Write-operation hook for create, update, and delete calls. Does not
- * auto-execute — call `mutate(params)` explicitly.
- *
- * @param mutationFunction - Async write function taking typed params
- * @param options - `UseMutationOptions<T, P>`
- * @returns `UseMutationReturn<T, P>` — data, loading, error, mutate, reset
- *
- * @sideEffects React state mutations; triggers `onSuccess/onError/onSettled` callbacks
- * @calledBy useEntityRecord.ts (save and delete mutations)
- *
- * @example
- * ```tsx
- * const { mutate, loading } = useMutation(
- *   async (id: string) => apiFetch(`/api/items?action=delete&id=${id}`, { method: 'DELETE' }),
- *   { onSuccess: () => navigate('/items') }
- * )
- * ```
- */
+// CIL[END chunk_id="useapi_usemutationreturn_1783740744"]
+// CIL[BEGIN chunk_id="useapi_usemutation_1783740744" type="function" identity="useMutation" parent="none"]
+// CIL[DOC-MACRO purpose="Write-operation hook for create, update, and delete operations"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage mutation state and lifecycle callbacks"]
+// CIL[DOC-CONTEXT module="useApi" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="UseMutationReturn" errors="throws mutation errors" side_effects="React state, callbacks"]
+// CIL[DOC-MICRO logic_summary="Wraps async write operations with loading state and lifecycle callbacks" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// 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"]
 export function useMutation<T, P = void>(
   mutationFunction: (params: P) => Promise<T>,
   options: UseMutationOptions<T, P> = {}
@@ -524,3 +572,4 @@ export function useMutation<T, P = void>(
     reset
   }
 }
+// CIL[END chunk_id="useapi_usemutation_1783740744"]

package/.framework/src/hooks/useAppPath.ts

@@ -1,38 +1,47 @@
-import { useCurrentApp } from '../contexts/AppContext'
 
-/**
- * Returns a helper function that prepends the current app's route_prefix
- * to a root-relative path.
- *
- * Use this instead of hardcoding absolute paths in app components so that
- * changing `route_prefix` in manifest.json (and running update-db-app) is
- * the only change needed to move an app to a new URL location.
- *
- * @example
- * const appPath = useAppPath()
- * appPath('/dashboard')      // → '/cortex/dashboard'  (if prefix is /cortex)
- * appPath('/crm/accounts')   // → '/cortex/crm/accounts'
- * appPath('/')               // → '/cortex'
- *
- * // With route_prefix = '/'
- * appPath('/dashboard')      // → '/dashboard'
- * appPath('/crm/accounts')   // → '/crm/accounts'
- */
+// CIL[BEGIN chunk_id="useapppath_module_header_1783740744" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import app context hook for route prefix access"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide access to current app configuration"]
+// CIL[DOC-CONTEXT module="useAppPath" layer="frontend-hook" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="useCurrentApp hook" errors="none" side_effects="Module imports"]
+// CIL[DOC-MICRO logic_summary="Imports useCurrentApp hook from AppContext for app-specific routing" 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: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/migrations/015_simplify_apps_table.sql, custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/principal.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"]
+import { useCurrentApp } from '../contexts/AppContext'
+// CIL[END chunk_id="useapppath_module_header_1783740744"]
+// CIL[BEGIN chunk_id="useapppath_useapppath_1783740744" type="function" identity="useAppPath" parent="none"]
+// CIL[DOC-MACRO purpose="Generate app-specific path helper with route prefix handling"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage route prefix logic for app-relative paths"]
+// CIL[DOC-CONTEXT module="useAppPath" layer="frontend-hook" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="path helper function" errors="none" side_effects="React hook dependency"]
+// CIL[DOC-MICRO logic_summary="Creates path function that prepends app route_prefix to root-relative paths" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 7. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 7. Total affected: 7."]
+// 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"]
 export function useAppPath(): (path: string) => string {
   const app = useCurrentApp()
 
-  // Normalize: '/' prefix means the app owns root — no prefix to prepend.
-  // Any other prefix is prepended as-is (trailing slash stripped).
   const prefix =
     !app.route_prefix || app.route_prefix === '/'
       ? ''
       : app.route_prefix.replace(/\/$/, '')
 
   return (path: string): string => {
-    // path should be root-relative (start with /)
-    // If the caller passes '/' return just the prefix (or '/' if no prefix)
     if (path === '/') return prefix || '/'
     const normalized = path.startsWith('/') ? path : `/${path}`
     return `${prefix}${normalized}`
   }
 }
+// CIL[END chunk_id="useapppath_useapppath_1783740744"]