@jkwd/inbase 0.1.0

package/bin/session.mjs

@@ -0,0 +1,241 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { explorerRoot, takeFlagValue, takeFlagValues } from './project.mjs'
+
+async function loadExplorer() {
+  const storePath = pathToFileURL(
+    path.join(explorerRoot, 'scripts/session-store.mjs'),
+  ).href
+  const patchPath = pathToFileURL(
+    path.join(explorerRoot, 'scripts/patch-lib.mjs'),
+  ).href
+  const configPath = pathToFileURL(
+    path.join(explorerRoot, 'scripts/target-config.mjs'),
+  ).href
+  const [store, patchLib, config] = await Promise.all([
+    import(storePath),
+    import(patchPath),
+    import(configPath),
+  ])
+  return { store, patchLib, config }
+}
+
+function usage(name, example) {
+  console.error(`Usage: inbase ${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"]')
+
+  const manifest = store.startSession(config.dataDir, { sessionId, feature })
+  if (manifest.phase === 'blueprint_ask' || manifest.phase === 'blueprint') {
+    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.`,
+    )
+  } else {
+    console.log(
+      `VISUAL_CODER_PREPARING Session ${sessionId} is visible in the visualizer (${manifest.phase}). Draft the plan next with inbase report-plan.`,
+    )
+  }
+}
+
+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]')
+
+  const started = Date.now()
+  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}.`)
+  }
+
+  while (Date.now() - started < timeoutMs) {
+    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. Create those paths in the plan even if they are not on disk.`
+          : '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))
+  }
+
+  console.error('Timed out waiting for the blueprint handshake. Do not modify files.')
+  process.exit(3)
+}
+
+export async function reportPlan(args) {
+  const { store, config } = await loadExplorer()
+  const sessionParsed = takeFlagValues(args, '--session')
+  const featureParsed = takeFlagValues(sessionParsed.rest, '--feature')
+  const stepsParsed = takeFlagValues(featureParsed.rest, '--steps')
+  const sessionId = sessionParsed.values[0]
+  const existing = sessionId ? store.readManifest(config.dataDir, sessionId) : null
+  const feature = featureParsed.values[0] ?? existing?.feature
+
+  if (!sessionId || !feature || stepsParsed.values.length === 0) {
+    usage(
+      'report-plan',
+      '--session <cursor-chat-id> --feature "name" --steps "one" [--steps "two"]',
+    )
+  }
+
+  const manifest = store.reportPlan(config.dataDir, {
+    sessionId,
+    feature,
+    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}.`,
+  )
+}
+
+export async function waitForApproval(args) {
+  const { store, config } = await loadExplorer()
+  const sessionId = takeFlagValue(args, '--session')
+  const timeoutMs = Number(takeFlagValue(args, '--timeout') ?? 600000)
+  if (!sessionId) usage('wait-for-approval', '--session <cursor-chat-id> [--timeout ms]')
+
+  const started = Date.now()
+  const initial = store.readManifest(config.dataDir, sessionId)
+  const initialDiff = initial?.diffs?.at(-1)
+  if (!initial) {
+    console.error(`No workflow session found for ${sessionId}`)
+    process.exit(1)
+  }
+  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}...`
+        : `Waiting for the visual workflow in session ${sessionId}...`,
+  )
+
+  while (Date.now() - started < timeoutMs) {
+    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. Report the revised tail with inbase report-plan, then wait for invocation.${instruction}`,
+      )
+      process.exit(4)
+    }
+    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))
+  }
+
+  console.error('Timed out waiting for visualizer review. Do not modify files.')
+  process.exit(3)
+}
+
+export async function proposePatch(args) {
+  const { store, patchLib, config } = await loadExplorer()
+  const clear = args.includes('--clear')
+  const withoutClear = args.filter((arg) => arg !== '--clear')
+  const sessionParsed = takeFlagValues(withoutClear, '--session')
+  const patchFile = sessionParsed.rest[0]
+  const sessionId = sessionParsed.values[0]
+  const cwd = process.cwd()
+
+  if (clear) {
+    if (!sessionId) usage('propose-patch', '--session <cursor-chat-id> --clear')
+    store.stopSession(config.dataDir, sessionId)
+    console.log(
+      `Cleared session ${sessionId}; stored diffs and blueprint drafts were removed.`,
+    )
+    process.exit(0)
+  }
+
+  if (!sessionId || !patchFile) {
+    usage('propose-patch', '--session <cursor-chat-id> <file.patch|->')
+  }
+
+  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.')
+    process.exit(1)
+  }
+
+  const parsed = patchLib.parseUnifiedPatch(patchText)
+  if (parsed.entries.length === 0) {
+    console.error('Patch did not contain any file changes.')
+    process.exit(1)
+  }
+
+  const { entry, manifest } = store.appendDiff(config.dataDir, config.targetRoot, {
+    sessionId,
+    patchText,
+  })
+
+  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.`,
+  )
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@jkwd/inbase",
+  "version": "0.1.0",
+  "description": "A first-person 3D map of a codebase, with a visual coding workflow for Cursor.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jk-wd/inbase"
+  },
+  "homepage": "https://github.com/jk-wd/inbase",
+  "bugs": {
+    "url": "https://github.com/jk-wd/inbase/issues"
+  },
+  "type": "module",
+  "bin": {
+    "inbase": "bin/inbase.mjs"
+  },
+  "files": [
+    "bin/inbase.mjs",
+    "bin/project.mjs",
+    "bin/session.mjs",
+    "skill",
+    "apps/explorer/index.html",
+    "apps/explorer/package.json",
+    "apps/explorer/tsconfig.json",
+    "apps/explorer/vite.config.ts",
+    "apps/explorer/src/*.ts",
+    "apps/explorer/src/*.tsx",
+    "apps/explorer/src/*.css",
+    "apps/explorer/src/scene",
+    "apps/explorer/src/ui",
+    "apps/explorer/scripts/js-source.mjs",
+    "apps/explorer/scripts/patch-lib.d.ts",
+    "apps/explorer/scripts/patch-lib.mjs",
+    "apps/explorer/scripts/scan-target.mjs",
+    "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"
+  ],
+  "workspaces": [
+    "apps/*"
+  ],
+  "scripts": {
+    "dev": "npm run dev -w @visual-coder/explorer",
+    "dev:target": "npm run dev -w @visual-coder/example-target",
+    "build": "npm run build -w @visual-coder/explorer",
+    "scan": "npm run scan -w @visual-coder/explorer",
+    "inbase": "node bin/inbase.mjs",
+    "test": "npm test -w @visual-coder/explorer && node --test bin/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@react-three/drei": "^9.117.3",
+    "@react-three/fiber": "^8.17.10",
+    "@vitejs/plugin-react": "^4.3.4",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "three": "^0.170.0",
+    "vite": "^6.0.3"
+  }
+}

