@devmarketplacenpm/devmp 0.1.1-beta.5

package/README.md

@@ -0,0 +1,208 @@
+# devmp — DevMarketplace CLI
+
+A terminal coding agent, like Claude Code / Codex — but the **agent brain runs on
+the DevMarketplace server**, and the **files land on your machine**.
+
+- The server runs the agent over a WebSocket tunnel and streams back what to do.
+  Prompts, model provider keys, and agent logic never leave the backend.
+- The CLI is the "hands": it snapshots your folder, sends the request, and writes
+  the files the server produces to your local disk (sandboxed to the workspace).
+- Login reuses the existing `cli-auth` device flow (browser approval).
+
+No build step, no dependencies — just Node 22+.
+
+## Install
+
+```bash
+npm i -g @devmarketplacenpm/devmp@beta   # testers, current builds
+npm i -g @devmarketplacenpm/devmp        # once a stable release is out
+
+devmp login           # opens the browser approval page
+devmp doctor          # confirms Node, API and session
+```
+
+Node 22 or newer — the tunnel uses the global `WebSocket`. On an older Node the
+CLI says so and stops rather than failing part-way through a turn.
+
+Working on the CLI itself instead? Clone the repo and run `node bin/devmp.js
+<command>`, or `npm link` to put `devmp` on your PATH.
+
+## Project instructions
+
+Drop an `AGENTS.md` in your workspace and the agent follows it on every turn —
+conventions, build steps, the things newcomers get wrong:
+
+```markdown
+# Project conventions
+
+1. Every JavaScript file starts with `// devmp-conventions-v1`.
+2. Use 4-space indentation.
+3. Export with `module.exports` at the bottom of the file.
+```
+
+`DEVMP.md`, `CLAUDE.md` and `.devmp.md` are accepted too, in that order, so a
+repo that already has one does not need a new file. The first 8 KB are sent, and
+the CLI prints which file it picked up. Without one nothing changes.
+
+Don't have one? Run `/init` in the session and the agent reads the project and
+writes it for you. It refuses to overwrite a file you already wrote — use
+`/init update` when you want it revised against the current code.
+
+## Usage
+
+```bash
+# 1. Log in (opens the browser approval page).
+devmp login
+
+# 2. Open a persistent coding session in the current folder.
+devmp
+
+# Then ask questions, plan, implement, and follow up:
+devmp [auto] › explain this repository
+devmp [auto] › add input validation and run the tests
+
+# Or run one script-friendly task without the interactive shell.
+mkdir demo && cd demo
+devmp run "build a tiny express hello world api"
+
+# 3. Extend existing code — the agent reads your files first.
+devmp run "add a /health route that returns { ok: true }"
+
+devmp status             # account + token balance
+devmp doctor             # environment, session and reachability
+devmp --version          # the installed version (works in pipes and CI)
+
+# The prompt can be piped in, for scripts and heredocs:
+echo "add a /health route" | devmp run
+devmp logout
+```
+
+Inside an interactive session:
+
+```text
+/status
+/mode auto|chat|plan|act
+/plan [optional prompt]
+/model [provider] [model]
+/permissions ask|edits|commands|auto
+/diff
+/undo
+/new
+/resume
+/help
+/quit
+```
+
+`chat` and `plan` are read-only. Ctrl-C cancels the active model turn and local
+command, then returns to the prompt instead of exiting the session.
+
+Interactive changes are diff-reviewed by default. An approval can apply once or
+allow ordinary edits for the session; command approval can also allow one exact
+command for the session. Delete and move always ask, even in `auto` permissions.
+Each turn is checkpointed before accepted mutations: `/diff` reviews the latest
+agent change and `/undo` restores it only when the files have not been edited
+again afterward. `/status` includes the current Git branch/change count when the
+workspace is a Git worktree.
+
+## Environments
+
+An environment is a **pair** of URLs — API and approval page — and they are always
+resolved together, so you can never log in against one and approve on the other:
+
+| | API | Approval page |
+|---|---|---|
+| *(default)* | `api-prod.devmarketplace.com` | `beta.devmarketplace.com` |
+| `--env dev` | `api-dev.devmarketplace.com` | `dev.devmarketplace.com` |
+| `--local` (= `--env local`) | `localhost:8000` | `localhost:3000` |
+
+An unrecognised name falls back to production rather than failing, so a typo
+cannot strand you with no usable target. `--api-base-url` / `DEVMP_API_BASE_URL`
+still override a single URL when you need that.
+
+## In the session
+
+The input box is a real editor, not a `readline` prompt.
+
+| | |
+|---|---|
+| `Tab` | Completes a `/command` or an `@path` |
+| `Enter` | Sends — or queues a follow-up while the agent is working |
+| `Ctrl-J` | Newline without sending |
+| `↑` / `↓` | Earlier prompts, including from previous sessions |
+| `Esc` | Clears the input, or the queue |
+| `Ctrl-C` | Cancels the turn; twice on an empty line exits |
+
+Paste freely. A stack trace pasted straight into the box stays **one** prompt —
+its newlines are text, not twelve separate questions billed one at a time. Large
+pastes scroll inside the box instead of pushing the conversation off screen.
+
+`/help` lists the commands. The ones worth knowing first are `/init` (teach the
+agent about this project), `/diff` (what the last turn changed) and `/undo`.
+
+## Settings
+
+Stop retyping flags. A `.devmp.json` next to your code, or
+`~/.devmarketplace/config.json` for every project:
+
+```json
+{
+  "local": true,
+  "provider": "anthropic",
+  "yes": true,
+  "allowCommands": true
+}
+```
+
+A flag typed now always beats a file written earlier, and the environment sits
+between the two. An unreadable file is reported and skipped, never fatal.
+
+## Pointing at files
+
+Name a file with `@` and it goes into the turn immediately, instead of the agent
+spending a round trip deciding it needs to look:
+
+```bash
+devmp run "why does @src/cart.js round twice?"
+```
+
+Only real files in the workspace expand, so `x@example.com`, `@scope/package`
+and `@Injectable` are left exactly as written. Secrets are never attached.
+
+## Updates
+
+The agent runs on the server, so most changes reach you the moment the backend
+deploys — there is nothing to install. Only this client ships through npm, and
+prereleases go to the `beta` dist-tag so `npm i -g @devmarketplacenpm/devmp`
+stays on the last stable build.
+
+The server reports the newest published client and the oldest one it still
+speaks to. A newer version shows a one-line notice at the end of a session; a
+client below the minimum refuses to start and says so, rather than failing
+part-way through a turn.
+
+## How it works
+
+```
+devmp  ─────────► WebSocket /api/platform/v1/agent/ws
+  │                  │
+  │ repeated turns   │ server-side agent + conversation history
+  │◄────────────────►│
+  │ fs/cmd requests
+  ▼
+local workspace + shell
+```
+
+The login session is stored at `~/.devmarketplace/cli-auth.json`. Visible
+conversation history is stored per API + workspace at
+`~/.devmarketplace/cli-conversations.json` so the backend session can be
+rehydrated after a restart. Agent prompts, tool design, provider keys, and hidden
+logic remain on the backend.
+
+File recovery checkpoints are stored locally at
+`~/.devmarketplace/cli-checkpoints.json` with mode `0600`; checkpoint contents
+are not sent to the backend. `/undo` covers regular text-file changes, not side
+effects caused by an approved shell command such as package installs or database
+updates.
+
+`devmp run "..."` remains available. It uses the live WebSocket tunnel by
+default and `--snapshot` for the older HTTP snapshot fallback.

package/bin/devmp.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+"use strict";
+
+const { resolveConfig } = require("../lib/config");
+const { warn: warnUser } = require("../lib/ui");
+const commands = require("../lib/commands");
+const { color, banner, fail } = require("../lib/ui");
+
+// Node 22 is the floor: the tunnel uses the global WebSocket, and `engines` only
+// warns during `npm i -g` — it does not stop the install. Without this check a
+// user on Node 20 gets "WebSocket is not defined" from deep inside a run and
+// concludes the product is broken. `--version`, `--help` and `doctor` still work,
+// because those are what someone reaches for when reporting the problem.
+const NODE_MAJOR = Number(process.versions.node.split(".")[0]);
+if (NODE_MAJOR < 22) {
+  const args = process.argv.slice(2);
+  const diagnostic =
+    args[0] === "doctor" ||
+    args.some((a) => ["--version", "-v", "--help", "-h"].includes(a));
+  if (!diagnostic) {
+    fail(`devmp needs Node 22 or newer — this is ${process.version}.`);
+    console.error("  Upgrade Node, then run `devmp doctor` to confirm.");
+    process.exit(1);
+  }
+}
+
+// Flags that never take a value — so `--yes "prompt"` can't swallow the prompt.
+const BOOLEAN_FLAGS = new Set([
+  "version",
+  "local",
+  "yes",
+  "help",
+  "snapshot",
+  "allow-commands",
+]);
+
+// Parse `command [positional...] [--flag value | --flag=value | --flag | -y]`.
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  let command = null;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-y") {
+      flags.yes = true;
+      continue;
+    }
+    if (arg === "-v") {
+      flags.version = true;
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      if (!command) command = arg;
+      else positional.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    const name = arg.slice(2, eq >= 0 ? eq : undefined);
+    if (eq >= 0) {
+      flags[name] = arg.slice(eq + 1);
+      continue;
+    }
+    const next = argv[i + 1];
+    if (!BOOLEAN_FLAGS.has(name) && next && !next.startsWith("--")) {
+      flags[name] = next;
+      i += 1;
+    } else {
+      flags[name] = true;
+    }
+  }
+  return { command, positional, flags };
+}
+
+function printHelp() {
+  banner();
+  console.log("");
+  console.log("The agent runs on the server; the files land in your folder.");
+  console.log("");
+  console.log(color.bold("Usage"));
+  console.log(
+    "  devmp [options]              Open an interactive coding session"
+  );
+  console.log("  devmp <command> [options]");
+  console.log("");
+  console.log(color.bold("Commands"));
+  console.log(
+    `  ${color.cyan("(no command)")}        Open the interactive workspace`
+  );
+  console.log(
+    `  ${color.cyan("login")}              Connect your DevMarketplace account`
+  );
+  console.log(
+    `  ${color.cyan("signup")}             Create an account and connect it`
+  );
+  console.log(
+    `  ${color.cyan(
+      "status"
+    )}             Show the logged-in account and token balance`
+  );
+  console.log(
+    `  ${color.cyan("doctor")}             Diagnose environment and API connectivity`
+  );
+  console.log(
+    `  ${color.cyan(
+      "run"
+    )} "<prompt>"     Build/change code in the current folder`
+  );
+  console.log(
+    `  ${color.cyan("logout")}             Remove the saved CLI session`
+  );
+  console.log("");
+  console.log(color.bold("Options"));
+  console.log("  --version, -v        Print the installed devmp version");
+  console.log("  --env <name>         production (default), dev, or local");
+  console.log("  --local              Shorthand for --env local");
+  console.log("  --api-base-url <url> Override the API base URL");
+  console.log(
+    "  --cwd <path>         Workspace directory for `run` (default: .)"
+  );
+  console.log(
+    "  --yes, -y            Auto-approve ordinary file edits (delete/move still ask)"
+  );
+  console.log(
+    "  --allow-commands     Let the agent run commands (npm/tests) without asking each time"
+  );
+  console.log(
+    "  --snapshot           Use HTTP snapshot mode instead of the live tunnel"
+  );
+  console.log("  --provider <name>    openai | anthropic | ollama");
+  console.log("  --model <id>         Model id for the provider");
+  console.log("  --max-files <n>      Max files the agent may create");
+  console.log("");
+  console.log(color.bold("Examples"));
+  // Examples are copy-pasted verbatim. `--local` here sent every new installer
+  // to a localhost backend that is not running on their machine.
+  console.log("  devmp login");
+  console.log('  devmp run "build a tiny express hello world api"');
+  console.log('  devmp run "add a /health route" --cwd ./my-app');
+  console.log("  devmp doctor --env dev");
+}
+
+function toInt(value) {
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+async function main() {
+  const { command, positional, flags } = parseArgs(process.argv.slice(2));
+  const config = resolveConfig(flags, {
+    cwd: typeof flags.cwd === "string" ? flags.cwd : undefined,
+    onWarn: (message) => warnUser(message),
+  });
+  // A flag typed now beats a file written earlier; the file only fills the gaps.
+  const d = config.defaults;
+  const pick = (flagValue, fallback) =>
+    flagValue !== undefined ? flagValue : fallback;
+
+  // Before anything else, and before the TTY check the bare `devmp` path runs:
+  // asking a program its version must work everywhere, including in a pipe or a
+  // CI log. It is also the first thing anyone is asked for in a bug report.
+  if (flags.version || command === "version") {
+    console.log(require("../package.json").version);
+    return;
+  }
+
+  if (flags.help || command === "help") {
+    printHelp();
+    return;
+  }
+
+  const provider =
+    typeof flags.provider === "string" ? flags.provider : undefined;
+
+  if (!command) {
+    await commands.shell(config, {
+      cwd: typeof flags.cwd === "string" ? flags.cwd : undefined,
+      provider: pick(provider, d.provider),
+      model: pick(
+        typeof flags.model === "string" ? flags.model : undefined,
+        d.model,
+      ),
+      maxFiles: pick(
+        typeof flags["max-files"] === "string"
+          ? toInt(flags["max-files"])
+          : undefined,
+        d.maxFiles,
+      ),
+      yes: flags.yes === true || d.yes,
+      allowCommands: flags["allow-commands"] === true || d.allowCommands,
+      permissions: d.permissions,
+      mode: d.mode,
+    });
+    return;
+  }
+
+  switch (command) {
+    case "login":
+      await commands.login(config);
+      return;
+    case "signup":
+    case "register":
+      await commands.signup(config);
+      return;
+    case "status":
+      await commands.status(config);
+      return;
+    case "doctor":
+      await commands.doctor(config);
+      return;
+    case "logout":
+      await commands.logout();
+      return;
+    case "run":
+      await commands.run(config, {
+        prompt: positional.join(" ").trim(),
+        cwd: typeof flags.cwd === "string" ? flags.cwd : undefined,
+        provider: pick(provider, d.provider),
+        model: pick(
+          typeof flags.model === "string" ? flags.model : undefined,
+          d.model,
+        ),
+        maxFiles: pick(
+          typeof flags["max-files"] === "string"
+            ? toInt(flags["max-files"])
+            : undefined,
+          d.maxFiles,
+        ),
+        yes: flags.yes === true || d.yes,
+        allowCommands: flags["allow-commands"] === true || d.allowCommands,
+        snapshot: flags.snapshot === true,
+      });
+      return;
+    default:
+      fail(`Unknown command "${command}".`);
+      console.log("");
+      printHelp();
+      process.exitCode = 1;
+  }
+}
+
+main().catch((error) => {
+  fail(error && error.message ? error.message : String(error));
+  process.exitCode = 1;
+});

package/lib/api.js

@@ -0,0 +1,231 @@
+'use strict';
+
+const os = require('os');
+const { saveSession } = require('./session');
+const { agentRunUrl, usageUrl } = require('./routes');
+const { record: recordClientVersion } = require('./version');
+
+// ── low-level HTTP ─────────────────────────────────────────────────────────
+
+async function fetchOrThrow(url, init) {
+  try {
+    return await fetch(url, init);
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    throw new Error(
+      `Could not reach the DevMarketplace API at ${url}. ` +
+        `Is the backend running and the URL correct? (${message})`,
+    );
+  }
+}
+
+async function readJson(response) {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { message: text };
+  }
+}
+
+function errorMessage(data) {
+  if (typeof data.message === 'string') return data.message;
+  if (Array.isArray(data.message)) return data.message.join(', ');
+  if (typeof data.error === 'string') return data.error;
+  return 'Unknown error';
+}
+
+/**
+ * A 404 on the CLI's own routes has exactly one meaning worth saying out loud:
+ * this server has no CLI support deployed. "Cannot POST /api/cli-auth/start" is
+ * accurate and useless — nobody reading it knows what to do next.
+ */
+function describeFailure(url, status, data) {
+  if (status === 404 && /\/(cli-auth|platform\/v1)\b/.test(String(url))) {
+    let origin = String(url);
+    try {
+      origin = new URL(url).origin;
+    } catch {
+      /* keep the raw URL if it will not parse */
+    }
+    return (
+      `This server has no CLI support enabled (${origin} returned 404). ` +
+      'It may need updating, or --api-base-url may be pointing somewhere else.'
+    );
+  }
+  return `${status}: ${errorMessage(data)}`;
+}
+
+async function requestJson(url, init) {
+  const response = await fetchOrThrow(url, init);
+  const data = await readJson(response);
+  if (!response.ok) {
+    const err = new Error(describeFailure(url, response.status, data));
+    err.status = response.status;
+    throw err;
+  }
+  return data;
+}
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// ── device authorization (reuses the backend's /cli-auth flow) ─────────────
+
+async function startDeviceAuth(config) {
+  const data = await requestJson(`${config.apiBaseUrl}/cli-auth/start`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ clientName: `${os.hostname()} devmp CLI` }),
+  });
+  if (!data.deviceCode || !data.userCode) {
+    throw new Error('CLI auth start response was missing deviceCode/userCode.');
+  }
+  return {
+    deviceCode: data.deviceCode,
+    userCode: data.userCode,
+    expiresIn: Number(data.expiresIn) || 600,
+    interval: Number(data.interval) || 3,
+  };
+}
+
+// `signal` lets an interactive host abandon the wait (Ctrl-C) without leaving
+// a polling loop running behind the shell.
+async function pollDeviceAuth(config, start, { signal } = {}) {
+  const deadline = Date.now() + start.expiresIn * 1000;
+  let intervalMs = Math.max(1, start.interval) * 1000;
+
+  while (Date.now() < deadline) {
+    if (signal?.aborted) throw new Error('Login cancelled.');
+    await delay(intervalMs);
+    if (signal?.aborted) throw new Error('Login cancelled.');
+    const response = await fetchOrThrow(`${config.apiBaseUrl}/cli-auth/token`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ deviceCode: start.deviceCode }),
+    });
+    const data = await readJson(response);
+
+    if (response.ok && data.accessToken) {
+      const session = {
+        apiBaseUrl: config.apiBaseUrl,
+        frontendBaseUrl: config.frontendBaseUrl,
+        accessToken: data.accessToken,
+        ...(data.refreshToken ? { refreshToken: data.refreshToken } : {}),
+        ...(data.user ? { user: data.user } : {}),
+        savedAt: new Date().toISOString(),
+      };
+      await saveSession(session);
+      return session;
+    }
+
+    // 428 = authorization pending; keep waiting at the server's cadence.
+    if (response.status === 428 || data.error === 'authorization_pending') {
+      if (data.interval) intervalMs = Math.max(1, data.interval) * 1000;
+      continue;
+    }
+    throw new Error(errorMessage(data) || 'CLI login failed.');
+  }
+  throw new Error('CLI login code expired. Run `devmp login` again.');
+}
+
+async function refreshSession(session) {
+  if (!session.refreshToken) {
+    throw new Error('No refresh token saved. Run `devmp login` again.');
+  }
+  const data = await requestJson(`${session.apiBaseUrl}/user/refresh`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ refreshToken: session.refreshToken }),
+  });
+  const next = {
+    ...session,
+    accessToken: data.accessToken,
+    refreshToken: data.refreshToken || session.refreshToken,
+    savedAt: new Date().toISOString(),
+  };
+  await saveSession(next);
+  return next;
+}
+
+/**
+ * Token allowance + rate-limit headroom from the platform surface.
+ *
+ * Returns the balance shape the status card renders, with `limits` attached
+ * when the server reports them.
+ */
+async function getTokenBalance(session) {
+  const data = await requestJson(usageUrl(session.apiBaseUrl), {
+    headers: { authorization: `Bearer ${session.accessToken}` },
+  });
+  // Every authenticated call is a chance to learn which client the server
+  // expects; the notice and the version gate both read what this records.
+  recordClientVersion(data?.client);
+  const tokens = data?.tokens ?? data;
+  return { ...tokens, limits: data?.rateLimits ?? null };
+}
+
+// ── the agent run: stream NDJSON events from the platform run endpoint ──────
+
+/**
+ * POST the run and yield parsed stream events. Retries once through a token
+ * refresh on 401/403 so an expired access token doesn't interrupt a demo.
+ */
+async function* streamRun(session, body, { refreshed = false } = {}) {
+  const response = await fetchOrThrow(agentRunUrl(session.apiBaseUrl), {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${session.accessToken}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    if ((response.status === 401 || response.status === 403) && !refreshed) {
+      const next = await refreshSession(session);
+      yield* streamRun(next, body, { refreshed: true });
+      return;
+    }
+    const data = await readJson(response);
+    const err = new Error(errorMessage(data));
+    err.status = response.status;
+    throw err;
+  }
+
+  // Parse the NDJSON stream line by line across chunk boundaries.
+  const decoder = new TextDecoder();
+  let buffer = '';
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let nl;
+    while ((nl = buffer.indexOf('\n')) >= 0) {
+      const rawLine = buffer.slice(0, nl);
+      buffer = buffer.slice(nl + 1);
+      const line = rawLine.trim();
+      if (!line) continue;
+      try {
+        yield JSON.parse(line);
+      } catch {
+        // ignore malformed keep-alive/partial lines
+      }
+    }
+  }
+  const rest = buffer.trim();
+  if (rest) {
+    try {
+      yield JSON.parse(rest);
+    } catch {
+      /* ignore trailing noise */
+    }
+  }
+}
+
+module.exports = {
+  requestJson,
+  startDeviceAuth,
+  pollDeviceAuth,
+  refreshSession,
+  getTokenBalance,
+  streamRun,
+};

package/lib/browser.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const { spawn } = require('child_process');
+
+// Best-effort "open this URL in the default browser". Returns false if it could
+// not be launched, so the caller can fall back to printing the URL.
+function openBrowser(url) {
+  const platform = process.platform;
+  const command =
+    platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { openBrowser };