project-mgr 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.5.0 - 2026-10-29
+
+### Added
+
+- Store new snapshot next work as `nextTodoUids` references. `add --next` creates Todos and those refs in one transaction; `add --next-todo` pins existing UIDs.
+- Reject mixed prose and refs, duplicate UIDs, combining `--next` with `--next-todo`, cross-project refs, and project changes that conflict with any historical reference.
+- Export version 4 carries refs and every Todo they need, including unassigned Todos referenced by a project export.
+- `todos --status open` lists open work. With `--project`, current snapshot pins are ordered first.
+- Dashboard activity history and project cards show referenced Todos with live status.
+
+### Changed
+
+- New snapshots no longer persist next-step prose. Legacy string `nextSteps` stay readable. Per-index conversion does not rewrite history; completion copies the full string list until every source index has a Todo, then materializes refs without creating Todos or changing their status.
+
+### Fixed
+
+- Detach the dashboard browser launch so a long-lived browser does not keep the process alive.
+- Reject dangling and cross-project `nextTodoUids` from `importStatuses`, and require imported refs to name Todos in the same payload. Entry-only imports declare no Todos, so they cannot reference existing rows.
+- Treat a fixed-UID retry of `--next` text as the same write after it has been stored as refs. Portable imports still require an exact snapshot match.
+
+## 0.4.0 - 2026-10-28
+
+### Added
+
+- Add independent Todos with optional project/source links, per-item completion, cancellation, reopening, and CLI commands.
+- Create Todos atomically from new next steps and explicitly convert legacy steps without rewriting history.
+- Add dashboard activity completion controls and project-filtered Todo views.
+- Preserve Todo state in version-3 exports and enforce same-origin local JSON writes.
+
+### Changed
+
+- Guide agents to ask before recording multiple sub-projects, either under one project name or with snapshot tags.
+- Sync the Chinese README with CLI help, activity completion, and Todo documentation.
+
 ## 0.3.2 - 2026-10-16
 
 - Add general and per-command CLI help, no-argument help, and package version aliases without opening the database.

package/README.md

