project-mgr 0.1.7 → 0.2.0

package/.claude/settings.local.json

@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "allow": ["Bash(pnpm test *)", "Bash(pnpm tsc *)"]
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.0 - 2026-08-07
+
+### Added
+
+- Added local HTTP Web Server & SPA Dashboard via `pmgr serve` (`GET /`, REST API `/api/projects`, `/api/history`, `/api/stats`).
+- Added Activity Feed date filtering with native Date Picker (defaulting to Today's local date).
+- Added Activity Feed Grouping Mode toggle: Grouped by Project (Default) vs Flat List.
+- Made `--status` parameter in `pmgr add` optional (defaults to `completed`, with `done` as a normalized alias).
+- Added `countEntries` query for accurate database metrics.
+- Fixed XSS vulnerability in Web UI event handling via HTML5 data attribute event delegation.
+- Added descending project sorting by latest update timestamp.
+
 ## 0.1.7 - 2026-08-07
 
 ### Added

package/README.md

@@ -171,11 +171,12 @@ pnpm start at \
 `add` requires:
 
 - `--project`: Unique project name. It may contain English letters, numbers, `.`, `_`, and `-`, and must start with a letter or number.
-- `--status`: One of `idea`, `planned`, `active`, `blocked`, `paused`, `completed`, or `archived`.
 - `--summary`: A summary of this status.
 
 Optional arguments:
 
+- `--status`: One of `idea`, `planned`, `active`, `blocked`, `paused`, `completed`, or `archived` (`done` is accepted as an alias for `completed`). Defaults to `completed` if omitted.
+
 - `--description`: Project introduction or description (updates project metadata).
 - `--notes`: Project notes/remarks (updates project metadata).
 - `--progress`: Work already completed.
@@ -236,6 +237,32 @@ pnpm start import --file statuses.jsonl --json
 
 Unknown fields, unknown CLI options, extra positional arguments, invalid statuses, and timestamps without a timezone are rejected.
 
+## Local Web Dashboard
+
+Launch a local HTTP server to view project overviews and project activity history in your browser:
+
+```bash
+pmgr serve
+```
+
+By default, `pmgr serve` listens on `http://127.0.0.1:3000` and automatically opens the web dashboard in your default browser.
+
+Options:
+
+- `--port`: HTTP server port (default: `3000` or `PORT` environment variable).
+- `--host`: Host interface to bind (default: `127.0.0.1`).
+- `--no-open`: Do not automatically open the web browser.
+- `--json`: Output server startup details in JSON format.
+
+### REST API Endpoints
+
+The server also exposes JSON API endpoints:
+
+- `GET /api/projects`: List project overviews (supports `?query=...`).
+- `GET /api/projects/:slug`: Detailed metadata and latest status of a specific project.
+- `GET /api/history`: Timeline activity log across all or specific projects (supports `?project=...`, `?since=...`, `?until=...`, `?limit=...`, `?offset=...`).
+- `GET /api/stats`: Overview metrics (total projects count, status breakdowns, total activity entries count).
+
 ## Query and export
 
 | Command       | Purpose                                               | Key options                                                                                                 |
@@ -246,8 +273,9 @@ Unknown fields, unknown CLI options, extra positional arguments, invalid statuse
 | `history`     | History for all projects or one project, newest first | `--project`, `--since`, `--until`, `--limit`, `--offset`, `--json`                                          |
 | `at`          | The latest status at or before a specified time       | `--project`, `--at`, `--json`                                                                               |
 | `export`      | Export all records or one project's records           | `--project`, `--format json\|jsonl`                                                                         |
+| `serve`       | Start local HTTP server & interactive web dashboard   | `--port`, `--host`, `--open`, `--no-open`, `--json`                                                         |
 
-All actions can also use the compatible `status <action>` form, for example `pmgr status projects`. Human-readable multi-record results list projects and their latest status, or `No entries found.` / `No projects found.` when empty. `add`, `import`, `current`, `projects`, `list`, `set-project`, `history`, and `at` support `--json`; `export` uses `--format` to select its format.
+All actions can also use the compatible `status <action>` form, for example `pmgr status projects`. Human-readable multi-record results list projects and their latest status, or `No entries found.` / `No projects found.` when empty. `add`, `import`, `current`, `projects`, `list`, `set-project`, `history`, `at`, and `serve` support `--json`; `export` uses `--format` to select its format.
 
 Exports omit the database-internal `id` and `recordedAt` fields and can be imported directly. Records are exported from oldest to newest so that restoring them preserves the insertion order of records with the same timestamp:
 

package/README_CN.md

@@ -168,14 +168,15 @@ pnpm start at \
 
 ## 状态写入
 
-`add` 必须提供：
+`add` 必需参数：
 
-- `--project`：项目唯一名称，只能使用英文字母、数字、`.`、`_`、`-`，并以字母或数字开头。
-- `--status`：`idea`、`planned`、`active`、`blocked`、`paused`、`completed` 或 `archived`。
-- `--summary`：本次状态摘要。
+- `--project`：唯一的项目名称。可包含英文字母、数字、`.`、`_` 和 `-`，且必须以字母或数字开头。
+- `--summary`：本次动态的摘要。
 
 可选参数：
 
+- `--status`：`idea`、`planned`、`active`、`blocked`、`paused`、`completed`、`archived` 之一（`done` 可作为 `completed` 的别名）。若省略则默认值为 `completed`。
+
 - `--description`：项目简介/描述（更新项目元数据）。
 - `--notes`：项目备注（更新项目元数据）。
 - `--progress`：已经完成的工作。
@@ -236,18 +237,45 @@ pnpm start import --file statuses.jsonl --json
 
 未知字段、未知 CLI 参数、多余位置参数、非法状态和无时区时间都会被拒绝。
 
-## 查询与导出
+## 本地 Web 画布 (Web Server)
+
+启动本地 HTTP 服务器，在浏览器中可视化查看项目概览与项目动态（Timeline 演进）：
+
+```bash
+pmgr serve
+```
+
+默认情况下，`pmgr serve` 监听 `http://127.0.0.1:3000` 并自动在默认浏览器中打开页面。
 
-| 命令          | 用途                                     | 主要选项                                                                                                    |
-| ------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `projects`    | 列出所有项目或按关键词模糊匹配搜索项目   | `--query`、`--json`                                                                                         |
-| `set-project` | 设置/更新/清空项目的显示名称、简介与备注 | `--project`、`--display-name`、`--description`、`--notes`、`--clear-description`、`--clear-notes`、`--json` |
-| `current`     | 所有项目或单项目的当前状态               | `--project`、`--json`                                                                                       |
-| `history`     | 全部或单个项目的历史，最新记录在前       | `--project`、`--since`、`--until`、`--limit`、`--offset`、`--json`                                          |
-| `at`          | 指定时间点及之前的最后状态               | `--project`、`--at`、`--json`                                                                               |
-| `export`      | 导出全部或单项目记录                     | `--project`、`--format json\|jsonl`                                                                         |
+可选项：
+
+- `--port`：HTTP 服务器端口（默认 `3000` 或环境变量 `PORT`）。
+- `--host`：绑定主机地址（默认 `127.0.0.1`）。
+- `--no-open`：禁止自动打开浏览器。
+- `--json`：以 JSON 格式输出服务器启动信息。
+
+### REST API 接口
+
+服务器同时暴露以下 JSON API 接口：
+
+- `GET /api/projects`：列出项目概览（支持 `?query=...` 检索）。
+- `GET /api/projects/:slug`：查看指定项目的元数据与最新状态。
+- `GET /api/history`：查看全量或指定项目的状态动态演进（支持 `?project=...`, `?since=...`, `?until=...`, `?limit=...`, `?offset=...`）。
+- `GET /api/stats`：查看整体统计指标（项目总数、不同状态分布、动态总条数）。
+
+## 查询与导出
 
-全部 action 仍可使用 `status <action>` 的兼容形式，例如 `pmgr status projects`。人类可读的多条结果按项目及其最新状态输出；为空时输出 `No entries found.` 或 `No projects found.`。`add`、`import`、`current`、`projects`、`list`、`set-project`、`history`、`at` 支持 `--json`；`export` 由 `--format` 控制格式。
+| 命令          | 用途                                      | 主要选项                                                                                                    |
+| ------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `projects`    | 列出所有项目或按关键词模糊匹配搜索项目    | `--query`、`--json`                                                                                         |
+| `set-project` | 设置/更新/清空项目的显示名称、简介与备注  | `--project`、`--display-name`、`--description`、`--notes`、`--clear-description`、`--clear-notes`、`--json` |
+| `current`     | 所有项目或单项目的当前状态                | `--project`、`--json`                                                                                       |
+| `history`     | 全部或单个项目的历史，最新记录在前        | `--project`、`--since`、`--until`、`--limit`、`--offset`、`--json`                                          |
+| `at`          | 指定时间点及之前的最后状态                | `--project`、`--at`、`--json`                                                                               |
+| `export`      | 导出全部或单项目记录                      | `--project`、`--format json\|jsonl`                                                                         |
+| `serve`       | 启动本地 HTTP 服务器与 Web 动态可视化画布 | `--port`、`--host`、`--open`、`--no-open`、`--json`                                                         |
+
+全部 action 仍可使用 `status <action>` 的兼容形式，例如 `pmgr status projects`。人类可读的多条结果按项目及其最新状态输出；为空时输出 `No entries found.` 或 `No projects found.`。`add`、`import`、`current`、`projects`、`list`、`set-project`、`history`、`at`、`serve` 支持 `--json`；`export` 由 `--format` 控制格式。
 
 导出内容不包含数据库内部的 `id` 和 `recordedAt`，可以直接重新导入。记录按时间从旧到新导出，从而在恢复时保留相同时间戳记录的先后关系：
 

package/dist/cli.d.ts

@@ -2,4 +2,4 @@
 export declare function run(argv: string[], write?: {
     (buffer: Uint8Array | string, cb?: (err?: Error | null) => void): boolean;
     (str: Uint8Array | string, encoding?: BufferEncoding, cb?: (err?: Error | null) => void): boolean;
-}): void;
+}): unknown;

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { readFileSync, realpathSync } from "node:fs";
 import { basename } from "node:path";
 import { pathToFileURL } from "node:url";
