@nimbus-sh/core 0.1.0

package/src/runtime/framework-detect.ts

@@ -0,0 +1,245 @@
+/**
+ * framework-detect.ts — single source of truth for "what kind of project
+ * is this?" Pure function — no I/O of its own. Takes a parsed
+ * package.json + a set of root-level filenames + (optional) per-file
+ * contents and returns a discriminated union.
+ *
+ * Resolution order (first match wins):
+ *
+ *   0. Wrangler-on-framework override:
+ *      `wrangler.{toml,jsonc,json}` at root AND any framework dep present
+ *      → framework: <fw>, devCommand: 'wrangler-dev'
+ *      W10's wrangler-dev path loads the framework's CF adapter.
+ *      MUST come first — Remix-on-CF and SK-on-CF projects have BOTH a
+ *      framework dep AND a wrangler config; without this rule W10's
+ *      path never sees them.
+ *
+ *   1. `next` in deps                            → 'next'
+ *   2. `astro` in deps                           → 'astro'
+ *   3. `nuxt` in deps                            → 'nuxt'
+ *   4. `@remix-run/dev` in deps AND vite.config* references @remix-run/dev
+ *                                                → 'remix'
+ *   5. `@sveltejs/kit` in deps                   → 'sveltekit'
+ *   6. (rule moved to step 0)
+ *   7. `wrangler.{toml,jsonc,json}` alone        → 'wrangler'
+ *   8. `vite` in deps                            → 'vite' (generic)
+ *   9. else                                      → 'unknown'
+ *
+ * Bare `@remix-run/react` without `@remix-run/dev` falls through to step 7
+ * — it's a runtime dep alone, not a Remix v2 vite-plugin project.
+ *
+ */
+
+export type Framework =
+  | 'next'
+  | 'astro'
+  | 'nuxt'
+  | 'remix'
+  | 'sveltekit'
+  | 'vite'
+  | 'wrangler'
+  | 'unknown';
+
+export type DevCommand =
+  | 'next-cli'
+  | 'astro-cli'
+  | 'nuxt-cli'
+  | 'remix-cli'
+  | 'sveltekit-vite'
+  | 'vite-real'
+  | 'wrangler-dev'
+  | 'generic';
+
+export interface DetectInput {
+  pkg: {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+  };
+  /** Basenames at project root, e.g. {'package.json', 'svelte.config.js'} */
+  files: Set<string>;
+  /**
+   * Optional: file contents keyed by basename. Currently used for:
+   *   - vite.config.{ts,js,mjs} — Remix gate (must reference @remix-run/dev)
+   * If undefined, the Remix gate falls back to dep-presence only with a
+   * lower confidence.
+   */
+  fileContents?: Record<string, string>;
+}
+
+export interface DetectResult {
+  framework: Framework;
+  /** 0..1; ≥0.7 means "act on it without asking". */
+  confidence: number;
+  /** Human-readable reason, suitable for logging to the user terminal. */
+  reason: string;
+  /** What the supervisor should treat `npm run dev` as. */
+  devCommand: DevCommand;
+}
+
+const WRANGLER_CONFIG_FILES = ['wrangler.toml', 'wrangler.jsonc', 'wrangler.json'];
+const VITE_CONFIG_FILES = ['vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'vite.config.cjs'];
+
+function hasDep(pkg: DetectInput['pkg'], name: string): boolean {
+  return (
+    !!(pkg.dependencies && pkg.dependencies[name]) ||
+    !!(pkg.devDependencies && pkg.devDependencies[name])
+  );
+}
+
+function hasAnyFile(files: Set<string>, candidates: string[]): string | null {
+  for (const c of candidates) {
+    if (files.has(c)) return c;
+  }
+  return null;
+}
+
+function readViteConfig(input: DetectInput): { name: string; contents: string } | null {
+  if (!input.fileContents) return null;
+  for (const c of VITE_CONFIG_FILES) {
+    if (input.fileContents[c]) return { name: c, contents: input.fileContents[c] };
+  }
+  return null;
+}
+
+/**
+ * Detect what framework "owns" this project for purposes of routing
+ * `npm run dev`/`npm run build`. Pure; deterministic; no I/O.
+ */
+export function detectFramework(input: DetectInput): DetectResult {
+  const { pkg, files } = input;
+
+  // ── Step 0: Wrangler-on-framework override ──────────────────────────
+  const wranglerCfg = hasAnyFile(files, WRANGLER_CONFIG_FILES);
+  if (wranglerCfg) {
+    // Determine the underlying framework first (informational).
+    const underlying = detectUnderlyingFramework(input);
+    if (underlying.framework !== 'unknown' && underlying.framework !== 'wrangler') {
+      return {
+        framework: underlying.framework,
+        confidence: 0.85,
+        reason:
+          `wrangler config (${wranglerCfg}) AND ${underlying.reason} — routing through ` +
+          `wrangler-dev so the framework's Cloudflare adapter loads.`,
+        devCommand: 'wrangler-dev',
+      };
+    }
+  }
+
+  // ── Steps 1-5 + 7-9: underlying framework (or generic) ───────────────
+  return detectUnderlyingFramework(input);
+}
+
+function detectUnderlyingFramework(input: DetectInput): DetectResult {
+  const { pkg, files } = input;
+
+  // Step 1: Next.js
+  if (hasDep(pkg, 'next')) {
+    return {
+      framework: 'next',
+      confidence: 0.95,
+      reason: "found 'next' in dependencies",
+      devCommand: 'next-cli',
+    };
+  }
+
+  // Step 2: Astro
+  if (hasDep(pkg, 'astro')) {
+    return {
+      framework: 'astro',
+      confidence: 0.95,
+      reason: "found 'astro' in dependencies",
+      devCommand: 'astro-cli',
+    };
+  }
+
+  // Step 3: Nuxt
+  if (hasDep(pkg, 'nuxt')) {
+    return {
+      framework: 'nuxt',
+      confidence: 0.95,
+      reason: "found 'nuxt' in dependencies",
+      devCommand: 'nuxt-cli',
+    };
+  }
+
+  // Step 4: Remix v2 (vite-plugin path).
+  // Gate: @remix-run/dev in deps AND vite.config* references @remix-run/dev.
+  if (hasDep(pkg, '@remix-run/dev')) {
+    const cfg = readViteConfig(input);
+    if (cfg && cfg.contents.includes('@remix-run/dev')) {
+      return {
+        framework: 'remix',
+        confidence: 0.95,
+        reason: `found '@remix-run/dev' in deps and ${cfg.name} imports it`,
+        devCommand: 'remix-cli',
+      };
+    }
+    // Lower-confidence fallback: dep present but no contents to verify.
+    if (!input.fileContents) {
+      return {
+        framework: 'remix',
+        confidence: 0.7,
+        reason: "found '@remix-run/dev' in deps (vite.config contents not inspected)",
+        devCommand: 'remix-cli',
+      };
+    }
+    // Contents inspected and the import is missing — fall through.
+  }
+
+  // Step 5: SvelteKit
+  if (hasDep(pkg, '@sveltejs/kit')) {
+    return {
+      framework: 'sveltekit',
+      confidence: 0.95,
+      reason: "found '@sveltejs/kit' in dependencies",
+      devCommand: 'sveltekit-vite',
+    };
+  }
+
+  // Step 7: standalone wrangler (no framework deps)
+  if (hasAnyFile(files, WRANGLER_CONFIG_FILES) || hasDep(input.pkg, 'wrangler')) {
+    return {
+      framework: 'wrangler',
+      confidence: 0.85,
+      reason: "wrangler config or dep present, no framework dep — routing to wrangler-dev",
+      devCommand: 'wrangler-dev',
+    };
+  }
+
+  // Step 8: generic Vite
+  if (hasDep(pkg, 'vite')) {
+    return {
+      framework: 'vite',
+      confidence: 0.7,
+      reason: "found 'vite' in dependencies (no specific framework)",
+      devCommand: 'vite-real',
+    };
+  }
+
+  // Step 9: unknown
+  const depCount =
+    Object.keys(pkg.dependencies || {}).length +
+    Object.keys(pkg.devDependencies || {}).length;
+  return {
+    framework: 'unknown',
+    confidence: depCount === 0 ? 0.1 : 0.3,
+    reason:
+      depCount === 0
+        ? 'no dependencies declared'
+        : 'no recognized framework dep (next/astro/nuxt/remix/sveltekit/vite)',
+    devCommand: 'generic',
+  };
+}
+
+/**
+ * Companion helper: detection result is reportable as a one-line MOTD.
+ * Used by initSession to print a single boot line:
+ *   [nimbus] detected framework: sveltekit (sveltekit-vite, conf=0.95)
+ */
+export function describeDetect(result: DetectResult): string {
+  return (
+    `framework=${result.framework} dev=${result.devCommand} ` +
+    `confidence=${result.confidence.toFixed(2)} (${result.reason})`
+  );
+}

package/src/runtime/import-meta-transform.ts

@@ -0,0 +1,16 @@
+const IMPORT_META_RESOLVE_HELPER = '__nimbusImportMetaResolveForModule';
+
+export function importMetaDefines(absUrl: string): Record<string, string> {
+  return {
+    'import.meta.url': JSON.stringify(absUrl),
+    'import.meta.resolve': IMPORT_META_RESOLVE_HELPER,
+  };
+}
+
+export function bindImportMetaResolve(source: string, absUrl: string): string {
+  if (!source.includes(IMPORT_META_RESOLVE_HELPER)) return source;
+  return [
+    `const ${IMPORT_META_RESOLVE_HELPER} = (specifier) => globalThis.__nimbusImportMetaResolve(specifier, ${JSON.stringify(absUrl)});`,
+    source,
+  ].join('\n');
+}

package/src/runtime/javascript-ast.ts

@@ -0,0 +1,66 @@
+import { parse, type AnyNode } from 'acorn';
+
+export type AstNode = AnyNode & Record<string, unknown>;
+
+export function parseJavaScriptModule(source: string): AstNode {
+  return parse(source, {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    allowHashBang: true,
+  }) as AstNode;
+}
+
+export function hasTopLevelModuleSyntax(source: string): boolean {
+  let ast: AstNode;
+  try {
+    ast = parseJavaScriptModule(source);
+  } catch {
+    return false;
+  }
+  return nodeList(ast, 'body').some((node) =>
+    node.type === 'ImportDeclaration' ||
+    node.type === 'ExportNamedDeclaration' ||
+    node.type === 'ExportDefaultDeclaration' ||
+    node.type === 'ExportAllDeclaration'
+  );
+}
+
+export function nodeList(node: AstNode, key: string): AstNode[] {
+  const value = node[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter(isAstNode);
+}
+
+export function nodeProp(node: AstNode | undefined, key: string): AstNode | undefined {
+  if (!node) return undefined;
+  const value = node[key];
+  return isAstNode(value) ? value : undefined;
+}
+
+export function nodeName(node: AstNode | undefined): string | undefined {
+  if (node?.type !== 'Identifier' && node?.type !== 'Literal') return undefined;
+  if (node.type === 'Identifier') return stringField(node, 'name');
+  return literalStringValue(node);
+}
+
+export function stringField(node: AstNode, key: string): string | undefined {
+  const value = node[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function booleanField(node: AstNode, key: string): boolean {
+  const value = node[key];
+  return typeof value === 'boolean' ? value : false;
+}
+
+export function literalStringValue(node: AstNode | undefined): string | undefined {
+  return node?.type === 'Literal' && typeof node.value === 'string' ? node.value : undefined;
+}
+
+export function literalBooleanValue(node: AstNode | undefined): boolean | undefined {
+  return node?.type === 'Literal' && typeof node.value === 'boolean' ? node.value : undefined;
+}
+
+export function isAstNode(value: unknown): value is AstNode {
+  return !!value && typeof value === 'object' && typeof (value as { type?: unknown }).type === 'string';
+}

package/src/runtime/long-running-handle.ts

@@ -0,0 +1,185 @@
+/**
+ * long-running-handle.ts — generic adapter (primitive #3 + #4).
+ *
+ * Goal: any long-running thing in a Nimbus session that *behaves* like
+ * an HTTP server should plug into the supervisor's port registry the
+ * same way, so:
+ *
+ *   - `ps` shows it (via the process supervisor's long-running spawn)
+ *   - `/preview/?port=N` routes to it
+ *   - `/preview/` routes to the default-target one
+ *   - `vite stop` / `kill <pid>` tears it down
+ *
+ * Today, two "long-running things" exist in-process:
+ *
+ *   1. ViteDevServer (the built-in Cirrus shim)
+ *   2. CirrusReal (the experimental real-vite facet)
+ *
+ * Both already expose a `handleRequest(request, pathname)` method.
+ * `PortRegistry` expects facets exposing `handleHttpRequest(request)`
+ * (single-arg, full request, with the inner path baked into the URL).
+ *
+ * `makeLongRunningPortStub` adapts the (request, pathname) shape into
+ * the (request) shape, by stripping a configurable `basePath` prefix
+ * from `request.url.pathname` and forwarding the rest. It is the ONE
+ * hook every future long-running thing will use; we do not write a new
+ * adapter per framework.
+ *
+ * NOTE: this is a SUPERVISOR-LOCAL stub, NOT a `WorkerEntrypoint`
+ * RPC stub. The port-registry handler at `routeRequest` happily
+ * accepts any object exposing `handleHttpRequest`, including in-DO
+ * wrappers. That is by design — a long-running facet is NOT required
+ * to live in a separate isolate; the routing primitive is the same
+ * either way.
+ */
+
+/**
+ * The minimal shape any long-running HTTP-like thing in a Nimbus
+ * session must expose to be registered as a port handler. The first
+ * arg is the original Request (in case the handler wants headers /
+ * body / method); the second is the inner path with any base-prefix
+ * already stripped, plus the original querystring.
+ */
+export interface LongRunningHttpHandler {
+  handleRequest(request: Request, innerPath: string): Promise<Response>;
+}
+
+/**
+ * Build a port-registry-compatible stub that forwards into the given
+ * handler.
+ *
+ * The supervisor calls `stub.handleHttpRequest(request)` with a request
+ * whose URL pathname is the path relative to the port (`PortRegistry`
+ * already strips the `/port/<n>` prefix). We pass that pathname to the
+ * underlying handler unchanged.
+ *
+ * Concretely: `GET /port/3000/api/users?id=42`
+ *   → port-registry rewrites url to `/api/users?id=42`
+ *   → stub.handleHttpRequest(req)  // req.url has /api/users?id=42
+ *   → handler.handleRequest(req, "/api/users?id=42")
+ */
+export function makeLongRunningPortStub(handler: LongRunningHttpHandler) {
+  return {
+    async handleHttpRequest(request: Request): Promise<Response> {
+      const url = new URL(request.url);
+      const innerPath = (url.pathname || '/') + url.search;
+      return handler.handleRequest(request, innerPath);
+    },
+  };
+}
+
+/**
+ * Parse `--port N`, `--port=N`, `-p N`, `-p=N` from argv. Returns the
+ * parsed integer, or null. Last-wins (so `--port 3000 --port 4000` →
+ * 4000), matching POSIX convention.
+ *
+ * Out-of-range or non-numeric values are returned as null without
+ * throwing — callers fall back to the next source (env, config, default).
+ */
+export function parsePortFromArgv(argv: string[]): number | null {
+  let result: number | null = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    let candidate: string | undefined;
+    if (a === '--port' || a === '-p') {
+      candidate = argv[i + 1];
+      i++;
+    } else if (a.startsWith('--port=')) {
+      candidate = a.slice('--port='.length);
+    } else if (a.startsWith('-p=')) {
+      candidate = a.slice('-p='.length);
+    }
+    if (!candidate) continue;
+    const n = parseInt(candidate, 10);
+    if (Number.isFinite(n) && n > 0 && n < 65536) result = n;
+  }
+  return result;
+}
+
+/**
+ * Resolve a final port to bind to, given the various sources in
+ * priority order. Returns the first finite source.
+ *
+ *   1. argv flags (--port / -p)
+ *   2. env.PORT (post-shell-expansion; Markflow's `${PORT:-3000}` → 3000)
+ *   3. viteConfig.port (explicit `port: NNNN` in vite.config.ts)
+ *   4. fallback (caller-provided default, e.g. 5173 for vite, 3000 for express)
+ */
+export function resolveLongRunningPort(opts: {
+  argv?: string[];
+  env?: Record<string, any> | undefined;
+  configPort?: number | undefined;
+  fallback: number;
+}): number {
+  const argvPort = opts.argv ? parsePortFromArgv(opts.argv) : null;
+  if (argvPort) return argvPort;
+  const envPortStr = opts.env?.PORT;
+  if (envPortStr !== undefined && envPortStr !== null && envPortStr !== '') {
+    const n = parseInt(String(envPortStr), 10);
+    if (Number.isFinite(n) && n > 0 && n < 65536) return n;
+  }
+  if (opts.configPort && opts.configPort > 0 && opts.configPort < 65536) {
+    return opts.configPort;
+  }
+  return opts.fallback;
+}
+
+/**
+ * Expand shell-style `${VAR}` and `${VAR:-default}` references in a
+ * single argv token, against the supplied env map.
+ *
+ * Nimbus's shell does not expand parameter substitution, so a
+ * package.json script line like
+ *
+ *     "dev": "vite --host 0.0.0.0 --port ${PORT:-3000}"
+ *
+ * arrives at the vite handler as the literal token `${PORT:-3000}`.
+ * Without expansion, `--port ${PORT:-3000}` is parsed as a non-numeric
+ * port and discarded. With expansion (against `env.PORT` falling back
+ * to `3000`), the user gets the port they asked for.
+ *
+ * Supports the two forms commonly seen in `package.json` scripts:
+ *
+ *   - ${VAR}             → env[VAR] || ''
+ *   - ${VAR:-default}    → env[VAR] || default
+ *   - ${VAR:-other_var}  → recursive (one level), so the default may
+ *                          itself reference an env var
+ *
+ * Does NOT support: command substitution, arithmetic substitution,
+ * pattern operators (`${VAR##pat}` etc.), positional params, glob.
+ * That is intentional — full shell semantics belong in the shell, not
+ * the argv expander; this helper covers ~95% of dev-script usage.
+ */
+export function expandShellDefaults(
+  token: string,
+  env: Record<string, any> | undefined,
+): string {
+  if (!token || token.indexOf('${') < 0) return token;
+  const lookup = (name: string): string | undefined => {
+    const v = env?.[name];
+    if (v === undefined || v === null || v === '') return undefined;
+    return String(v);
+  };
+  // ${VAR:-default}, ${VAR}. One pass; default value is itself
+  // recursively expanded once.
+  return token.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_m, name, def) => {
+    const v = lookup(name);
+    if (v !== undefined) return v;
+    if (def === undefined) return '';
+    // One recursion level so `${PORT:-${PORT_FALLBACK:-3000}}` works.
+    if (def.indexOf('${') >= 0) return expandShellDefaults(def, env);
+    return def;
+  });
+}
+
+/**
+ * Apply `expandShellDefaults` to every argv token. Used at the top of
+ * a long-running handler before argv parsing so flag values are
+ * fully resolved.
+ */
+export function expandArgvShellDefaults(
+  argv: ReadonlyArray<string>,
+  env: Record<string, any> | undefined,
+): string[] {
+  return argv.map((t) => expandShellDefaults(t, env));
+}

package/src/runtime/module-source-rewriter.ts

@@ -0,0 +1,95 @@
+import { simple } from 'acorn-walk';
+import MagicString from 'magic-string';
+
+import {
+  type AstNode,
+  literalStringValue,
+  nodeList,
+  nodeProp,
+  parseJavaScriptModule,
+  stringField,
+} from './javascript-ast.js';
+
+export interface StaticModuleSpecifierContext {
+  nodeType: string;
+  isSideEffectImport: boolean;
+}
+
+export interface ModuleSourceRewriteOptions {
+  staticSpecifier(specifier: string, context: StaticModuleSpecifierContext): string | undefined;
+  dynamicImport?(specifier: string): string | undefined;
+  createRequireCallee?: string;
+}
+
+export function rewriteJavaScriptModuleSource(
+  source: string,
+  options: ModuleSourceRewriteOptions,
+): string {
+  const ast = parseJavaScriptModule(source);
+  const edits = new MagicString(source);
+
+  simple(ast, {
+    ImportDeclaration(node) {
+      rewriteStaticSpecifier(node as AstNode, options, edits);
+    },
+    ExportNamedDeclaration(node) {
+      rewriteStaticSpecifier(node as AstNode, options, edits);
+    },
+    ExportAllDeclaration(node) {
+      rewriteStaticSpecifier(node as AstNode, options, edits);
+    },
+    ImportExpression(node) {
+      rewriteDynamicImport(node as AstNode, options, edits);
+    },
+    CallExpression(node) {
+      rewriteCreateRequireCall(node as AstNode, options, edits);
+    },
+  });
+
+  return edits.toString();
+}
+
+function rewriteStaticSpecifier(
+  node: AstNode,
+  options: ModuleSourceRewriteOptions,
+  edits: MagicString,
+): void {
+  const sourceNode = nodeProp(node, 'source');
+  const specifier = literalStringValue(sourceNode);
+  if (!specifier) return;
+  const replacement = options.staticSpecifier(specifier, {
+    nodeType: node.type,
+    isSideEffectImport: node.type === 'ImportDeclaration' && nodeList(node, 'specifiers').length === 0,
+  });
+  if (replacement) overwriteNode(edits, sourceNode, JSON.stringify(replacement));
+}
+
+function rewriteDynamicImport(
+  node: AstNode,
+  options: ModuleSourceRewriteOptions,
+  edits: MagicString,
+): void {
+  if (!options.dynamicImport) return;
+
+  const sourceNode = nodeProp(node, 'source');
+  const specifier = literalStringValue(sourceNode);
+  if (!specifier) return;
+  const replacement = options.dynamicImport(specifier);
+  if (replacement) overwriteNode(edits, node, replacement);
+}
+
+function rewriteCreateRequireCall(
+  node: AstNode,
+  options: ModuleSourceRewriteOptions,
+  edits: MagicString,
+): void {
+  if (!options.createRequireCallee || node.type !== 'CallExpression') return;
+  const callee = nodeProp(node, 'callee');
+  if (callee?.type !== 'Identifier' || stringField(callee, 'name') !== 'createRequire') return;
+  overwriteNode(edits, callee, options.createRequireCallee);
+}
+
+function overwriteNode(edits: MagicString, node: AstNode | undefined, text: string): void {
+  if (typeof node?.start !== 'number' || typeof node.end !== 'number') return;
+  edits.overwrite(node.start, node.end, text);
+}