@mocklane/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asis Paudel
+
+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.

package/README.md

@@ -0,0 +1,386 @@
+# Mocklane
+
+Generate, edit, and serve mock HTTP responses with browser-local AI.
+
+Mocklane turns a pasted data model and a plain-language request into a structured JSON HTTP response. Its CLI opens the browser workspace, serves generated mocks from a local API, and can proxy every unmatched request to an existing backend.
+
+## Features
+
+- Generates complete HTTP response objects from models and prompts
+- Runs generation locally with Transformers.js, WebLLM, or native browser AI
+- Accepts TypeScript, Python/Pydantic, Go, Java, Prisma, SQL, OpenAPI/JSON schemas, and example JSON
+- Validates edited output before saving it
+- Copies and downloads generated JSON
+- Serves mocks from `localhost:4000`
+- Proxies unmatched requests to an optional upstream API
+- Handles mock CORS headers and preflight requests
+- Stores models in the browser cache after the first download
+- Keeps mock data in memory and binds its servers to the local machine
+
+## Requirements
+
+- Node.js 20 or newer
+- A modern browser with WebGPU for Transformers.js and WebLLM
+- Enough browser storage and memory for the selected local model
+
+Native Browser AI is shown only when the browser exposes the `LanguageModel` API. The first Transformers.js or WebLLM load downloads model assets; later loads can reuse the browser cache.
+
+## Quick Start
+
+Run Mocklane without installing it globally:
+
+```bash
+npx mocklane
+```
+
+For a global installation:
+
+```bash
+npm install --global mocklane
+mocklane
+```
+
+Mocklane starts two local servers and opens the browser workspace automatically:
+
+```text
+Mocklane UI:      http://localhost:4001
+Mock API proxy:   http://localhost:4000
+Upstream server:  none (standalone mode)
+```
+
+In the browser:
+
+1. Select an AI provider and model.
+2. Load the model when the provider requires it.
+3. Paste or edit the data structure under **Model / Structure**.
+4. Describe the endpoint and response under **Prompt**.
+5. Select **Generate**.
+6. Review or edit the generated HTTP JSON.
+7. Enter the endpoint path and select **Mock API**.
+
+Call the active mock from any local client:
+
+```bash
+curl http://localhost:4000/api/products
+```
+
+Select **Unmock API** to remove it, or press `Ctrl+C` in the terminal to stop Mocklane.
+
+## Generated Response Format
+
+Mocklane generates a JSON object containing the complete HTTP response definition:
+
+```json
+{
+  "method": "GET",
+  "path": "/api/products",
+  "status": 200,
+  "headers": {
+    "content-type": "application/json"
+  },
+  "body": [
+    {
+      "id": "1",
+      "name": "Example product"
+    }
+  ]
+}
+```
+
+The local mock server returns the value of `body` with the configured status and headers. Before registering the mock, the endpoint path can be changed in the field below the JSON output.
+
+## AI Providers
+
+### Transformers.js
+
+The default provider uses WebGPU through Transformers.js. Available models are:
+
+- `onnx-community/Qwen3-0.6B-ONNX` using `q4f16`
+- `onnx-community/gemma-3-1b-it-ONNX-GQA` using `q4`
+
+Mocklane displays model download progress and identifies whether the model is loading for the first time or from the browser cache.
+
+### WebLLM
+
+WebLLM uses:
+
+```text
+Qwen2.5-0.5B-Instruct-q4f16_1-MLC
+```
+
+The model runs through WebGPU and must be loaded before generation.
+
+### Native Browser AI
+
+When the browser provides `window.LanguageModel` or the legacy `window.ai.languageModel`, Mocklane can generate with the browser's native Gemini Nano runtime. Availability and model download behavior are controlled by the browser.
+
+Mocklane does not send prompts to a hosted inference API. Model files may be downloaded from their model providers during initial setup, but response generation happens in the browser.
+
+## Editing Output
+
+The output toolbar supports:
+
+- **Edit**: opens the generated response in the JSON editor
+- **Save**: parses and formats the edited JSON
+- **Cancel**: discards the current edits
+- **Copy**: copies the response to the clipboard
+- **Download**: saves the response as a `.json` file
+
+Invalid JSON cannot be saved. Mocklane displays the parser error in the editor so the response can be corrected without losing the draft.
+
+## Standalone Mock Server
+
+Standalone mode is the default:
+
+```bash
+npx mocklane
+```
+
+Registered routes return their configured mock responses. Unmatched routes return `404`:
+
+```json
+{
+  "error": "No Mocklane mock matches this route.",
+  "method": "GET",
+  "path": "/api/unknown"
+}
+```
+
+Mocks are matched by HTTP method and exact pathname. Query strings do not affect matching. Mock state is kept in memory and is cleared when the CLI exits.
+
+## Proxy Mode
+
+Use proxy mode when an application already has a backend and only selected routes should be mocked:
+
+```bash
+npx mocklane --target http://localhost:8000
+```
+
+Point the application at `http://localhost:4000` instead of the upstream server:
+
+```text
+Application -> localhost:4000 -> Mocklane -> localhost:8000
+```
+
+- A matching method and pathname returns the registered mock.
+- An unmatched request is forwarded to the upstream server.
+- Request methods, headers, bodies, and query strings are forwarded.
+- Upstream status codes, headers, and response bodies are passed back to the client.
+
+For example, with only `GET /api/products` mocked:
+
+```bash
+curl http://localhost:4000/api/products
+curl http://localhost:4000/api/users
+```
+
+The first request uses the mock. The second request is forwarded to `http://localhost:8000/api/users`.
+
+## CLI Reference
+
+```text
+Usage:
+  mocklane [options]
+
+Options:
+  --target <url>       Optional upstream API URL for unmatched routes
+  --proxy-port <port>  Mock/proxy port (default: 4000)
+  --ui-port <port>     Mocklane UI port (default: 4001)
+  -h, --help           Show CLI help
+```
+
+### Custom ports
+
+```bash
+npx mocklane --proxy-port 5000 --ui-port 5001
+```
+
+### Proxy with custom ports
+
+```bash
+npx mocklane \
+  --target http://localhost:8000 \
+  --proxy-port 5000 \
+  --ui-port 5001
+```
+
+The proxy and UI ports must be different. Both servers bind to `127.0.0.1` and are not exposed to the local network.
+
+## Local Control API
+
+The browser workspace registers mocks through a control API on the UI port.
+
+### Health
+
+```bash
+curl http://localhost:4001/__mocklane/health
+```
+
+```json
+{
+  "ready": true,
+  "proxyPort": 4000,
+  "mocks": 0
+}
+```
+
+### List mocks
+
+```bash
+curl http://localhost:4001/__mocklane/mocks
+```
+
+### Register a mock
+
+Save a response definition as `response.json`, then run:
+
+```bash
+curl --request PUT \
+  --header "content-type: application/json" \
+  --data @response.json \
+  http://localhost:4001/__mocklane/mocks
+```
+
+### Remove a mock
+
+```bash
+curl --request DELETE \
+  --header "content-type: application/json" \
+  --data @response.json \
+  http://localhost:4001/__mocklane/mocks
+```
+
+Control API request bodies are limited to 10 MB. A response definition must contain a method, a path beginning with `/`, an HTTP status from `100` to `599`, and a headers object.
+
+## CORS Behavior
+
+Mock responses include `access-control-allow-origin: *` unless the response already defines that header. An `OPTIONS` request containing `access-control-request-method` receives a `204` preflight response when Mocklane has a matching mock for that method and pathname.
+
+## Development
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/aasispaudel/Mocklane.git
+cd Mocklane
+pnpm install
+```
+
+Start the React Router development server:
+
+```bash
+pnpm dev
+```
+
+The development UI runs at `http://localhost:3010`. Development-only model test benches are available at:
+
+```text
+http://localhost:3010/test
+http://localhost:3010/test-t
+http://localhost:3010/test-n
+```
+
+The main application uses Transformers.js by default. The test routes isolate WebLLM, Transformers.js, and Native Browser AI behavior.
+
+### Run the source CLI
+
+Build the browser UI before starting the TypeScript CLI:
+
+```bash
+pnpm build
+pnpm mocklane
+```
+
+Run the compiled CLI and rebuild everything first:
+
+```bash
+pnpm mocklane:build
+```
+
+### Validation
+
+```bash
+pnpm typecheck
+pnpm test:cli
+pnpm build:package
+```
+
+- `typecheck` generates React Router types and runs TypeScript validation.
+- `test:cli` verifies UI serving, mock registration, standalone `404` responses, CORS preflight handling, and upstream proxying.
+- `build:package` creates the production browser bundle and compiled CLI.
+
+## Packaging
+
+Create the npm tarball locally:
+
+```bash
+npm pack
+```
+
+The `prepack` script automatically runs the production UI and CLI builds. The package contains:
+
+```text
+build/client/   Production browser application
+dist/cli.js     Compiled Node.js executable
+README.md       Package documentation
+LICENSE         MIT license
+```
+
+Inspect the package without publishing:
+
+```bash
+npm publish --dry-run
+```
+
+## Architecture
+
+```text
+app/
+  components/                 Shared interface components
+  routes/home.tsx             Main generator workspace
+  routes/test*.tsx            Development model test benches
+  test-benches/               Provider-specific test interfaces
+  styles/app.css              Application styles
+cli/
+  index.ts                    CLI entry point and argument parsing
+  server.ts                   UI server, mock server, and upstream proxy
+  mockRegistry.ts             In-memory method/path registry
+  server.test.ts              CLI integration tests
+src/
+  ai/localModel.ts            WebLLM provider
+  ai/transformersModel.ts     Transformers.js provider
+  ai/nativeBrowserModel.ts    Native LanguageModel provider
+  core/browserApiMock.ts      Browser-to-CLI mock registration
+  core/generateMockResponse.ts Provider orchestration
+  core/intent.ts              Input structure detection
+  core/jsonUtils.ts           JSON extraction and formatting
+  types/mockApi.ts            HTTP response types
+```
+
+The CLI serves the built SPA on the UI port and the mock/proxy server on the proxy port. The browser performs AI generation, then sends validated response definitions to the CLI control API. No Node.js AI runtime is required.
+
+## Operational Notes
+
+- Local models can produce imperfect data. Review generated responses before using them in tests or demonstrations.
+- Very large responses depend on model context limits, available GPU memory, and browser stability.
+- Transformers.js and WebLLM are unavailable when WebGPU is unavailable.
+- Native Browser AI depends on an experimental browser API and may not be present.
+- Mocks are not persisted between CLI sessions.
+- Mock matching is exact and does not interpret path parameters or wildcard routes.
+- The proxy forwards credentials and authorization headers supplied by the client; use trusted upstream targets.
+
+## Contributing
+
+Issues and pull requests are welcome at [github.com/aasispaudel/Mocklane](https://github.com/aasispaudel/Mocklane).
+
+Before opening a pull request, run:
+
+```bash
+pnpm typecheck
+pnpm test:cli
+pnpm build:package
+```
+
+## License
+
+Mocklane is released under the [MIT License](LICENSE).