project-mgr 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-mgr",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Local-first append-only project status ledger",
   "type": "module",
   "bin": {
@@ -34,5 +34,11 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@10.30.2"
+  "packageManager": "pnpm@10.30.2",
+  "files": [
+    "dist/",
+    "skills/",
+    "README_CN.md",
+    "CHANGELOG.md"
+  ]
 }

package/skills/project-mgr/SKILL.md

@@ -5,7 +5,9 @@ description: Manage project status with the local-first project-mgr CLI. Use whe
 
 # project-mgr
 
-Use `npx --yes --package project-mgr pmgr`. In a source checkout, use `pnpm pmgr` instead.
+Use `npx --yes --package project-mgr@latest pmgr`. In a source checkout, use `pnpm pmgr` instead.
+
+Completion links and version-2 exports require project-mgr 0.3.0 or later. This skill is updated through Git and has no independent release version.
 
 ## Database safety
 
@@ -30,29 +32,39 @@ Prefer `--json` for data that must be interpreted or reported programmatically.
 
 ```bash
 # Set, update, or clear project metadata (description, notes, display name).
-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
+npx --yes --package project-mgr@latest pmgr set-project --project my-project --description "Project summary" --notes "Internal notes" --json
+npx --yes --package project-mgr@latest 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
+npx --yes --package project-mgr@latest pmgr projects --json
+npx --yes --package project-mgr@latest pmgr list --query "keyword" --json
 
 # Start the local Web Dashboard & REST API server.
-npx --yes --package project-mgr pmgr serve --port 3000 --no-open --json
+npx --yes --package project-mgr@latest 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" \
+npx --yes --package project-mgr@latest 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
-npx --yes --package project-mgr pmgr history --project my-project --limit 20 --json
-npx --yes --package project-mgr pmgr history --limit 20 --json
-npx --yes --package project-mgr pmgr at --project my-project --at 2026-08-03T12:00:00+08:00 --json
+npx --yes --package project-mgr@latest pmgr current --project my-project --json
+npx --yes --package project-mgr@latest pmgr history --project my-project --limit 20 --json
+npx --yes --package project-mgr@latest pmgr history --limit 20 --json
+npx --yes --package project-mgr@latest pmgr at --project my-project --at 2026-08-03T12:00:00+08:00 --json
 
 # Import validated JSON/JSONL, or export portable records.
-npx --yes --package project-mgr pmgr import statuses.jsonl --json
-npx --yes --package project-mgr pmgr export --project my-project --format jsonl > statuses.jsonl
+npx --yes --package project-mgr@latest pmgr import statuses.jsonl --json
+npx --yes --package project-mgr@latest pmgr export --project my-project --format jsonl > statuses.jsonl
 ```
 
-Use `PMGR_DB_PATH=/absolute/path/test.sqlite npx --yes --package project-mgr pmgr ...` to isolate a manual test database. Import validates the entire batch before one transaction writes it; export output can be imported directly.
+Use `PMGR_DB_PATH=/absolute/path/test.sqlite npx --yes --package project-mgr@latest pmgr ...` to isolate a manual test database. Import validates and writes the entire batch within one transaction; export output can be imported directly.
+
+## Complete predecessor activities
+
+Before recording follow-up work, inspect `history --project <name> --json`, including the original `status`, `effectiveStatus`, and `completedBy` evidence. Do not interpret a missing completion link as unfinished work. Inspect older pages with `--offset` when needed.
+
+When this update resolves all commitments of earlier entries (including blockers and next steps), pass repeatable `--completes <id-or-uid>` to `add`. One follow-up may complete several entries. For partial progress, describe the remaining work and do not link. A commit/deployment is sufficient only when it resolves all the targeted entry's commitments.
+
+Use `complete --entry <id-or-uid> --by <id-or-uid> --source agent` for an existing follow-up. Use `revoke-completion --entry <id-or-uid> --by <id-or-uid> --reason "..." --source agent` to correct a mistaken link. Links require the same project and strictly increasing occurrence times. Query the affected history afterward to verify effective completion. Do not bulk-close old entries without evidence.
+
+Export produces version-2 bundles (one bundle per line for JSONL), preserving entry/event identities and audit history; legacy imports remain supported. `at` has no completion annotations. Project current state still comes from the latest snapshot.

package/.claude/settings.local.json

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

package/.env_sample

