project-mgr 0.1.6 → 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,24 @@
 # 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
+
+- Added project metadata management (`displayName`, `description`, `notes`) and fuzzy search via `projects` / `list --query`.
+- Added explicit field clearing for project metadata via `--clear-description` and `--clear-notes` flags in `pmgr set-project`.
+
 ## 0.1.6 - 2026-08-03
 
 ### Fixed

package/README.md

@@ -171,11 +171,14 @@ 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.
 - `--blocker`, `--next`, `--decision`, and `--tag`: May be specified repeatedly.
 - `--at`: When the status actually occurred. It must be an ISO 8601 timestamp with a timezone; defaults to the current time.
@@ -183,6 +186,29 @@ Optional arguments:
 - `--external-ref`: A globally idempotent key. A duplicate write to the same project returns the existing record; use by another project is an error.
 - `--json`: Emit stable JSON.
 
+### Project Metadata & Fuzzy Search
+
+Set or update a project's display name, description, and notes with `set-project`, or clear metadata using `--clear-description` / `--clear-notes`:
+
+```bash
+pnpm start set-project \
+  --project project-mgr \
+  --display-name "Project Manager" \
+  --description "Local-first append-only project status ledger" \
+  --notes "Core CLI and Agent Skill are published"
+
+# Clear description or notes
+pnpm start set-project --project project-mgr --clear-description --clear-notes
+```
+
+List projects or search projects using fuzzy matching across slug, display name, description, notes, latest status summary, and tags with `projects` (or `list`):
+
+```bash
+pnpm start projects
+pnpm start list --query "ledger"
+pnpm start projects --query "mvp" --json
+```
+
 ## Bulk import
 
 `import` accepts a JSON object, a JSON array, or a JSONL file containing one object per line. Every record is validated before the whole batch is written in one SQLite transaction; any failure rolls back the entire batch.
@@ -211,16 +237,45 @@ pnpm start import --file statuses.jsonl --json
 
 Unknown fields, unknown CLI options, extra positional arguments, invalid statuses, and timestamps without a timezone are rejected.
 
-## Query and export
+## 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.
 
-| Command   | Purpose                                               | Key options                                                        |
-| --------- | ----------------------------------------------------- | ------------------------------------------------------------------ |
-| `current` | Current status for all projects or one project        | `--project`, `--json`                                              |
-| `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`                                |
+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
 
-All six actions can also use the compatible `status <action>` form, for example `pmgr status export`. Human-readable multi-record results list project, status, occurrence time, and summary, or `No entries found.` when empty. `add`, `import`, `current`, `history`, and `at` support `--json`; `export` uses `--format` to select its format.
+| Command       | Purpose                                               | Key options                                                                                                 |
+| ------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `projects`    | List all projects or fuzzy search by query            | `--query`, `--json`                                                                                         |
+| `set-project` | Set/update project display name, description, & notes | `--project`, `--display-name`, `--description`, `--notes`, `--clear-description`, `--clear-notes`, `--json` |
+| `current`     | Current status for all projects or one project        | `--project`, `--json`                                                                                       |
+| `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`, `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,17 @@ 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`：已经完成的工作。
 - `--blocker`、`--next`、`--decision`、`--tag`：可以重复传入。
 - `--at`：状态实际发生时间，必须是带时区的 ISO 8601 时间；缺省为当前时间。
@@ -183,6 +186,29 @@ pnpm start at \
 - `--external-ref`：全局幂等键。重复写入同一项目时返回原记录；若被其他项目占用则报错。
 - `--json`：输出稳定 JSON。
 
+## 项目元数据与模糊查询
+
+可通过 `set-project` 设置或更新项目的名称、简介与备注，或使用 `--clear-description` / `--clear-notes` 清空：
+
+```bash
+pnpm start set-project \
+  --project project-mgr \
+  --display-name "Project Manager" \
+  --description "本地优先、只追加的项目状态账本" \
+  --notes "核心 CLI 与 Agent Skill 已上线"
+
+# 清空简介或备注
+pnpm start set-project --project project-mgr --clear-description --clear-notes
+```
+
+可通过 `projects`（或 `list`）列出所有项目或使用 `--query` 进行模糊匹配搜索（匹配项目名称 slug、显示名称、简介、备注、最新状态摘要及标签）：
+
+```bash
+pnpm start projects
+pnpm start list --query "账本"
+pnpm start projects --query "mvp" --json
+```
+
 ## 批量导入
 
 `import` 接受一个 JSON 对象、JSON 数组，或每行一个对象的 JSONL 文件。所有记录先校验，再在同一个 SQLite 事务中写入；任一记录失败时整批回滚。
