@jkwd/inbase 0.1.9 → 0.1.11

package/bin/session.mjs

@@ -26,81 +26,201 @@ function usage(name, example) {
   process.exit(1)
 }
 
-export async function startSession(args) {
-  const { store, config } = await loadExplorer()
-  const sessionId = takeFlagValue(args, '--session')
-  const feature = takeFlagValue(args, '--feature')
-  if (!sessionId) usage('start-session', '--session <cursor-chat-id> [--feature "name"]')
+function printAck(kind, detail) {
+  console.log(`VISUAL_CODER_ACK ${kind}: ${detail}`)
+}
+
+function createManifestGate(manifestPath) {
+  const dir = path.dirname(manifestPath)
+  let wake = () => {}
+  let watcher = null
+  try {
+    watcher = fs.watch(dir, () => wake())
+  } catch {
+    watcher = null
+  }
+  return {
+    wait(ms) {
+      return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms)
+        wake = () => {
+          clearTimeout(timer)
+          resolve()
+        }
+      })
+    },
+    close() {
+      watcher?.close()
+    },
+  }
+}
+
+function signalAck(store, dataDir, sessionId, kind, detail) {
+  printAck(kind, detail)
+  try {
+    store.recordSessionAck(dataDir, sessionId, kind, detail)
+  } catch {
+    // Session folder may already be gone.
+  }
+}
+
+function waitingMessage(sessionId, manifest) {
+  if (manifest.phase === 'plan_ready') {
+    return `Waiting for the user to invoke step ${manifest.currentStep}...`
+  }
+  if (manifest.phase === 'review' && manifest.diffs?.at(-1)) {
+    return manifest.stepByStep === false
+      ? `Waiting for the user to accept the proposal after ${manifest.diffs.at(-1).id}...`
+      : `Waiting for the user to accept the proposal on ${manifest.diffs.at(-1).id}...`
+  }
+  return `Waiting for the visual workflow in session ${sessionId}...`
+}
+
+function emitStopped(store, dataDir, sessionId) {
+  if (store && dataDir && sessionId) {
+    signalAck(store, dataDir, sessionId, 'stopped', 'the workflow was stopped')
+  } else {
+    printAck('stopped', 'the workflow was stopped')
+  }
+  console.error(
+    'VISUAL_CODER_STOPPED The workflow was stopped. Do not modify project files.',
+  )
+  process.exit(2)
+}
 
