@jkwd/inbase 0.1.21 → 0.1.23

package/apps/explorer/src/agentIntent.ts

@@ -3,6 +3,7 @@ import type {
   AgentIntentBundle,
   BlueprintNote,
   BlueprintPointer,
+  LocalBlueprint,
   PatchImport,
   PatchImportAddition,
   PatchSymbolAddition,
@@ -10,6 +11,7 @@ import type {
   UserCreatedIsland,
   WorkflowAction,
 } from './types'
+import { GLOBAL_BLUEPRINT_COLOR } from './types'
 import {
   parseBlueprintNotes,
   parseBlueprintPointers,
@@ -92,6 +94,9 @@ export const emptyIntent: AgentIntent = {
   showMap: false,
   status: 'idle',
   name: null,
+  color: null,
+  colorName: null,
+  colorHex: null,
   feature: null,
   steps: [],
   step: null,
@@ -121,7 +126,8 @@ export const emptyIntent: AgentIntent = {
   llmIdle: false,
   awaitingAttach: false,
   listening: false,
-  lastAck: null,
+    lastAck: null,
+    pendingExplain: false,
   initialInstruction: null,
   contextFiles: [],
   creationMode: false,
@@ -129,6 +135,7 @@ export const emptyIntent: AgentIntent = {
   blueprintHidden: false,
   blueprintRevision: 0,
   blueprintSessionId: null,
+  localBlueprintEnabled: false,
   userCreatedBlocks: [],
   userCreatedIslands: [],
   blueprintFunctions: [],
@@ -144,6 +151,9 @@ function normalize(data: Partial<AgentIntent> | null | undefined): AgentIntent {
     showMap: Boolean(data?.showMap),
     status: data?.status ?? 'idle',
     name: data?.name ?? null,
+    color: typeof data?.color === 'string' ? data.color : null,
+    colorName: typeof data?.colorName === 'string' ? data.colorName : null,
+    colorHex: typeof data?.colorHex === 'string' ? data.colorHex : null,
     feature: data?.feature ?? null,
     steps: Array.isArray(data?.steps) ? data.steps : [],
     step: typeof data?.step === 'number' ? data.step : null,
@@ -177,6 +187,7 @@ function normalize(data: Partial<AgentIntent> | null | undefined): AgentIntent {
     awaitingAttach: Boolean(data?.awaitingAttach),
     listening: Boolean(data?.listening),
     lastAck: normalizeAck(data?.lastAck),
+    pendingExplain: Boolean(data?.pendingExplain),
     initialInstruction:
       typeof data?.initialInstruction === 'string' ? data.initialInstruction : null,
     contextFiles: normalizeContextFiles(data?.contextFiles),
@@ -189,6 +200,7 @@ function normalize(data: Partial<AgentIntent> | null | undefined): AgentIntent {
       typeof data?.blueprintSessionId === 'string'
         ? data.blueprintSessionId
         : null,
+    localBlueprintEnabled: Boolean(data?.localBlueprintEnabled),
     userCreatedBlocks: parseUserCreatedBlocks(data?.userCreatedBlocks),
     userCreatedIslands: parseUserCreatedIslands(data?.userCreatedIslands),
     blueprintFunctions: normalizeSymbolAdditions(data?.blueprintFunctions),
@@ -214,6 +226,28 @@ function normalizeBlueprint(data: Partial<AgentIntentBundle['blueprint']> | null
   }
 }
 
+function normalizeLocalBlueprints(value: unknown): LocalBlueprint[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((item) => {
+    if (!item || typeof item !== 'object') return []
+    const row = item as Partial<LocalBlueprint>
+    const color = typeof row.color === 'string' ? row.color : ''
+    const colorName = typeof row.colorName === 'string' ? row.colorName : ''
+    const colorHex = typeof row.colorHex === 'string' ? row.colorHex : ''
+    const sessionId = typeof row.sessionId === 'string' ? row.sessionId : ''
+    if (!color || !sessionId) return []
+    return [
+      {
+        ...normalizeBlueprint(row),
+        color,
+        colorName,
+        colorHex,
+        sessionId,
+      },
+    ]
+  })
+}
+
 export async function fetchAgentIntents(): Promise<AgentIntentBundle> {
   const query = new URLSearchParams({ t: String(Date.now()) })
   const response = await fetch(`/api/agent-intent?${query}`)
@@ -224,6 +258,7 @@ export async function fetchAgentIntents(): Promise<AgentIntentBundle> {
       nextAttachSessionId: null,
       intents: [],
       blueprint: emptyBlueprint,
+      localBlueprints: [],
     }
   }
   const data = (await response.json()) as {
@@ -232,6 +267,7 @@ export async function fetchAgentIntents(): Promise<AgentIntentBundle> {
     intents?: unknown
     sessionId?: string | null
     blueprint?: Partial<AgentIntentBundle['blueprint']>
+    localBlueprints?: unknown
   } & Partial<AgentIntent>
   if (Array.isArray(data.intents)) {
     return {
@@ -245,6 +281,7 @@ export async function fetchAgentIntents(): Promise<AgentIntentBundle> {
         .map((intent) => normalize(intent as Partial<AgentIntent>))
         .filter((intent) => Boolean(intent.sessionId)),
       blueprint: normalizeBlueprint(data.blueprint),
+      localBlueprints: normalizeLocalBlueprints(data.localBlueprints),
     }
   }
   const intent = normalize(data)
@@ -252,6 +289,7 @@ export async function fetchAgentIntents(): Promise<AgentIntentBundle> {
     focusedSessionId: intent.sessionId,
     nextAttachSessionId: intent.awaitingAttach ? intent.sessionId : null,
     intents: intent.sessionId ? [intent] : [],
+    localBlueprints: [],
     blueprint: normalizeBlueprint(data.blueprint ?? {
       hidden: intent.blueprintHidden,
       revision: intent.blueprintRevision,
@@ -320,6 +358,7 @@ export async function performAgentAction(
 export function persistSessionBlueprint(
   sessionId: string | null | undefined,
   payload: {
+    color?: string | null
     userCreatedBlocks: UserCreatedBlock[]
     userCreatedIslands: UserCreatedIsland[]
     addedFunctions?: PatchSymbolAddition[]
@@ -336,36 +375,51 @@ export function persistSessionBlueprint(
       action: 'blueprint_update',
       sessionId,
       ...payload,
+      color: payload.color ?? GLOBAL_BLUEPRINT_COLOR.id,
     }),
   }).catch(() => {
-    // Keep local drafts if the visualizer could not save the shared blueprint.
+    // Keep local drafts if the visualizer could not save the blueprint.
   })
 }
 
-export function persistBlueprintHidden(hidden: boolean) {
+export function persistBlueprintHidden(
+  hidden: boolean,
+  color: string | null | undefined = GLOBAL_BLUEPRINT_COLOR.id,
+) {
   return fetch('/api/agent-intent', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
       action: 'blueprint_set_hidden',
       hidden,
+      color: color ?? GLOBAL_BLUEPRINT_COLOR.id,
     }),
   })
 }
 
-export function persistBlueprintClear() {
+export function persistBlueprintClear(
+  color: string | null | undefined = GLOBAL_BLUEPRINT_COLOR.id,
+) {
   return fetch('/api/agent-intent', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ action: 'blueprint_clear' }),
+    body: JSON.stringify({
+      action: 'blueprint_clear',
+      color: color ?? GLOBAL_BLUEPRINT_COLOR.id,
+    }),
   })
 }
 
-export function persistBlueprintCleanup() {
+export function persistBlueprintCleanup(
+  color: string | null | undefined = GLOBAL_BLUEPRINT_COLOR.id,
+) {
   return fetch('/api/agent-intent', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ action: 'blueprint_cleanup' }),
+    body: JSON.stringify({
+      action: 'blueprint_cleanup',
+      color: color ?? GLOBAL_BLUEPRINT_COLOR.id,
+    }),
   })
 }
 

package/apps/explorer/src/codebase.ts

@@ -1,6 +1,6 @@
 import type { CodebaseGraph } from './types'
 
-function parseCodebase(data: unknown): CodebaseGraph | null {
+export function parseCodebase(data: unknown): CodebaseGraph | null {
   if (
     !data ||
     typeof data !== 'object' ||

package/apps/explorer/src/devTargets.ts

@@ -0,0 +1,66 @@
+import { parseCodebase } from './codebase'
+import type { CodebaseGraph } from './types'
+
+export type DevTargetOption = {
+  id: string
+  label: string
+}
+
+export type DevTargetsState = {
+  enabled: boolean
+  currentId: string | null
+  targets: DevTargetOption[]
+}
+
+export const emptyDevTargets: DevTargetsState = {
+  enabled: false,
+  currentId: null,
+  targets: [],
+}
+
+function parseState(data: unknown): DevTargetsState {
+  if (!data || typeof data !== 'object') return emptyDevTargets
+  const record = data as DevTargetsState
+  if (!record.enabled || !Array.isArray(record.targets)) return emptyDevTargets
+  return {
+    enabled: true,
+    currentId: typeof record.currentId === 'string' ? record.currentId : null,
+    targets: record.targets.filter(
+      (item): item is DevTargetOption =>
+        Boolean(item) &&
+        typeof item.id === 'string' &&
+        typeof item.label === 'string',
+    ),
+  }
+}
+
+export async function fetchDevTargets(): Promise<DevTargetsState> {
+  try {
+    const response = await fetch('/api/dev-targets')
+    if (!response.ok) return emptyDevTargets
+    return parseState(await response.json())
+  } catch {
+    return emptyDevTargets
+  }
+}
+
+export async function selectDevTarget(id: string): Promise<{
+  state: DevTargetsState
+  graph: CodebaseGraph | null
+} | null> {
+  try {
+    const response = await fetch('/api/dev-targets', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id }),
+    })
+    if (!response.ok) return null
+    const payload = (await response.json()) as { codebase?: unknown }
+    return {
+      state: parseState(payload),
+      graph: parseCodebase(payload.codebase),
+    }
+  } catch {
+    return null
+  }
+}

package/apps/explorer/src/explain.ts

@@ -0,0 +1,312 @@
+import { folderOfFile } from './layout'
+import type {
+  CodebaseGraph,
+  ExplainSession,
+  ExplainStep,
+  ExplainSymbolRef,
+  ExplainTargetKind,
+  FileNode,
+  PatchImport,
+} from './types'
+
+export function emptyExplain(): ExplainSession {
+  return {
+    active: false,
+    question: '',
+    steps: [],
+    currentStep: '1',
+    pendingQuestion: null,
+    pendingStart: null,
+    answering: false,
+    presentation: 'walk',
+    updatedAt: null,
+  }
+}
+
+export function explainIsCard(explain: ExplainSession) {
+  return explain.active && explain.presentation === 'card'
+}
+
+export async function fetchExplain(): Promise<ExplainSession> {
+  try {
+    const query = new URLSearchParams({ t: String(Date.now()) })
+    const response = await fetch(`/api/explain?${query}`)
+    if (!response.ok) return emptyExplain()
+    return (await response.json()) as ExplainSession
+  } catch {
+    return emptyExplain()
+  }
+}
+
+export function persistExplainStep(step: string) {
+  return fetch('/api/explain', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'set_step', step }),
+  }).catch(() => {
+    // Keep the local step if the visualizer could not save it.
+  })
+}
+
+export function persistExplainAsk(step: string, question: string) {
+  return fetch('/api/explain', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'ask', step, question }),
+  }).catch(() => {
+    // Keep the local question if the visualizer could not save it.
+  })
+}
+
+export function persistExplainStop() {
+  return fetch('/api/explain', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'stop' }),
+  }).catch(() => {
+    // Keep the local overlay if the visualizer could not stop.
+  })
+}
+
+export function explainTargetLabel(input: {
+  kind: ExplainTargetKind
+  path: string
+  name?: string
+}) {
+  const symbol = input.name?.trim() ?? ''
+  return symbol
+    ? `${input.kind} ${symbol} in ${input.path}`
+    : `${input.kind} ${input.path}`
+}
+
+export function explainTargetQuestion(
+  kind: ExplainTargetKind,
+  path: string,
+  name?: string,
+) {
+  return `Explain the function of the ${explainTargetLabel({ kind, path, name })} and where it fits in the codebase.`
+}
+
+export function persistExplainStart(input: {
+  kind: ExplainTargetKind
+  path: string
+  name?: string
+  sessionId?: string | null
+}) {
+  return fetch('/api/explain', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'start', ...input }),
+  }).catch(() => {
+    // Keep the local overlay if the visualizer could not start.
+  })
+}
+
+export function currentExplainStep(explain: ExplainSession): ExplainStep | null {
+  if (!explain.active || explain.steps.length === 0) return null
+  return (
+    explain.steps.find((step) => step.index === explain.currentStep) ??
+    explain.steps[0] ??
+    null
+  )
+}
+
+export function explainStepPosition(explain: ExplainSession, id: string) {
+  return explain.steps.findIndex((step) => step.index === id)
+}
+
+export function explainNeighbor(
+  explain: ExplainSession,
+  id: string,
+  delta: number,
+) {
+  const position = explainStepPosition(explain, id)
+  if (position < 0) return null
+  return explain.steps[position + delta]?.index ?? null
+}
+
+export function explainStepDepth(id: string) {
+  return String(id).split('.').length - 1
+}
+
+export function topLevelExplainStepId(id: string) {
+  const next = String(id)
+  const dot = next.indexOf('.')
+  return dot === -1 ? next : next.slice(0, dot)
+}
+
+export function stripExplainSubSteps(steps: ExplainStep[]): ExplainStep[] {
+  return steps
+    .filter((step) => !step.index.includes('.'))
+    .map((step) => ({ ...step, asked: '' }))
+}
+
+export function explainIsPreparing(explain: ExplainSession) {
+  if (!explain.active) return false
+  if (explain.steps.length === 0) return true
+  return Boolean(explain.pendingQuestion) || explain.answering
+}
+
+export function explainSpeechText(step: Pick<ExplainStep, 'title' | 'body'> | null) {
+  if (!step) return ''
+  return [step.title, step.body]
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .join('. ')
+}
+
+export function explainCardCopy(explain: ExplainSession) {
+  const first =
+    explain.steps.find((step) => !step.index.includes('.') && step.body.trim()) ??
+    explain.steps.find((step) => !step.index.includes('.')) ??
+    null
+  const pending = explain.pendingStart
+  const title = pending
+    ? pending.name?.trim() || pending.path.split('/').pop() || pending.path
+    : first?.title.trim() || 'Explanation'
+  return {
+    title,
+    body: first?.body.trim() ?? '',
+    ready: Boolean(first?.body.trim()),
+  }
+}
+
+export function explainSymbolKey(ref: ExplainSymbolRef) {
+  return `${ref.kind}:${ref.name}`
+}
+
+export function explainMatchesSymbol(
+  ref: ExplainSymbolRef | null | undefined,
+  kind: FileNode['symbols'][number]['kind'] | 'file',
+  name: string,
+) {
+  if (!ref) return false
+  if (ref.kind === 'file') return kind === 'file'
+  if (ref.kind === 'symbol') return kind !== 'file' && ref.name === name
+  return ref.kind === kind && ref.name === name
+}
+
+export function explainHitsSymbol(
+  refs: ExplainSymbolRef[],
+  kind: FileNode['symbols'][number]['kind'] | 'file',
+  name: string,
+) {
+  return refs.some((ref) => explainMatchesSymbol(ref, kind, name))
+}
+
+export function explainInfoFile(
+  step: ExplainStep | null,
+  graph: CodebaseGraph,
+): FileNode | null {
+  if (!step?.info || !step.select) return null
+  return (
+    graph.files.find((file) => file.id === step.select) ?? {
+      id: step.select,
+      name: step.select.split('/').pop() || step.select,
+      path: step.select,
+      folder: '',
+      lines: 0,
+      language: '',
+      symbols: [],
+      imports: [],
+    }
+  )
+}
+
+export type ExplainFocus = {
+  files: Set<string>
+  folders: Set<string>
+  select: string | null
+  importedBy: boolean
+  relations: PatchImport[]
+  zoomFiles: string[]
+  zoomFolders: string[]
+}
+
+export function explainFocus(
+  step: ExplainStep | null,
+  graph: CodebaseGraph,
+): ExplainFocus | null {
+  if (!step) return null
+  const files = new Set(step.files)
+  const folders = new Set(step.folders)
+  if (step.select) files.add(step.select)
+  const relations: PatchImport[] = step.relations.map((edge) => ({
+    from: edge.from,
+    to: edge.to,
+  }))
+  for (const edge of relations) {
+    files.add(edge.from)
+    files.add(edge.to)
+  }
+  if (step.select) {
+    if (step.importedBy) {
+      for (const file of graph.files) {
+        if (file.imports.includes(step.select)) files.add(file.id)
+      }
+    } else {
+      const selected = graph.files.find((file) => file.id === step.select)
+      for (const id of selected?.imports ?? []) files.add(id)
+    }
+  }
+  for (const file of graph.files) {
+    if (folders.has(file.folder)) files.add(file.id)
+  }
+  for (const id of files) {
+    const folder = graph.files.find((file) => file.id === id)?.folder ?? folderOfFile(id)
+    if (folder) folders.add(folder)
+  }
+
+  const zoomFolders = step.zoom
+    ? graph.folders.some((folder) => folder.path === step.zoom)
+      ? [step.zoom]
+      : []
+    : [...step.folders]
+  const zoomFiles = step.zoom
+    ? graph.files.some((file) => file.id === step.zoom)
+      ? [step.zoom]
+      : []
+    : [...step.files]
+  if (step.zoom && zoomFolders.length === 0 && zoomFiles.length === 0) {
+    zoomFiles.push(step.zoom)
+  }
+
+  return {
+    files,
+    folders,
+    select: step.select,
+    importedBy: step.importedBy,
+    relations,
+    zoomFiles: zoomFiles.length > 0 ? zoomFiles : [...files],
+    zoomFolders: zoomFolders.length > 0 ? zoomFolders : [...folders],
+  }
+}
+
+export function explainHasFocus(focus: ExplainFocus | null) {
+  return Boolean(focus && (focus.files.size > 0 || focus.folders.size > 0))
+}
+
+export function explainFileFocused(
+  focus: ExplainFocus | null,
+  fileId: string,
+  _folder?: string,
+) {
+  if (!explainHasFocus(focus) || !focus) return true
+  return focus.files.has(fileId)
+}
+
+export function explainFileHighlighted(
+  focus: ExplainFocus | null,
+  fileId: string,
+  folder?: string,
+) {
+  return explainHasFocus(focus) && explainFileFocused(focus, fileId, folder)
+}
+
+export function explainFolderFocused(focus: ExplainFocus | null, folderPath: string) {
+  if (!explainHasFocus(focus) || !focus) return true
+  for (const id of focus.files) {
+    if (folderOfFile(id) === folderPath) return true
+  }
+  return false
+}