pi-forge 0.0.0 → 1.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devin Marks and pi-forge contributors
+
+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

@@ -1,7 +1,51 @@
 # pi-forge
 
-Reserved for an in-progress rename of the browser workbench currently
-developed at [Devin-Marks/pi-workbench](https://github.com/Devin-Marks/pi-workbench).
+Browser UI for the [pi coding agent](https://github.com/badlogic/pi-mono) —
+an embedded HTTP server with a React workbench (chat, file browser,
+terminal, git integration, MCP support).
 
-Real releases follow the rename. Until then this `0.0.0` placeholder
-just holds the name on npm.
+## Install
+
+```bash
+# One-shot
+npx pi-forge
+
+# Or install globally
+npm i -g pi-forge
+pi-forge
+```
+
+Open <http://localhost:3000> and pick a workspace folder.
+
+## Configuration
+
+All knobs are environment variables. Sensible defaults — set only what
+you need.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PORT` | `3000` | HTTP listen port |
+| `WORKSPACE_PATH` | `~/.pi-forge/workspace` | Where project code lives |
+| `PI_CONFIG_DIR` | `~/.pi/agent` | Pi SDK config (auth, models, settings) |
+| `FORGE_DATA_DIR` | `~/.pi-forge` | pi-forge state (project list) |
+| `UI_PASSWORD` | (unset) | Enables browser login if set |
+| `API_KEY` | (unset) | Enables `Authorization: Bearer` for programmatic use |
+
+If both `UI_PASSWORD` and `API_KEY` are unset, auth is disabled. For
+production, set at minimum `API_KEY`.
+
+## Programmatic API
+
+REST + Server-Sent Events under `/api/v1/`. Interactive docs at
+`/api/docs`. See the [project README](https://github.com/Devin-Marks/pi-forge#readme)
+for the full surface and example curl flows.
+
+## Versioning
+
+This package version (`1.1.5`) tracks the [GitHub release](https://github.com/Devin-Marks/pi-forge/releases)
+of the same name. Docker images and the npm package are published in
+lockstep on each `v*` tag.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/fix-pty-perms.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * pi-forge postinstall: ensure node-pty's prebuilt `spawn-helper`
+ * binaries are executable.
+ *
+ * The bug: `node-pty` ships prebuilt native binaries at
+ *   `node_modules/node-pty/prebuilds/<platform>/spawn-helper`
+ * The tarball's mode bits don't always survive npm's tar extract —
+ * fresh installs frequently land `spawn-helper` at `0644` with no
+ * exec bit. When pi-forge later spawns a PTY, `posix_spawnp` fails
+ * with the unhelpful "spawn EACCES" or "posix_spawnp failed."
+ *
+ * `node-pty`'s own postinstall script handles the from-source-built
+ * path (`build/Release/`) but NOT the prebuilt path (`prebuilds/`),
+ * so the bug ships on every npm-published install of pi-forge.
+ *
+ * Why this script lives in pi-forge and not upstream: the upstream
+ * fix would need to land in node-pty itself. Until then, every
+ * package that depends on node-pty needs its own postinstall to
+ * cover the gap. We pay one trivial chmod per install in exchange
+ * for the integrated terminal actually working.
+ *
+ * Idempotent: chmod +x on something already +x is a no-op.
+ * Failure-tolerant: missing node-pty (e.g. `--omit=optional`),
+ * missing prebuilds dir (unusual platform), or chmod failure
+ * (read-only mount, EPERM) all warn instead of failing the install.
+ */
+import { chmodSync, existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+let nodePtyDir;
+try {
+  nodePtyDir = dirname(require.resolve("node-pty/package.json"));
+} catch {
+  // node-pty not installed — no-op.
+  process.exit(0);
+}
+
+const prebuildsDir = join(nodePtyDir, "prebuilds");
+if (!existsSync(prebuildsDir)) process.exit(0);
+
+let fixed = 0;
+for (const platform of readdirSync(prebuildsDir)) {
+  const helper = join(prebuildsDir, platform, "spawn-helper");
+  if (!existsSync(helper)) continue;
+  try {
+    const mode = statSync(helper).mode;
+    // 0o111 = any-x bits. If even one is set, assume the file is
+    // already runnable.
+    if ((mode & 0o111) !== 0) continue;
+    chmodSync(helper, mode | 0o755);
+    fixed++;
+  } catch (err) {
+    console.warn(
+      `[pi-forge postinstall] could not chmod ${helper}: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+}
+
+if (fixed > 0) {
+  console.log(
+    `[pi-forge postinstall] fixed exec bit on ${fixed} node-pty spawn-helper binar${
+      fixed === 1 ? "y" : "ies"
+    }`,
+  );
+}

package/bin/pi-forge.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * pi-forge CLI launcher.
+ *
+ * The published npm package layout is:
+ *
+ *   pi-forge/
+ *   ├── bin/pi-forge.mjs       (this file)
+ *   ├── dist/server/           (built Fastify server — copy of packages/server/dist/)
+ *   └── dist/client/           (built Vite SPA — copy of packages/client/dist/)
+ *
+ * The server's default `CLIENT_DIST_PATH` resolves relative to its own
+ * compiled file (`dist/server/config.js` → `../../client/dist`), which
+ * works for the in-repo `npm run build && node dist/index.js` flow and
+ * the Docker image (both share the `packages/server/dist/` +
+ * `packages/client/dist/` layout) but NOT for the flat published
+ * package. We override `CLIENT_DIST_PATH` here so the same server entry
+ * works in all three deployment shapes without touching server code.
+ *
+ * Everything else (workspace path, pi config dir, forge data dir, port,
+ * auth) is read from env vars and uses the server's existing defaults
+ * (`~/.pi-forge/workspace`, `~/.pi/agent`, `~/.pi-forge`, port 3000) —
+ * users who installed via `npm i -g pi-forge` get sensible per-user
+ * paths under their home directory without any setup.
+ */
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(here, "..");
+
+process.env.CLIENT_DIST_PATH ??= resolve(packageRoot, "dist", "client");
+process.env.NODE_ENV ??= "production";
+
+const serverEntry = resolve(packageRoot, "dist", "server", "index.js");
+const { start } = await import(pathToFileURL(serverEntry).href);
+await start();