npm - @jkwd/inbase - Versions diffs - 0.1.0 - Mend

@jkwd/inbase 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/README.md +76 -0
package/apps/explorer/index.html +12 -0
package/apps/explorer/package.json +28 -0
package/apps/explorer/scripts/js-source.mjs +188 -0
package/apps/explorer/scripts/patch-lib.d.ts +115 -0
package/apps/explorer/scripts/patch-lib.mjs +472 -0
package/apps/explorer/scripts/scan-target.mjs +188 -0
package/apps/explorer/scripts/session-store.d.ts +156 -0
package/apps/explorer/scripts/session-store.mjs +809 -0
package/apps/explorer/scripts/target-config.d.ts +8 -0
package/apps/explorer/scripts/target-config.mjs +42 -0
package/apps/explorer/src/App.tsx +941 -0
package/apps/explorer/src/agentIntent.ts +182 -0
package/apps/explorer/src/codebase.ts +15 -0
package/apps/explorer/src/index.css +632 -0
package/apps/explorer/src/layout.ts +508 -0
package/apps/explorer/src/main.tsx +16 -0
package/apps/explorer/src/scene/BlockPlacer.tsx +87 -0
package/apps/explorer/src/scene/Bridge.tsx +290 -0
package/apps/explorer/src/scene/FileBlock.tsx +256 -0
package/apps/explorer/src/scene/FolderArea.tsx +96 -0
package/apps/explorer/src/scene/IslandPlacer.tsx +40 -0
package/apps/explorer/src/scene/MapSelectBorder.tsx +57 -0
package/apps/explorer/src/scene/MapView.tsx +247 -0
package/apps/explorer/src/scene/Player.tsx +245 -0
package/apps/explorer/src/scene/RelationLines.tsx +223 -0
package/apps/explorer/src/scene/SelectionController.tsx +89 -0
package/apps/explorer/src/scene/UserContextTracker.tsx +152 -0
package/apps/explorer/src/scene/World.tsx +323 -0
package/apps/explorer/src/theme.ts +111 -0
package/apps/explorer/src/types.ts +245 -0
package/apps/explorer/src/ui/CanvasErrorBoundary.tsx +38 -0
package/apps/explorer/src/ui/HUD.tsx +1090 -0
package/apps/explorer/src/ui/NameInput.tsx +45 -0
package/apps/explorer/src/userContext.ts +73 -0
package/apps/explorer/src/userCreated.ts +354 -0
package/apps/explorer/src/vite-env.d.ts +1 -0
package/apps/explorer/tsconfig.json +21 -0
package/apps/explorer/vite.config.ts +295 -0
package/bin/inbase.mjs +170 -0
package/bin/project.mjs +94 -0
package/bin/session.mjs +241 -0
package/package.json +63 -0
package/skill/inbase/SKILL.md +167 -0

package/README.md ADDED Viewed

