@jkwd/inbase 0.1.4 → 0.1.6

package/apps/explorer/vite.config.ts

@@ -11,12 +11,15 @@ import { editorFileUri, openInEditor } from './scripts/open-editor.mjs'
 import {
   answerBlueprint,
   continueDiff,
+  discardInactiveDiffSessions,
   inspectTargetFile,
   invokeStep,
+  listSessionIntents,
   readActiveSession,
   requestReplan,
   sendBlueprint,
   sessionIntent,
+  setStepByStep,
   stopSession,
   updateBlueprint,
 } from './scripts/session-store.mjs'
@@ -45,6 +48,17 @@ function readBody(req: IncomingMessage) {
   })
 }
 
+function rescanTarget(when: string) {
+  const scan = spawnSync(process.execPath, [scanScript], {
+    cwd: here,
+    encoding: 'utf8',
+    env: scanEnv,
+  })
+  if (scan.status !== 0) {
+    console.error(scan.stderr || scan.stdout || `scan failed ${when}`)
+  }
+}
+
 function knownFileIds() {
   try {
     const graph = JSON.parse(fs.readFileSync(codebaseFile, 'utf8')) as {
@@ -68,6 +82,8 @@ function jsonFilePlugin(): Plugin {
   return {
     name: 'visual-coder-json-files',
     configureServer(server) {
+      discardInactiveDiffSessions(dataDir, targetRoot)
+      rescanTarget('after discarding inactive sessions')
       server.middlewares.use('/api/user-context', (req, res, next) => {
         if (req.method === 'GET') {
           sendJson(res, 200, readUserContext())
@@ -91,12 +107,22 @@ function jsonFilePlugin(): Plugin {
       server.middlewares.use('/api/agent-intent', (req, res, next) => {
         if (req.method === 'GET') {
           const url = new URL(req.url ?? '/', 'http://visual-coder.local')
-          const sessionId = url.searchParams.get('sessionId') ?? readActiveSession(dataDir)
+          const sessionId = url.searchParams.get('sessionId')
           const diffId = url.searchParams.get('diffId') ?? undefined
-          const intent = sessionId
-            ? sessionIntent(dataDir, sessionId, knownFileIds(), diffId)
-            : null
-          sendJson(res, 200, intent ?? { ...emptyIntent })
+          if (sessionId) {
+            const intent = sessionIntent(
+              dataDir,
+              sessionId,
+              knownFileIds(),
+              diffId,
+            )
+            sendJson(res, 200, intent ?? { ...emptyIntent })
+            return
+          }
+          sendJson(res, 200, {
+            focusedSessionId: readActiveSession(dataDir),
+            intents: listSessionIntents(dataDir, knownFileIds()),
+          })
           return
         }
 
@@ -155,6 +181,7 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
       diffId?: string
       instruction?: string
       step?: number
+      stepByStep?: boolean
       userCreatedBlocks?: unknown[]
       userCreatedIslands?: unknown[]
       addedFunctions?: unknown[]
@@ -170,7 +197,8 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
       action !== 'blueprint_yes' &&
       action !== 'blueprint_no' &&
       action !== 'blueprint_send' &&
-      action !== 'blueprint_update'
+      action !== 'blueprint_update' &&
+      action !== 'set_step_by_step'
     ) {
       sendJson(res, 400, { error: 'invalid workflow action' })
       return
@@ -193,28 +221,14 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
         return
       }
       invokeStep(dataDir, body.sessionId, body.step as number, targetRoot)
-      const scan = spawnSync(process.execPath, [scanScript], {
-        cwd: here,
-        encoding: 'utf8',
-        env: scanEnv,
-      })
-      if (scan.status !== 0) {
-        console.error(scan.stderr || scan.stdout || 'scan failed after invoking step')
-      }
+      rescanTarget('after invoking step')
     } else if (action === 'continue') {
       if (!body.diffId) {
         sendJson(res, 400, { error: 'diffId is required for continue' })
         return
       }
       continueDiff(dataDir, targetRoot, body.sessionId, body.diffId)
-      const scan = spawnSync(process.execPath, [scanScript], {
-        cwd: here,
-        encoding: 'utf8',
-        env: scanEnv,
-      })
-      if (scan.status !== 0) {
-        console.error(scan.stderr || scan.stdout || 'scan failed after applying patch')
-      }
+      rescanTarget('after applying patch')
     } else if (action === 'instruct') {
       if (!body.diffId) {
         sendJson(res, 400, { error: 'diffId is required for instruct' })
@@ -246,8 +260,16 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
         addedVariables: body.addedVariables,
         addedImports: body.addedImports,
       })
+    } else if (action === 'set_step_by_step') {
+      if (typeof body.stepByStep !== 'boolean') {
+        sendJson(res, 400, { error: 'stepByStep is required' })
+        return
+      }
+      setStepByStep(dataDir, body.sessionId, body.stepByStep, targetRoot)
+      rescanTarget('after changing step-by-step mode')
     } else {
       stopSession(dataDir, body.sessionId, targetRoot)
+      rescanTarget('after stopping session')
     }
     const next = sessionIntent(dataDir, body.sessionId, knownFileIds())
     sendJson(res, 200, next ?? { ...emptyIntent })

package/bin/session.mjs

@@ -52,6 +52,12 @@ export async function waitForBlueprint(args) {
 
   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)
+  }
   if (!initial) {
     console.error(`No workflow session found for ${sessionId}`)
     process.exit(1)
@@ -68,6 +74,7 @@ export async function waitForBlueprint(args) {
   }
 
   while (Date.now() - started < timeoutMs) {
+    store.touchSessionConnection(config.dataDir, sessionId)
     const manifest = store.readManifest(config.dataDir, sessionId)
     if (!manifest || manifest.phase === 'stopped') {
       console.error(
@@ -81,7 +88,7 @@ export async function waitForBlueprint(args) {
       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. Create those paths in the plan even if they are not on disk.`
+          ? `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')
@@ -118,7 +125,9 @@ export async function reportPlan(args) {
     stepTitles: stepsParsed.values,
   })
   console.log(
-    `VISUAL_CODER_PLAN_READY Reported ${manifest.steps.length} plan step(s) for session ${sessionId}. Wait for the user to invoke step ${manifest.currentStep}.`,
+    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}. Wait for the user to invoke step ${manifest.currentStep}.`,
   )
 }
 
@@ -131,19 +140,31 @@ export async function waitForApproval(args) {
   const started = Date.now()
   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)
+  }
   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(
-    initial.phase === 'plan_ready'
-      ? `Waiting for the user to invoke step ${initial.currentStep}...`
-      : initial.phase === 'review' && initialDiff
-        ? `Waiting for the user to run the next step after ${initialDiff.id}...`
+    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(
@@ -173,7 +194,7 @@ export async function waitForApproval(args) {
         ? `\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. Report the revised tail with inbase report-plan, then wait for invocation.${instruction}`,
+        `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)
     }
@@ -235,7 +256,12 @@ export async function proposePatch(args) {
     patchText,
   })
 
+  const last = entry.step >= manifest.steps.length
   console.log(
-    `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.`,
+    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.`
+      : 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.`,
   )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jkwd/inbase",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A first-person 3D map of a codebase, with a visual coding workflow for Cursor.",
   "repository": {
     "type": "git",

package/skill/inbase/SKILL.md

@@ -14,10 +14,13 @@ Skip it for git, lockfiles, `.inbase`, `.cursor`, or questions with no code
 changes.
 
 The LLM uses a plan-first loop. It reports the complete plan before writing a
-patch, waits for the user to invoke the highlighted step, publishes only that
-step's diff, then waits for **Run step** on the following step or an alternative
-instruction. Always work via patch files. Do not Write, StrReplace, or Delete
-project files.
+patch. When **Step by step** is on, it waits for the user to invoke the
+highlighted step, publishes only that step's diff, then waits for **Run step**
+on the following step or an alternative instruction. When **Step by step** is
+off, `inbase wait-for-approval` returns `VISUAL_CODER_EXECUTE` for every
+remaining step without the user clicking Run step; after the last patch, wait
+for the user to **Complete**. They can still walk Previous/Next over the diffs.
+Always work via patch files. Do not Write, StrReplace, or Delete project files.
 
 Every Cursor chat has an explicit session ID. Pass that same ID to every
 command. The visualizer stores immutable diffs under `.inbase/diff-sessions/<session-id>/diffs/`.
@@ -48,12 +51,17 @@ npx inbase wait-for-blueprint --session "<current-cursor-chat-id>"
 3. Read the handshake output between `VISUAL_CODER_BLUEPRINT_START` and
    `VISUAL_CODER_BLUEPRINT_END`, or read
    `.inbase/diff-sessions/<session-id>/blueprint.json`.
-   If `enabled` is true, always create `userCreatedBlocks` and
-   `userCreatedIslands` at the given path/folder. Those files and folders do
-   not exist on disk yet. They belong to this chat only.
-   Also honor `addedFunctions`, `addedVariables`, and `addedImports`: add those
-   symbols and imports to the named files. They are blueprint intentions, not
-   files that already exist on disk.
+   If `enabled` is true, **the blueprint is leading**. Treat
+   `userCreatedBlocks`, `userCreatedIslands`, `addedFunctions`,
+   `addedVariables`, and `addedImports` as the source of truth for this chat.
+   Create those paths and add those symbols even if they are not on disk.
+   They belong to this chat only.
+   Do not omit, rename, relocate, or replace a blueprint file, island, symbol,
+   or import. Extra edits to existing files are allowed when needed to finish
+   the feature. Extra new files that are not in the blueprint are a deviation.
+   If the user request, viewpoint, a later instruction, or your own plan would
+   differ from the blueprint, **stop and ask the user in chat** before
+   reporting the plan. Do not silently deviate.
 4. Read `.inbase/user-context.json` for viewpoint only.
 5. Use the user's viewpoint only when `followLook` is true:
    - `island` is where they are standing
@@ -62,8 +70,8 @@ npx inbase wait-for-blueprint --session "<current-cursor-chat-id>"
    - `filesOnIsland` is the rest of that folder
    Prefer those files while `followLook` is true, unless the request clearly
    needs something else. If `followLook` is false or missing, ignore viewpoint
-   and choose files from the request itself. Still include this session's
-   blueprint files and islands when `enabled` is true.
+   and choose files from the request itself. Viewpoint never overrides the
+   blueprint: still follow this session's blueprint when `enabled` is true.
 6. List **all** steps needed to finish the feature. Keep steps small enough that
    one patch is one landscape change (usually one new file, or a few related
    edits).
@@ -83,7 +91,8 @@ npx inbase report-plan \
 npx inbase wait-for-approval --session "<current-cursor-chat-id>"
 ```
 
-   Do not write a patch until this prints `VISUAL_CODER_EXECUTE`.
+   Do not write a patch until this prints `VISUAL_CODER_EXECUTE`. If Step by
+   step is off, this returns immediately for each remaining step.
 9. Implement only the invoked step as a unified diff. Paths are relative to the
    project root (same ids as `codebase.json`):
 
@@ -116,8 +125,9 @@ npx inbase propose-patch \
    stored in the session folder.
 
 10. **Stop.** Do not apply the patch and do not edit project files directly.
-11. Wait until the user clicks **Run step** on the next step, sends an alternative instruction,
-   or stops the workflow:
+11. Wait until the user clicks **Run step** on the next step (or, when Step by
+   step is off, until the next step is auto-invoked), sends an alternative
+   instruction, clicks **Complete** on the last step, or stops the workflow:
 
 ```bash
 npx inbase wait-for-approval --session "<current-cursor-chat-id>"
@@ -136,10 +146,12 @@ npx inbase wait-for-approval --session "<current-cursor-chat-id>"
      an earlier diff. Follow the text between
      `VISUAL_CODER_INSTRUCTION_START` and `VISUAL_CODER_INSTRUCTION_END`, read
      this session's `blueprint.json` when it is enabled (files, islands,
-     `addedFunctions`, `addedVariables`, `addedImports`), read
-     `user-context.json` (follow the viewpoint only if `followLook` is true),
-     replace the plan from the current step onward using `inbase report-plan`,
-     then wait for the user to invoke the first revised step.
+     `addedFunctions`, `addedVariables`, `addedImports`). The blueprint stays
+     leading. If the new instruction would differ from it, ask the user before
+     replacing the plan. Read `user-context.json` (follow the viewpoint only if
+     `followLook` is true), replace the plan from the current step onward using
+     `inbase report-plan`, then wait for the user to invoke the first revised
+     step.
    - Exit `2` (`VISUAL_CODER_STOPPED`) or `3` (timeout): make no further
      project changes.
 
@@ -154,14 +166,15 @@ npx inbase propose-patch --session "<current-cursor-chat-id>" --clear
 
 - Skip `inbase start-session` once this skill applies
 - Skip `inbase wait-for-blueprint` or report a plan before `VISUAL_CODER_BLUEPRINT_READY`
-- Skip this session's `blueprint.json` `userCreatedBlocks` or `userCreatedIslands` when `enabled` is true
-- Skip `addedFunctions`, `addedVariables`, or `addedImports` from that blueprint when `enabled` is true
+- Treat the chat request, viewpoint, or your own plan as overriding an enabled blueprint
+- Skip, rename, relocate, or replace this session's `blueprint.json` files, islands, functions, variables, or imports when `enabled` is true
+- Silently differ from the blueprint; ask the user first
 - Read global `user-context.json` for placed files; those live on the session blueprint
 - Follow the user's look when `followLook` is false
 - Write, edit, create, or delete project files directly
 - Announce file lists instead of a patch
 - Write a patch before its plan step is invoked
-- Propose the next step before the user clicks **Run step**
+- Propose the next step before `inbase wait-for-approval` returns `VISUAL_CODER_EXECUTE`
 - Propose another patch after `VISUAL_CODER_FINISHED`
 - Reuse, overwrite, or expand an existing session diff
 - Use this flow for git, lockfiles, or other non-source work