@unbrained/pm-web 2026.5.29 → 2026.6.2-1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 2026.6.2-1 - 2026-06-02
+
+### Added
+
+- Do NOT add the 'services' extension capability to pm-web ([pm-web-vyfp](https://github.com/unbraind/pm-web/blob/main/.agents/pm/decisions/pm-web-vyfp.toon))
+- Deepen pm-web extension command surface \(status/stop/doctor\) + services-capability evaluation ([pm-web-7pxa](https://github.com/unbraind/pm-web/blob/main/.agents/pm/features/pm-web-7pxa.toon))
+- Add /healthz version + unit tests + README docs ([pm-web-edyj](https://github.com/unbraind/pm-web/blob/main/.agents/pm/tasks/pm-web-edyj.toon))
+- Introduce CommandError \(numeric exitCode\) for new handlers ([pm-web-9ycn](https://github.com/unbraind/pm-web/blob/main/.agents/pm/tasks/pm-web-9ycn.toon))
+
+### Other
+
+- Implement 'pm web doctor' command ([pm-web-vyqb](https://github.com/unbraind/pm-web/blob/main/.agents/pm/tasks/pm-web-vyqb.toon))
+- Implement 'pm web stop' command + pidfile-on-detach ([pm-web-odwq](https://github.com/unbraind/pm-web/blob/main/.agents/pm/tasks/pm-web-odwq.toon))
+- Implement 'pm web status' command ([pm-web-8eqs](https://github.com/unbraind/pm-web/blob/main/.agents/pm/tasks/pm-web-8eqs.toon))
+
+## 2026.05.30 - 2026-05-30
+
+### Fixed
+
+- Daily Release fails at changelog:check — version-format mismatch \(padded tag vs npm version\) ([pm-web-ysd5](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-ysd5.toon))
+
+### Other
+
+- Keep pm-web published scoped as @unbrained/pm-web \(not unscoped pm-web\) ([pm-web-1qq4](https://github.com/unbraind/pm-web/blob/main/.agents/pm/decisions/pm-web-1qq4.toon))
+- Production-readiness audit 2026-05-28 ([pm-web-8u17](https://github.com/unbraind/pm-web/blob/main/.agents/pm/tasks/pm-web-8u17.toon))
+
+## 2026.05.29-1 - 2026-05-29
+
+### Added
+
+- Hands-on functional test pass 2026-05-29 \(real data + Postgres\) ([pm-web-ul0n](https://github.com/unbraind/pm-web/blob/main/.agents/pm/features/pm-web-ul0n.toon))
+
+### Fixed
+
+- Catalog npm link points to unpublished unscoped pm-web \(404\) ([pm-web-2wrz](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-2wrz.toon))
+- Server hangs/cryptic error when DATABASE\_URL is unset ([pm-web-onv4](https://github.com/unbraind/pm-web/blob/main/.agents/pm/issues/pm-web-onv4.toon))
+
 ## 2026.05.29 - 2026-05-29
 
 ### Fixed

package/README.md

@@ -52,8 +52,55 @@ The package repository is at **github.com/unbraind/pm-web**.
 
 | Command | Description |
 |---|---|
-| `pm web` | Start the pm-web server |
+| `pm web` | Start the pm-web server (foreground) |
 | `pm web --port 8080` | Start on a custom port |
+| `pm web --detach` | Start the server in the background (tracked via a pidfile) |
+| `pm web status` | Report whether a server is reachable (probes `/healthz`); `--json` supported |
+| `pm web stop` | Stop a server previously started with `--detach`; `--json` supported |
+| `pm web doctor` | Preflight diagnostics (Node, runtime deps, port, pm, workspace); `--json` supported |
+
+#### `pm web status`
+
+Probes `http://localhost:<port>/healthz` and reports `up`/`down`, the responding
+port, and the server version. Never errors when the server is down — it returns a
+structured `down` result. The port is resolved from `--port`, then `PORT`, then
+the default `4000`.
+
+```bash
+pm web status                 # human-readable
+pm web status --port 8080 --json
+```
+
+#### `pm web stop`
+
+Stops a server started with `pm web --detach`. The detached PID is recorded in a
+pidfile (under `PM_WEB_STATE_DIR` if set, otherwise the OS temp dir, keyed by
+port). `pm web stop` reads the pidfile, sends `SIGTERM`, and clears the pidfile.
+If nothing is running it reports `not_running` gracefully and cleans up any stale
+pidfile.
+
+```bash
+pm web stop                   # stops the server on the default port
+pm web stop --port 8080 --json
+```
+
+#### `pm web doctor`
+
+Runs preflight checks before starting the server: Node version (>= 20), whether
+runtime dependencies (express, etc.) are installed, whether the target port is
+free, whether `pm` is on `PATH`, and whether the workspace is initialized.
+Returns an overall `ok` boolean. The `port_available` check is informational (a
+busy port may just be a server you already started) and does not gate `ok`.
+
+```bash
+pm web doctor
+pm web doctor --json
+```
+
+> Note: the `services` extension capability is intentionally **not** declared.
+> The pm SDK's `registerService` only overrides one of eight fixed core services
+> (e.g. `output_format`), which would alter core output for unrelated commands;
+> the server lifecycle is exposed safely through the commands above instead.
 
 ### Environment Variables
 
@@ -64,6 +111,7 @@ The package repository is at **github.com/unbraind/pm-web**.
 | `PM_WEB_SECRET_KEY` | Recommended | At-rest encryption key for saved GitHub PATs. Falls back to `JWT_SECRET`; use at least 32 characters |
 | `PM_WEB_BOOTSTRAP_ADMIN_EMAIL` | Recommended | Email of the user account to auto-promote to admin on schema init. Leave unset to skip auto-promotion (manage admins via the admin UI). |
 | `PORT` | No | Server port (default: 4000) |
+| `PM_WEB_STATE_DIR` | No | Directory for the `--detach` pidfile used by `pm web stop` (default: OS temp dir) |
 | `NODE_ENV` | No | `production` enables caching |
 | `OLLAMA_BASE_URL` / `OLLAMA_HOST` | No | Local Ollama endpoint for semantic pm search |
 | `PM_OLLAMA_MODEL` | No | Embedding model for new projects, default `qwen3-embedding:0.6b` |
@@ -105,3 +153,19 @@ MIT
 ## Release Automation
 
 This package is release-ready for GitHub, npm, and Bun-compatible installs. CI runs type checking, build, production dependency audit, package packing, Bun install verification, and pm-changelog validation. The daily release workflow publishes only when commits exist after the latest release tag and uses pm-changelog to generate CHANGELOG.md and GitHub release notes.
+
+## New data endpoints (kanban board & search)
+
+The pm data API now exposes board and search views, both driven by the
+workspace's live `pm contracts` schema (so they reflect the installed pm CLI +
+extensions):
+
+- `GET /api/projects/:projectId/pm/board` — items grouped into kanban columns by
+  the workspace's runtime statuses (unlisted statuses fall into `(other)`).
+- `GET /api/projects/:projectId/pm/search?q=<text>` — case-insensitive full-text
+  search over id, title, tags and body.
+- `GET /api/projects/:projectId/pm/schema` — runtime types/statuses (existing).
+- `GET /api/projects/:projectId/pm/graph` — dependency graph (existing).
+
+The pure grouping/search helpers live in `src/board.ts` and are unit-tested
+independently of the database.

package/dist/board.js

@@ -0,0 +1,41 @@
+// Pure, dependency-free helpers for the kanban board and search endpoints.
+// Kept in their own module (no db/neo4j imports) so they are unit-testable
+// without booting the server or a database.
+// Group items into board columns keyed by the workspace's actual statuses
+// (from `pm contracts`), so the kanban board reflects whatever statuses the
+// installed pm CLI + extensions define. Items with an unlisted status fall into
+// a trailing "(other)" column so nothing is silently dropped.
+export function boardColumns(items, statuses) {
+    const known = statuses.length > 0 ? statuses : ["open", "in_progress", "blocked", "closed"];
+    const columns = new Map();
+    for (const s of known)
+        columns.set(s, []);
+    const OTHER = "(other)";
+    for (const item of items) {
+        const s = item.status ?? "open";
+        if (columns.has(s))
+            columns.get(s).push(item);
+        else {
+            if (!columns.has(OTHER))
+                columns.set(OTHER, []);
+            columns.get(OTHER).push(item);
+        }
+    }
+    return [...columns.entries()].map(([status, list]) => ({ status, items: list }));
+}
+// Case-insensitive full-text filter over id, title, tags and body.
+export function filterItemsByQuery(items, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return items;
+    return items.filter((item) => {
+        const hay = [
+            item.id,
+            item.title ?? "",
+            (item.tags ?? []).join(" "),
+            item.body ?? "",
+        ].join(" ").toLowerCase();
+        return hay.includes(q);
+    });
+}
+//# sourceMappingURL=board.js.map

package/dist/board.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board.js","sourceRoot":"","sources":["../src/board.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,2EAA2E;AAC3E,4CAA4C;AAU5C,0EAA0E;AAC1E,4EAA4E;AAC5E,gFAAgF;AAChF,8DAA8D;AAC9D,MAAM,UAAU,YAAY,CAC1B,KAAU,EACV,QAAkB;IAElB,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC5F,MAAM,OAAO,GAAG,IAAI,GAAG,EAAe,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,SAAS,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;QAChC,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aAC1C,CAAC;YACJ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAChD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACnF,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,kBAAkB,CAAsB,KAAU,EAAE,KAAa;IAC/E,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrB,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAC3B,MAAM,GAAG,GAAG;YACV,IAAI,CAAC,EAAE;YACP,IAAI,CAAC,KAAK,IAAI,EAAE;YAChB,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;YAC3B,IAAI,CAAC,IAAI,IAAI,EAAE;SAChB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QAC1B,OAAO,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/db.js

@@ -1,15 +1,49 @@
 import pg from "pg";
 const { Pool } = pg;
-export const pool = new Pool({
-    ...(process.env.DATABASE_URL
-        ? { connectionString: process.env.DATABASE_URL }
-        : {
-            host: process.env.POSTGRES_HOST || "127.0.0.1",
+/**
+ * Resolve the PostgreSQL connection config from the environment.
+ *
+ * pm-web requires a PostgreSQL database. Rather than silently falling back to
+ * an opaque default host (which produces a cryptic `getaddrinfo` DNS error
+ * several seconds after start), we validate up front and throw a clear,
+ * actionable error when no database is configured.
+ */
+function resolvePoolConfig() {
+    if (process.env.DATABASE_URL) {
+        return { connectionString: process.env.DATABASE_URL };
+    }
+    // Allow discrete POSTGRES_* vars as an alternative to DATABASE_URL.
+    if (process.env.POSTGRES_HOST && process.env.POSTGRES_DB) {
+        return {
+            host: process.env.POSTGRES_HOST,
             port: parseInt(process.env.POSTGRES_PORT || "5432", 10),
             user: process.env.POSTGRES_USER,
             password: process.env.POSTGRES_PASSWORD,
             database: process.env.POSTGRES_DB,
-        }),
+        };
+    }
+    return {};
+}
+/**
+ * Throw a clear, actionable error when no database is configured.
+ *
+ * pm-web requires a PostgreSQL database. Without this guard, an unset
+ * DATABASE_URL produced a cryptic `getaddrinfo` DNS error several seconds
+ * after start (or a silent hang). Call this before using the pool so the
+ * server fails fast with guidance instead.
+ */
+export function assertDbConfigured() {
+    const configured = Boolean(process.env.DATABASE_URL) ||
+        Boolean(process.env.POSTGRES_HOST && process.env.POSTGRES_DB);
+    if (configured)
+        return;
+    throw new Error("DATABASE_URL is not set. pm-web requires a PostgreSQL database.\n" +
+        "  Set it before starting, e.g.:\n" +
+        "    export DATABASE_URL=postgres://user:pass@localhost:5432/pmweb\n" +
+        "  (or provide POSTGRES_HOST + POSTGRES_DB and related POSTGRES_* vars).");
+}
+export const pool = new Pool({
+    ...resolvePoolConfig(),
     max: 10,
     idleTimeoutMillis: 30_000,
     connectionTimeoutMillis: 5_000,

package/dist/db.js.map

@@ -1 +1 @@
-{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAEpB,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC;IAC3B,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY;QAC1B,CAAC,CAAC,EAAE,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE;QAChD,CAAC,CAAC;YACE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,WAAW;YAC9C,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,MAAM,EAAE,EAAE,CAAC;YACvD,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa;YAC/B,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;YACvC,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;SAClC,CAAC;IACN,GAAG,EAAE,EAAE;IACP,iBAAiB,EAAE,MAAM;IACzB,uBAAuB,EAAE,KAAK;CAC/B,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,EAAE,CAAC;KACzE,IAAI,EAAE;KACN,WAAW,EAAE,CAAC;AAEjB,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDhB,CAAC,CAAC;IAEH,0CAA0C;IAC1C,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;GAMhB,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,KAAK,CACd;;;;;;MAME,CACH,CAAC;IAEF,MAAM,IAAI,CAAC,KAAK,CACd,yFAAyF,CAC1F,CAAC;IAEF,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;GAUhB,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,KAAK,CACd,6FAA6F,CAC9F,CAAC;IAEF,IAAI,mBAAmB,EAAE,CAAC;QACxB,MAAM,IAAI,CAAC,KAAK,CACd,wFAAwF,EACxF,CAAC,mBAAmB,CAAC,CACtB,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAEpB;;;;;;;GAOG;AACH,SAAS,iBAAiB;IACxB,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;QAC7B,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;IACxD,CAAC;IAED,oEAAoE;IACpE,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACzD,OAAO;YACL,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa;YAC/B,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,MAAM,EAAE,EAAE,CAAC;YACvD,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa;YAC/B,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;YACvC,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;SAClC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,UAAU,GACd,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;QACjC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAChE,IAAI,UAAU;QAAE,OAAO;IACvB,MAAM,IAAI,KAAK,CACb,mEAAmE;QACjE,mCAAmC;QACnC,qEAAqE;QACrE,yEAAyE,CAC5E,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC;IAC3B,GAAG,iBAAiB,EAAE;IACtB,GAAG,EAAE,EAAE;IACP,iBAAiB,EAAE,MAAM;IACzB,uBAAuB,EAAE,KAAK;CAC/B,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,EAAE,CAAC;KACzE,IAAI,EAAE;KACN,WAAW,EAAE,CAAC;AAEjB,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDhB,CAAC,CAAC;IAEH,0CAA0C;IAC1C,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;GAMhB,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,KAAK,CACd;;;;;;MAME,CACH,CAAC;IAEF,MAAM,IAAI,CAAC,KAAK,CACd,yFAAyF,CAC1F,CAAC;IAEF,MAAM,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;GAUhB,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,KAAK,CACd,6FAA6F,CAC9F,CAAC;IAEF,IAAI,mBAAmB,EAAE,CAAC;QACxB,MAAM,IAAI,CAAC,KAAK,CACd,wFAAwF,EACxF,CAAC,mBAAmB,CAAC,CACtB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/index.js

@@ -2,16 +2,81 @@
 // This file registers the web server as a pm extension command.
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 // Inline defineExtension helper (avoids runtime dependency on @unbrained/pm-cli/sdk)
 function defineExtension(m) { return m; }
+// ---------------------------------------------------------------------------
+// Error contract
+// CommandError carries a numeric exitCode so the pm runtime surfaces a clean
+// failure instead of double-invoking the handler on a plain thrown Error.
+//   1 = generic, 2 = usage, 3 = not-found
+// ---------------------------------------------------------------------------
+class CommandError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = "CommandError";
+        this.exitCode = exitCode;
+    }
+}
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, "..");
 let serverProcess = null;
-function ensureRuntimeDependencies() {
+const DEFAULT_PORT = "4000";
+// ---------------------------------------------------------------------------
+// Pure helpers (unit-tested in test/)
+// ---------------------------------------------------------------------------
+/** Resolve the port from flag → PORT env → default 4000. */
+export function resolvePort(options, env = process.env) {
+    const flag = options["port"];
+    if (flag !== undefined && flag !== null && String(flag).length > 0) {
+        return String(flag);
+    }
+    if (env["PORT"] && String(env["PORT"]).length > 0) {
+        return String(env["PORT"]);
+    }
+    return DEFAULT_PORT;
+}
+/**
+ * Resolve the pidfile path used to track a detached server.
+ * Uses PM_WEB_STATE_DIR when set, else the OS temp dir, keyed by port so
+ * multiple detached servers don't clobber each other's pidfile.
+ */
+export function pidfilePath(port, env = process.env, tmpDir = os.tmpdir()) {
+    const baseDir = env["PM_WEB_STATE_DIR"] && String(env["PM_WEB_STATE_DIR"]).length > 0
+        ? String(env["PM_WEB_STATE_DIR"])
+        : tmpDir;
+    return path.join(baseDir, `pm-web-${String(port)}.pid`);
+}
+/** Shape a /healthz probe outcome into a stable status result object. */
+export function shapeStatusResult(input) {
+    const portNum = Number(input.port);
+    const body = (input.body ?? null);
+    const version = body && typeof body["version"] === "string" ? body["version"] : null;
+    const result = {
+        status: input.reachable ? "up" : "down",
+        port: portNum,
+        reachable: input.reachable,
+        url: `http://localhost:${portNum}/healthz`,
+        version,
+        healthz: input.body ?? null,
+    };
+    if (input.error)
+        result.error = input.error;
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Runtime helpers
+// ---------------------------------------------------------------------------
+function runtimeDependenciesInstalled() {
     const expressPackage = path.join(packageRoot, "node_modules", "express", "package.json");
-    if (fs.existsSync(expressPackage))
+    return fs.existsSync(expressPackage);
+}
+function ensureRuntimeDependencies() {
+    if (runtimeDependenciesInstalled())
         return;
     console.error("Installing pm-web runtime dependencies...");
     const install = spawnSync("npm", ["install", "--omit=dev"], {
@@ -22,7 +87,77 @@ function ensureRuntimeDependencies() {
     if (install.error)
         throw install.error;
     if (install.status !== 0) {
-        throw new Error(`npm install --omit=dev failed with exit code ${install.status ?? "unknown"}`);
+        throw new CommandError(`npm install --omit=dev failed with exit code ${install.status ?? "unknown"}`);
+    }
+}
+/** HTTP GET /healthz with a short timeout. Never throws; returns a probe result. */
+async function probeHealthz(port) {
+    const url = `http://localhost:${port}/healthz`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1500);
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        let body = null;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = null;
+        }
+        return { reachable: res.ok, body };
+    }
+    catch (err) {
+        return { reachable: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Check whether a TCP port is free to bind locally. Never throws. */
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const tester = net
+            .createServer()
+            .once("error", () => resolve(false))
+            .once("listening", () => {
+            tester.close(() => resolve(true));
+        })
+            .listen(port, "127.0.0.1");
+    });
+}
+function pmOnPath() {
+    const probe = spawnSync("pm", ["--version"], { stdio: "ignore" });
+    return !probe.error && probe.status === 0;
+}
+function workspaceInitialized(pmRoot) {
+    if (!pmRoot)
+        return false;
+    // A pm workspace has a settings.json plus item-type directories under the
+    // pm root (e.g. tasks/, features/). Match on the settings file or a known
+    // item-type dir so detection is robust across pm versions.
+    if (!fs.existsSync(pmRoot))
+        return false;
+    return (fs.existsSync(path.join(pmRoot, "settings.json")) ||
+        fs.existsSync(path.join(pmRoot, "schema")) ||
+        fs.existsSync(path.join(pmRoot, "tasks")));
+}
+function readPackageVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH = no such process; EPERM = exists but not ours (treat as alive)
+        return err.code === "EPERM";
     }
 }
 export default defineExtension({
@@ -30,7 +165,7 @@ export default defineExtension({
     version: "1.0.0",
     activate(api) {
         // -----------------------------------------------------------------------
-        // Command: pm web [--port <port>]
+        // Command: pm web [--port <port>] [--detach]
         // -----------------------------------------------------------------------
         api.registerCommand({
             name: "web",
@@ -39,13 +174,14 @@ export default defineExtension({
             examples: [
                 "pm web",
                 "pm web --port 8080",
+                "pm web --detach",
             ],
             flags: [
                 { long: "--port", value_name: "port", description: "Port to listen on (default: 4000 or PORT env var)" },
                 { long: "--detach", description: "Run the server in the background" },
             ],
             async run(ctx) {
-                const port = ctx.options["port"] ?? process.env["PORT"] ?? "4000";
+                const port = resolvePort(ctx.options);
                 const detach = Boolean(ctx.options["detach"]);
                 const serverPath = path.resolve(__dirname, "server.js");
                 ensureRuntimeDependencies();
@@ -60,6 +196,15 @@ export default defineExtension({
                         stdio: "ignore",
                     });
                     serverProcess.unref();
+                    // Track the detached PID so `pm web stop` can terminate it.
+                    if (serverProcess.pid) {
+                        try {
+                            fs.writeFileSync(pidfilePath(port), String(serverProcess.pid), "utf8");
+                        }
+                        catch (err) {
+                            console.error(`Warning: could not write pidfile: ${err instanceof Error ? err.message : String(err)}`);
+                        }
+                    }
                     console.error(`pm-web started on port ${port} (PID ${serverProcess.pid})`);
                     return { status: "started", port: Number(port), pid: serverProcess.pid };
                 }
@@ -77,12 +222,212 @@ export default defineExtension({
                             resolve();
                             return;
                         }
-                        reject(new Error(`pm-web exited with code ${code ?? `signal ${signal}`}`));
+                        reject(new CommandError(`pm-web exited with code ${code ?? `signal ${signal}`}`));
                     });
                 });
                 return { status: "stopped", port: Number(port) };
             },
         });
+        // -----------------------------------------------------------------------
+        // Command: pm web status [--port <port>] [--json]
+        // -----------------------------------------------------------------------
+        api.registerCommand({
+            name: "web status",
+            description: "Report whether a pm-web server is reachable on the configured port.",
+            intent: "check pm-web server status",
+            examples: ["pm web status", "pm web status --port 8080 --json"],
+            flags: [
+                { long: "--port", value_name: "port", description: "Port to probe (default: 4000 or PORT env var)" },
+                { long: "--json", description: "Emit machine-readable JSON" },
+            ],
+            async run(ctx) {
+                const port = resolvePort(ctx.options);
+                const json = Boolean(ctx.options["json"]);
+                const probe = await probeHealthz(port);
+                const result = shapeStatusResult({
+                    port,
+                    reachable: probe.reachable,
+                    body: probe.body,
+                    error: probe.error,
+                });
+                if (json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else if (result.status === "up") {
+                    console.log(`pm-web is UP on port ${result.port}` +
+                        (result.version ? ` (version ${result.version})` : ""));
+                }
+                else {
+                    console.log(`pm-web is DOWN on port ${result.port}`);
+                }
+                return result;
+            },
+        });
+        // -----------------------------------------------------------------------
+        // Command: pm web stop [--port <port>] [--json]
+        // -----------------------------------------------------------------------
+        api.registerCommand({
+            name: "web stop",
+            description: "Stop a pm-web server previously started with --detach.",
+            intent: "stop a detached pm-web server",
+            examples: ["pm web stop", "pm web stop --port 8080"],
+            flags: [
+                { long: "--port", value_name: "port", description: "Port of the detached server (default: 4000 or PORT env var)" },
+                { long: "--json", description: "Emit machine-readable JSON" },
+            ],
+            async run(ctx) {
+                const port = resolvePort(ctx.options);
+                const json = Boolean(ctx.options["json"]);
+                const pidfile = pidfilePath(port);
+                const emit = (result) => {
+                    if (json) {
+                        console.log(JSON.stringify(result, null, 2));
+                    }
+                    else {
+                        console.log(String(result["message"]));
+                    }
+                    return result;
+                };
+                // Prefer the in-process handle if we started it this session.
+                let pid = null;
+                if (serverProcess?.pid) {
+                    pid = serverProcess.pid;
+                }
+                else if (fs.existsSync(pidfile)) {
+                    const raw = fs.readFileSync(pidfile, "utf8").trim();
+                    const parsed = Number.parseInt(raw, 10);
+                    if (Number.isInteger(parsed) && parsed > 0)
+                        pid = parsed;
+                }
+                if (pid === null) {
+                    return emit({
+                        status: "not_running",
+                        port: Number(port),
+                        message: `pm-web is not running (no pidfile for port ${port}).`,
+                    });
+                }
+                if (!processAlive(pid)) {
+                    // Stale pidfile — clean it up and report gracefully.
+                    if (fs.existsSync(pidfile))
+                        fs.rmSync(pidfile, { force: true });
+                    return emit({
+                        status: "not_running",
+                        port: Number(port),
+                        pid,
+                        message: `pm-web process (PID ${pid}) is not running; cleared stale pidfile.`,
+                    });
+                }
+                try {
+                    process.kill(pid, "SIGTERM");
+                }
+                catch (err) {
+                    throw new CommandError(`Failed to stop pm-web (PID ${pid}): ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (fs.existsSync(pidfile))
+                    fs.rmSync(pidfile, { force: true });
+                if (serverProcess?.pid === pid)
+                    serverProcess = null;
+                return emit({
+                    status: "stopped",
+                    port: Number(port),
+                    pid,
+                    message: `Stopped pm-web (PID ${pid}) on port ${port}.`,
+                });
+            },
+        });
+        // -----------------------------------------------------------------------
+        // Command: pm web doctor [--port <port>] [--json]
+        // -----------------------------------------------------------------------
+        api.registerCommand({
+            name: "web doctor",
+            description: "Preflight diagnostics for running pm-web (Node, deps, port, pm, workspace).",
+            intent: "diagnose pm-web preflight readiness",
+            examples: ["pm web doctor", "pm web doctor --json"],
+            flags: [
+                { long: "--port", value_name: "port", description: "Port to check availability for (default: 4000 or PORT env var)" },
+                { long: "--json", description: "Emit machine-readable JSON" },
+            ],
+            async run(ctx) {
+                const port = resolvePort(ctx.options);
+                const json = Boolean(ctx.options["json"]);
+                const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+                const depsInstalled = runtimeDependenciesInstalled();
+                const portFree = await isPortFree(Number(port));
+                const pmAvailable = pmOnPath();
+                const wsInit = workspaceInitialized(ctx.pm_root);
+                const checks = [
+                    {
+                        name: "node_version",
+                        ok: nodeMajor >= 20,
+                        detail: `Node ${process.versions.node} (requires >= 20)`,
+                    },
+                    {
+                        name: "runtime_dependencies",
+                        ok: depsInstalled,
+                        detail: depsInstalled
+                            ? "express and runtime deps installed"
+                            : "runtime deps missing (will auto-install on `pm web`)",
+                    },
+                    {
+                        name: "port_available",
+                        ok: portFree,
+                        detail: portFree
+                            ? `port ${port} is free`
+                            : `port ${port} is in use (a server may already be running)`,
+                    },
+                    {
+                        name: "pm_on_path",
+                        ok: pmAvailable,
+                        detail: pmAvailable ? "pm CLI is on PATH" : "pm CLI not found on PATH",
+                    },
+                    {
+                        name: "workspace_initialized",
+                        ok: wsInit,
+                        detail: wsInit
+                            ? `pm workspace found at ${ctx.pm_root}`
+                            : `no pm workspace at ${ctx.pm_root || "(unset)"} — run \`pm init\``,
+                    },
+                ];
+                // port_available is informational (in-use can be a healthy running server),
+                // so it does not gate overall readiness.
+                const ok = checks
+                    .filter((c) => c.name !== "port_available")
+                    .every((c) => c.ok);
+                const result = {
+                    ok,
+                    version: readPackageVersion(),
+                    node: process.versions.node,
+                    port: Number(port),
+                    checks,
+                };
+                if (json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    console.log(`pm-web doctor — overall: ${ok ? "OK" : "ISSUES"}`);
+                    for (const c of checks) {
+                        console.log(`  [${c.ok ? "ok" : "!!"}] ${c.name}: ${c.detail}`);
+                    }
+                }
+                return result;
+            },
+        });
+        // -----------------------------------------------------------------------
+        // services capability — intentionally NOT registered.
+        //
+        // The SDK's `registerService(name, override)` only accepts one of the eight
+        // fixed CORE service names (output_format, error_format, help_format,
+        // lock_acquire, lock_release, history_append, item_store_write,
+        // item_store_delete) and OVERRIDES that core service on every pm command.
+        // There is no API to register a new "pm-web lifecycle" service, and
+        // overriding a core service would alter/replace core output for unrelated
+        // commands. The pm-web server lifecycle is surfaced safely via the
+        // web/status/stop/doctor commands instead. The guarded block below
+        // documents the deliberate no-op; the "services" capability is therefore
+        // NOT declared in manifest.json.
+        if (typeof api.registerService === "function") {
+            // Deliberately register no service overrides — see comment above.
+        }
     },
 });
 //# sourceMappingURL=index.js.map