@@ -0,0 +1,76 @@
+# Inbase
+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.
+Install the package in a project, run `inbase init`, then `inbase run`. Cursor uses the installed skill so code changes go through the visual map.
+The npm package is `@jkwd/inbase` (npm blocks the unscoped name `inbase`). The command is still `inbase`.
+## Use in a project
+```bash
+npm install -D @jkwd/inbase
+npx inbase init
+npx inbase run
+```
+Or install globally:
+```bash
+npm install -g @jkwd/inbase
+inbase init
+inbase run
+```
+Open the printed URL (http://localhost:5173 by default), click the scene, then walk with WASD.
+`inbase run` maps the current directory. To map another folder:
+```bash
+inbase run --target /path/to/your/project
+```
+`inbase init` copies a Cursor skill into `.cursor/skills/inbase/` and gitignores `.inbase/`. After that, ask Cursor to change source files in this repo — it should follow the visual plan/patch workflow while `inbase run` is up.
+## Commands
+| Command | What it does |
+| --- | --- |
+| `inbase init` | Install the Cursor skill in this repo |
+| `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.
+## 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.
+## How to read the map
+- Each **file** is a block. Taller blocks have more lines of code.
+- Small cubes on a block are **functions** (blue) and **variables** (tan).
+- Each **folder** is a floor area with a center walkway.
+- At the far end of an area, **bridges** lead into child folders. The folder name hangs above the bridge.
+- Click a block to see **import relations**. Connected files stay lit and arcs draw to them.
+## Develop Inbase itself
+This repository is a workspace. The bundled demo target is `apps/example-target`.
+```bash
+npm install
+npm run dev
+```
+That still maps `apps/example-target` by default. To map a different project without the CLI:
+```bash
+VISUAL_CODER_TARGET=/path/to/your/project npm run dev
+```
+To run the example React app itself:
+```bash
+npm run dev:target
+```

package/apps/explorer/index.html ADDED Viewed

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Inbase</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/apps/explorer/package.json ADDED Viewed

@@ -0,0 +1,28 @@
+{
+  "name": "@visual-coder/explorer",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "scan": "node scripts/scan-target.mjs",
+    "dev": "node scripts/scan-target.mjs && vite",
+    "build": "node scripts/scan-target.mjs && tsc --noEmit && vite build",
+    "test": "node --test scripts/*.test.mjs",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@react-three/drei": "^9.117.3",
+    "@react-three/fiber": "^8.17.10",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "three": "^0.170.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@types/three": "^0.170.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.6.3",
+    "vite": "^6.0.3"
+  }
+}

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

@@ -0,0 +1,188 @@
+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 = [
+  '.tsx',
+  '.ts',
+  '.jsx',
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.css',
+  '.scss',
+  '.json',
+]
+export function extractJsSymbols(source) {
+  const symbols = []
+  const seen = new Set()
+  const add = (name, kind) => {
+    if (!name || seen.has(name)) return
+    seen.add(name)
+    symbols.push({ name, kind })
+  }
+  for (const match of source.matchAll(/\b(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g)) {
+    add(match[1], 'function')
+  }
+  for (const match of source.matchAll(
+    /\b(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/g,
+  )) {
+    add(match[1], 'class')
+  }
+  for (const match of source.matchAll(
+    /(?:export\s+)?(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/g,
+  )) {
+    add(match[1], 'function')
+  }
+  for (const match of source.matchAll(/(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)/g)) {
+    add(match[1], 'variable')
+  }
+  for (const match of source.matchAll(
+    /(?:export\s+)?(?:const|let|var)\s+(\[[^\]]+\]|\{[^}]+\})/g,
+  )) {
+    for (const ident of destructuredNames(match[1])) add(ident, 'variable')
+  }
+  return symbols
+}
+export function collectImportSpecifiers(source) {
+  const specifiers = new Set()
+  for (const match of source.matchAll(/from\s+['"]([^'"]+)['"]/g)) {
+    specifiers.add(match[1])
+  }
+  for (const match of source.matchAll(/import\s+['"]([^'"]+)['"]/g)) {
+    specifiers.add(match[1])
+  }
+  for (const match of source.matchAll(/\brequire\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+    specifiers.add(match[1])
+  }
+  return [...specifiers]
+}
+export function extractImportBindings(source) {
+  const bindings = []
+  const seen = new Set()
+  const add = (name, from) => {
+    const ident = name?.trim()
+    const specifier = from?.trim()
+    if (!ident || !specifier) return
+    const key = `${ident}\0${specifier}`
+    if (seen.has(key)) return
+    seen.add(key)
+    bindings.push({ name: ident, from: specifier })
+  }
+  for (const match of source.matchAll(/^[ \t]*import\s+['"]([^'"]+)['"]/gm)) {
+    add(match[1], match[1])
+  }
+  for (const match of source.matchAll(
+    /^[ \t]*import\s+(?:type\s+)?([\s\S]*?)\s+from\s+['"]([^'"]+)['"]/gm,
+  )) {
+    const clause = match[1].trim()
+    const from = match[2]
+    const star = clause.match(/^\*\s+as\s+([A-Za-z_$][\w$]*)/)
+    if (star) {
+      add(star[1], from)
+      continue
+    }
+    const named = clause.match(/\{([^}]*)\}/)
+    const defaultPart = clause
+      .replace(/\{[^}]*\}/, '')
+      .replace(/,/g, '')
+      .replace(/^type\s+/, '')
+      .trim()
+    if (defaultPart && /^[A-Za-z_$][\w$]*$/.test(defaultPart)) {
+      add(defaultPart, from)
+    }
+    if (!named) continue
+    for (const ident of destructuredNames(`{${named[1]}}`, { importClause: true })) {
+      add(ident, from)
+    }
+  }
+  const boundRequires = new Set()
+  for (const match of source.matchAll(
+    /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*require\(\s*['"]([^'"]+)['"]\s*\)/g,
+  )) {
+    add(match[1], match[2])
+    boundRequires.add(match[2])
+  }
+  for (const match of source.matchAll(
+    /\b(?:const|let|var)\s+(\{[^}]+\}|\[[^\]]+\])\s*=\s*require\(\s*['"]([^'"]+)['"]\s*\)/g,
+  )) {
+    boundRequires.add(match[2])
+    for (const ident of destructuredNames(match[1])) add(ident, match[2])
+  }
+  for (const match of source.matchAll(/\brequire\(\s*['"]([^'"]+)['"]\s*\)/g)) {
+    if (boundRequires.has(match[1])) continue
+    add(match[1], match[1])
+  }
+  return bindings
+}
+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
+  }
+  for (const ext of RESOLVE_EXTENSIONS) {
+    const indexFile = `${candidate}/index${ext}`
+    if (known.has(indexFile)) return indexFile
+  }
+  return null
+}
+function destructuredNames(pattern, { importClause = false } = {}) {
+  const names = []
+  const inner = pattern.slice(1, -1)
+  for (const part of inner.split(',')) {
+    let token = part.trim()
+    if (!token) continue
+    token = token.replace(/^\.\.\./, '')
+    if (importClause) {
+      const aliased = token.match(/^(?:type\s+)?[A-Za-z_$][\w$]*\s+as\s+([A-Za-z_$][\w$]*)$/)
+      if (aliased) {
+        names.push(aliased[1])
+        continue
+      }
+      const ident = token.replace(/^type\s+/, '').trim()
+      if (/^[A-Za-z_$][\w$]*$/.test(ident)) names.push(ident)
+      continue
+    }
+    const aliased = token.match(/^[A-Za-z_$][\w$]*\s*:\s*([A-Za-z_$][\w$]*)/)
+    if (aliased) {
+      names.push(aliased[1])
+      continue
+    }
+    const ident = token.split(/\s*=/)[0].trim()
+    if (/^[A-Za-z_$][\w$]*$/.test(ident)) names.push(ident)
+  }
+  return names
+}

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

@@ -0,0 +1,115 @@
+export type PatchImport = {
+  from: string
+  to: string
+}
+export type PatchSymbolAddition = {
+  name: string
+  file: string
+}
+export type PatchImportAddition = {
+  name: string
+  from: string
+  file: string
+}
+export function parseUnifiedPatch(patch: string): {
+  files: string[]
+  creates: string[]
+  deletes: string[]
+  createLines: Record<string, number>
+  entries: Array<{
+    id: string
+    kind: 'add' | 'modify' | 'delete'
+    addedLines: number
+    hunks: unknown[]
+  }>
+}
+export function extractPatchImports(
+  entries: Array<{
+    id: string
+    kind: 'add' | 'modify' | 'delete'
+    hunks: unknown[]
+  }>,
+  knownFileIds?: string[],
+): PatchImport[]
+export function extractPatchAdditions(
+  entries: Array<{
+    id: string
+    kind: 'add' | 'modify' | 'delete'
+    hunks: unknown[]
+  }>,
+): {
+  addedFunctions: PatchSymbolAddition[]
+  addedVariables: PatchSymbolAddition[]
+  addedImports: PatchImportAddition[]
+}
+export function accumulatePatchAdditions(patches?: string[]): {
+  addedFunctions: PatchSymbolAddition[]
+  addedVariables: PatchSymbolAddition[]
+  addedImports: PatchImportAddition[]
+}
+export function applyUnifiedPatch(
+  patch: string,
+  targetRoot: string,
+): ReturnType<typeof parseUnifiedPatch>
+export function folderOfFile(fileId: string): string
+export function folderParent(folderPath: string): string | null
+export function foldersFromFileIds(ids?: string[]): Set<string>
+export function collectCreateFolders(
+  creates?: string[],
+  existingFolders?: Iterable<string>,
+): string[]
+export const emptyIntent: {
+  updatedAt: null
+  showMap: boolean
+  status: string
+  feature: null
+  steps: unknown[]
+  step: null
+  files: string[]
+  creates: string[]
+  deletes: string[]
+  createFolders: string[]
+  createLines: Record<string, number>
+  imports: PatchImport[]
+  addedFunctions: PatchSymbolAddition[]
+  addedVariables: PatchSymbolAddition[]
+  addedImports: PatchImportAddition[]
+  reason: null
+  sessionId: null
+  diffId: null
+  parentDiffId: null
+  chainIndex: null
+  chain: unknown[]
+  isActiveDiff: boolean
+  preview: boolean
+  phase: null
+  working: boolean
+  creationMode: boolean
+  canEnterBlueprint: boolean
+  blueprintSessionId: string | null
+  userCreatedBlocks: unknown[]
+  userCreatedIslands: unknown[]
+  blueprintFunctions: unknown[]
+  blueprintVariables: unknown[]
+  blueprintImports: unknown[]
+}
+export function isLastStep(intent: {
+  step?: number | null
+  steps?: unknown[]
+}): boolean
+export function overlayPatch(
+  intent: Record<string, unknown>,
+  patchText: string,
+  knownFileIds?: string[],
+): Record<string, unknown>