@@ -225,7 +225,7 @@ 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.
+`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. The example below is a legacy entry: string `nextSteps` are kept and do not create Todos. New snapshots created with `add` store `nextTodoUids` instead.
 
 ```json
 {
@@ -333,3 +333,52 @@ Activity cards display Completed with a follow-up link and retain original detai
 Export now emits a version-2 bundle `{ "version": 2, "entries": [...], "completions": [...] }`. JSONL emits one complete bundle per line. Entries retain UUIDs and recording times; events retain UUIDs and per-target predecessor links, including revocations. Import accepts legacy entry objects/arrays/JSONL and version-2 bundles, checks identity conflicts, and applies each file atomically. Re-importing the same bundle is idempotent. Event order is significant: import events in exported order; divergent histories fail instead of silently merging. Older clients cannot import version-2 bundles. Migration adds UUIDs to existing snapshots without changing their content.
 
 Independently migrated copies of legacy data receive different UUIDs. Cross-import may fail on an existing `externalRef`; no implicit identity adoption occurs. Restore a bundle into a fresh database for a faithful migration. Older writers are rejected if they omit UUIDs. With an existing `externalRef`, `add` retains its existing snapshot and applies explicitly supplied `--completes` links to that snapshot; identical active links are no-ops. Use `complete` to make after-the-fact reconciliation explicit.
+
+### Todos and dashboard actions
+
+Todos own actionable work. A new status snapshot stores ordered `nextTodoUids`
+and does not persist next-step prose. `add --next` creates one Todo per title
+and stores those UIDs in the same transaction. Repeating the same text on a
+later snapshot creates new Todos; pass `--next-todo` to keep existing work.
+Do not combine `--next` with `--next-todo`. Duplicate UIDs in one list are rejected.
+
+```sh
+pmgr add --project demo --status active --summary "Review queued" \
+  --next "Collect logs" --next "Write the note" --source agent --json
+pmgr todo-add --title "Unassigned idea" --json
+pmgr add --project demo --status active --summary "Pin the idea" \
+  --next-todo <todo-uuid> --source agent --json
+pmgr todos --project demo --status open --json
+pmgr todo-update --uid <todo-uuid> --status completed --json
+pmgr todo-update --uid <todo-uuid> --status cancelled --json
+```
+
+`todos --status open` answers open work from Todos, not from string next steps.
+With `--project`, UIDs pinned on the current snapshot are ordered first.
+Completing or cancelling a Todo updates every resolved view and does not rewrite
+snapshots. Omitting a UID from a newer snapshot unpins it and does not change
+the Todo status.
+
+Legacy snapshots keep string `nextSteps` and omit `nextTodoUids`. Convert each
+index explicitly; conversion does not append a snapshot. While any source index
+is still unconverted, a completion follow-up copies the full string list and
+`nextStepsSourceUid`. After every index has a Todo, the follow-up materializes
+`nextTodoUids` in source-index order and does not create Todos or change status.
+A snapshot never stores both prose and refs.
+
+`current` and `history` include stored `nextTodoUids` plus live `nextTodos`
+(`uid`, `title`, `status`, `project`). That view is the Todo now, not its state
+at the snapshot time. `at` returns the stored snapshot, including refs when
+present, and does not add the live view.
+
+A snapshot may reference Todos that are unassigned or already in that project.
+If a Todo appears in any `nextTodoUids`, or is linked to a source entry, its
+project cannot be changed. Unpinning the current snapshot does not lift that lock.
+
+Exports that contain refs use version 4 and include every referenced Todo.
+Version 3 remains the Todo bundle without refs. Version 2 and legacy imports
+do not invent open work. Dangling, duplicate, mixed, or cross-project refs fail
+the whole import. Dashboard writes stay same-origin localhost JSON. Activity
+cards still offer **Mark completed**, which appends a follow-up and does not
+complete the project or its Todos. Adding a Todo from the dashboard does not
+pin it; pinning requires a new snapshot.

package/README_CN.md

@@ -127,6 +127,18 @@ pnpm start history --project test-project
 
 自动化测试会使用内存数据库或系统临时目录中的 SQLite 文件，不会读写默认数据库。`PMGR_DB_PATH=:memory:` 也可用于单条命令，但每个 CLI 命令都是独立进程，命令结束后数据就会消失，不适合连续手工测试。
 
+## CLI 帮助与版本
+
+```bash
+pmgr                    # 显示通用帮助
+pmgr -h                 # 也可使用 --help 或 help
+pmgr add --help          # 命令用法与可用选项
+pmgr help history       # 等价于 history -h
+pmgr -v                 # 也可使用 -V、--version 或 version
+```
+
+帮助与版本命令会成功退出，且不会打开或创建数据库。版本输出来自已安装包的元数据。也支持兼容形式 `pmgr status <command> --help`。
+
 ## 快速开始
 
 追加一条项目状态：
@@ -186,7 +198,7 @@ pnpm start at \
 - `--external-ref`：全局幂等键。重复写入同一项目时返回原记录；若被其他项目占用则报错。
 - `--json`：输出稳定 JSON。
 
-## 项目元数据与模糊查询
+### 项目元数据与模糊查询
 
 可通过 `set-project` 设置或更新项目的名称、简介与备注，或使用 `--clear-description` / `--clear-notes` 清空：
 
@@ -211,7 +223,7 @@ pnpm start projects --query "mvp" --json
 
 ## 批量导入
 
-`import` 接受一个 JSON 对象、JSON 数组，或每行一个对象的 JSONL 文件。所有记录先校验，再在同一个 SQLite 事务中写入；任一记录失败时整批回滚。
+`import` 接受一个 JSON 对象、JSON 数组，或每行一个对象的 JSONL 文件。所有记录先校验，再在同一个 SQLite 事务中写入；任一记录失败时整批回滚。下面的示例是旧格式条目：字符串 `nextSteps` 会保留，且不会创建待办。用 `add` 写入的新快照会改为存储 `nextTodoUids`。
 
 ```json
 {
@@ -298,3 +310,68 @@ pnpm build
 ```
 
 Statements、branches、functions、lines 的覆盖率门槛均为 100%。详细设计见[架构文档](docs/architecture.md)。
+
+## 补全更早的动态
+
+项目状态和动态是否完成是两回事。关联条目前，先查看 `pmgr history --project demo --json`。`status` 是原始快照；`effectiveStatus` 计入显式的后续完成；`isCurrent` 标识该项目的最新快照。缺少 `completedBy` 并不表示这条动态尚未完成。
+
+```bash
+# 一次更新可完成多条更早的记录（本地数字 ID 或可移植 UUID）。
+pmgr add --project demo --status active --summary "部署已验收" \
+  --completes 12 --completes 15 --source agent --json
+# 关联一条已有的后续记录，或不删除历史地纠正错误关联。
+pmgr complete --entry 12 --by 18 --source agent --json
+pmgr revoke-completion --entry 12 --by 18 --reason "验收仍未完成" --source agent --json
+```
+
+只关联那些全部未完成工作（包括阻塞和下一步）都已解决的条目。同一项目内的关联要求后续记录的发生时间严格更晚；发生时间相同的关联会被拒绝。每个目标只能有一个有效的完成来源。重复同一关联是空操作；要替换时需先撤销。`add --completes` 会原子写入快照、元数据和关联。已有历史不会自动对账。
+
+动态卡片会显示已完成，并链到后续动态；原始详情保留在可展开的「原始记录」中。「当前状态」和「已有后续更新」只表示快照新旧，与是否完成相互独立。`/api/entries/<id-or-uid>` 和 `/?entry=<uid>` 即使不在初始动态页，也能打开一条记录。日期筛选选择的是快照；完成标注反映的是当前结果。`at` 仍然返回不含完成信息的历史项目快照；按历史时点查询完成状态暂不支持。
+
+导出现在会输出 version 2 包 `{ "version": 2, "entries": [...], "completions": [...] }`。JSONL 每行输出一个完整包。条目保留 UUID 和记录时间；事件保留 UUID，以及每个目标的前驱链接（含撤销）。导入同时接受旧版条目对象、数组、JSONL 和 version 2 包，会检查身份冲突，并按文件原子应用。重复导入同一包是幂等的。事件顺序有意义：须按导出顺序导入；历史不一致时导入失败，不会静默合并。旧客户端无法导入 version 2 包。迁移会给已有快照补上 UUID，不改变其内容。
+
+各自独立迁移的旧数据副本会得到不同的 UUID。跨库导入可能因已存在的 `externalRef` 失败，不会隐式沿用对方身份。要忠实迁移，请把包恢复到一个全新数据库。省略 UUID 的旧写入会被拒绝。若 `externalRef` 已存在，`add` 会保留原快照，并把显式传入的 `--completes` 关联应用到该快照；相同且仍然有效的关联是空操作。事后补关联请使用 `complete`，让对账显式发生。
+
+### 待办与仪表板操作
+
+待办是具体工作的来源。新的状态快照按顺序存储 `nextTodoUids`，不再把下一步原文写入快照。
+`add --next` 会为每条标题创建一个待办，并在同一事务里写入这些 UID。
+之后的快照如果再次输入相同文本，会创建新的待办；要沿用已有工作，请传 `--next-todo`。
+不要把 `--next` 和 `--next-todo` 写在同一次 `add` 里。同一列表里的重复 UID 会被拒绝。
+
+```sh
+pmgr add --project demo --status active --summary "已排队复查" \
+  --next "收集日志" --next "写说明" --source agent --json
+pmgr todo-add --title "未归属的想法" --json
+pmgr add --project demo --status active --summary "钉住这个想法" \
+  --next-todo <todo-uuid> --source agent --json
+pmgr todos --project demo --status open --json
+pmgr todo-update --uid <todo-uuid> --status completed --json
+pmgr todo-update --uid <todo-uuid> --status cancelled --json
+```
+
+`todos --status open` 从待办而不是字符串下一步回答「还有哪些未完成工作」。
+加上 `--project` 时，当前快照钉住的 UID 会排在前面。
+完成或取消待办会立刻反映在所有解析视图上，且不会改写历史快照。
+新快照不再列入某个 UID，只表示它不再是当前下一步，不会改变该待办的状态。
+
+旧快照保留字符串 `nextSteps`，并省略 `nextTodoUids`。转换仍按来源下标显式进行，且不会追加快照。
+只要还有来源下标未转换，完成活动时的后续快照会复制完整字符串列表和 `nextStepsSourceUid`。
+每个下标都已有待办之后，后续快照才按原下标顺序写入 `nextTodoUids`，不新建待办，也不改变状态。
+一条快照不能同时保存原文和引用。
+
+`current` 和 `history` 会带上存储的 `nextTodoUids`，以及实时的 `nextTodos`（`uid`、`title`、`status`、`project`）。
+这个视图是待办的当前状态，不是快照发生时的历史状态。
+`at` 返回当时的快照；如果存了引用就包含引用，但不会附加实时视图。
+
+快照只能引用未归属的待办，或已经属于该项目的待办。
+待办一旦出现在任意 `nextTodoUids` 中，或关联了来源动态，就不能再改项目。
+从当前快照拿掉引用，也不会解除这个限制。
+
+带引用的导出使用 version 4，并包含被引用的待办。
+没有引用、但有待办的导出仍是 version 3。
+version 2 和旧版导入不会凭空创建待办。
+悬空、重复、混用或跨项目引用会使整批导入失败。
+仪表板写入仍只接受同源的 localhost JSON 请求。
+动态卡片上的 **标为已完成** 会追加一条后续动态，既不完成项目，也不完成待办。
+在仪表板里新增待办不会把它钉进当前下一步；钉住需要再写一条快照。

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, importLedger, exportLedger, changeCompletion, listProjects, openLedger, parseTime, setProjectMetadata, startServer, ValidationError, } from "./index.js";
+import { addStatus, createTodo, listTodos, updateTodo, at, current, history, importLedger, exportLedger, changeCompletion, listProjects, openLedger, parseTime, setProjectMetadata, startServer, ValidationError, } from "./index.js";
 const booleanFlags = new Set([
     "json",
     "clear-description",
@@ -12,7 +12,14 @@ const booleanFlags = new Set([
     "help",
     "version",
 ]);
-const repeats = new Set(["next", "blocker", "decision", "tag", "completes"]);
+const repeats = new Set([
+    "next",
+    "next-todo",
+    "blocker",
+    "decision",
+    "tag",
+    "completes",
+]);
 function parse(argv) {
     const command = [];
     const flags = Object.create(null);
@@ -58,6 +65,7 @@ const allowedFlags = new Map([
             "progress",
             "blocker",
             "next",
+            "next-todo",
             "decision",
             "tag",
             "at",
@@ -67,6 +75,9 @@ const allowedFlags = new Map([
             "json",
         ]),
     ],
+    ["todo-add", new Set(["title", "project", "entry", "json"])],
+    ["todos", new Set(["project", "status", "json"])],
+    ["todo-update", new Set(["uid", "status", "project", "json"])],
     ["complete", new Set(["entry", "by", "reason", "source", "json"])],
     ["revoke-completion", new Set(["entry", "by", "reason", "source", "json"])],
     ["import", new Set(["file", "json"])],
@@ -94,9 +105,21 @@ const allowedFlags = new Map([
     ["serve", new Set(["port", "host", "open", "no-open", "json"])],
 ]);
 const commandHelp = {
+    "todo-add": [
+        "Create an independent or linked Todo",
+        "--title <text> [--project <name>] [--entry <uid>] [--json]",
+    ],
+    todos: [
+        "List Todos",
+        "[--project <name>] [--status open|completed|cancelled] [--json]",
+    ],
+    "todo-update": [
+        "Change Todo status or assign a project",
+        "--uid <uuid> [--status open|completed|cancelled] [--project <name>] [--json]",
+    ],
     add: [
         "Append a status snapshot",
-        "--project <name> --summary <text> [options]",
+        "--project <name> --summary <text> [--next <text> | --next-todo <uid>] [options]",
     ],
     complete: [
         "Link a completed activity to its follow-up",
@@ -289,10 +312,45 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
     const json = flags.json === true;
     try {
         switch (action) {
+            case "todo-add":
+                output(createTodo(db, {
+                    title: stringFlag(flags, "title", true),
+                    project: stringFlag(flags, "project"),
+                    entryUid: stringFlag(flags, "entry"),
+                }), json, write);
+                break;
+            case "todos": {
+                const status = stringFlag(flags, "status");
+                if (status !== undefined &&
+                    status !== "open" &&
+                    status !== "completed" &&
+                    status !== "cancelled")
+                    throw new ValidationError("--status must be open, completed, or cancelled");
+                const todos = listTodos(db, stringFlag(flags, "project"), status === undefined
+                    ? {}
+                    : { status: status });
+                if (json)
+                    output(todos, true, write);
+                else
+                    write(todos
+                        .map((t) => `${t.uid}\t${t.status}\t${t.project ?? "-"}\t${t.title}`)
+                        .join("\n") + "\n");
+                break;
+            }
+            case "todo-update":
+                output(updateTodo(db, stringFlag(flags, "uid", true), {
+                    status: stringFlag(flags, "status"),
+                    project: stringFlag(flags, "project"),
+                }), json, write);
+                break;
             case "add": {
                 const project = stringFlag(flags, "project", true);
                 const description = stringFlag(flags, "description");
                 const notes = stringFlag(flags, "notes");
+                const next = listFlag(flags, "next");
+                const nextTodo = listFlag(flags, "next-todo");
+                if (next.length > 0 && nextTodo.length > 0)
+                    throw new ValidationError("cannot combine --next and --next-todo");
                 const result = db
                     .transaction(() => {
                     if (description !== undefined || notes !== undefined) {
@@ -304,7 +362,8 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
                         summary: stringFlag(flags, "summary", true),
                         progress: stringFlag(flags, "progress"),
                         blockers: listFlag(flags, "blocker"),
-                        nextSteps: listFlag(flags, "next"),
+                        nextSteps: next,
+                        ...(nextTodo.length > 0 ? { nextTodoUids: nextTodo } : {}),
                         decisions: listFlag(flags, "decision"),
                         tags: listFlag(flags, "tag"),
                         occurredAt: stringFlag(flags, "at"),

package/dist/db.d.ts

@@ -36,11 +36,14 @@ export type CompletionEvent = {
 export declare function getEntry(db: Ledger, ref: string): StatusEntry | undefined;
 export declare function changeCompletion(db: Ledger, targetRef: string, byRef: string, action?: CompletionEvent["action"], reason?: string, source?: Source): CompletionEvent;
 export declare function exportLedger(db: Ledger, project?: string): {
-    version: number;
+    todos?: Todo[] | undefined;
+    version: 3 | 2 | 4;
     entries: {
         recordedAt: string;
         progress?: string | undefined;
         externalRef?: string | undefined;
+        nextStepsSourceUid?: string | undefined;
+        nextTodoUids?: string[] | undefined;
         uid: string;
         project: string;
         status: import("./domain.js").ProjectStatus;
@@ -55,3 +58,20 @@ export declare function exportLedger(db: Ledger, project?: string): {
     completions: CompletionEvent[];
 };
 export declare function importLedger(db: Ledger, values: unknown[]): InsertResult[];
+export type Todo = {
+    uid: string;
+    title: string;
+    project: string | null;
+    entryUid: string | null;
+    stepIndex: number | null;
+    status: "open" | "completed" | "cancelled";
+    createdAt: string;
+    completedAt: string | null;
+};
+export declare function listTodos(db: Ledger, project?: string, options?: {
+    status?: Todo["status"];
+}): Todo[];
+export declare function createTodo(db: Ledger, value: unknown): Todo;
+export declare function convertNextStep(db: Ledger, ref: string, index: number): Todo;
+export declare function updateTodo(db: Ledger, uid: string, value: unknown): Todo;
+export declare function completeActivity(db: Ledger, ref: string): StatusEntry;