@@ -1,10 +0,0 @@
-# Optional SQLite database override. When unset, the database is stored at
-# ~/.local/share/project-mgr/project-mgr.sqlite.
-# Use a literal absolute path here; .env files do not expand ~ or $HOME.
-# PMGR_DB_PATH=/absolute/path/to/project-mgr.sqlite
-
-# For isolated manual testing, use a separate database instead:
-# PMGR_DB_PATH=/tmp/project-mgr-manual-test.sqlite
-
-# Local Web server port.
-PORT=3000

package/.prettierignore

@@ -1,4 +0,0 @@
-dist
-coverage
-node_modules
-data

package/AGENTS.md

@@ -1,5 +0,0 @@
-# Project instructions
-
-Follow the user-level instructions in `~/.agents/AGENTS.md`.
-
-Unless the user explicitly requests another language, write project files, code comments, documentation, changelog entries, and agent-authored artifacts in English.

package/docs/architecture.md

@@ -1,95 +0,0 @@
-# Architecture
-
-## Design goals
-
-`project-mgr` is a local, single-machine, append-only project status ledger. The first release follows four principles:
-
-- History is never overwritten: every write appends a status snapshot.
-- One source of truth: the CLI and any future interfaces must reuse the same domain and database logic.
-- Clear time semantics: distinguish when a status occurred from when the system recorded it.
-- Portable: exports can be imported into a new database to restore the status timeline.
-
-The first release has no work that needs to run continuously, so it provides neither an HTTP API nor PM2 configuration. Consider a service layer only when other local processes need a stable interface or background jobs.
-
-## Module boundaries
-
-```text
-User / script
-    │
-    ▼
-src/cli.ts       Argument parsing, file input, output formatting, command-level constraints
-    │
-    ├──────────────► src/domain.ts
-    │                 Types, field validation, time normalization, portable record conversion
-    ▼
-src/db.ts        SQLite connection, migrations, transactions, idempotent writes, and queries
-    │
-    ▼
-SQLite file
-```
-
-`src/index.ts` exports only public types and functions. Business validation does not depend on the CLI, so bulk imports and direct database API calls use the same rules.
-
-The CLI accepts `pmgr <action>` for `add`, `import`, `current`, `history`, `at`, and `export`; `pmgr status <action>` remains a compatible form. Both forms share the same validation and execution path.
-
-## Data model
-
-The database contains three structures:
-
-- `schema_migrations`: Applied migration versions (1: base tables, 2: project description & notes columns).
-- `projects`: Project slug, display name, description, notes, and creation time.
-- `status_entries`: Immutable status snapshots and their project foreign keys.
-
-Key `status_entries` fields:
-
-| Field                                                             | Meaning                                                                                  |
-| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `status`, `summary`, `progress`                                   | Status enum, summary, and completed work                                                 |
-| `blockers_json`, `next_steps_json`, `decisions_json`, `tags_json` | JSON-encoded string arrays                                                               |
-| `occurred_at`                                                     | When the status actually occurred, supplied by the caller or generated during validation |
-| `recorded_at`                                                     | When the database actually wrote the entry                                               |
-| `source`                                                          | `human`, `agent`, or `import`                                                            |
-| `external_ref`                                                    | Optional globally unique idempotency key                                                 |
-
-The `project_id, occurred_at DESC, id DESC` index supports current-status and history queries.
-
-## Initialization and migrations
-
-After opening the database, `openLedger()` enables foreign keys, creates the migration table, and checks for and applies migrations 1 and 2 within a `BEGIN IMMEDIATE` transaction. The immediate transaction prevents migration checks and writes from interleaving when several local processes open the database for the first time at once.
-
-The database path is read from `PMGR_DB_PATH` first; otherwise, it uses the absolute path `~/.local/share/project-mgr/project-mgr.sqlite`, resolved from the current user's home directory. Non-memory databases create their parent directory automatically.
-
-## Write flow
-
-A single write proceeds as follows:
-
-1. Reject unknown fields and validate the project name, status, source, string arrays, and time.
-2. Normalize all timestamps to UTC ISO 8601 strings.
-3. In a transaction, check `externalRef`: repeated calls for the same project return the existing entry; cross-project conflicts fail.
-4. Create the project when needed, then append a status snapshot.
-5. Read and return the final entry from the database.
-
-Bulk import validates all input first, then executes the same write logic for each entry in one transaction. A database constraint or any failed write rolls back the entire batch.
-
-## Query semantics
-
-- Current status: take the first entry for each project ordered by `occurred_at DESC, id DESC`.
-- History: use the same occurrence-time and ID descending order, with inclusive `since` / `until` bounds and `limit` / `offset`.
-- Status at a time: take the first entry with `occurred_at <=` the specified time.
-- Same occurrence time: the later-written, larger `id` wins, keeping results deterministic.
-
-All ISO 8601 timestamps are converted to UTC on write, so SQLite string ordering matches time ordering.
-
-## Import and export
-
-Complete records returned by database queries include the internal `id` and `recordedAt`. The export layer removes these read-only fields while preserving business fields, original source, and the idempotency key, so JSON and JSONL can pass strict input validation when imported again.
-
-Exports have no record limit and reverse descending history results into oldest-to-newest order. When restoring to an empty database, entries with the same `occurredAt` receive IDs in their original append order, so the current status remains the same.
-
-## Consistency and limits
-
-- SQLite transactions guarantee atomic single writes and bulk imports.
-- `externalRef` is unique across the entire database; cross-project reuse is explicitly rejected.
-- Current status is derived from history; no separate cache table can drift.
-- Version 1 is for trusted local users and includes no authentication, authorization, multi-user synchronization, or encryption.
-- JSON arrays are stored as text. Evaluate a normalized schema only when cross-field full-text search or complex tag statistics are needed.

