project-mgr 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.1.4 - 2026-08-03
+
+### Changed
+
+- Renamed the Agent Skill from `project-mgr-status` to `project-mgr`.
+
+## 0.1.3 - 2026-08-03
+
+### Added
+
+- Packaged the `project-mgr-status` Agent Skill for status ledger operations.
+
+### Fixed
+
+- Made the CLI run through npm-created `pmgr` symlinks and corrected the no-install examples.
+
 ## 0.1.2 - 2026-08-03
 
 ### Changed

package/README.md

@@ -4,7 +4,7 @@
 
 `project-mgr` is a local-first, append-only ledger for project status. It stores progress, blockers, decisions, and next steps as timestamped status snapshots, so people and AI agents can quickly inspect each project's current state, complete history, or state at a particular time.
 
-The first release provides only a local CLI and SQLite. It has no HTTP API, long-running service, or agent skills. Data stays on the local machine and requires no account or cloud service.
+The first release provides a local CLI, SQLite, and an optional Agent Skill. It has no HTTP API or long-running service. Data stays on the local machine and requires no account or cloud service.
 
 ## Run from npm
 
@@ -13,7 +13,7 @@ Requires Node.js 22+.
 Run without installing:
 
 ```bash
-npx --yes project-mgr current
+npx --yes --package project-mgr pmgr current
 ```
 
 Or install the CLI globally:
@@ -28,9 +28,23 @@ The database defaults to `~/.local/share/project-mgr/project-mgr.sqlite`, regard
 Set `PMGR_DB_PATH` to use another location:
 
 ```bash
-PMGR_DB_PATH=/absolute/path/projects.sqlite npx --yes project-mgr current
+PMGR_DB_PATH=/absolute/path/projects.sqlite npx --yes --package project-mgr pmgr current
 ```
 
