DERANGED PREVIEWER

A universal project preview, runtime, build, recovery & inspection system for VS Code.

Understand the project first. Then decide how to preview it.

Most previewers look at a file extension. Deranged reads your whole workspace — languages, frameworks, package managers, runtimes, build systems, scripts, entry points, services and their dependencies — builds a Preview Plan, and starts the best available preview in its own window. When something is broken it keeps previewing what still works and shows exactly what failed, instead of collapsing to a single BUILD FAILED screen.

✨ Highlights

🧠 Project Intelligence

Evidence-based, confidence-scored detection of languages, frameworks, package managers and architecture. Never claims a framework from a filename alone.

🕸️ Monorepo & service graph

A workspace can hold a frontend, an API, a worker and a database. Deranged maps the graph and lets you pick which app to preview.

🛟 Best Effort recovery

When one part breaks, the rest keeps previewing. Last-Known-Good is preserved and clearly labelled — errors are never hidden.

⚡ Live & incremental

Uses your framework's own HMR (Vite/Next/…) when present, plus a built-in SSE reload for the static fallback. A dependency graph rebuilds only what changed.

🔧 Runs your real tooling

npm / pnpm / yarn / bun, python, cargo, go, dotnet, gradle/maven, gcc/clang — detected locally, never bundled, never installed without consent.

🔒 Security-first

Argument-array execution, path-traversal & symlink guards, localhost-only servers, secret redaction in every log, and consent before custom commands.

🎥 In action


Live web preview — dev server + Console / Problems / Services / Network / Inspector	Best Effort — a module fails, the rest of the app keeps previewing

Monorepo picker — choose which application to preview	Document previewers — Markdown, JSON tree, CSV, YAML, XML, TOML, SVG

🧠 How it thinks

VS Code Workspace
      │
      ▼
 Scanner ─► Project Intelligence ─► Architecture & Components
      │            │                        │
      │     Confidence + evidence     Service graph
      ▼            ▼                        ▼
 Dependency Graph ─► Runtime probe ─► Preview Planner ─► Orchestrator ─► Window

The planner answers, per component: what should render, run, compile, serve, or inspect — what's missing, what can preview independently, and what's the safe fallback?

🧩 Supported technologies

Only genuinely implemented tech is listed. Tested = covered by the automated suite; Implemented = the code path exists but its toolchain wasn't available to exercise end-to-end in the build environment.

Technology	Mode	External runtime	Status
HTML / CSS / JS (static)	Static Preview (built-in server)	No	Tested
React + Vite	Web Preview (project dev server)	Node	Tested
Vue / Svelte / Angular / Next / Nuxt / Astro	Web Preview	Node	Implemented
Node.js app / CLI	Runtime Execution	Node	Tested
Express / Fastify / Nest / Koa	Server Preview	Node	Implemented
Python (script)	Runtime Execution	Python	Tested
Django / Flask / FastAPI	Server Preview	Python	Implemented
Rust · Go · .NET · Java/Kotlin · C/C++	Compile & Run	toolchain	Implemented (toolchain-gated)
Markdown · JSON · CSV · YAML · XML · TOML · SVG · SQL	Render / Inspect	No	Tested
Docker / Compose	Detection + service graph	Docker	Implemented (never auto-run)

🚀 Quick start

Open a project folder in VS Code.
Run Deranged: Open Preview (F5, or the 👁 icon in the editor title bar).
Deranged analyses the workspace and starts the best preview in its own panel. Click ⧉ New Window (or drag the tab out) to float it as a separate window.
Edit code — affected parts update live; errors appear without destroying the working preview.

To preview a single file (Markdown, JSON, CSV, …), right-click it in the Explorer → Preview with Deranged Previewer.

🧭 Commands

Command	What it does
`Deranged: Open Preview`	Analyse the workspace and start the best preview
`Deranged: Refresh / Restart / Stop Preview`	Control the running session
`Deranged: Open in Browser`	Open the running URL externally
`Deranged: Detect Project`	Show a project-analysis report without previewing
`Deranged: Check Environment`	List detected runtimes/toolchains + versions
`Deranged: Configure Preview`	Create/edit `.deranged/preview.json`
`Deranged: Select Application`	Pick an app in a monorepo
`Deranged: Set Preview Mode`	Toggle Best Effort / Strict

⚙️ Settings

All under derangedPreview.* — only implemented features are exposed: previewMode, liveReload, autoDetect, defaultPort, openBrowser, killProcessesOnClose, maxScanDepth, ignorePatterns, logLevel, rememberWindowState, host, allowCustomCommands.

Manual override for unusual projects (.deranged/preview.json):

{
  "preview": {
    "command": ["npm", "run", "dev"],
    "port": 5173,
    "url": "http://127.0.0.1:5173",
    "kind": "web"
  }
}

🔒 Security

Deranged can execute code, so it treats the workspace as hostile: argv-only execution (no shell strings), shell-metacharacter rejection, path-traversal & symlink-escape guards, localhost-only servers, secret redaction in every log and report, and explicit consent for custom commands and installs. No telemetry, no uploads. Full threat model in SECURITY.md.

🧱 Architecture & docs

ARCHITECTURE.md — the VS Code-free core, layers, incremental model
SECURITY.md — threat model & mitigations
CONTRIBUTING.md — add a detector / adapter / renderer
PUBLISHING.md — Marketplace release flow

⚠️ Known limitations (honest)

Separate OS window uses a WebviewPanel floated via VS Code's official "Move Editor into New Window" — the extension API exposes no public native window, and this is documented, not faked.
Compiled-language adapters (Rust/Go/.NET/Java/C++) are implemented and toolchain-gated but were not run end-to-end where the compiler is absent.
Network panel observes the built-in server only (no packet capture); Inspector is lightweight DOM, not DevTools; SQL is analysed, not auto-executed; Markdown covers a documented subset.

📦 Build & install

npm install
npm run compile && npm test && npm run lint
npm run package          # -> deranged-previewer-<version>.vsix
code --install-extension deranged-previewer-0.1.2.vsix

Made for developers who are tired of "it works on my machine". Released under the MIT License.

Deranged Previewer

All-Previewer