-import { addStatus, at, current, history, importStatuses, listProjects, openLedger, parseTime, setProjectMetadata, toPortableStatusEntry, ValidationError, } from "./index.js";
+import { addStatus, at, current, history, importStatuses, listProjects, openLedger, parseTime, setProjectMetadata, startServer, toPortableStatusEntry, ValidationError, } from "./index.js";
 const repeats = new Set(["next", "blocker", "decision", "tag"]);
 function parse(argv) {
     const command = [];
@@ -16,7 +16,9 @@ function parse(argv) {
         const key = token.slice(2);
         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`);
             flags[key] = true;
@@ -76,13 +78,14 @@ const allowedFlags = new Map([
     ],
     ["at", new Set(["project", "at", "json"])],
     ["export", new Set(["project", "format"])],
+    ["serve", new Set(["port", "host", "open", "no-open", "json"])],
 ]);
 function validateInvocation(command, flags) {
     const statusCommand = command[0] === "status";
     const action = command[statusCommand ? 1 : 0];
     const allowed = 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>)");
+        throw new ValidationError("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") {
         if (positional.length > 1)
@@ -190,7 +193,7 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
                 }
                 output(addStatus(db, {
                     project,
-                    status: stringFlag(flags, "status", true),
+                    status: stringFlag(flags, "status"),
                     summary: stringFlag(flags, "summary", true),
                     progress: stringFlag(flags, "progress"),
                     blockers: listFlag(flags, "blocker"),
@@ -273,17 +276,35 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
                     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();
+        }
     }
 }
 /* c8 ignore start -- process entry glue is covered by the CLI integration tests through run(). */
 if (process.argv[1] &&
     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));

package/dist/db.d.ts

@@ -22,3 +22,4 @@ export declare function importStatuses(db: Ledger, values: unknown[]): InsertRes
 export declare function current(db: Ledger, project?: string): StatusEntry[];
 export declare function history(db: Ledger, project?: string, options?: HistoryOptions): StatusEntry[];
 export declare function at(db: Ledger, project: string, occurredAt: string): StatusEntry | undefined;
+export declare function countEntries(db: Ledger, project?: string): number;

package/dist/db.js

@@ -142,6 +142,14 @@ export function listProjects(db, options = {}) {
             ...(latestStatus ? { latestStatus } : {}),
         };
     });
+    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) => {
@@ -154,13 +162,12 @@ export function listProjects(db, options = {}) {
         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)))
+            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;
@@ -229,3 +236,15 @@ export function history(db, project, options = {}) {
 export function at(db, project, occurredAt) {
     return one(db, `${select} WHERE p.slug = ? AND e.occurred_at <= ? ORDER BY e.occurred_at DESC, e.id DESC LIMIT 1`, project, occurredAt);
 }
+export function countEntries(db, project) {
+    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);
+        return row.count;
+    }
+    const row = db
+        .prepare("SELECT COUNT(*) AS count FROM status_entries")
+        .get();
+    return row.count;
+}

package/dist/domain.js

@@ -103,7 +103,15 @@ export function validateStatusEntry(value, defaultSource = "human") {
     const project = text(input.project, "project", true);
     if (!projectName.test(project))
         throw new ValidationError("project must use letters, numbers, dots, underscores, or hyphens");
-    if (!statuses.includes(input.status))
+    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))
         throw new ValidationError("status is invalid");
     const source = input.source === undefined ? defaultSource : input.source;
     if (!sources.includes(source))
@@ -113,7 +121,7 @@ export function validateStatusEntry(value, defaultSource = "human") {
         throw new ValidationError("externalRef must be at most 200 characters");
     return {
         project,
-        status: input.status,
+        status: statusInput,
         summary: text(input.summary, "summary", true),
         progress: text(input.progress, "progress"),
         blockers: textList(input.blockers, "blockers"),

package/dist/index.d.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/dist/index.js

@@ -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/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { type Ledger } from "./db.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 declare function openBrowser(url: string): void;
+export declare function handleRequest(req: IncomingMessage, res: ServerResponse, db: Ledger): void;
+export declare function startServer(options?: ServerOptions): Promise<ServerInstance>;

package/dist/server.js

@@ -0,0 +1,147 @@
+import { exec } from "node:child_process";
+import { createServer, } from "node:http";
+import { URL } from "node:url";
+import { countEntries, history, listProjects, openLedger, } from "./db.js";
+import { getWebUIHTML } from "./web/ui.js";
+export function openBrowser(url) {
+    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) {
+    const params = {};
+    for (const [key, value] of url.searchParams.entries()) {
+        params[key] = value;
+    }
+    return params;
+}
+function sendJson(res, statusCode, data) {
+    res.writeHead(statusCode, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-cache",
+    });
+    res.end(JSON.stringify(data));
+}
+export function handleRequest(req, res, db) {
+    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 = {};
+        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 = {}) {
+    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((resClose, rejClose) => {
+                    server.close((err) => {
+                        if (!options.db) {
+                            db.close();
+                        }
+                        if (err)
+                            rejClose(err);
+                        else
+                            resClose();
+                    });
+                }),
+            });
+        });
+    });
+}

package/dist/web/ui.d.ts

@@ -0,0 +1 @@
+export declare function getWebUIHTML(): string;