+## Install the Agent Skill
+
+The repository includes `skills/project-mgr`, which guides compatible AI agents to add, import, query, and export status records. Install it with the [skills CLI](https://skills.sh/docs/cli):
+
+```bash
+npx skills add deanplus/project-manager
+```
+
+The installer detects supported agents and asks where to install the skill. No separate `project-mgr` installation is required: the skill runs the CLI through `npx`. Restart or reload the selected agent after installation.
+
+The skill uses the same `PMGR_DB_PATH` behavior as the CLI: it defaults to `~/.local/share/project-mgr/project-mgr.sqlite`; set an absolute path to work in another ledger. For manual or exploratory work, use a dedicated database such as `PMGR_DB_PATH=/tmp/project-mgr-skill-test.sqlite` rather than the default ledger.
+
+Then ask the agent, for example: `Use project-mgr to add an active status after checking its current status.`
+
 ## Build from source
 
 Requires Node.js 22+ and pnpm 10.30.2.

package/README_CN.md

@@ -4,7 +4,7 @@
 
 `project-mgr` 是一个本地优先、只追加的项目状态账本。它把项目进展、阻塞、决策和下一步保存为带时间的状态快照，让个人或 AI Agent 能快速查询每个项目的当前状态、完整历史以及某个时间点的状态。
 
-首版只提供本地 CLI 和 SQLite，不包含 HTTP API、常驻服务或 Agent Skills。数据默认保存在本机，无需账号或云服务。
+首版提供本地 CLI、SQLite 和可选的 Agent Skill，不包含 HTTP API 或常驻服务。数据默认保存在本机，无需账号或云服务。
 
 ## 从 npm 运行
 
@@ -13,7 +13,7 @@
 无需安装即可运行：
 
 ```bash
-npx --yes project-mgr current
+npx --yes --package project-mgr pmgr current
 ```
 
 也可以全局安装 CLI：
@@ -28,9 +28,23 @@ pmgr current
 通过 `PMGR_DB_PATH` 指定其他位置：
 
 ```bash
-PMGR_DB_PATH=/absolute/path/projects.sqlite npx --yes project-mgr current
+PMGR_DB_PATH=/absolute/path/projects.sqlite npx --yes --package project-mgr pmgr current
 ```
 
+## 安装 Agent Skill
+
+仓库包含 `skills/project-mgr`，用于指导兼容 Skills 的 AI Agent 新增、导入、查询和导出项目状态记录。通过 [skills CLI](https://skills.sh/docs/cli) 安装：
+
+```bash
+npx skills add deanplus/project-manager
+```
+
+安装器会检测支持的 Agent，并询问安装目标。无需单独安装 `project-mgr`：该 Skill 会通过 `npx` 运行 CLI。安装后重启或重新加载所选 Agent。
+
+该 Skill 与 CLI 使用相同的 `PMGR_DB_PATH` 规则：默认使用 `~/.local/share/project-mgr/project-mgr.sqlite`；如需使用其他账本，请设置绝对路径。手工或探索性操作请使用独立数据库，例如 `PMGR_DB_PATH=/tmp/project-mgr-skill-test.sqlite`，避免写入默认账本。
+
+随后可向 Agent 提出，例如：`使用 project-mgr，在查询当前状态后新增一条 active 状态。`
+
 ## 从源码构建
 
 需要 Node.js 22+ 和 pnpm 10.30.2。

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
+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";
 const repeats = new Set(["next", "blocker", "decision", "tag"]);
@@ -201,7 +201,7 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
 }
 /* c8 ignore start -- process entry glue is covered by the CLI integration tests through run(). */
 if (process.argv[1] &&
-    import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+    import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
     try {
         run(process.argv.slice(2));
     }

package/package.json

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

package/skills/project-mgr/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: project-mgr
+description: Manage project status with the local-first project-mgr CLI. Use when an AI agent needs to add an append-only project update, import status records, query current or historical project state, or export a status ledger.
+---
+
+# Project Mgr
+
+Use `npx --yes --package project-mgr pmgr`. In a source checkout, use `pnpm pmgr` instead.
+
+## Database safety
+
+- Read `PMGR_DB_PATH` before operating. If unset, the CLI uses `~/.local/share/project-mgr/project-mgr.sqlite`.
+- For exploratory or test work, set `PMGR_DB_PATH` to a dedicated absolute SQLite path for every command. Do not use `:memory:` when more than one CLI invocation must share data.
+- Query before writing. `add` appends a snapshot; it does not edit the previous one.
+- Set `--source agent` for agent-authored updates. Use `--external-ref` only when a stable idempotency key is available.
+
+## Operations
+
+Prefer `--json` for data that must be interpreted or reported programmatically.
+
+```bash
+# Add an agent-authored status snapshot.
+npx --yes --package project-mgr pmgr add --project my-project --status active --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 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
+```
+
+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.

package/skills/project-mgr/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Project Manager"
+  short_description: "Manage local project status records safely"
+  default_prompt: "Use $project-mgr to add and inspect this project status."

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
+import { readFileSync, realpathSync } from "node:fs";
+import { basename } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
   addStatus,
@@ -260,7 +260,7 @@ export function run(
 /* c8 ignore start -- process entry glue is covered by the CLI integration tests through run(). */
 if (
   process.argv[1] &&
-  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+  import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href
 ) {
   try {
     run(process.argv.slice(2));

package/test/core.test.ts

@@ -1,8 +1,10 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
+import { fileURLToPath } from "node:url";
 import { run } from "../src/cli.js";
 import {
   addStatus,
@@ -187,6 +189,26 @@ test("database path has a stable default and environment override creates its pa
   rmSync(directory, { recursive: true, force: true });
 });
 
+test("CLI runs through a package-style symlink", () => {
+  const directory = mkdtempSync(join(tmpdir(), "pmgr-bin-"));
+  const executable = join(directory, "pmgr");
+  symlinkSync(
+    fileURLToPath(new URL("../src/cli.ts", import.meta.url)),
+    executable,
+  );
+  const result = spawnSync(
+    process.execPath,
+    ["--import", "tsx", executable, "current", "--json"],
+    {
+      encoding: "utf8",
+      env: { ...process.env, PMGR_DB_PATH: ":memory:" },
+    },
+  );
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stdout, "[]\n");
+  rmSync(directory, { recursive: true, force: true });
+});
+
 test("CLI supports add, import, reads, errors, and export formats", () => {
   const directory = mkdtempSync(join(tmpdir(), "pmgr-cli-"));
   const file = join(directory, "ledger.sqlite");