@jkwd/inbase 0.1.9 → 0.1.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joris Kuijper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,7 +5,7 @@
   </picture>
 </p>
 
-A first-person 3D map of a JavaScript or TypeScript codebase. Files become blocks, folders become walkable areas, and imports become lines in the air.
+A first-person 3D map of a codebase. Files become blocks, folders become walkable areas, and imports become lines in the air.
 
 <p align="center">
   <img src="docs/inbase-1.png" alt="First-person walk view of the codebase map" width="47%" />
@@ -47,13 +47,21 @@ inbase run --target /path/to/your/project
 
 <img src="docs/inbase-llm.png" alt="LLM working through a plan in the heads-up display overlay" align="left" width="280" hspace="16" />
 
-Inbase does not call a model itself. The visual coding loop currently supports **Cursor**. The installed skill makes the agent work through the map: it reports a plan, waits on the **HUD** (heads-up display — the overlay panel on the 3D map), and publishes each step as a patch you can walk before it is applied.
+Inbase does not call a model itself. The visual coding loop currently supports **Cursor**. The installed skill makes the agent work through the map: it reports a plan, waits on the **HUD** (heads-up display — the overlay panel on the 3D map), edits live files for each invoked step, and records that step as a patch. Those stored patches are the session record and are applied on every step update.
 
-When a chat starts, that overlay asks whether to set up a **blueprint**. **Create blueprint** lets you place files (`Space`) and folders (`B`), then **Send blueprint** — that layout is the source of truth for the chat. **Let LLM continue** skips placement and lets the agent choose files from the request.
+Sessions start in the map: click **Setup LLM session**, type an **initial instruction**, optionally place a **blueprint** (`Space` for files, `B` for folders), then open a Cursor chat and run **`/inbase`**. That command connects the chat and starts the work. The layout is the source of truth for the chat. You can still place files and islands on later steps; they are stored on that chat’s blueprint. When the session finishes, placement stops and the session is discarded. Restarting the visualizer also starts with no LLM session; leftover session files are not restored.
 
-Turn on **Make LLM look where I look** if the agent should prefer the island you are standing on and the blocks you are facing. With **Step by step** on, click **Run step** for each patch. With it off, the LLM implements the full plan; you can still walk Previous/Next over the diffs, then **Complete**. Send an alternative instruction from the HUD to revise the remaining plan, or **Stop** to end the session.
+A normal chat request does not open a session. Use `/inbase` after Setup LLM session, or `/skipinbase [request]` to work outside the map. `/inbase` starts the session immediately; `wait-for-blueprint` only reads the optional blueprint.
 
-The LLM never writes project files itself. Patches apply when you run or complete steps in the visualizer.
+If several sessions are open, only one session window is shown at a time. Switch tabs so the focused session is the one `/inbase` connects to.
+
+Turn on **Make LLM look where I look** if the agent should prefer the island you are standing on and the blocks you are facing. With **Step by step** on, click **Create proposal** to start a step, then **Accept proposal** when the patch is ready. With it off, the LLM implements the full plan; you can still walk Previous/Next over the diffs, then **Accept proposal**. Send an alternative instruction from the HUD to revise the remaining plan, or **Stop** to end the session.
+
+When no LLM is currently making changes, turn on **Show branch changes** (or press **G**) to highlight the current git branch against its base — committed, unstaged, and untracked files — instead of LLM patch files. The control is disabled while an LLM session is writing or reviewing a patch.
+
+The LLM edits project files after a step is invoked. Inbase records those edits
+as a patch against the snapshot taken at invoke. Those stored patches are the
+session record and are applied on every step update.
 
 <br clear="all" />
 
@@ -65,7 +73,7 @@ The LLM never writes project files itself. Patches apply when you run or complet
 | `inbase run` | Scan this repo and start the local map |
 | `inbase run --port 5174` | Start on another port |
 
-Session commands (`start-session`, `wait-for-blueprint`, `report-plan`, `wait-for-approval`, `propose-patch`) are used by the Cursor skill. You do not need to run them yourself.
+Session commands (`attach`, `wait-for-blueprint`, `report-plan`, `wait-for-approval`, `propose-patch`) are used by the Cursor skill. You do not need to run them yourself.
 
 ## Editor support
 
