@scelar/nodepod 1.0.0

package/LICENSE

@@ -0,0 +1,43 @@
+MIT License
+
+Copyright (c) 2026 R1ck404 / ScelarOrg
+
+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.
+
+Commons Clause License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as defined
+below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under
+the License will not include, and the License does not grant to you, the right
+to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of the rights
+granted to you under the License to provide to third parties, for a fee or
+other consideration (including without limitation fees for hosting or
+consulting/support services related to the Software), a product or service
+whose value derives, entirely or substantially, from the functionality of the
+Software. Any licensee who utilizes the Software as a component of a larger
+application or service — where the primary value is derived from the licensee's
+own original work — is not considered to be Selling the Software.
+
+Licensor: R1ck404 / ScelarOrg
+Software: Nodepod
+License: MIT

package/README.md

@@ -0,0 +1,240 @@
+# nodepod
+
+[![npm version](https://img.shields.io/npm/v/@scelar/nodepod.svg)](https://www.npmjs.com/package/@scelar/nodepod)
+[![license](https://img.shields.io/npm/l/@scelar/nodepod.svg)](https://github.com/ScelarOrg/Nodepod/blob/main/LICENSE)
+
+Browser-native Node.js runtime. Run real Node.js code — filesystem, modules, `require()`, npm packages, HTTP servers — entirely inside the browser.
+
+No backend. No containers. No WASM Node binary. Just polyfills, an in-memory filesystem, and a JavaScript execution engine.
+
+Built by [@R1ck404](https://github.com/R1ck404) — powering [Scelar](https://scelar.com), the AI app builder that actually COMPLETELY builds your apps, from idea to production in a matter of minutes.
+
+## Features
+
+- **Virtual Filesystem** — Full in-memory `fs` API (read, write, watch, streams, symlinks, glob)
+- **Module System** — `require()`, `import`, `module.exports`, `package.json` resolution, conditional exports
+- **npm Packages** — Install real packages from the npm registry, extracted and resolved in-browser
+- **HTTP Servers** — Run Express, Hono, Elysia, vite and other frameworks with real request/response routing
+- **Shell** — Built-in bash-like shell with 35+ commands (ls, cat, grep, find, sed, etc.), pipes, redirections, variable expansion
+- **Process Model** — Web Worker-based processes with `child_process.exec/spawn/fork`, `worker_threads`, and IPC
+- **Terminal** — Drop-in xterm.js integration with line editing, history, raw mode, Ctrl+C
+- **Preview** — Service Worker-based iframe preview with script injection and WebSocket bridging
+- **Snapshots** — Save and restore the entire filesystem state
+
+## Install
+
+```bash
+npm install @scelar/nodepod
+```
+
+## Quick Start
+
+```typescript
+import { Nodepod } from '@scelar/nodepod';
+
+// Boot a nodepod instance with some files
+const nodepod = await Nodepod.boot({
+  files: {
+    '/index.js': 'console.log("Hello from the browser!")',
+  },
+});
+
+// Run a script
+const proc = await nodepod.spawn('node', ['index.js']);
+proc.on('output', (text) => console.log(text));
+await proc.completion;
+
+// Read/write files
+await nodepod.fs.writeFile('/data.json', JSON.stringify({ hello: 'world' }));
+const content = await nodepod.fs.readFile('/data.json', 'utf8');
+```
+
+## Terminal Integration
+
+nodepod provides built-in xterm.js terminal support:
+
+```typescript
+import { Nodepod } from '@scelar/nodepod';
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+
+const nodepod = await Nodepod.boot();
+const terminal = nodepod.createTerminal({ Terminal, FitAddon });
+terminal.attach('#terminal-container');
+```
+
+The terminal handles line editing, command history, prompt rendering, raw/cooked mode, and streaming output out of the box.
+
+## Running an Express Server
+
+```typescript
+const nodepod = await Nodepod.boot({
+  files: {
+    '/server.js': `
+      const express = require('express');
+      const app = express();
+      app.get('/', (req, res) => res.json({ status: 'ok' }));
+      app.listen(3000, () => console.log('Server running on port 3000'));
+    `,
+  },
+});
+
+// Install express
+await nodepod.install(['express']);
+
+// Run the server
+const proc = await nodepod.spawn('node', ['server.js']);
+
+// Dispatch requests to the virtual server
+const response = await nodepod.request(3000, 'GET', '/');
+console.log(response.body); // { status: 'ok' }
+```
+
+## Preview Script Injection
+
+Inject scripts into preview iframes before any page content loads — useful for setting up bridges between the main window and the iframe:
+
+```typescript
+await nodepod.setPreviewScript(`
+  window.__bridge = {
+    sendToParent(msg) { window.parent.postMessage(msg, '*'); }
+  };
+`);
+
+// Remove it later
+await nodepod.clearPreviewScript();
+```
+
+## SDK API
+
+### `Nodepod.boot(options?)`
+
+Creates a fully wired nodepod instance.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `files` | `Record<string, string>` | — | Initial files to populate the filesystem |
+| `workdir` | `string` | `"/"` | Working directory |
+| `env` | `Record<string, string>` | — | Environment variables |
+| `swUrl` | `string` | — | Service Worker URL (enables preview iframes) |
+| `watermark` | `boolean` | `true` | Show a small "nodepod" badge in preview iframes |
+| `onServerReady` | `(port, url) => void` | — | Callback when a virtual server starts listening |
+
+### Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `spawn(cmd, args?)` | Run a command, returns `NodepodProcess` |
+| `createTerminal(opts)` | Create an interactive terminal |
+| `install(packages)` | Install npm packages |
+| `fs.readFile(path, enc?)` | Read a file |
+| `fs.writeFile(path, data)` | Write a file |
+| `fs.readdir(path)` | List directory contents |
+| `fs.stat(path)` | Get file stats |
+| `fs.mkdir(path, opts?)` | Create a directory |
+| `fs.rm(path, opts?)` | Remove files/directories |
+| `snapshot()` | Capture filesystem state |
+| `restore(snapshot)` | Restore filesystem from snapshot |
+| `setPreviewScript(script)` | Inject JS into preview iframes |
+| `clearPreviewScript()` | Remove injected preview script |
+| `port(num)` | Get preview URL for a virtual server port |
+
+### `NodepodProcess`
+
+Returned by `spawn()`. An EventEmitter with:
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `output` | `string` | stdout data |
+| `error` | `string` | stderr data |
+| `exit` | `number` | exit code |
+
+Property: `completion` — a `Promise<void>` that resolves when the process exits.
+
+## Architecture
+
+```
+nodepod
+├── src/
+│   ├── script-engine.ts       # JavaScript execution engine (require, ESM→CJS, REPL)
+│   ├── memory-volume.ts       # In-memory virtual filesystem
+│   ├── syntax-transforms.ts   # ESM-to-CJS conversion via acorn
+│   ├── module-transformer.ts  # esbuild-wasm code transforms
+│   ├── polyfills/             # Node.js built-in module polyfills
+│   │   ├── fs.ts              #   Filesystem (read, write, watch, streams, glob)
+│   │   ├── http.ts            #   HTTP server/client
+│   │   ├── stream.ts          #   Readable, Writable, Transform, Duplex
+│   │   ├── events.ts          #   EventEmitter
+│   │   ├── path.ts            #   Path operations
+│   │   ├── crypto.ts          #   Hashing, randomBytes, randomUUID
+│   │   ├── child_process.ts   #   exec, spawn, fork, execSync
+│   │   ├── net.ts             #   TCP Socket, Server
+│   │   └── ...                #   40+ more polyfills
+│   ├── shell/                 # Bash-like shell interpreter
+│   │   ├── shell-parser.ts    #   Tokenizer + recursive-descent parser
+│   │   ├── shell-builtins.ts  #   35+ built-in commands
+│   │   └── shell-interpreter.ts # AST executor, pipes, redirections
+│   ├── packages/              # npm package management
+│   │   ├── installer.ts       #   Package installer
+│   │   ├── registry-client.ts #   npm registry client
+│   │   └── version-resolver.ts #  Semver resolution
+│   ├── threading/             # Worker-based process model
+│   │   ├── process-manager.ts #   Process lifecycle management
+│   │   └── process-handle.ts  #   Process I/O handle
+│   └── sdk/                   # Public SDK layer
+│       ├── nodepod.ts          #   Nodepod.boot() entry point
+│       ├── nodepod-fs.ts       #   Async filesystem facade
+│       ├── nodepod-process.ts  #   Process handle
+│       └── nodepod-terminal.ts #   xterm.js terminal integration
+└── static/
+    └── __sw__.js              # Service Worker for HTTP request interception
+```
+
+## Supported Node.js Modules
+
+**Full implementations:** fs, path, events, stream, buffer, process, http, https, net, crypto, zlib, url, querystring, util, os, tty, child_process, assert, readline, module, timers, string_decoder, perf_hooks, constants, punycode
+
+**Shims/stubs:** dns, worker_threads, vm, v8, tls, dgram, cluster, http2, inspector, domain, diagnostics_channel, async_hooks
+
+## CDN Usage
+Once published to npm, nodepod is automatically available on CDNs:
+
+```html
+<!-- unpkg -->
+<script src="https://unpkg.com/@scelar/nodepod"></script>
+
+<!-- jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/@scelar/nodepod"></script>
+```
+
+## Development
+
+```bash
+git clone https://github.com/ScelarOrg/Nodepod.git
+cd Nodepod
+npm install
+npm run type-check    # TypeScript validation
+npm run build:lib     # Build ESM + CJS bundles
+npm test              # Run tests
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions and guidelines.
+
+## Author
+
+Created by [@R1ck404](https://github.com/R1ck404). Part of the [Scelar](https://scelar.com) ecosystem.
+
+## License
+
+[MIT + Commons Clause](./LICENSE)
+
+This project uses the MIT license with the [Commons Clause](https://commonsclause.com/) restriction. In plain terms:
+
+- **Use it** freely in your own projects, including commercial ones
+- **Modify it**, fork it, learn from it
+- **Ship products** built with nodepod — that's totally fine
+- **Don't resell nodepod itself** as a standalone product or hosted service
+
+Basically, build whatever you want with it — just don't take nodepod, rebrand it, and sell it as your own thing.