package/skill/inbase/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: inbase
+description: >-
+  Grounds source-file changes in the Inbase visual map. Use when creating,
+  editing, or deleting application source files in this repository. Lists every
+  feature step, then works only via patch files. Do not use for git, docs-only,
+  lockfiles, or questions.
+---
+
+# Inbase visual edits
+
+Apply this skill **whenever the work is file changes in this repository**.
+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.
+
+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/`.
+
+Inbase must already be running (`inbase run` or `npx inbase run`). Prefer
+`npx inbase` so the local package is used.
+
+## Required sequence
+
+1. As soon as this skill applies, start the visual session so the explorer can
+   offer a blueprint handshake. Do this before reading context or listing steps:
+
+```bash
+npx inbase start-session --session "<current-cursor-chat-id>"
+```
+
+2. **Stop and wait for the blueprint handshake**. Do not report a plan and do
+   not write a patch until this prints `VISUAL_CODER_BLUEPRINT_READY`:
+
+```bash
+npx inbase wait-for-blueprint --session "<current-cursor-chat-id>"
+```
+
+   The explorer asks **Setup blueprint: Yes vs No**.
+   - **No**: skip placement; continue without user-placed files or islands.
+   - **Yes**: the user places files (`Space`) and islands (`B`), then clicks
+     **Send blueprint**.
+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.
+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
+   - `lookingAt` / `lookingAtFiles` are the blocks they are looking at
+   - `selected` is the block they clicked
+   - `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.
+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).
+7. Report the plan before making a diff:
+
+```bash
+npx inbase report-plan \
+  --session "<current-cursor-chat-id>" \
+  --feature "short feature name" \
+  --steps "Add Clock component" \
+  --steps "Show Clock on Home"
+```
+
+8. **Stop and wait for invocation**:
+
+```bash
+npx inbase wait-for-approval --session "<current-cursor-chat-id>"
+```
+
+   Do not write a patch until this prints `VISUAL_CODER_EXECUTE`.
+9. Implement only the invoked step as a unified diff. Paths are relative to the
+   project root (same ids as `codebase.json`):
+
+```diff
+--- /dev/null
++++ b/src/components/Clock.tsx
+@@ -0,0 +1,5 @@
++export function Clock() {
++  return <time>00:00</time>
++}
+```
+
+```diff
+--- a/src/pages/Home.tsx
++++ b/src/pages/Home.tsx
+@@ -1,3 +1,4 @@
++import { Clock } from '../components/Clock'
+ import { Counter } from '../components/Counter'
+```
+
+   Write that diff to a new `.patch` file, then publish it:
+
+```bash
+npx inbase propose-patch \
+  --session "<current-cursor-chat-id>" \
+  /tmp/step.patch
+```
+
+   The patch path or stdin is required. Never write or replace a patch already
+   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:
+
+```bash
+npx inbase wait-for-approval --session "<current-cursor-chat-id>"
+```
+
+12. Read the wait command output:
+
+   - Exit `0` (`VISUAL_CODER_EXECUTE`): the highlighted step was invoked. Build
+     only that step, publish its incremental diff with `inbase propose-patch`,
+     then wait again.
+   - Exit `5` (`VISUAL_CODER_FINISHED`): that was the last step. The visualizer
+     already applied the final patch and removed stored session diffs and
+     blueprint drafts. Optionally run `--clear` if anything remains, tell the
+     user the feature is done, and **stop**. Do not propose another patch.
+   - Exit `4` (`VISUAL_CODER_REPLAN`): do **not** apply files and do not rewrite
+     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.
+   - Exit `2` (`VISUAL_CODER_STOPPED`) or `3` (timeout): make no further
+     project changes.
+
+13. After a finished handshake, the explorer already removed stored session
+    diffs and blueprint drafts. Optionally run:
+
+```bash
+npx inbase propose-patch --session "<current-cursor-chat-id>" --clear
+```
+
+## Do not
+
+- 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
+- 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 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