@@ -211,16 +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` 并自动在默认浏览器中打开页面。
 
-| 命令      | 用途                               | 主要选项                                                           |
-| --------- | ---------------------------------- | ------------------------------------------------------------------ |
-| `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 export`。人类可读的多条结果按“项目、状态、发生时间、摘要”输出；为空时输出 `No entries found.`。`add`、`import`、`current`、`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, openLedger, parseTime, 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 = [];
@@ -14,7 +14,11 @@ function parse(argv) {
             continue;
         }
         const key = token.slice(2);
-        if (key === "json") {
+        if (key === "json" ||
+            key === "clear-description" ||
+            key === "clear-notes" ||
+            key === "open" ||
+            key === "no-open") {
             if (flags[key] !== undefined)
                 throw new ValidationError(`--${key} may only be supplied once`);
             flags[key] = true;
@@ -39,6 +43,8 @@ const allowedFlags = new Map([
             "project",
             "status",
             "summary",
+            "description",
+            "notes",
             "progress",
             "blocker",
             "next",
@@ -52,19 +58,34 @@ const allowedFlags = new Map([
     ],
     ["import", new Set(["file", "json"])],
     ["current", new Set(["project", "json"])],
+    ["projects", new Set(["query", "json"])],
+    ["list", new Set(["query", "json"])],
+    [
+        "set-project",
+        new Set([
+            "project",
+            "display-name",
+            "description",
+            "notes",
+            "clear-description",
+            "clear-notes",
+            "json",
+        ]),
+    ],
     [
         "history",
         new Set(["project", "since", "until", "limit", "offset", "json"]),
     ],
     ["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|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)
@@ -110,6 +131,28 @@ function output(value, json, write) {
     else
         write(`${JSON.stringify(value, null, 2)}\n`);
 }
+function formatProjectOverview(item) {
+    const lines = [`${item.project}\t${item.displayName}`];
+    if (item.description)
+        lines.push(`  Description: ${item.description}`);
+    if (item.notes)
+        lines.push(`  Notes: ${item.notes}`);
+    if (item.latestStatus) {
+        lines.push(`  Latest Status: ${item.latestStatus.status}\t${item.latestStatus.occurredAt}\t${item.latestStatus.summary}`);
+    }
+    else {
+        lines.push(`  Latest Status: (none)`);
+    }
+    return lines.join("\n");
+}
+function outputProjects(items, json, write) {
+    if (json)
+        write(`${JSON.stringify(items)}\n`);
+    else if (items.length === 0)
+        write("No projects found.\n");
+    else
+        write(`${items.map(formatProjectOverview).join("\n")}\n`);
+}
 function imported(file) {
     if (!file)
         throw new ValidationError("import file is required");
@@ -141,10 +184,16 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
     const json = flags.json === true;
     try {
         switch (action) {
-            case "add":
+            case "add": {
+                const project = stringFlag(flags, "project", true);
+                const description = stringFlag(flags, "description");
+                const notes = stringFlag(flags, "notes");
+                if (description !== undefined || notes !== undefined) {
+                    setProjectMetadata(db, { project, description, notes });
+                }
                 output(addStatus(db, {
-                    project: stringFlag(flags, "project", true),
-                    status: stringFlag(flags, "status", true),
+                    project,
+                    status: stringFlag(flags, "status"),
                     summary: stringFlag(flags, "summary", true),
                     progress: stringFlag(flags, "progress"),
                     blockers: listFlag(flags, "blocker"),
@@ -156,6 +205,7 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
                     externalRef: stringFlag(flags, "external-ref"),
                 }).entry, json, write);
                 break;
+            }
             case "import":
                 output(importStatuses(db, imported(stringFlag(flags, "file") ??
                     command[command[0] === "status" ? 2 : 1] ??
@@ -164,6 +214,39 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
             case "current":
                 output(current(db, stringFlag(flags, "project")), json, write);
                 break;
+            case "projects":
+            case "list":
+                outputProjects(listProjects(db, { query: stringFlag(flags, "query") }), json, write);
+                break;
+            case "set-project": {
+                const project = stringFlag(flags, "project", true);
+                const displayName = stringFlag(flags, "display-name");
+                let description = undefined;
+                if (flags["clear-description"] === true) {
+                    if (flags.description !== undefined)
+                        throw new ValidationError("cannot specify both --description and --clear-description");
+                    description = null;
+                }
+                else if (flags.description !== undefined) {
+                    description = stringFlag(flags, "description");
+                }
+                let notes = undefined;
+                if (flags["clear-notes"] === true) {
+                    if (flags.notes !== undefined)
+                        throw new ValidationError("cannot specify both --notes and --clear-notes");
+                    notes = null;
+                }
+                else if (flags.notes !== undefined) {
+                    notes = stringFlag(flags, "notes");
+                }
+                output(setProjectMetadata(db, {
+                    project,
+                    displayName,
+                    description,
+                    notes,
+                }), json, write);
+                break;
+            }
             case "history":
                 output(history(db, stringFlag(flags, "project"), {
                     since: stringFlag(flags, "since") &&
@@ -193,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

@@ -1,5 +1,5 @@
 import Database from "better-sqlite3";
-import { type Source, type StatusEntry } from "./domain.js";
+import { type ProjectMetadata, type ProjectOverview, type Source, type StatusEntry } from "./domain.js";
 export type Ledger = Database.Database;
 export type InsertResult = {
     entry: StatusEntry;
@@ -13,8 +13,13 @@ export type HistoryOptions = {
 };
 export declare function databasePath(): string;
 export declare function openLedger(path?: string): Ledger;
+export declare function setProjectMetadata(db: Ledger, value: unknown): ProjectMetadata;
+export declare function listProjects(db: Ledger, options?: {
+    query?: string;
+}): ProjectOverview[];
 export declare function addStatus(db: Ledger, value: unknown, defaultSource?: Source): InsertResult;
 export declare function importStatuses(db: Ledger, values: unknown[]): InsertResult[];
 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

@@ -2,8 +2,8 @@ import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-import { validateStatusEntry, ValidationError, } from "./domain.js";
-const migration = `
+import { validateProjectMetadataInput, validateStatusEntry, ValidationError, } from "./domain.js";
+const migration1 = `
 CREATE TABLE IF NOT EXISTS projects (
   id INTEGER PRIMARY KEY,
   slug TEXT NOT NULL UNIQUE,
@@ -27,6 +27,10 @@ CREATE TABLE IF NOT EXISTS status_entries (
 );
 CREATE INDEX IF NOT EXISTS idx_status_entries_project_occurred ON status_entries(project_id, occurred_at DESC, id DESC);
 `;
+const migration2 = `
+ALTER TABLE projects ADD COLUMN description TEXT;
+ALTER TABLE projects ADD COLUMN notes TEXT;
+`;
 export function databasePath() {
     return (process.env.PMGR_DB_PATH ||
         resolve(homedir(), ".local", "share", "project-mgr", "project-mgr.sqlite"));
@@ -39,9 +43,13 @@ export function openLedger(path = databasePath()) {
     db.exec("CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY)");
     db.transaction(() => {
         if (!db.prepare("SELECT 1 FROM schema_migrations WHERE version = 1").get()) {
-            db.exec(migration);
+            db.exec(migration1);
             db.prepare("INSERT INTO schema_migrations(version) VALUES (1)").run();
         }
+        if (!db.prepare("SELECT 1 FROM schema_migrations WHERE version = 2").get()) {
+            db.exec(migration2);
+            db.prepare("INSERT INTO schema_migrations(version) VALUES (2)").run();
+        }
     }).immediate();
     return db;
 }
@@ -67,6 +75,104 @@ function one(db, sql, ...params) {
     const row = db.prepare(sql).get(...params);
     return row && entryFromRow(row);
 }
+function upsertProjectMetadata(db, input) {
+    const existing = db
+        .prepare("SELECT 1 FROM projects WHERE slug = ?")
+        .get(input.project);
+    if (!existing) {
+        const now = new Date().toISOString();
+        db.prepare("INSERT INTO projects(slug, display_name, description, notes, created_at) VALUES (?, ?, ?, ?, ?)").run(input.project, input.displayName ?? input.project, input.description ?? null, input.notes ?? null, now);
+    }
+    else {
+        const updates = [];
+        const params = [];
+        if (input.displayName !== undefined) {
+            updates.push("display_name = ?");
+            params.push(input.displayName);
+        }
+        if (input.description !== undefined) {
+            updates.push("description = ?");
+            params.push(input.description);
+        }
+        if (input.notes !== undefined) {
+            updates.push("notes = ?");
+            params.push(input.notes);
+        }
+        if (updates.length > 0) {
+            params.push(input.project);
+            db.prepare(`UPDATE projects SET ${updates.join(", ")} WHERE slug = ?`).run(...params);
+        }
+    }
+}
+export function setProjectMetadata(db, value) {
+    const input = validateProjectMetadataInput(value);
+    return db.transaction(() => {
+        upsertProjectMetadata(db, input);
+        const row = db
+            .prepare("SELECT * FROM projects WHERE slug = ?")
+            .get(input.project);
+        return {
+            project: row.slug,
+            displayName: row.display_name,
+            ...(row.description ? { description: row.description } : {}),
+            ...(row.notes ? { notes: row.notes } : {}),
+            createdAt: row.created_at,
+        };
+    })();
+}
+export function listProjects(db, options = {}) {
+    const query = options.query?.trim().toLowerCase();
+    const projects = db
+        .prepare("SELECT * FROM projects ORDER BY slug ASC")
+        .all();
+    const latestStatuses = current(db);
+    const statusMap = new Map();
+    for (const entry of latestStatuses) {
+        statusMap.set(entry.project, entry);
+    }
+    const overviews = projects.map((row) => {
+        const slug = row.slug;
+        const latestStatus = statusMap.get(slug);
+        return {
+            project: slug,
+            displayName: row.display_name,
+            ...(row.description ? { description: row.description } : {}),
+            ...(row.notes ? { notes: row.notes } : {}),
+            createdAt: row.created_at,
+            ...(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) => {
+        if (overview.project.toLowerCase().includes(query))
+            return true;
+        if (overview.displayName.toLowerCase().includes(query))
+            return true;
+        if (overview.description?.toLowerCase().includes(query))
+            return true;
+        if (overview.notes?.toLowerCase().includes(query))
+            return true;
+        if (overview.latestStatus) {
+            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;
+    });
+}
 export function addStatus(db, value, defaultSource = "human") {
     const input = validateStatusEntry(value, defaultSource);
     return db.transaction(() => addValidatedStatus(db, input))();
@@ -81,7 +187,7 @@ function addValidatedStatus(db, input) {
         }
     }
     const now = new Date().toISOString();
-    db.prepare("INSERT INTO projects(slug, display_name, created_at) VALUES (?, ?, ?) ON CONFLICT(slug) DO NOTHING").run(input.project, input.project, now);
+    upsertProjectMetadata(db, { project: input.project });
     const project = db
         .prepare("SELECT id FROM projects WHERE slug = ?")
         .get(input.project);
@@ -130,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.d.ts

@@ -2,6 +2,22 @@ export declare const statuses: readonly ["idea", "planned", "active", "blocked",
 export declare const sources: readonly ["human", "agent", "import"];
 export type ProjectStatus = (typeof statuses)[number];
 export type Source = (typeof sources)[number];
+export type ProjectMetadata = {
+    project: string;
+    displayName: string;
+    description?: string;
+    notes?: string;
+    createdAt: string;
+};
+export type ProjectOverview = ProjectMetadata & {
+    latestStatus?: StatusEntry;
+};
+export type ProjectMetadataInput = {
+    project: string;
+    displayName?: string;
+    description?: string | null;
+    notes?: string | null;
+};
 export type StatusEntryInput = {
     project: string;
     status: ProjectStatus;
@@ -26,5 +42,6 @@ export declare class ValidationError extends Error {
     constructor(message: string);
 }
 export declare function parseTime(value: unknown, field: string): string;
+export declare function validateProjectMetadataInput(value: unknown): ProjectMetadataInput;
 export declare function validateStatusEntry(value: unknown, defaultSource?: Source): StatusEntryInput & Required<Pick<StatusEntryInput, "occurredAt" | "source">>;
 export declare function toPortableStatusEntry(entry: StatusEntry): PortableStatusEntry;