-  const manifest = store.startSession(config.dataDir, { sessionId, feature })
-  if (manifest.phase === 'blueprint_ask' || manifest.phase === 'blueprint') {
+function emitApprovalHandshake(store, dataDir, sessionId, manifest, initialDiff) {
+  const current = initialDiff
+    ? manifest?.diffs.find((entry) => entry.id === initialDiff.id)
+    : null
+  if (!manifest || manifest.phase === 'stopped' || current?.status === 'rejected') {
+    emitStopped(store, dataDir, sessionId)
+    return
+  }
+  if (manifest.phase === 'finished') {
+    signalAck(store, dataDir, sessionId, 'finished', 'the final step was accepted')
     console.log(
-      `VISUAL_CODER_BLUEPRINT_WAIT Session ${sessionId} is visible in the visualizer (${manifest.phase}). Wait with inbase wait-for-blueprint before drafting the plan.`,
+      `VISUAL_CODER_FINISHED The final step was applied. Feature is done. Run inbase propose-patch --session ${sessionId} --clear, then tell the user it is finished.`,
     )
-  } else {
+    process.exit(5)
+  }
+  if (manifest.phase === 'working') {
+    const next = manifest.steps.find((step) => step.index === manifest.currentStep)
+    const title = next?.title
+    signalAck(
+      store,
+      dataDir,
+      sessionId,
+      'execute',
+      title
+        ? `step ${manifest.currentStep} — ${title}`
+        : `step ${manifest.currentStep}`,
+    )
+    const continuing = (manifest.diffs?.length ?? 0) > 0
     console.log(
-      `VISUAL_CODER_PREPARING Session ${sessionId} is visible in the visualizer (${manifest.phase}). Draft the plan next with inbase report-plan.`,
+      continuing
+        ? `VISUAL_CODER_EXECUTE Step ${manifest.currentStep} is invoked${title ? `: ${title}` : ''}. Continue immediately: edit live files for this step only, then inbase propose-patch --session ${sessionId} with no patch file. Do not explore, re-plan, or run wait-for-blueprint.`
+        : `VISUAL_CODER_EXECUTE Step ${manifest.currentStep} is invoked${title ? `: ${title}` : ''}. Re-read this session's blueprint.json before implementing; the user can place files and islands on any step. Edit the live project files for this step only (Write, StrReplace, Delete). Then record the step with inbase propose-patch --session ${sessionId} — no patch file. Inbase diffs those edits against the invoke snapshot and stores the patch. Do not write a unified diff yourself.`,
     )
+    process.exit(0)
+  }
+  if (manifest.phase === 'replanning') {
+    signalAck(
+      store,
+      dataDir,
+      sessionId,
+      'replan',
+      `revise the plan from step ${manifest.currentStep}`,
+    )
+    const instruction = manifest.pendingInstruction
+      ? `\nVISUAL_CODER_INSTRUCTION_START\n${manifest.pendingInstruction}\nVISUAL_CODER_INSTRUCTION_END`
+      : ''
+    console.log(
+      `VISUAL_CODER_REPLAN Keep accepted patch files before step ${manifest.currentStep}. Disk is baseline + accepted patches. Do not edit project files until the next EXECUTE. The session blueprint remains leading; if this instruction would differ from it, ask the user before replacing the plan. Report the revised tail with inbase report-plan, then wait for invocation.${instruction}`,
+    )
+    process.exit(4)
   }
 }
 
+export async function startSession(args) {
+  const { store, config } = await loadExplorer()
+  const sessionId = takeFlagValue(args, '--session')
+  const name = takeFlagValue(args, '--name') || takeFlagValue(args, '--feature')
+  const feature = takeFlagValue(args, '--feature')
+  if (!sessionId || !name) {
+    usage('start-session', '--session <cursor-chat-id> --name "short name"')
+  }
+
+  const manifest = store.startSession(config.dataDir, { sessionId, name, feature })
+  console.log(
+    `VISUAL_CODER_BLUEPRINT_WAIT Session ${manifest.name || sessionId} is visible in the visualizer (${manifest.phase}). Wait with inbase wait-for-blueprint before drafting the plan. A running visualizer does not skip this handshake.`,
+  )
+}
+
+export async function attachSession(args) {
+  const { store, config } = await loadExplorer()
+  const sessionId = takeFlagValue(args, '--session')
+  const manifest = store.attachSession(config.dataDir, sessionId)
+  console.log(`VISUAL_CODER_SESSION ${manifest.sessionId}`)
+  printAck('attached', manifest.name || manifest.sessionId)
+  console.log(
+    `VISUAL_CODER_ATTACHED Attached to the focused visualizer session ${manifest.name || manifest.sessionId} (${manifest.phase}). Use --session ${manifest.sessionId} for every later command. Run inbase wait-for-blueprint --session ${manifest.sessionId} to read the optional blueprint and instruction; it does not wait.`,
+  )
+}
+
 export async function waitForBlueprint(args) {
   const { store, config } = await loadExplorer()
   const sessionId = takeFlagValue(args, '--session')
-  const timeoutMs = Number(takeFlagValue(args, '--timeout') ?? 600000)
-  if (!sessionId) usage('wait-for-blueprint', '--session <cursor-chat-id> [--timeout ms]')
+  if (!sessionId) usage('wait-for-blueprint', '--session <cursor-chat-id>')
 
-  const started = Date.now()
-  const initial = store.readManifest(config.dataDir, sessionId)
   if (store.isWorkflowStopped(config.dataDir, sessionId)) {
-    console.error(
-      'VISUAL_CODER_STOPPED The workflow was stopped. Do not modify project files.',
-    )
-    process.exit(2)
+    emitStopped(store, config.dataDir, sessionId)
   }
+  const initial = store.readManifest(config.dataDir, sessionId)
   if (!initial) {
     console.error(`No workflow session found for ${sessionId}`)
     process.exit(1)
   }
 
-  if (initial.phase === 'blueprint_ask' || initial.phase === 'blueprint') {
-    console.log(
-      initial.phase === 'blueprint_ask'
-        ? 'Waiting for the user to choose Setup blueprint: Yes or No...'
-        : 'Waiting for the user to send the blueprint...',
-    )
-  } else {
-    console.log(`Blueprint handshake already finished for session ${sessionId}.`)
+  store.touchSessionConnection(config.dataDir, sessionId)
+  store.maybeStartVisualizerHandshake(config.dataDir, sessionId)
+  const manifest = store.readManifest(config.dataDir, sessionId)
+  if (!manifest || manifest.phase === 'stopped') {
+    emitStopped(store, config.dataDir, sessionId)
   }
 
-  while (Date.now() - started < timeoutMs) {
-    store.touchSessionConnection(config.dataDir, sessionId)
-    const manifest = store.readManifest(config.dataDir, sessionId)
-    if (!manifest || manifest.phase === 'stopped') {
-      console.error(
-        'VISUAL_CODER_STOPPED The workflow was stopped. Do not modify project files.',
-      )
-      process.exit(2)
-    }
-    if (manifest.phase !== 'blueprint_ask' && manifest.phase !== 'blueprint') {
-      const blueprint = store.readBlueprint(config.dataDir, sessionId)
-      const blocks = blueprint.userCreatedBlocks ?? []
-      const islands = blueprint.userCreatedIslands ?? []
-      console.log(
-        blueprint.enabled
-          ? `VISUAL_CODER_BLUEPRINT_READY The user sent ${blocks.length} file(s) and ${islands.length} island(s) for this chat. The blueprint is leading: create those paths and honor addedFunctions, addedVariables, and addedImports even if they are not on disk. Do not omit, rename, relocate, or replace them. Extra new files not in the blueprint are a deviation. If you would differ from the blueprint, ask the user first; do not silently deviate.`
-          : 'VISUAL_CODER_BLUEPRINT_READY The user skipped the blueprint. Continue without user-placed files or islands.',
-      )
-      console.log('VISUAL_CODER_BLUEPRINT_START')
-      console.log(JSON.stringify(blueprint, null, 2))
-      console.log('VISUAL_CODER_BLUEPRINT_END')
-      process.exit(0)
-    }
-    await new Promise((resolve) => setTimeout(resolve, 500))
+  const blueprint = store.readBlueprint(config.dataDir, sessionId)
+  const blocks = blueprint.userCreatedBlocks ?? []
+  const islands = blueprint.userCreatedIslands ?? []
+  signalAck(
+    store,
+    config.dataDir,
+    sessionId,
+    'blueprint',
+    blueprint.enabled
+      ? `${blocks.length} file(s), ${islands.length} island(s)`
+      : 'none',
+  )
+  console.log(
+    blueprint.enabled
+      ? `VISUAL_CODER_BLUEPRINT_READY The session started with ${blocks.length} file(s) and ${islands.length} island(s). The blueprint is leading: create those paths and honor addedFunctions, addedVariables, and addedImports even if they are not on disk. Do not omit, rename, relocate, or replace them. Extra new files not in the blueprint are a deviation. If you would differ from the blueprint, ask the user first; do not silently deviate. The user can still place files and islands on later steps; re-read this session's blueprint.json before each step.`
+      : 'VISUAL_CODER_BLUEPRINT_READY The session started without a blueprint. They can still place files and islands on later steps; re-read this session\'s blueprint.json before each step. Continue without user-placed files until that file is enabled.',
+  )
+  console.log('VISUAL_CODER_BLUEPRINT_START')
+  console.log(JSON.stringify(blueprint, null, 2))
+  console.log('VISUAL_CODER_BLUEPRINT_END')
+  const instruction =
+    typeof manifest.initialInstruction === 'string'
+      ? manifest.initialInstruction.trim()
+      : ''
+  if (instruction) {
+    console.log(
+      'Honor the user\'s initial instruction between VISUAL_CODER_INSTRUCTION_START and END together with the blueprint.',
+    )
+    console.log('VISUAL_CODER_INSTRUCTION_START')
+    console.log(instruction)
+    console.log('VISUAL_CODER_INSTRUCTION_END')
   }
-
-  console.error('Timed out waiting for the blueprint handshake. Do not modify files.')
-  process.exit(3)
+  process.exit(0)
 }
 
 export async function reportPlan(args) {
@@ -123,10 +243,11 @@ export async function reportPlan(args) {
     sessionId,
     feature,
     stepTitles: stepsParsed.values,
+    targetRoot: config.targetRoot,
   })
   console.log(
     manifest.phase === 'working'
-      ? `VISUAL_CODER_PLAN_READY Reported ${manifest.steps.length} plan step(s) for session ${sessionId}. Step by step is off, so step ${manifest.currentStep} is already invoked. Implement it, then wait again.`
+      ? `VISUAL_CODER_PLAN_READY Reported ${manifest.steps.length} plan step(s) for session ${sessionId}. Step by step is off, so step ${manifest.currentStep} is already invoked. Edit the live files for that step, then inbase propose-patch --session ${sessionId} with no patch file.`
       : `VISUAL_CODER_PLAN_READY Reported ${manifest.steps.length} plan step(s) for session ${sessionId}. Wait for the user to invoke step ${manifest.currentStep}.`,
   )
 }
@@ -141,72 +262,36 @@ export async function waitForApproval(args) {
   const initial = store.readManifest(config.dataDir, sessionId)
   const initialDiff = initial?.diffs?.at(-1)
   if (store.isWorkflowStopped(config.dataDir, sessionId)) {
-    console.error(
-      'VISUAL_CODER_STOPPED The workflow was stopped. Do not modify project files.',
-    )
-    process.exit(2)
+    emitStopped(store, config.dataDir, sessionId)
   }
   if (!initial) {
     console.error(`No workflow session found for ${sessionId}`)
     process.exit(1)
   }
   store.autoAdvance(config.dataDir, sessionId, config.targetRoot)
-  const afterAdvance = store.readManifest(config.dataDir, sessionId) ?? initial
-  console.log(
-    afterAdvance.phase === 'plan_ready'
-      ? `Waiting for the user to invoke step ${afterAdvance.currentStep}...`
-      : afterAdvance.phase === 'review' && afterAdvance.diffs?.at(-1)
-        ? afterAdvance.stepByStep === false
-          ? `Waiting for the finish step after ${afterAdvance.diffs.at(-1).id}...`
-          : `Waiting for the user to run the next step after ${afterAdvance.diffs.at(-1).id}...`
-        : `Waiting for the visual workflow in session ${sessionId}...`,
-  )
-
-  while (Date.now() - started < timeoutMs) {
-    store.touchSessionConnection(config.dataDir, sessionId)
-    store.autoAdvance(config.dataDir, sessionId, config.targetRoot)
-    const manifest = store.readManifest(config.dataDir, sessionId)
-    if (!manifest) {
-      console.error(
-        'VISUAL_CODER_STOPPED The workflow was stopped. Do not modify project files.',
-      )
-      process.exit(2)
-    }
-    const current = initialDiff
-      ? manifest.diffs.find((entry) => entry.id === initialDiff.id)
-      : null
 
-    if (manifest.phase === 'finished') {
-      console.log(
-        `VISUAL_CODER_FINISHED The final step was applied. Feature is done. Run inbase propose-patch --session ${sessionId} --clear, then tell the user it is finished.`,
-      )
-      process.exit(5)
-    }
-    if (manifest.phase === 'working') {
-      const next = manifest.steps.find((step) => step.index === manifest.currentStep)
-      console.log(
-        `VISUAL_CODER_EXECUTE Step ${manifest.currentStep} is invoked${next ? `: ${next.title}` : ''}. Implement only this step, publish its incremental diff with inbase propose-patch --session ${sessionId}, then wait again.`,
-      )
-      process.exit(0)
-    }
-    if (manifest.phase === 'replanning') {
-      const instruction = manifest.pendingInstruction
-        ? `\nVISUAL_CODER_INSTRUCTION_START\n${manifest.pendingInstruction}\nVISUAL_CODER_INSTRUCTION_END`
-        : ''
-      console.log(
-        `VISUAL_CODER_REPLAN Keep accepted steps before step ${manifest.currentStep}. Replace the plan from step ${manifest.currentStep} onward using the instruction below. The session blueprint remains leading; if this instruction would differ from it, ask the user before replacing the plan. Report the revised tail with inbase report-plan, then wait for invocation.${instruction}`,
-      )
-      process.exit(4)
+  const { manifest: manifestPath } = store.sessionPaths(config.dataDir, sessionId)
+  const gate = createManifestGate(manifestPath)
+  let lastWaiting = null
+  try {
+    while (Date.now() - started < timeoutMs) {
+      store.touchSessionConnection(config.dataDir, sessionId)
+      store.autoAdvance(config.dataDir, sessionId, config.targetRoot)
+      const manifest = store.readManifest(config.dataDir, sessionId)
+      emitApprovalHandshake(store, config.dataDir, sessionId, manifest, initialDiff)
+      if (!manifest) continue
+      const waiting = waitingMessage(sessionId, manifest)
+      if (waiting !== lastWaiting) {
+        console.log(waiting)
+        lastWaiting = waiting
+      }
+      await gate.wait(50)
     }
-    if (manifest.phase === 'stopped' || current?.status === 'rejected') {
-      console.error(
-        'VISUAL_CODER_STOPPED The workflow was stopped. Do not modify project files.',
-      )
-      process.exit(2)
-    }
-    await new Promise((resolve) => setTimeout(resolve, 500))
+  } finally {
+    gate.close()
   }
 
+  signalAck(store, config.dataDir, sessionId, 'timeout', 'no visualizer signal')
   console.error('Timed out waiting for visualizer review. Do not modify files.')
   process.exit(3)
 }
@@ -229,39 +314,44 @@ export async function proposePatch(args) {
     process.exit(0)
   }
 
-  if (!sessionId || !patchFile) {
-    usage('propose-patch', '--session <cursor-chat-id> <file.patch|->')
+  if (!sessionId) {
+    usage('propose-patch', '--session <cursor-chat-id> [file.patch|-]')
   }
 
-  let patchText = ''
+  let patchText
   if (patchFile && patchFile !== '-') {
     patchText = fs.readFileSync(path.resolve(cwd, patchFile), 'utf8')
   } else if (patchFile === '-') {
     patchText = fs.readFileSync(0, 'utf8')
   }
 
-  if (!patchText.trim()) {
-    console.error('No unified diff provided. Pass a .patch file or use stdin.')
+  if (patchFile && !patchText.trim()) {
+    console.error('No unified diff provided. Pass a .patch file, use stdin, or omit the file to record live edits.')
     process.exit(1)
   }
 
-  const parsed = patchLib.parseUnifiedPatch(patchText)
-  if (parsed.entries.length === 0) {
-    console.error('Patch did not contain any file changes.')
+  let recorded
+  try {
+    recorded = store.appendDiff(config.dataDir, config.targetRoot, {
+      sessionId,
+      ...(patchText !== undefined ? { patchText } : {}),
+    })
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error)
     process.exit(1)
   }
+  const { entry, manifest } = recorded
 
-  const { entry, manifest } = store.appendDiff(config.dataDir, config.targetRoot, {
-    sessionId,
-    patchText,
-  })
+  const parsed = patchLib.parseUnifiedPatch(
+    store.readDiff(config.dataDir, sessionId, entry),
+  )
 
   const last = entry.step >= manifest.steps.length
   console.log(
     manifest.phase === 'working'
-      ? `VISUAL_CODER_STEP_READY Published diff ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Step by step is off, so the next step is already invoked. Wait again.`
+      ? `VISUAL_CODER_STEP_READY Recorded live edits as patch ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Do not keep editing until the next EXECUTE. Step by step is off, so the next step is already invoked. Wait again.`
       : last
-        ? `VISUAL_CODER_STEP_READY Published diff ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Walk the diffs, then Complete to finish.`
-        : `VISUAL_CODER_STEP_READY Published diff ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Wait for Continue or an alternative instruction.`,
+        ? `VISUAL_CODER_STEP_READY Recorded live edits as patch ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Do not keep editing. Walk the diffs, then Accept proposal to finish.`
+        : `VISUAL_CODER_STEP_READY Recorded live edits as patch ${entry.id} for session ${sessionId}, step ${entry.step}/${manifest.steps.length}: ${parsed.files.length} changed, ${parsed.creates.length} added. Immediately run wait-for-approval. Do not explore or plan. Accept proposal invokes the next step; when EXECUTE returns, implement that step at once.`,
   )
 }

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@jkwd/inbase",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "A first-person 3D map of a codebase, with a visual coding workflow for Cursor.",
+  "license": "MIT",
+  "author": "Joris Kuijper",
+  "keywords": [
+    "inbase",
+    "codebase",
+    "visualization",
+    "3d",
+    "first-person",
+    "cursor",
+    "devtools",
+    "llm"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/jk-wd/inbase"
@@ -10,6 +22,9 @@
   "bugs": {
     "url": "https://github.com/jk-wd/inbase/issues"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "bin": {
     "inbase": "bin/inbase.mjs"
@@ -28,6 +43,8 @@
     "apps/explorer/src/*.css",
     "apps/explorer/src/scene",
     "apps/explorer/src/ui",
+    "apps/explorer/scripts/branch-changes.d.ts",
+    "apps/explorer/scripts/branch-changes.mjs",
     "apps/explorer/scripts/js-source.mjs",
     "apps/explorer/scripts/open-editor.d.ts",
     "apps/explorer/scripts/open-editor.mjs",
@@ -37,7 +54,8 @@
     "apps/explorer/scripts/session-store.d.ts",
     "apps/explorer/scripts/session-store.mjs",
     "apps/explorer/scripts/target-config.d.ts",
-    "apps/explorer/scripts/target-config.mjs"
+    "apps/explorer/scripts/target-config.mjs",
+    "apps/explorer/scripts/tree-diff.mjs"
   ],
   "workspaces": [
     "apps/*"

package/skill/commands/inbase.md

@@ -0,0 +1,17 @@
+---
+description: Attach this chat to the focused Inbase visualizer session
+---
+
+The user invoked `/inbase`. This is how a chat joins the visualizer session that **Setup LLM session** already created.
+
+Do **not** ask for a session id. Do **not** run `inbase start-session`. Do **not** print the "direct chat interaction not allowed" message.
+
+1. Attach to the focused visualizer session:
+
+```bash
+npx inbase attach
+```
+
+2. Read `VISUAL_CODER_SESSION` from the output. That id is the session to use for every later `inbase` command.
+
+3. Continue the Inbase visual edits skill from `wait-for-blueprint` onward with that `--session` id. `/inbase` already started the session. `wait-for-blueprint` only reads the optional blueprint and instruction; it does not wait.

package/skill/commands/skipinbase.md

@@ -0,0 +1,9 @@
+---
+description: Bypass Inbase and do the request directly in this chat
+---
+
+The user invoked `/skipinbase`. Do **not** start or attach an Inbase visual session. Do **not** print the "direct chat interaction not allowed" message.
+
+Fulfill this request directly, without the Inbase plan/patch loop:
+
+$ARGUMENTS