Monday, February 2, 2026

i come not to bury php

 license: public domain CC0

NOTE: expanded version here: https://claude.ai/public/artifacts/64cf67f1-6067-4187-b15f-fdf4402274ef




Design Document: A Modern PHP‑Inspired Web Runtime for Node + TypeScript

1. Introduction: The Spirit of PHP

PHP earned its place in web history not because it was elegant, but because it was immediately useful. Its defining virtues were:

  • Zero‑friction iteration — edit a file, refresh the browser, see the result.
  • Stateless execution — every request starts fresh, no global state leaks.
  • Trivial deployment — copy a file to a server and it runs.
  • Beginner‑friendly failure model — crashes affect only the current request.
  • Massive accessibility — no build steps, no daemons, no containers.

These qualities created a development loop that felt like a REPL for the web. You didn’t “build” an app — you tinkered with it, live, with instant feedback.

But PHP’s strengths came bundled with limitations:

  • No type safety
  • Inconsistent standard library
  • Weak module system
  • Poor tooling
  • Limited modern ergonomics
  • No REPL, no notebook‑style exploration
  • Primitive deployment safety

The goal of this project is to preserve the spirit of PHP while modernizing everything else, using Node + TypeScript as the foundation.

2. Vision: Expanding and Modernizing PHP’s Wins for Node + TypeScript

The core idea is simple:

Bring PHP’s frictionless iteration and deployment model into the TypeScript + Node ecosystem, enhanced with modern tooling, REPL workflows, and programmable safety.

This means:

  • TypeScript as the first‑class language
  • Node as the long‑lived host
  • VM contexts as the per‑request sandbox
  • A TS loader that eliminates build steps
  • A local development loop that feels like a notebook
  • A remote REPL for staging and production
  • A sync‑based deployment model
  • A programmable friction pipeline for safe deploys
  • VSCode integration for diagnostics and deploy UX
  • A batteries‑included web standard library

The result is a system that feels like:

  • PHP’s simplicity
  • Node’s ecosystem
  • TypeScript’s safety
  • Cloudflare Workers’ isolation model
  • Jupyter’s iterative workflow
  • Git’s extensibility

All fused into a single, coherent developer experience.

3. High‑Level Goals

3.1 Zero‑Friction Local Development

Local iteration should feel like breathing:

  • tsweb dev starts everything
  • Hot reload on file change
  • Instant TS → JS transform
  • Automatic context reload
  • Browser auto‑refresh
  • Inline VSCode diagnostics
  • Local REPL for experimentation

No build step. No bundler. No config.

3.2 Safe, Structured Deployment

Deployment should be:

  • sync‑based (like PHP)
  • secure (key‑based auth)
  • environment‑aware (staging vs prod)
  • programmable (hook pipeline)
  • deliberate (double confirmations, branch checks)

3.3 Stateless Request Execution

Each request runs in a fresh VM context:

  • No global state leakage
  • Deterministic behavior
  • Easy debugging
  • Safe remote REPL

3.4 Batteries‑Included Web Standard Library

A cohesive TS‑native stdlib:

  • Request/response helpers
  • Cookie/session utilities
  • File uploads
  • Routing
  • DB connectors
  • HTML templating

3.5 Canonical Setup Across All OSes

Everything should “just work”:

  • npm package + CLI
  • optional Docker image
  • VSCode extension
  • minimal configuration

4. Architecture Overview

┌──────────────────────────────────────────┐
│              tsweb CLI                   │
│ dev, deploy, repl, logs, diff            │
└───────────────────┬──────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────┐
│      Environment & Friction Engine       │
│ staging/prod rules, hooks, confirmations │
└───────────────────┬──────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────┐
│        Secure Deployment Channel         │
│ signed payloads, key-based auth          │
└───────────────────┬──────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────┐
│            Remote TS Runtime             │
│ VM pool, TS loader, hot reload, REPL     │
└──────────────────────────────────────────┘

5. Core Components

5.1 TypeScript Loader

A fast, production‑grade TS loader:

  • Uses swc/esbuild for TS → JS
  • Caches aggressively
  • Works inside VM contexts
  • Supports hot reload
  • Integrates with VSCode diagnostics

This eliminates the build step entirely.

5.2 VM Context Pool

Node’s VM module provides per‑request isolation:

  • Fresh global scope per request
  • Deterministic teardown
  • No state leakage
  • Optional snapshotting for speed

This recreates PHP’s statelessness.

5.3 Web Standard Library

A cohesive, batteries‑included API:

  • Request, Response (WHATWG)
  • Cookies, sessions
  • File uploads
  • Routing
  • DB connectors
  • HTML templating
  • JSON helpers

This replaces Node’s low‑level primitives with something closer to PHP’s ergonomics.

5.4 Local Development Loop

tsweb dev provides:

  • File watcher
  • Hot reload
  • Automatic TS compilation
  • Browser auto‑refresh
  • Local REPL
  • Inline VSCode diagnostics

This is the modern equivalent of “edit file → refresh browser.”

5.5 Remote REPL

A secure REPL for staging and production:

  • Evaluate code in isolated contexts
  • Inspect logs
  • Run smoke tests
  • Debug issues
  • Validate migrations

This is a superpower PHP never had.

5.6 Deployment System

Deployments are:

  • sync‑based (diff of changed files)
  • signed (key‑based auth)
  • environment‑aware
  • safe (friction pipeline)
  • fast (no build step)

Deployment flow:

  1. Compute diff
  2. Run friction hooks
  3. Sign payload
  4. Upload to server
  5. Server verifies signature
  6. Server reloads VM contexts
  7. Health checks
  8. Swap traffic

5.7 Programmable Friction Pipeline

Friction is a first‑class concept.

Each environment defines a pipeline of hooks:

{
  "environments": {
    "staging": {
      "friction": ["confirm_environment", "show_diff"]
    },
    "prod": {
      "friction": [
        "confirm_environment",
        "show_diff",
        "require_clean_working_tree",
        "require_on_main",
        "double_confirm",
        "type_environment_name"
      ]
    }
  }
}

Hooks are just TypeScript functions.

Teams can add:

  • Slack notifications
  • Jira ticket checks
  • Peer approval
  • Deployment windows
  • Custom validations

This prevents accidental deploys without slowing down intentional ones.

6. Developer Workflow

6.1 Local Development

npx tsweb dev
  • Edit files
  • Save
  • Browser reloads
  • Errors appear in VSCode
  • REPL available

6.2 Deploy to Staging

npx tsweb deploy staging
  • Light friction
  • Diff preview
  • Single confirmation

6.3 Remote Debugging

npx tsweb repl staging

6.4 Deploy to Production

npx tsweb deploy prod
  • Heavy friction
  • Branch enforcement
  • Clean working tree required
  • Double confirmation
  • Type environment name

7. Why This System Matters

This design:

  • preserves PHP’s magic
  • fixes PHP’s weaknesses
  • leverages Node’s ecosystem
  • embraces TypeScript’s safety
  • integrates with modern tooling
  • supports REPL‑driven development
  • enforces safe, deliberate deployments
  • remains simple, predictable, and fast

It’s not a framework.
It’s not a serverless platform.
It’s not a bundler.

It’s a developer experience layer that makes building web apps feel effortless again — but without sacrificing safety, structure, or modern ergonomics.


 

Posted by at

1 comment:

Subscribe to: Post Comments (Atom)