@caryhu/codemine-forge 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,108 @@
+# Codemine Forge
+
+Codemine Forge is the browser-side runtime layer for Codemine demos.
+
+It is not a full Node.js emulator and it is not a backend runner. Its job is to
+make browser-hosted projects feel like a small StackBlitz-style environment by
+owning the virtual workspace, simulated terminal commands, dependency
+resolution, browser bundling, and preview runtime.
+
+## Scope
+
+Forge owns these capabilities:
+
+- Virtual file system for project files, snapshots, package cache, and build
+  cache.
+- Fake terminal with a controlled command registry.
+- Browser bundling through `esbuild-wasm`.
+- TS, JSX, TSX, CSS, JSON, and static asset bundling.
+- `package.json` dependency parsing.
+- Import map generation or bundle alias generation.
+- Simulated `npm install`, `npm run build`, and `npm run dev` experience.
+- Vite-like dev server compatibility for preview workflows.
+
+Forge does not own:
+
+- User accounts, billing, permissions, or product navigation.
+- Server-side execution, containers, SSH, or unrestricted shell access.
+- Full npm CLI compatibility.
+- Native Node modules, `node-gyp`, install scripts, or arbitrary process
+  spawning.
+- Generated frontend output in the main Codemine repository.
+
+## Runtime Shape
+
+```text
+Codemine host app
+  Editor / file tree / demo page
+        |
+        v
+Codemine Forge
+  Virtual FS
+  Fake terminal
+  Package resolver
+  Build worker
+  Dev server facade
+        |
+        v
+Preview iframe
+  Runs compiled browser modules
+```
+
+Forge should expose a small API to the host application. The host application
+can render its own editor, file tree, tabs, and buttons, while Forge provides
+the runtime behavior behind those controls.
+
+## Document Map
+
+- [Architecture](docs/architecture.md)
+- [Virtual File System](docs/virtual-file-system.md)
+- [Package Resolution](docs/package-resolution.md)
+- [Build Pipeline](docs/build-pipeline.md)
+- [Terminal Commands](docs/terminal-commands.md)
+- [Vite-like Dev Server](docs/vite-like-dev-server.md)
+- [Roadmap](docs/roadmap.md)
+
+## Publishing
+
+Publish prerelease builds to npm with:
+
+```powershell
+pnpm run publish:npm
+```
+
+The script validates the package, checks that the current version is not already
+published, runs a package dry run, and publishes with the `alpha` dist-tag by
+default. If npm login is required, it starts the npm web login flow in the
+browser and waits for authentication to complete.
+
+Useful options:
+
+```powershell
+pnpm run publish:npm -- --dry-run
+pnpm run publish:npm -- --tag next
+pnpm run publish:npm -- --login-only
+pnpm run publish:npm -- --otp 123456
+```
+
+## Design Principles
+
+- Prefer browser-native execution over hidden backend work.
+- Keep commands deterministic and explicitly supported.
+- Treat `npm` commands as product affordances, not a real shell.
+- Make unsupported Node behavior fail early with clear diagnostics.
+- Cache aggressively, but keep cache invalidation visible and debuggable.
+- Keep the preview iframe isolated from Codemine application privileges.
+
+## First Milestone
+
+The first useful milestone is a browser-only runner that can:
+
+- Load a template workspace from memory.
+- Persist edits in IndexedDB.
+- Parse `package.json`.
+- Resolve public browser-compatible dependencies.
+- Bundle a React or Vue entry with `esbuild-wasm`.
+- Simulate `npm install`, `npm run build`, and `npm run dev`.
+- Render the result in an iframe.
+- Rebuild and refresh the iframe after file changes.

package/dist/build-pipeline/browser-bundle.d.ts

@@ -0,0 +1,31 @@
+import type { ForgePackageResolutionResult } from "../package-resolution";
+import { type ForgeVirtualFileSystem } from "../virtual-file-system";
+import type { ForgeBrowserBundle, ForgeBuildOutputFile, ForgeBuildPipelineDiagnostic } from "./types";
+export interface ForgeBrowserBundleResult {
+    readonly browserBundle?: ForgeBrowserBundle;
+    readonly diagnostics: readonly ForgeBuildPipelineDiagnostic[];
+    readonly outputFiles: readonly ForgeBuildOutputFile[];
+}
+interface CreateBrowserBundleOptions {
+    readonly entry: string;
+    readonly fileSystem: ForgeVirtualFileSystem;
+    readonly packageResolution: ForgePackageResolutionResult;
+    readonly scriptTransformer?: ForgeBrowserBundleScriptTransformer;
+}
+export type ForgeBrowserBundleScriptLoader = "ts" | "tsx";
+export interface ForgeBrowserBundleScriptTransformRequest {
+    readonly loader: ForgeBrowserBundleScriptLoader;
+    readonly sourcePath: string;
+    readonly sourceText: string;
+}
+export type ForgeBrowserBundleScriptTransformResult = {
+    readonly success: true;
+    readonly outputText: string;
+    readonly diagnostics: readonly [];
+} | {
+    readonly success: false;
+    readonly diagnostics: readonly ForgeBuildPipelineDiagnostic[];
+};
+export type ForgeBrowserBundleScriptTransformer = (request: ForgeBrowserBundleScriptTransformRequest) => Promise<ForgeBrowserBundleScriptTransformResult>;
+export declare function createBrowserBundle(options: CreateBrowserBundleOptions): Promise<ForgeBrowserBundleResult>;
+export {};