project-mgr 0.1.7 → 0.2.1

package/ecosystem.config.cjs

@@ -0,0 +1,21 @@
+module.exports = {
+  apps: [
+    {
+      name: "project-mgr-web",
+      cwd: __dirname,
+      script: process.execPath,
+      interpreter: "none",
+      args: [
+        "--env-file-if-exists=.env",
+        "dist/cli.js",
+        "serve",
+        "--host",
+        "127.0.0.1",
+        "--no-open",
+      ],
+      env: {
+        PMGR_DB_PATH: `${process.env.HOME}/.local/share/project-mgr/project-mgr.sqlite`,
+      },
+    },
+  ],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-mgr",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "description": "Local-first append-only project status ledger",
   "type": "module",
   "bin": {

package/skills/project-mgr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-mgr
-description: Manage project status with the local-first project-mgr CLI. Use when an AI agent needs to add an append-only project update, set project descriptions/notes, list or fuzzy-search projects, import status records, query current or historical project state, or export a status ledger.
+description: Manage project status with the local-first project-mgr CLI. Use when an AI agent needs to add an append-only project update, set project descriptions/notes, list or fuzzy-search projects, start the local Web Dashboard, import status records, query current or historical project state, or export a status ledger.
 ---
 
 # project-mgr
@@ -13,6 +13,16 @@ Use `npx --yes --package project-mgr pmgr`. In a source checkout, use `pnpm pmgr
 - For exploratory or test work, set `PMGR_DB_PATH` to a dedicated absolute SQLite path for every command. Do not use `:memory:` when more than one CLI invocation must share data.
 - Query before writing. `add` appends a snapshot; it does not edit the previous one.
 - Set `--source agent` for agent-authored updates. Use `--external-ref` only when a stable idempotency key is available.
+- If the project is not yet in the ledger database, initialize its metadata with `set-project`, backfill 3–5 historical major changes/milestones using `add` (setting appropriate historical `--at` timestamps), and then append the latest status snapshot.
+
+## Metadata vs. status entries
+
+- **Project notes (`--notes`)**: Reserved for persistent, medium-to-long-term project context (e.g., architectural constraints, permanent tech stack choices, long-term goals, or critical environment caveats).
+  - Manage notes via `set-project --project <name> --notes "..."`.
+  - **Do NOT** put transient progress, session logs, or one-off status messages into `--notes`.
+  - Avoid passing `--notes` during routine `add` commands to prevent accidentally overwriting long-term project notes.
+- **Project description (`--description`)**: A high-level, stable summary of the project's purpose.
+- **Status snapshots (`add`)**: Use `--summary` (concise milestone headline), `--progress` (detailed work accomplished), `--next` (immediate next steps), `--blocker` (current obstacles), and `--decision` for transactional, append-only updates.
 
 ## Operations
 
@@ -23,14 +33,16 @@ Prefer `--json` for data that must be interpreted or reported programmatically.
 npx --yes --package project-mgr pmgr set-project --project my-project --description "Project summary" --notes "Internal notes" --json
 npx --yes --package project-mgr pmgr set-project --project my-project --clear-description --clear-notes --json
 
-
 # List all projects or fuzzy search across project names, descriptions, notes, status summaries, and tags.
 npx --yes --package project-mgr pmgr projects --json
 npx --yes --package project-mgr pmgr list --query "keyword" --json
 
-# Add an agent-authored status snapshot (optionally with project description or notes).
-npx --yes --package project-mgr pmgr add --project my-project --status active --summary "Implemented the CLI" \
-  --description "Project description" --progress "Tests pass" --next "Publish the package" --source agent --json
+# Start the local Web Dashboard & REST API server.
+npx --yes --package project-mgr pmgr serve --port 3000 --no-open --json
+
+# Add an agent-authored status snapshot (status defaults to completed if omitted).
+npx --yes --package project-mgr pmgr add --project my-project --summary "Implemented the CLI" \
+  --progress "Tests pass" --next "Publish the package" --source agent --json
 
 # Query current state, history, or state at a time.
 npx --yes --package project-mgr pmgr current --project my-project --json

package/src/cli.ts

@@ -12,7 +12,9 @@ import {
   openLedger,
   parseTime,
   type ProjectOverview,
+  type ProjectStatus,
   setProjectMetadata,
+  startServer,
   toPortableStatusEntry,
   ValidationError,
 } from "./index.js";
@@ -33,7 +35,9 @@ function parse(argv: string[]): { command: string[]; flags: Flags } {
     if (
       key === "json" ||
       key === "clear-description" ||
-      key === "clear-notes"
+      key === "clear-notes" ||
+      key === "open" ||
+      key === "no-open"
     ) {
       if (flags[key] !== undefined)
         throw new ValidationError(`--${key} may only be supplied once`);
@@ -94,6 +98,7 @@ const allowedFlags = new Map<string, ReadonlySet<string>>([
   ],
   ["at", new Set(["project", "at", "json"])],
   ["export", new Set(["project", "format"])],
+  ["serve", new Set(["port", "host", "open", "no-open", "json"])],
 ]);
 
 function validateInvocation(command: string[], flags: Flags): string {
@@ -103,7 +108,7 @@ function validateInvocation(command: string[], flags: Flags): string {
     typeof action === "string" ? allowedFlags.get(action) : undefined;
   if (typeof action !== "string" || !allowed)
     throw new ValidationError(
-      "usage: pmgr <add|import|current|projects|list|set-project|history|at|export> (or: pmgr status <action>)",
+      "usage: pmgr <add|import|current|projects|list|set-project|history|at|export|serve> (or: pmgr status <action>)",
     );
   const positional = command.slice(statusCommand ? 2 : 1);
   if (action === "import") {
@@ -212,7 +217,7 @@ function imported(file: string): unknown[] {
 export function run(
   argv: string[],
   write = process.stdout.write.bind(process.stdout),
-): void {
+): unknown {
   const { command, flags } = parse(argv);
   const action = validateInvocation(command, flags);
   const db = openLedger();
@@ -229,7 +234,7 @@ export function run(
         output(
           addStatus(db, {
             project,
-            status: stringFlag(flags, "status", true),
+            status: stringFlag(flags, "status") as unknown as ProjectStatus,
             summary: stringFlag(flags, "summary", true),
             progress: stringFlag(flags, "progress"),
             blockers: listFlag(flags, "blocker"),
@@ -352,9 +357,30 @@ export function run(
         else throw new ValidationError("--format must be json or jsonl");
         break;
       }
+
+      case "serve": {
+        const port =
+          flags.port !== undefined
+            ? numberFlag(flags, "port", 3000)
+            : undefined;
+        const host = stringFlag(flags, "host");
+        const open = flags["no-open"] === true ? false : true;
+        return startServer({ port, host, open, db }).then((instance) => {
+          if (json) {
+            write(
+              `${JSON.stringify({ url: instance.url, port: instance.port, host: instance.host })}\n`,
+            );
+          } else {
+            write(`Server running at ${instance.url}\n`);
+          }
+          return instance;
+        });
+      }
     }
   } finally {
-    db.close();
+    if (action !== "serve") {
+      db.close();
+    }
   }
 }
 
@@ -364,7 +390,7 @@ if (
   import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href
 ) {
   try {
-    run(process.argv.slice(2));
+    await run(process.argv.slice(2));
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;

package/src/db.ts

@@ -207,6 +207,15 @@ export function listProjects(
     };
   });
 
+  overviews.sort((a, b) => {
+    const timeA = a.latestStatus?.occurredAt ?? a.createdAt;
+    const timeB = b.latestStatus?.occurredAt ?? b.createdAt;
+    if (timeA !== timeB) {
+      return timeB.localeCompare(timeA);
+    }
+    return a.project.localeCompare(b.project);
+  });
+
   if (!query) return overviews;
 
   return overviews.filter((overview) => {
@@ -215,16 +224,13 @@ export function listProjects(
     if (overview.description?.toLowerCase().includes(query)) return true;
     if (overview.notes?.toLowerCase().includes(query)) return true;
     if (overview.latestStatus) {
-      if (overview.latestStatus.status.toLowerCase().includes(query))
-        return true;
-      if (overview.latestStatus.summary.toLowerCase().includes(query))
-        return true;
-      if (overview.latestStatus.progress?.toLowerCase().includes(query))
-        return true;
-      if (
-        overview.latestStatus.tags.some((t) => t.toLowerCase().includes(query))
-      )
-        return true;
+      const st = overview.latestStatus;
+      const match =
+        st.status.toLowerCase().includes(query) ||
+        st.summary.toLowerCase().includes(query) ||
+        (st.progress && st.progress.toLowerCase().includes(query)) ||
+        st.tags.some((t) => t.toLowerCase().includes(query));
+      if (match) return true;
     }
     return false;
   });
@@ -350,3 +356,18 @@ export function at(
     occurredAt,
   );
 }
+
+export function countEntries(db: Ledger, project?: string): number {
+  if (project) {
+    const row = db
+      .prepare(
+        "SELECT COUNT(*) AS count FROM status_entries e JOIN projects p ON p.id = e.project_id WHERE p.slug = ?",
+      )
+      .get(project) as { count: number };
+    return row.count;
+  }
+  const row = db
+    .prepare("SELECT COUNT(*) AS count FROM status_entries")
+    .get() as { count: number };
+  return row.count;
+}

package/src/domain.ts

@@ -173,7 +173,16 @@ export function validateStatusEntry(
     throw new ValidationError(
       "project must use letters, numbers, dots, underscores, or hyphens",
     );
-  if (!statuses.includes(input.status as ProjectStatus))
+  let statusInput = input.status;
+  if (statusInput === undefined || statusInput === null) {
+    statusInput = "completed";
+  } else if (
+    typeof statusInput === "string" &&
+    statusInput.trim().toLowerCase() === "done"
+  ) {
+    statusInput = "completed";
+  }
+  if (!statuses.includes(statusInput as ProjectStatus))
     throw new ValidationError("status is invalid");
   const source = input.source === undefined ? defaultSource : input.source;
   if (!sources.includes(source as Source))
@@ -183,7 +192,7 @@ export function validateStatusEntry(
     throw new ValidationError("externalRef must be at most 200 characters");
   return {
     project,
-    status: input.status as ProjectStatus,
+    status: statusInput as ProjectStatus,
     summary: text(input.summary, "summary", true) as string,
     progress: text(input.progress, "progress"),
     blockers: textList(input.blockers, "blockers"),

package/src/index.ts

@@ -1,2 +1,5 @@
+export * from "./cli.js";
 export * from "./db.js";
 export * from "./domain.js";
+export * from "./server.js";
+export * from "./web/ui.js";

package/src/server.ts

@@ -0,0 +1,202 @@
+import { exec } from "node:child_process";
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import { URL } from "node:url";
+import {
+  countEntries,
+  history,
+  listProjects,
+  openLedger,
+  type Ledger,
+} from "./db.js";
+import { getWebUIHTML } from "./web/ui.js";
+
+export type ServerOptions = {
+  port?: number;
+  host?: string;
+  open?: boolean;
+  db?: Ledger;
+};
+
+export type ServerInstance = {
+  server: Server;
+  url: string;
+  port: number;
+  host: string;
+  close: () => Promise<void>;
+};
+
+export function openBrowser(url: string): void {
+  const platform = process.platform;
+  let command = "";
+  if (platform === "darwin") {
+    command = `open "${url}"`;
+  } else if (platform === "win32") {
+    command = `start "" "${url}"`;
+  } else {
+    command = `xdg-open "${url}"`;
+  }
+  exec(command, () => {
+    /* ignore background exec errors */
+  });
+}
+
+function parseQueryParams(url: URL): Record<string, string> {
+  const params: Record<string, string> = {};
+  for (const [key, value] of url.searchParams.entries()) {
+    params[key] = value;
+  }
+  return params;
+}
+
+function sendJson(
+  res: ServerResponse,
+  statusCode: number,
+  data: unknown,
+): void {
+  res.writeHead(statusCode, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-cache",
+  });
+  res.end(JSON.stringify(data));
+}
+
+export function handleRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  db: Ledger,
+): void {
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    sendJson(res, 405, { error: "Method not allowed" });
+    return;
+  }
+
+  const reqUrl = new URL(
+    req.url || "/",
+    `http://${req.headers.host || "localhost"}`,
+  );
+  const pathname = reqUrl.pathname;
+  const query = parseQueryParams(reqUrl);
+
+  if (pathname === "/" || pathname === "/index.html") {
+    res.writeHead(200, {
+      "Content-Type": "text/html; charset=utf-8",
+      "Cache-Control": "no-cache",
+    });
+    res.end(getWebUIHTML());
+    return;
+  }
+
+  if (pathname === "/api/projects") {
+    const projects = listProjects(db, { query: query.query });
+    sendJson(res, 200, projects);
+    return;
+  }
+
+  if (pathname.startsWith("/api/projects/")) {
+    const slug = decodeURIComponent(pathname.slice("/api/projects/".length));
+    const projects = listProjects(db);
+    const target = projects.find((p) => p.project === slug);
+    if (!target) {
+      sendJson(res, 404, { error: "Project not found" });
+    } else {
+      sendJson(res, 200, target);
+    }
+    return;
+  }
+
+  if (pathname === "/api/history") {
+    const project = query.project;
+    const since = query.since;
+    const until = query.until;
+    const rawLimit = Number(query.limit ?? 100);
+    const rawOffset = Number(query.offset ?? 0);
+
+    const entries = history(db, project, {
+      since,
+      until,
+      limit: Number.isInteger(rawLimit) && rawLimit >= 0 ? rawLimit : 100,
+      offset: Number.isInteger(rawOffset) && rawOffset >= 0 ? rawOffset : 0,
+    });
+    sendJson(res, 200, entries);
+    return;
+  }
+
+  if (pathname === "/api/stats") {
+    const projects = listProjects(db);
+    const totalEntries = countEntries(db);
+    const statusCounts: Record<string, number> = {};
+
+    for (const proj of projects) {
+      const st = proj.latestStatus?.status || "none";
+      statusCounts[st] = (statusCounts[st] || 0) + 1;
+    }
+
+    sendJson(res, 200, {
+      totalProjects: projects.length,
+      totalEntries,
+      statusCounts,
+    });
+    return;
+  }
+
+  sendJson(res, 404, { error: "Not found" });
+}
+
+export function startServer(
+  options: ServerOptions = {},
+): Promise<ServerInstance> {
+  const host = options.host ?? "127.0.0.1";
+  const port =
+    options.port ??
+    (process.env.PORT ? Number(process.env.PORT) : /* c8 ignore next */ 3000);
+  const db = options.db || openLedger();
+  const shouldOpen = options.open ?? true;
+
+  const server = createServer((req, res) => {
+    try {
+      handleRequest(req, res, db);
+    } catch (err) {
+      sendJson(res, 500, {
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      /* c8 ignore start -- server.address() ternary branch is Node network adapter glue */
+      const address = server.address();
+      const actualPort =
+        typeof address === "object" && address !== null ? address.port : port;
+      /* c8 ignore stop */
+      const url = `http://${host}:${actualPort}`;
+
+      if (shouldOpen) {
+        openBrowser(url);
+      }
+
+      resolve({
+        server,
+        url,
+        port: actualPort,
+        host,
+        close: () =>
+          new Promise<void>((resClose, rejClose) => {
+            server.close((err) => {
+              if (!options.db) {
+                db.close();
+              }
+              if (err) rejClose(err);
+              else resClose();
+            });
+          }),
+      });
+    });
+  });
+}