@@ -73,7 +81,7 @@ The map runs in the browser. The LLM plan and patch loop currently works in **Cu
 
 ## Language support
 
-Source files (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`) become blocks with **functions**, **classes**, and **variables**, plus import edges from `import` and `require()`. Styles and docs (`.css`, `.scss`, `.html`, `.json`, `.md`) show up as blocks without symbols. Only relative specifiers (`./`, `../`) become edges — package names like `react` or `@angular/core` do not.
+Every text file in the project becomes a block. JavaScript and TypeScript (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`) also get **functions**, **classes**, and **variables**. Relative `import` / `require()` specifiers become edges when they resolve — including `.astro` and other JS-style modules. Package names like `react` or `@angular/core` do not. Binary files are skipped.
 
 ## How to read the map
 
@@ -103,3 +111,11 @@ To run the example React app itself:
 ```bash
 npm run dev:target
 ```
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+Inbase is open source under the [MIT License](LICENSE).

package/apps/explorer/package.json

@@ -2,6 +2,7 @@
   "name": "@visual-coder/explorer",
   "private": true,
   "version": "0.0.1",
+  "license": "MIT",
   "type": "module",
   "scripts": {
     "scan": "node scripts/scan-target.mjs",

package/apps/explorer/scripts/branch-changes.d.ts

@@ -0,0 +1,24 @@
+import type { PatchImport, PatchImportAddition, PatchSymbolAddition } from './patch-lib.d.ts'
+
+export type BranchChanges = {
+  available: boolean
+  branch: string | null
+  base: string | null
+  files: string[]
+  creates: string[]
+  deletes: string[]
+  createFolders: string[]
+  createLines: Record<string, number>
+  imports: PatchImport[]
+  addedFunctions: PatchSymbolAddition[]
+  addedVariables: PatchSymbolAddition[]
+  addedImports: PatchImportAddition[]
+  changedFunctions: PatchSymbolAddition[]
+  changedVariables: PatchSymbolAddition[]
+}
+
+export function emptyBranchChanges(): BranchChanges
+export function readBranchChanges(
+  targetRoot: string,
+  knownFileIds?: string[],
+): BranchChanges

package/apps/explorer/scripts/branch-changes.mjs

@@ -0,0 +1,237 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  collectCreateFolders,
+  extractPatchAdditions,
+  extractPatchImports,
+  foldersFromFileIds,
+  parseUnifiedPatch,
+} from './patch-lib.mjs'
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  '.git',
+  '.inbase',
+])
+const SKIP_FILES = new Set(['package-lock.json'])
+const BINARY_PROBE_BYTES = 8000
+
+function toPosix(filePath) {
+  return filePath.split(path.sep).join('/')
+}
+
+function unique(ids) {
+  return [...new Set(ids)]
+}
+
+function runGit(cwd, args) {
+  return spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+  })
+}
+
+function gitTopLevel(fromDir) {
+  try {
+    const result = runGit(fromDir, ['rev-parse', '--show-toplevel'])
+    if (result.status !== 0) return null
+    const root = result.stdout.trim()
+    return root ? path.resolve(root) : null
+  } catch {
+    return null
+  }
+}
+
+function isBinaryFile(filePath) {
+  try {
+    const fd = fs.openSync(filePath, 'r')
+    try {
+      const buf = Buffer.alloc(BINARY_PROBE_BYTES)
+      const bytes = fs.readSync(fd, buf, 0, buf.length, 0)
+      return buf.subarray(0, bytes).includes(0)
+    } finally {
+      fs.closeSync(fd)
+    }
+  } catch {
+    return true
+  }
+}
+
+function shouldSkipPath(fileId) {
+  const parts = fileId.split('/').filter(Boolean)
+  if (parts.some((part) => part.startsWith('.') || SKIP_DIRS.has(part))) {
+    return true
+  }
+  return SKIP_FILES.has(parts.at(-1) ?? '')
+}
+
+function currentBranch(cwd) {
+  const result = runGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD'])
+  if (result.status !== 0) return null
+  const name = result.stdout.trim()
+  return name || null
+}
+
+function resolveBaseRef(gitRoot) {
+  const originHead = runGit(gitRoot, [
+    'symbolic-ref',
+    '--quiet',
+    'refs/remotes/origin/HEAD',
+  ])
+  if (originHead.status === 0) {
+    const ref = originHead.stdout.trim().replace(/^refs\/remotes\//, '')
+    if (ref) return ref
+  }
+  for (const name of ['origin/main', 'origin/master', 'main', 'master']) {
+    const check = runGit(gitRoot, ['rev-parse', '--verify', '--quiet', name])
+    if (check.status === 0 && check.stdout.trim()) return name
+  }
+  return 'HEAD'
+}
+
+function resolveMergeBase(gitRoot, baseRef) {
+  const result = runGit(gitRoot, ['merge-base', 'HEAD', baseRef])
+  if (result.status === 0 && result.stdout.trim()) return result.stdout.trim()
+  return 'HEAD'
+}
+
+function parseNameStatus(text) {
+  const files = []
+  const creates = []
+  const deletes = []
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue
+    const tab = line.indexOf('\t')
+    if (tab < 0) continue
+    const status = line.slice(0, tab).trim()
+    const filePath = toPosix(line.slice(tab + 1).trim())
+    if (!filePath || filePath.includes('\t') || shouldSkipPath(filePath)) continue
+    const code = status[0]
+    if (code === 'A') creates.push(filePath)
+    else if (code === 'D') deletes.push(filePath)
+    else if (code === 'M' || code === 'T') files.push(filePath)
+  }
+  return { files, creates, deletes }
+}
+
+function fileAsAddPatch(fileId, contents) {
+  const lines = contents.split('\n')
+  if (contents.endsWith('\n')) lines.pop()
+  const count = lines.length
+  const hunk =
+    count === 0
+      ? []
+      : [`@@ -0,0 +1,${count} @@`, ...lines.map((line) => `+${line}`)]
+  return [
+    `diff --git a/${fileId} b/${fileId}`,
+    'new file mode 100644',
+    '--- /dev/null',
+    `+++ b/${fileId}`,
+    ...hunk,
+    '',
+  ].join('\n')
+}
+
+function collectUntracked(targetRoot) {
+  const result = runGit(targetRoot, ['ls-files', '--others', '--exclude-standard'])
+  const creates = []
+  const patches = []
+  const createLines = {}
+  if (result.status !== 0) return { creates, patches, createLines }
+
+  for (const raw of result.stdout.split('\n')) {
+    const fileId = toPosix(raw.trim())
+    if (!fileId || shouldSkipPath(fileId)) continue
+    const absolute = path.join(targetRoot, fileId)
+    try {
+      if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) continue
+    } catch {
+      continue
+    }
+    if (isBinaryFile(absolute)) continue
+    const contents = fs.readFileSync(absolute, 'utf8')
+    creates.push(fileId)
+    patches.push(fileAsAddPatch(fileId, contents))
+    const lineCount =
+      contents === ''
+        ? 1
+        : contents.split('\n').length - (contents.endsWith('\n') ? 1 : 0)
+    createLines[fileId] = Math.max(1, lineCount)
+  }
+  return { creates, patches, createLines }
+}
+
+export function emptyBranchChanges() {
+  return {
+    available: false,
+    branch: null,
+    base: null,
+    files: [],
+    creates: [],
+    deletes: [],
+    createFolders: [],
+    createLines: {},
+    imports: [],
+    addedFunctions: [],
+    addedVariables: [],
+    addedImports: [],
+    changedFunctions: [],
+    changedVariables: [],
+  }
+}
+
+export function readBranchChanges(targetRoot, knownFileIds = []) {
+  const empty = emptyBranchChanges()
+  if (!targetRoot || !fs.existsSync(targetRoot)) return empty
+  const gitRoot = gitTopLevel(targetRoot)
+  if (!gitRoot) return empty
+
+  const branch = currentBranch(targetRoot) ?? currentBranch(gitRoot)
+  const base = resolveBaseRef(gitRoot)
+  const mergeBase = resolveMergeBase(gitRoot, base)
+  const diffArgs = [
+    '--no-color',
+    '--no-ext-diff',
+    '--no-renames',
+    '--relative',
+    mergeBase,
+  ]
+  const statusResult = runGit(targetRoot, ['diff', '--name-status', ...diffArgs])
+  const patchResult = runGit(targetRoot, ['diff', ...diffArgs])
+  const named = parseNameStatus(
+    statusResult.status === 0 ? statusResult.stdout : '',
+  )
+  const untracked = collectUntracked(targetRoot)
+  const creates = unique([...named.creates, ...untracked.creates])
+  const deletes = named.deletes.filter((id) => !creates.includes(id))
+  const files = named.files.filter(
+    (id) => !creates.includes(id) && !deletes.includes(id),
+  )
+  const patchText = [patchResult.status === 0 ? patchResult.stdout : '', ...untracked.patches]
+    .filter((part) => part.trim())
+    .join('\n')
+  const parsed = parseUnifiedPatch(patchText)
+  const known = unique([...knownFileIds, ...creates, ...files])
+
+  return {
+    available: true,
+    branch,
+    base,
+    files,
+    creates,
+    deletes,
+    createFolders: collectCreateFolders(
+      creates,
+      foldersFromFileIds(knownFileIds.filter((id) => !creates.includes(id))),
+    ),
+    createLines: { ...parsed.createLines, ...untracked.createLines },
+    imports: extractPatchImports(parsed.entries, known),
+    ...extractPatchAdditions(parsed.entries),
+  }
+}