package/ecosystem.config.cjs

@@ -1,21 +0,0 @@
-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/eslint.config.js

@@ -1,12 +0,0 @@
-import plugin from "@typescript-eslint/eslint-plugin";
-import parser from "@typescript-eslint/parser";
-
-export default [
-  {
-    files: ["src/**/*.ts", "test/**/*.ts"],
-    ignores: ["dist/**", "coverage/**", "node_modules/**"],
-    languageOptions: { parser },
-    plugins: { "@typescript-eslint": plugin },
-    rules: { "@typescript-eslint/no-unused-vars": "error" },
-  },
-];

package/pnpm-workspace.yaml

@@ -1,3 +0,0 @@
-onlyBuiltDependencies:
-  - better-sqlite3
-  - esbuild

package/src/cli.ts

@@ -1,399 +0,0 @@
-#!/usr/bin/env node
-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,
-  type ProjectOverview,
-  type ProjectStatus,
-  setProjectMetadata,
-  startServer,
-  toPortableStatusEntry,
-  ValidationError,
-} from "./index.js";
-
-type Flags = Record<string, string | string[] | boolean>;
-const repeats = new Set(["next", "blocker", "decision", "tag"]);
-
-function parse(argv: string[]): { command: string[]; flags: Flags } {
-  const command: string[] = [];
-  const flags: Flags = Object.create(null) as Flags;
-  for (let index = 0; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (!token.startsWith("--")) {
-      command.push(token);
-      continue;
-    }
-    const key = token.slice(2);
-    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;
-      continue;
-    }
-    const value = argv[++index];
-    if (!value || value.startsWith("--"))
-      throw new ValidationError(`--${key} requires a value`);
-    if (repeats.has(key))
-      flags[key] = [...((flags[key] as string[] | undefined) ?? []), value];
-    else if (flags[key] !== undefined)
-      throw new ValidationError(`--${key} may only be supplied once`);
-    else flags[key] = value;
-  }
-  return { command, flags };
-}
-
-const allowedFlags = new Map<string, ReadonlySet<string>>([
-  [
-    "add",
-    new Set([
-      "project",
-      "status",
-      "summary",
-      "description",
-      "notes",
-      "progress",
-      "blocker",
-      "next",
-      "decision",
-      "tag",
-      "at",
-      "source",
-      "external-ref",
-      "json",
-    ]),
-  ],
-  ["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: string[], flags: Flags): string {
-  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|serve> (or: pmgr status <action>)",
-    );
-  const positional = command.slice(statusCommand ? 2 : 1);
-  if (action === "import") {
-    if (positional.length > 1)
-      throw new ValidationError("import accepts at most one file argument");
-    if (positional.length === 1 && flags.file !== undefined)
-      throw new ValidationError(
-        "import file must be positional or --file, not both",
-      );
-  } else if (positional.length) {
-    throw new ValidationError(`${action} does not accept positional arguments`);
-  }
-  for (const key of Object.keys(flags))
-    if (!allowed.has(key))
-      throw new ValidationError(`unknown flag for ${action}: --${key}`);
-  return action;
-}
-
-function stringFlag(
-  flags: Flags,
-  name: string,
-  required = false,
-): string | undefined {
-  const value = flags[name];
-  if (required && typeof value !== "string")
-    throw new ValidationError(`--${name} is required`);
-  return typeof value === "string" ? value : undefined;
-}
-
-function listFlag(flags: Flags, name: string): string[] {
-  return (flags[name] as string[] | undefined) ?? [];
-}
-function numberFlag(flags: Flags, name: string, fallback: number): number {
-  const value = stringFlag(flags, name);
-  if (!value) return fallback;
-  const number = Number(value);
-  if (!Number.isInteger(number) || number < 0)
-    throw new ValidationError(`--${name} must be a non-negative integer`);
-  return number;
-}
-
-function output(
-  value: unknown,
-  json: boolean,
-  write: (text: string) => void,
-): void {
-  if (json) write(`${JSON.stringify(value)}\n`);
-  else if (Array.isArray(value)) {
-    const rows = value
-      .map(
-        (entry) =>
-          `${entry.project}\t${entry.status}\t${entry.occurredAt}\t${entry.summary}`,
-      )
-      .join("\n");
-    write(`${rows || "No entries found."}\n`);
-  } else write(`${JSON.stringify(value, null, 2)}\n`);
-}
-
-function formatProjectOverview(item: ProjectOverview): string {
-  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: ProjectOverview[],
-  json: boolean,
-  write: (text: string) => void,
-): void {
-  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: string): unknown[] {
-  if (!file) throw new ValidationError("import file is required");
-  const content = readFileSync(file, "utf8").trim();
-  if (!content) throw new ValidationError(`${basename(file)} is empty`);
-  if (file.endsWith(".jsonl"))
-    return content.split(/\r?\n/).map((line, index) => {
-      try {
-        return JSON.parse(line) as unknown;
-      } catch {
-        throw new ValidationError(
-          `${basename(file)} line ${index + 1} is not JSON`,
-        );
-      }
-    });
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(content) as unknown;
-  } catch {
-    throw new ValidationError(`${basename(file)} is not JSON`);
-  }
-  return Array.isArray(parsed) ? parsed : [parsed];
-}
-
-export function run(
-  argv: string[],
-  write = process.stdout.write.bind(process.stdout),
-): unknown {
-  const { command, flags } = parse(argv);
-  const action = validateInvocation(command, flags);
-  const db = openLedger();
-  const json = flags.json === true;
-  try {
-    switch (action) {
-      case "add": {
-        const project = stringFlag(flags, "project", true) as string;
-        const description = stringFlag(flags, "description");
-        const notes = stringFlag(flags, "notes");
-        if (description !== undefined || notes !== undefined) {
-          setProjectMetadata(db, { project, description, notes });
-        }
-        output(
-          addStatus(db, {
-            project,
-            status: stringFlag(flags, "status") as unknown as ProjectStatus,
-            summary: stringFlag(flags, "summary", true),
-            progress: stringFlag(flags, "progress"),
-            blockers: listFlag(flags, "blocker"),
-            nextSteps: listFlag(flags, "next"),
-            decisions: listFlag(flags, "decision"),
-            tags: listFlag(flags, "tag"),
-            occurredAt: stringFlag(flags, "at"),
-            source: stringFlag(flags, "source"),
-            externalRef: stringFlag(flags, "external-ref"),
-          }).entry,
-          json,
-          write,
-        );
-        break;
-      }
-
-      case "import":
-        output(
-          importStatuses(
-            db,
-            imported(
-              stringFlag(flags, "file") ??
-                command[command[0] === "status" ? 2 : 1] ??
-                "",
-            ),
-          ).map((result) => result.entry),
-          json,
-          write,
-        );
-        break;
-      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) as string;
-        const displayName = stringFlag(flags, "display-name");
-        let description: string | null | undefined = 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: string | null | undefined = 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") &&
-              parseTime(stringFlag(flags, "since"), "since"),
-            until:
-              stringFlag(flags, "until") &&
-              parseTime(stringFlag(flags, "until"), "until"),
-            limit: numberFlag(flags, "limit", 100),
-            offset: numberFlag(flags, "offset", 0),
-          }),
-          json,
-          write,
-        );
-        break;
-      case "at":
-        output(
-          at(
-            db,
-            stringFlag(flags, "project", true) as string,
-            parseTime(stringFlag(flags, "at", true), "at"),
-          ) ?? null,
-          json,
-          write,
-        );
-        break;
-      case "export": {
-        const entries = history(db, stringFlag(flags, "project"), {
-          limit: -1,
-        })
-          .reverse()
-          .map(toPortableStatusEntry);
-        const format = stringFlag(flags, "format") ?? "json";
-        if (format === "jsonl")
-          write(
-            entries.map((entry) => JSON.stringify(entry)).join("\n") +
-              (entries.length ? "\n" : ""),
-          );
-        else if (format === "json") output(entries, true, write);
-        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 {
-    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 {
-    await run(process.argv.slice(2));
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
-  }
-}
-/* c8 ignore stop */