merakcode 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Tong Tong
+
+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.
+
+---
+
+Parts of this software are derived from other open-source projects, most notably
+opencode (https://github.com/anomalyco/opencode), Copyright (c) 2025 opencode, MIT License.
+See THIRD_PARTY_NOTICES.md for their copyright notices and licenses.

package/README.md

@@ -1,3 +1,323 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="apps/desktop/renderer/public/logo.svg" width="72" alt="MerakCode" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">MerakCode</h1>
+
+<p align="center">Aiming to be the best AI coding tool to work with</p>
+
+<p align="center">
+  <a href="https://github.com/TongTong313/merakcode/actions/workflows/ci.yml"><img src="https://github.com/TongTong313/merakcode/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/TongTong313/merakcode/releases"><img src="https://img.shields.io/github/v/release/TongTong313/merakcode?include_prereleases" alt="Release" /></a>
+  <a href="https://www.npmjs.com/package/merakcode"><img src="https://img.shields.io/npm/v/merakcode" alt="npm" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/TongTong313/merakcode" alt="License" /></a>
+</p>
+
+<p align="center"><a href="README.md">简体中文</a> · English</p>
+
+---
+
+MerakCode is an open-source AI coding tool. Beyond strong coding skills, it can help with anything you need AI for. AI now writes far faster than people can read, so MerakCode puts a lot of care into how people and the agent work together: a better way to review what the agent produces and a smoother experience overall, so that its output is what you expect.
+
+We open-sourced this project to make up for a regret we have carried, and in the hope that the community can keep it going. The name comes from Merak, the star in the Big Dipper that, together with Dubhe, points to Polaris. We hope MerakCode does the same and points each of your ideas in the right direction.
+
+## What it does
+
+- **AI coding**: strong project-level coding across many languages, frameworks, paradigms and styles. Honestly, this part is no different from other AI coding products. You be the judge, and if you like it, a Star is the best way to support us.
+- **Collaboration across products**: MerakCode is designed around people and the agent working together. It has a review interface built specifically for checking what the agent produces (desktop app only) and a complete permission system for what the agent may do. It can also work alongside other AI coding products that ship a CLI, so the collaboration reaches across products.
+- **Model setup**: connect all kinds of model providers (only 8 for now, more to come) as well as local models. MerakCode can also use models through API relay services.
+- **Secure and reliable**: commands the agent runs go into our own OS sandbox. They cannot read your key folders, cannot write outside the workspace, and need your approval to reach unfamiliar websites. This is a small product built by a few people, with no server side (no time to build one...). We don't collect, and couldn't collect, any usage data, so there is nothing of yours to leak.
+- **Extensible**: MCP, skills, plugins, custom agents and slash commands.
+- **Beyond coding**: AI coding is one of the hardest kinds of task there is, so using MerakCode for other things works just fine.
+- **Build your own**: MerakCode ships an agent SDK, and every MerakCode product is built on it. You can build your own AI coding tool on the same engine.
+
+## How to install
+
+### Desktop app
+
+Download from the [Releases](https://github.com/TongTong313/merakcode/releases) page:
+
+| System  | File                                                                              |
+| ------- | --------------------------------------------------------------------------------- |
+| Windows | `MerakCode-<version>-windows-x64.exe`                                             |
+| macOS   | `MerakCode-<version>-darwin-arm64.dmg` (Apple silicon), `-darwin-x64.dmg` (Intel) |
+| Linux   | `MerakCode-<version>-linux-x64.AppImage` or `.deb`                                |
+
+The desktop app ships with its own engine; you do not need the command-line version as well.
+
+The installers are not code-signed yet, so the system stops them the first time:
+
+- **Windows**: when you see "Windows protected your PC", click "More info", then "Run anyway".
+- **macOS**: if the app "cannot be opened", go to System Settings → Privacy & Security and click "Open Anyway" near the bottom. Unsigned macOS builds cannot update themselves; the app tells you when a new version is out and opens the download page.
+
+### Command line
+
+The command-line version has no UI. It is for one-off tasks in a terminal, scripts, and editors (through ACP). It shares its config and keys with the desktop app.
+
+macOS / Linux:
+
+```sh
+curl -fsSL https://github.com/TongTong313/merakcode/releases/latest/download/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://github.com/TongTong313/merakcode/releases/latest/download/install.ps1 | iex
+```
+
+Or with npm (the package brings its own runtime; any Node.js 18 or newer can install it):
+
+```sh
+npm install -g merakcode
+```
+
+The command is `merak`. Upgrade later with `merak upgrade` (or `merak update`).
+
+To check a download yourself, put the release's `SHA256SUMS` in the same folder as the file and run:
+
+```sh
+sha256sum -c SHA256SUMS --ignore-missing          # Linux
+shasum -a 256 -c SHA256SUMS --ignore-missing      # macOS
+```
+
+```powershell
+# Windows: the output must equal the value on this file's line in SHA256SUMS
+(Get-FileHash .\merakcode-<version>-windows-x64.zip).Hash.ToLower()
+```
+
+### Uninstall
+
+On Windows, if you set up the sandbox, first click "Reset" under Settings → Permissions & security in the desktop app (or run `merak sandbox reset`). It removes the sandbox account and firewall rule and takes back the folder permissions it was given.
+
+- Desktop app: uninstall it from the system's app list.
+- Installed with the script: on macOS / Linux delete `~/.local/bin/merak`; on Windows remove `~\.merakcode\bin` from your user PATH.
+- Installed with npm: `npm uninstall -g merakcode`.
+- Config, sessions, logs and caches all live in one folder, `~/.merakcode` (on Windows `~` is `C:\Users\<you>`; the `MERAKCODE_HOME` environment variable moves it). Delete it if you no longer need it.
+
+## Quick start
+
+Open the desktop app and click "Open folder" to pick your project.
+
+The first time, connect a model provider: on the onboarding screen, pick a provider and enter its API key (change it later under Settings → Models & providers). The built-in catalog is OpenAI, Anthropic, Google, Alibaba Cloud Model Studio, Zhipu AI, DeepSeek, Moonshot AI and OpenRouter. Any other service is an OpenAI-compatible provider in your config, with its URL, model ids and API key.
+
+Then just say what you want:
+
+```text
+Add unit tests for formatDate in utils/date.ts
+```
+
+Handy actions (`⌘` on macOS, `Ctrl` on Windows and Linux):
+
+| Action                | What it does                                                                  |
+| --------------------- | ----------------------------------------------------------------------------- |
+| `⌘/Ctrl+K`            | Command palette: search conversation titles, conversation content or commands |
+| `⌘/Ctrl+N`            | New conversation                                                              |
+| `⌘/Ctrl+,`            | Open settings                                                                 |
+| `⌘/Ctrl+J`            | Open or close the terminal                                                    |
+| `⌘/Ctrl+B`            | Show or hide the side panel                                                   |
+| `Shift+Tab`           | Switch permission mode                                                        |
+| Type `/` in the input | Pick a slash command, such as `/compact` to shrink a long conversation        |
+| Type `@` in the input | Reference a file in the project                                               |
+
+## Commands
+
+The command-line version runs in a terminal. If you have not connected a model provider in the desktop app, run `merak provider login` first. Then run a task in your project folder and get the result printed:
+
+```sh
+cd your-project
+merak run "Explain how src/index.ts starts up"
+```
+
+| Command                       | What it does                                                                      |
+| ----------------------------- | --------------------------------------------------------------------------------- |
+| `merak run "<task>"`          | Run one task and print the result                                                 |
+| `merak provider login`        | Connect a model provider; `list` shows the connected ones, `logout` removes one   |
+| `merak serve --port 4096`     | Start only the engine, for the SDK or other programs                              |
+| `merak upgrade` (or `update`) | Upgrade. `--check` only looks for a new version, `--yes` skips the question       |
+| `merak models`                | List the models you can use                                                       |
+| `merak mcp list`              | Show MCP server status                                                            |
+| `merak sandbox status`        | Is the sandbox on? `setup` turns it on, `reset` removes it                        |
+| `merak doctor`                | Check the install, config, models and sandbox, and say what is wrong              |
+| `merak logs`                  | Where the logs are and recent runs; `--tail` follows the newest log               |
+| `merak bug-report`            | Zip the checks, config and logs for an issue; keys and conversations are left out |
+| `merak acp`                   | Run as an [ACP](https://agentclientprotocol.com) agent for editors such as Zed    |
+
+Add `--help` to any command for the full details.
+
+### In your editor (ACP)
+
+Editors that speak [ACP](https://agentclientprotocol.com) can use MerakCode as their agent. For Zed, add this to `~/.config/zed/settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "MerakCode": { "command": "merak", "args": ["acp"] }
+  }
+}
+```
+
+## Permissions and the sandbox
+
+MerakCode edits files and runs commands on your computer, so every action goes through the permission mode first: do it, ask you, or refuse.
+
+| Mode          | Good for                              | What happens                                                                                                                                                    |
+| ------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Read-only     | Designs and plans                     | Only reads files and runs read-only commands (such as `git status` or `ls`). No edits, no other commands                                                        |
+| Ask (default) | Everyday work                         | Reads files and edits inside the workspace right away; asks before running commands, editing outside the workspace, reading sensitive files or going online     |
+| Auto          | Large projects, when you trust the AI | Does most things right away; still asks before risky commands (such as `git push` or `sudo`), edits outside the workspace, sensitive files and unknown websites |
+
+Switch modes next to the input in the desktop app, or press `Shift+Tab`. When it asks, you can allow once, allow for this session, always allow (saved to the project config) or deny. By default, commands such as `rm -rf /` or formatting a disk never run, in any mode.
+
+Commands the agent runs also go into an **OS sandbox**: they can only write the workspace, temp folders and package manager caches; they cannot read key folders such as `~/.ssh` or `~/.aws`; they cannot change `.git/hooks` or `.git/config`; and network traffic goes through a local proxy that asks you about sites it has not seen. The sandbox is our own code on top of what each OS provides:
+
+| System  | Built on                                                      | What you need to do                                                                                                                                |
+| ------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Windows | A separate low-rights account, NTFS permissions, the firewall | Click "Set up" under Settings → Permissions & security in the desktop app (or run `merak sandbox setup` once) and approve one administrator prompt |
+| Linux   | Landlock (kernel 5.13 or newer)                               | Nothing. Network rules need kernel 6.7 or newer                                                                                                    |
+| macOS   | The built-in Seatbelt (sandbox-exec)                          | Nothing                                                                                                                                            |
+
+While the sandbox is not ready (for example before setup on Windows), commands that may change things ask first, even in auto mode. For what the sandbox does and does not protect against, see [SECURITY.md](SECURITY.md).
+
+## Configuration
+
+| Location                                               | Purpose                                                        |
+| ------------------------------------------------------ | -------------------------------------------------------------- |
+| `~/.merakcode/merakcode.json`                          | Global config (model, language, permission rules...)           |
+| `<project>/.merakcode/merakcode.json`                  | Project config, overrides the global one                       |
+| `<project>/AGENTS.md`                                  | Notes about your project for MerakCode (`CLAUDE.md` works too) |
+| `<project>/.merakcode/agents/`, `skills/`, `commands/` | Custom agents, skills and slash commands                       |
+
+Config files can be plain JSON or JSONC with comments. Add `"$schema"` at the top and your editor will autocomplete and check it:
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/TongTong313/merakcode/main/schema/config.json",
+  "model": "anthropic/claude-sonnet-4-5",
+  "locale": "en-US",
+  "permission": {
+    "bash": { "git status": "allow", "rm -rf *": "deny" },
+  },
+  "sandbox": { "mode": "preferred" },
+}
+```
+
+To switch to English: in the desktop app, use Settings → General → Language; for the command line, set `"locale": "en-US"` in the config or the environment variable `MERAKCODE_LOCALE=en-US`.
+
+## SDK
+
+To use MerakCode from your own program, use the TypeScript SDK:
+
+```sh
+npm install @merakcode/sdk
+```
+
+```ts
+import { createMerakCode } from "@merakcode/sdk"
+
+const merak = await createMerakCode({ cwd: process.cwd() })
+const session = await merak.session()
+for await (const event of session.run("What does this project do?")) {
+  if (event.type === "text") process.stdout.write(event.delta)
+}
+await merak.close()
+```
+
+See the [SDK guide](docs/sdk/README.en.md) for everything else.
+
+## Develop from source
+
+You need Node.js 26.12 or newer and pnpm 12.
+
+```sh
+git clone https://github.com/TongTong313/merakcode.git
+cd merakcode
+pnpm install
+pnpm hooks:install          # check formatting before each commit
+```
+
+### Run from source
+
+| To                         | Run                                                                              |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| Work on the desktop app    | `pnpm --dir apps/desktop/main dev`                                               |
+| Run a command-line command | `pnpm dev run "Explain this project"`                                            |
+| Start only the engine      | `pnpm dev serve --port 4096`                                                     |
+| Debug the engine           | `node --inspect --import ./script/node/register.mjs apps/cli/src/index.ts serve` |
+| Print detailed logs        | `pnpm dev serve --print-logs --log-level DEBUG`                                  |
+
+**Note**: desktop development reloads the UI as you save and restarts the main process and the engine when their code changes, which makes debugging much easier.
+
+`pnpm dev` runs the source directly; there is nothing to build first. Change the code and run it again.
+
+### Tests and checks
+
+```sh
+pnpm check                              # formatting, types, dependency boundaries, generated files... run before you commit
+cd packages/engine && pnpm test         # each package runs its own tests
+cd apps/cli && pnpm test test/cli/doctor-command.test.ts   # a single file
+```
+
+### Packaging
+
+```sh
+pnpm --dir apps/cli build --single      # CLI release bundle for this machine, in apps/cli/dist/
+pnpm --dir apps/desktop/main package    # desktop installer for this machine, in apps/desktop/main/release/
+```
+
+The CLI ends up at `apps/cli/dist/merakcode-<version>-<platform>/bin/merak` (`merak.cmd` on Windows). Packaging downloads Node and Electron; if that is slow, set `MERAKCODE_NODE_MIRROR` and `ELECTRON_MIRROR` to a closer mirror.
+
+### Generated files
+
+| If you changed     | Run                                                     |
+| ------------------ | ------------------------------------------------------- |
+| A server route     | `pnpm generate:sdk`, then `pnpm generate:sdk-reference` |
+| A config option    | `pnpm generate:schema`                                  |
+| An error code      | `pnpm generate:errors`                                  |
+| The SDK public API | `pnpm check:api --write`                                |
+
+### Point the SDK at the engine source
+
+```ts
+const merak = await createMerakCode({
+  executablePath: [process.execPath, "--import", "<repo>/script/node/register.mjs", "<repo>/apps/cli/src/index.ts"],
+})
+```
+
+### Layout
+
+```text
+apps/cli              the merak command; merak serve is the engine, and the desktop app ships the same one
+apps/desktop/main     desktop app main process (Electron)
+apps/desktop/renderer desktop app UI (SolidJS)
+packages/engine       the engine: sessions, models, tools, permissions, HTTP server
+packages/sandbox      the OS sandbox (Windows / Linux / macOS)
+packages/sdk/js       TypeScript SDK
+packages/util, log    shared helpers and logging
+packages/client-core  approval options for the desktop app
+```
+
+Neither the desktop app nor the command-line commands import engine code. They start a `merak serve` process through the SDK and talk to it over HTTP and an event stream. `pnpm check` enforces this. See [CONTRIBUTING.md](CONTRIBUTING.md) for the rest of the conventions.
+
+## When something goes wrong
+
+1. If the error has a code (such as `[MRK-2002]`), look it up in the [error code list](docs/errors.md).
+2. Run `merak doctor`; it tells you which part is broken.
+3. Still stuck? Run `merak bug-report` and attach the zip to an [issue](https://github.com/TongTong313/merakcode/issues/new/choose).
+4. To read the logs yourself: `merak logs` shows where they are, `merak logs --tail` follows the newest one.
+
+## Security
+
+Please do not report security problems in public issues. See [SECURITY.md](SECURITY.md) for how to report them privately.
+
+## Contributing
+
+Issues and pull requests are welcome; let's make MerakCode better together. See [CONTRIBUTING.md](CONTRIBUTING.md) for the guidelines.
+
+## License
+
+[MIT](LICENSE)
+
+## Thanks
+
+Parts of this project are based on code from [opencode](https://github.com/anomalyco/opencode), and we thank them for it. Their license notices are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,67 @@
+# Third-party notices
+
+MerakCode contains code taken from or based on the open-source projects below. Their licenses ask us to keep
+their copyright notices, so they are reproduced here in full.
+
+Release packages also contain `THIRD_PARTY_LICENSES.txt`, which lists every npm package bundled into that
+release together with its license text.
+
+## opencode
+
+- Project: https://github.com/anomalyco/opencode
+- Used in: the engine (sessions, tools, providers, server)
+- License: MIT
+
+```
+MIT License
+
+Copyright (c) 2025 opencode
+
+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.
+```
+
+## pi-mono
+
+- Project: https://github.com/badlogic/pi-mono
+- Used in: the patterns that detect "context window exceeded" errors in `packages/engine/src/provider/error.ts`
+- License: MIT
+
+```
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+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/bin/cli-name.cjs

@@ -0,0 +1,24 @@
+/**
+ * Command name and npm package names. Lives in bin/ because the npm launcher requires it at startup.
+ */
+
+const commandName = "merak"
+
+/** npm package id: the main package and the platform package prefix */
+const packageName = "merakcode"
+
+function binMap() {
+  return { [commandName]: `./bin/${commandName}` }
+}
+
+/** Platform package: merakcode-<os>-<arch>. Windows is spelled "windows"; npm reserves "win32" for its os field. */
+function platformPackage(platform, arch) {
+  return `${packageName}-${platform === "win32" ? "windows" : platform}-${arch}`
+}
+
+module.exports = {
+  commandName,
+  packageName,
+  binMap,
+  platformPackage,
+}

package/bin/crash-evidence.cjs

@@ -0,0 +1,98 @@
+// Deliberately standalone: copied beside the npm launcher, and bundled into desktop.
+const fs = require("node:fs")
+const path = require("node:path")
+const os = require("node:os")
+
+function safe(value) {
+  return (
+    String(value)
+      .replace(/[^a-zA-Z0-9_-]/g, "-")
+      .slice(0, 80) || "unknown"
+  )
+}
+
+function root() {
+  if (process.env.MERAKCODE_LOG_ROOT) return process.env.MERAKCODE_LOG_ROOT.replaceAll("\0", "")
+  return path.join(process.env.MERAKCODE_HOME?.replaceAll("\0", "") || path.join(os.homedir(), ".merakcode"), "logs")
+}
+
+// Only extracted, bounded identifiers reach disk. Never persist arbitrary stderr, argv, URLs or report payloads.
+function nativeEvidence(text) {
+  // Node/V8 fatal errors: heap exhaustion, failed V8 checks, and the native stack trace printed with them
+  const runtime = /FATAL ERROR:|# Fatal error in|Native stack trace/.test(text)
+  const native = /segmentation fault|access violation/i.test(text)
+  return {
+    runtime_crash_signature: runtime,
+    native_fault_signature: native,
+    runtime_version: text.match(/Node\.js v(\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)/)?.[1],
+    fault_address: text.match(/(?:fault at address|access violation at)\s+(0x[0-9a-f]+)/i)?.[1],
+    modules_observed:
+      runtime || native ? [...new Set(text.match(/[A-Za-z0-9_.-]{1,120}\.(?:dll|node)\b/gi) || [])].slice(0, 30) : [],
+  }
+}
+
+class CrashEvidence {
+  constructor(options) {
+    const dir = path.join(options.root || root(), ".state", "crash-evidence")
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+    this.file = path.join(dir, `${safe(options.component)}-${safe(options.runId)}.json`)
+    this.tail = ""
+    this.closed = false
+    this.data = {
+      schema: "merakcode.crash-evidence.v3",
+      owner_pid: process.pid,
+      component: safe(options.component),
+      run_id: safe(options.runId),
+      started_at: new Date().toISOString(),
+      evidence: nativeEvidence(""),
+    }
+    this.save()
+  }
+
+  save() {
+    fs.writeFileSync(this.file, JSON.stringify(this.data), { mode: 0o600 })
+  }
+
+  write(chunk) {
+    if (this.closed) return 0
+    try {
+      // Process bounded windows even if a caller hands us a very large chunk.
+      const value = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8")
+      for (let offset = 0; offset < value.length; offset += 8192) {
+        this.tail = (this.tail + value.slice(offset, offset + 8192)).slice(-32768)
+        const next = nativeEvidence(this.tail)
+        const previous = this.data.evidence
+        this.data.evidence = {
+          ...previous,
+          runtime_crash_signature: previous.runtime_crash_signature || next.runtime_crash_signature,
+          native_fault_signature: previous.native_fault_signature || next.native_fault_signature,
+          runtime_version: next.runtime_version || previous.runtime_version,
+          fault_address: next.fault_address || previous.fault_address,
+          modules_observed: [...new Set([...previous.modules_observed, ...next.modules_observed])].slice(0, 30),
+        }
+      }
+      if (this.data.evidence.runtime_crash_signature || this.data.evidence.native_fault_signature) this.save()
+      return value.length
+    } catch {
+      return 0
+    }
+  }
+
+  close(options = {}) {
+    if (this.closed) return
+    this.closed = true
+    this.tail = ""
+    try {
+      if (!options.keep) {
+        fs.rmSync(this.file, { force: true })
+        return
+      }
+      this.data.owner_pid = 0
+      this.data.exit_code = options.code ?? null
+      this.data.signal = options.signal ?? null
+      this.save()
+    } catch {}
+  }
+}
+
+module.exports = { CrashEvidence, nativeEvidence }

package/bin/merak

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+// npm entry point. npm installs only the platform package for this machine (merakcode-<os>-<arch>, see
+// optionalDependencies); find it and run its lib/index.js with its bundled Node.
+// MERAKCODE_BIN_PATH overrides the executable (for debugging).
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+const crypto = require("crypto")
+const { platformPackage } = require("./cli-name.cjs")
+
+function logRoot(env) {
+  if (env.MERAKCODE_LOG_ROOT) return env.MERAKCODE_LOG_ROOT.replaceAll("\0", "")
+  return path.join(env.MERAKCODE_HOME?.replaceAll("\0", "") || path.join(os.homedir(), ".merakcode"), "logs")
+}
+
+function runDirect(command, args, env) {
+  const result = childProcess.spawnSync(command, args, { stdio: "inherit", env })
+  if (result.error) {
+    console.error(result.error.message)
+    process.exit(1)
+  }
+  process.exit(typeof result.status === "number" ? result.status : 0)
+}
+
+function run(command, args, env) {
+  if (process.platform !== "win32") return runDirect(command, args, env)
+  // Windows: keep stderr as crash evidence when the process exits abnormally
+  const runId = crypto.randomUUID()
+  const childEnv = { ...env, MERAKCODE_RUN_ID: runId }
+  const evidence = (() => {
+    try {
+      const helper = fs.existsSync(path.join(__dirname, "crash-evidence.cjs"))
+        ? path.join(__dirname, "crash-evidence.cjs")
+        : path.join(__dirname, "../node_modules/@merakcode/log/src/crash-evidence.cjs")
+      const { CrashEvidence } = require(helper)
+      return new CrashEvidence({ root: logRoot(childEnv), component: "cli", runId })
+    } catch {
+      return undefined
+    }
+  })()
+  // Evidence failure never prevents launching the product.
+  let controlled = false
+  const child = childProcess.spawn(command, args, {
+    stdio: ["inherit", "inherit", "pipe"],
+    env: childEnv,
+  })
+  child.stderr.on("data", (chunk) => {
+    process.stderr.write(chunk)
+    evidence?.write(chunk)
+  })
+  child.on("error", (error) => {
+    evidence?.close()
+    console.error(error.message)
+    process.exit(1)
+  })
+  // close, unlike exit, waits for stderr to drain.
+  child.on("close", (code, signal) => {
+    evidence?.close({ keep: !controlled && (code !== 0 || !!signal), code, signal })
+    process.exit(typeof code === "number" ? code : signal ? 1 : 0)
+  })
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.once(signal, () => {
+      controlled = true
+      child.kill(signal)
+    })
+  }
+}
+
+/** Walks up from this script looking for node_modules/<platform package> */
+function findPlatformPackage(name) {
+  for (let dir = path.dirname(fs.realpathSync(__filename)); ; dir = path.dirname(dir)) {
+    const candidate = path.join(dir, "node_modules", name)
+    if (fs.existsSync(path.join(candidate, "lib", "index.js"))) return candidate
+    if (path.dirname(dir) === dir) return
+  }
+}
+
+const env = { ...process.env }
+const args = process.argv.slice(2)
+
+if (process.env.MERAKCODE_BIN_PATH) {
+  run(process.env.MERAKCODE_BIN_PATH, args, env)
+} else {
+  const name = platformPackage(process.platform, process.arch)
+  const pkg = findPlatformPackage(name)
+  if (!pkg) {
+    console.error(
+      `The package for this platform (${name}) is not installed. npm may have skipped optional dependencies; ` +
+        `reinstall with: npm install -g merakcode\n` +
+        `You can also use the install script or download a release from GitHub.`,
+    )
+    process.exit(1)
+  }
+  const node = path.join(pkg, "node", process.platform === "win32" ? "node.exe" : "bin/node")
+  // node:ffi (used by the engine) prints an ExperimentalWarning on every start
+  run(node, ["--disable-warning=ExperimentalWarning", path.join(pkg, "lib", "index.js"), ...args], env)
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "merakcode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MerakCode command line: run tasks, start the engine, ACP for editors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TongTong313/merakcode.git",
+    "directory": "apps/cli"
+  },
+  "bin": {
+    "merak": "./bin/merak"
+  },
+  "files": [
+    "bin",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "merakcode-darwin-arm64": "0.1.0",
+    "merakcode-darwin-x64": "0.1.0",
+    "merakcode-linux-arm64": "0.1.0",
+    "merakcode-linux-x64": "0.1.0",
+    "merakcode-windows-arm64": "0.1.0",
+    "merakcode-windows-x64": "0.1.0"
+  }
+}