package/apps/explorer/scripts/js-source.mjs

@@ -1,17 +1,3 @@
-export const FILE_EXTENSIONS = new Set([
-  '.ts',
-  '.tsx',
-  '.js',
-  '.jsx',
-  '.mjs',
-  '.cjs',
-  '.css',
-  '.scss',
-  '.json',
-  '.html',
-  '.md',
-])
-
 export const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'])
 
 export const RESOLVE_EXTENSIONS = [
@@ -147,16 +133,27 @@ export function extractImportBindings(source) {
   return bindings
 }
 
+function firstKnownWithPrefix(prefix, known) {
+  for (const id of known) {
+    if (!id.startsWith(prefix)) continue
+    if (id.slice(prefix.length).includes('/')) continue
+    return id
+  }
+  return null
+}
+
 export function resolveSpecifierAgainst(candidate, known) {
   if (known.has(candidate)) return candidate
   for (const ext of RESOLVE_EXTENSIONS) {
     if (known.has(candidate + ext)) return candidate + ext
   }
+  const withExt = firstKnownWithPrefix(`${candidate}.`, known)
+  if (withExt) return withExt
   for (const ext of RESOLVE_EXTENSIONS) {
     const indexFile = `${candidate}/index${ext}`
     if (known.has(indexFile)) return indexFile
   }
-  return null
+  return firstKnownWithPrefix(`${candidate}/index.`, known)
 }
 
 function destructuredNames(pattern, { importClause = false } = {}) {

package/apps/explorer/scripts/patch-lib.d.ts

@@ -80,6 +80,7 @@ export const emptyIntent: {
   updatedAt: null
   showMap: boolean
   status: string
+  name: null
   feature: null
   steps: unknown[]
   step: null
@@ -106,6 +107,11 @@ export const emptyIntent: {
   phase: null
   working: boolean
   stalledWait: boolean
+  llmIdle: boolean
+  awaitingAttach: boolean
+  listening: boolean
+  lastAck: { kind: string; detail: string; at: string | null } | null
+  initialInstruction: string | null
   creationMode: boolean
   canEnterBlueprint: boolean
   blueprintSessionId: string | null

package/apps/explorer/scripts/patch-lib.mjs

@@ -507,6 +507,7 @@ export const emptyIntent = {
   updatedAt: null,
   showMap: false,
   status: 'idle',
+  name: null,
   feature: null,
   steps: [],
   step: null,
@@ -533,6 +534,11 @@ export const emptyIntent = {
   phase: null,
   working: false,
   stalledWait: false,
+  llmIdle: false,
+  awaitingAttach: false,
+  listening: false,
+  lastAck: null,
+  initialInstruction: null,
   creationMode: false,
   canEnterBlueprint: false,
   blueprintSessionId: null,

package/apps/explorer/scripts/scan-target.mjs

@@ -2,7 +2,6 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import {
-  FILE_EXTENSIONS,
   SOURCE_EXTENSIONS,
   RESOLVE_EXTENSIONS,
   collectImportSpecifiers,
@@ -25,11 +24,23 @@ const IGNORE_DIRS = new Set([
   '.inbase',
 ])
 const IGNORE_FILES = new Set(['package-lock.json'])
+const BINARY_PROBE_BYTES = 8000
 
 function toPosix(filePath) {
   return filePath.split(path.sep).join('/')
 }
 
+function isBinaryFile(filePath) {
+  const fd = fs.openSync(filePath, 'r')
+  try {
+    const buf = Buffer.alloc(BINARY_PROBE_BYTES)
+    const bytes = fs.readSync(fd, buf, 0, buf.length, 0)
+    return buf.subarray(0, bytes).includes(0)
+  } finally {
+    fs.closeSync(fd)
+  }
+}
+
 function walk(dir, acc = []) {
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     if (entry.name.startsWith('.')) continue
@@ -39,8 +50,9 @@ function walk(dir, acc = []) {
       continue
     }
     if (IGNORE_FILES.has(entry.name)) continue
-    if (!FILE_EXTENSIONS.has(path.extname(entry.name))) continue
-    acc.push(path.join(dir, entry.name))
+    const absolutePath = path.join(dir, entry.name)
+    if (isBinaryFile(absolutePath)) continue
+    acc.push(absolutePath)
   }
   return acc
 }
@@ -55,24 +67,40 @@ function extractSymbols(source, ext) {
   return extractJsSymbols(source)
 }
 
-function resolveExisting(candidate) {
-  if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
-    return candidate
+function isUsableFile(filePath) {
+  return fs.existsSync(filePath) && fs.statSync(filePath).isFile() && !isBinaryFile(filePath)
+}
+
+function fileWithStem(dir, stem) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return null
+  for (const name of fs.readdirSync(dir)) {
+    if (name.startsWith('.')) continue
+    const parsed = path.parse(name)
+    if (parsed.name !== stem || !parsed.ext) continue
+    const full = path.join(dir, name)
+    if (isUsableFile(full)) return full
   }
+  return null
+}
+
+function resolveExisting(candidate) {
+  if (isUsableFile(candidate)) return candidate
 
   for (const ext of RESOLVE_EXTENSIONS) {
     const withExt = candidate + ext
-    if (fs.existsSync(withExt) && fs.statSync(withExt).isFile()) {
-      return withExt
-    }
+    if (isUsableFile(withExt)) return withExt
   }
 
-  const indexDir = candidate
-  if (fs.existsSync(indexDir) && fs.statSync(indexDir).isDirectory()) {
+  const sibling = fileWithStem(path.dirname(candidate), path.basename(candidate))
+  if (sibling) return sibling
+
+  if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
     for (const ext of RESOLVE_EXTENSIONS) {
-      const indexFile = path.join(indexDir, `index${ext}`)
-      if (fs.existsSync(indexFile)) return indexFile
+      const indexFile = path.join(candidate, `index${ext}`)
+      if (isUsableFile(indexFile)) return indexFile
     }
+    const indexFile = fileWithStem(candidate, 'index')
+    if (indexFile) return indexFile
   }
 
   return null
@@ -110,6 +138,11 @@ function ensureFolder(folders, folderPath, rootName) {
   if (parent) ensureFolder(folders, parent, rootName)
 }
 
+export function listSourceFiles(root) {
+  if (!root || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) return []
+  return walk(root).map((absolutePath) => toPosix(path.relative(root, absolutePath)))
+}
+
 export function scanTarget({
   root = defaultTargetRoot,
   name = path.basename(root),