project-mgr 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.3.2 - 2026-10-16
+
+- Add general and per-command CLI help, no-argument help, and package version aliases without opening the database.
+
+## 0.3.1 - 2026-10-16
+
+### Changed
+
+- Prefer an installed `pmgr` in the Skill and remove automatic `npx @latest` execution from examples.
+- Require explicit status values and evidence-backed historical backfills without a minimum entry count.
+- Document database permission handling, stable ledger paths, and read-back verification after writes.
+
+This release updates Skill guidance only; CLI behavior and storage architecture are unchanged.
+
 ## 0.3.0 - 2026-10-16
 
 ### Added

package/README.md

@@ -127,6 +127,20 @@ Delete `/tmp/project-mgr-manual-test.sqlite` when it is no longer needed.
 
 Automated tests use an in-memory database or SQLite files in the system temporary directory; they do not read or write the default database. `PMGR_DB_PATH=:memory:` also works for one command, but each CLI command runs in a separate process and its data disappears when the command exits, so it is not suitable for consecutive manual tests.
 
+## CLI help and version
+
+```bash
+pmgr                    # Show general help
+pmgr -h                 # Also: --help or help
+pmgr add --help          # Command usage and available options
+pmgr help history       # Equivalent to history -h
+pmgr -v                 # Also: -V, --version, or version
+```
+
+Help and version commands exit successfully without opening or creating a database.
+Version output comes from the installed package metadata. The compatible
+`pmgr status <command> --help` form is also supported.
+
 ## Quick start
 
 Append a project status:

package/dist/cli.js

@@ -3,22 +3,32 @@ 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";
+const booleanFlags = new Set([
+    "json",
+    "clear-description",
+    "clear-notes",
+    "open",
+    "no-open",
+    "help",
+    "version",
+]);
 const repeats = new Set(["next", "blocker", "decision", "tag", "completes"]);
 function parse(argv) {
     const command = [];
     const flags = Object.create(null);
     for (let index = 0; index < argv.length; index += 1) {
-        const token = argv[index];
+        const raw = argv[index];
+        const token = raw === "-h"
+            ? "--help"
+            : raw === "-v" || raw === "-V"
+                ? "--version"
+                : raw;
         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 (booleanFlags.has(key)) {
             if (flags[key] !== undefined)
                 throw new ValidationError(`--${key} may only be supplied once`);
             flags[key] = true;
@@ -83,6 +93,78 @@ const allowedFlags = new Map([
     ["export", new Set(["project", "format"])],
     ["serve", new Set(["port", "host", "open", "no-open", "json"])],
 ]);
+const commandHelp = {
+    add: [
+        "Append a status snapshot",
+        "--project <name> --summary <text> [options]",
+    ],
+    complete: [
+        "Link a completed activity to its follow-up",
+        "--entry <id-or-uid> --by <id-or-uid> [options]",
+    ],
+    "revoke-completion": [
+        "Revoke an activity completion link",
+        "--entry <id-or-uid> --by <id-or-uid> [options]",
+    ],
+    import: [
+        "Import a JSON or JSONL ledger",
+        "<file> [--json] | --file <path> [--json]",
+    ],
+    current: [
+        "Show the latest status of each project",
+        "[--project <name>] [--json]",
+    ],
+    projects: ["List or search projects", "[--query <text>] [--json]"],
+    list: ["Alias for projects", "[--query <text>] [--json]"],
+    "set-project": ["Update project metadata", "--project <name> [options]"],
+    history: [
+        "Show status history, newest first",
+        "[--project <name>] [options]",
+    ],
+    at: [
+        "Show a project's status at a time",
+        "--project <name> --at <ISO-timestamp> [--json]",
+    ],
+    export: [
+        "Export a portable ledger",
+        "[--project <name>] [--format json|jsonl]",
+    ],
+    serve: [
+        "Start the local web dashboard",
+        "[--port <number>] [--host <address>] [--no-open] [--json]",
+    ],
+};
+function help(action) {
+    if (action) {
+        const [description, usage] = commandHelp[action];
+        const options = [...allowedFlags.get(action)].map((key) => `  --${key}${booleanFlags.has(key) ? "" : " <value>"}${repeats.has(key) ? " (repeatable)" : ""}`);
+        return `Usage: pmgr ${action} ${usage}\n\n${description}\n\nOptions:\n${options.join("\n")}\n  -h, --help  Show this help\n`;
+    }
+    return `Usage: pmgr <command> [options]
+       pmgr status <command> [options]
+
+Local-first, append-only project status ledger.
+
+Commands:
+${Object.entries(commandHelp)
+        .map(([name, [description]]) => `  ${name.padEnd(20)}${description}`)
+        .join("\n")}
+  help [command]      Show general or command help
+  version             Show the installed package version
+
+Options:
+  -h, --help          Show help (also supported after a command)
+  -v, -V, --version   Show the installed package version
+
+Environment:
+  PMGR_DB_PATH        SQLite path (default: ~/.local/share/project-mgr/project-mgr.sqlite)
+
+Examples:
+  pmgr current --json
+  pmgr add --project demo --status active --summary "Work started"
+  pmgr help history
+`;
+}
 function validateInvocation(command, flags) {
     const statusCommand = command[0] === "status";
     const action = command[statusCommand ? 1 : 0];
@@ -182,6 +264,26 @@ function imported(file) {
 }
 export function run(argv, write = process.stdout.write.bind(process.stdout)) {
     const { command, flags } = parse(argv);
+    if (command[0] === "help") {
+        command.shift();
+        flags.help = true;
+    }
+    if (argv.length === 0 || flags.help === true) {
+        delete flags.help;
+        const action = command.length || Object.keys(flags).length
+            ? validateInvocation(command, flags)
+            : undefined;
+        write(help(action));
+        return;
+    }
+    if (flags.version === true || command[0] === "version") {
+        if (Object.keys(flags).some((key) => key !== "version") ||
+            (command.length > 0 && (command.length !== 1 || command[0] !== "version")))
+            throw new ValidationError("usage: pmgr --version (or: pmgr version)");
+        const metadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        write(`${metadata.version}\n`);
+        return;
+    }
     const action = validateInvocation(command, flags);
     const db = openLedger();
     const json = flags.json === true;

package/package.json

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

package/skills/project-mgr/SKILL.md

@@ -5,7 +5,11 @@ description: Manage project status with the local-first project-mgr CLI. Use whe
 
 # project-mgr
 
-Use `npx --yes --package project-mgr@latest pmgr`. In a source checkout, use `pnpm pmgr` instead.
+## CLI selection
+
+Prefer an installed `pmgr`: locate it with `command -v pmgr` and check the installed package metadata/documentation for the required version and capabilities. This source revision supports `-h` / `--help`, `help [command]`, and `-v` / `-V` / `--version` / `version` without opening the database. Older installed releases may not support these flags; inspect their package metadata instead. In a source checkout, use `pnpm pmgr` only when the local dependencies are already installed and the package manager is available without downloading it.
+
+Do not automatically install or upgrade dependencies, or fall back to `npx` / `npm exec`. If no usable CLI is available, report the missing executable, dependency, or capability and the setup needed. Perform installation or upgrades only when the user authorizes that setup.
 
 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.
 
@@ -13,9 +17,12 @@ Completion links and version-2 exports require project-mgr 0.3.0 or later. This
 
 - 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.
+- The database file and its parent directory must be accessible with the permissions SQLite needs for journal files and writes. Even query commands open the ledger and may initialize or migrate it; do not assume they are filesystem-read-only.
+- On a permission or read-only database error, report the command, resolved database path, and error without exposing credentials. Use the environment's approved permission mechanism when available; otherwise report the blocked operation. Do not reinstall the CLI, change permissions, or silently switch to another database to work around the error. Change the ledger location only when the user requests it.
+- Query before writing. `add` appends a snapshot; it does not edit the previous one. Read back the affected state after writing and report success only when verified. If a write's outcome is uncertain, query before retrying to avoid duplicates.
 - Set `--source agent` for agent-authored updates. Use `--external-ref` only when a stable idempotency key is available.
-- If the project is not yet in the ledger database, initialize its metadata with `set-project`, backfill 3–5 historical major changes/milestones using `add` (setting appropriate historical `--at` timestamps), and then append the latest status snapshot.
+- Explicitly pass `--status` on every `add`, and include `status` in every agent-authored import entry. The CLI defaults to `completed`; do not rely on that default. Choose the status from the evidence and inspect the current snapshot when unclear. Completing one activity does not necessarily complete the project; use `active` when project work continues. If the status remains uncertain, clarify before writing.
+- If the project is not yet in the ledger database, initialize its metadata with `set-project`. Backfill only milestones supported by verifiable Git commits, dated documents, or historical records, and include the evidence reference in `--progress`. Use historical `--at` timestamps only when supported by that evidence; a commit timestamp proves a commit, not a deployment. There is no required number of entries. Never invent milestones or dates; when evidence is unavailable, skip backfill and append only the current known status.
 
 ## Metadata vs. status entries
 
@@ -32,32 +39,32 @@ 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@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
+pmgr set-project --project my-project --description "Project summary" --notes "Internal notes" --json
+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@latest pmgr projects --json
-npx --yes --package project-mgr@latest pmgr list --query "keyword" --json
+pmgr projects --json
+pmgr list --query "keyword" --json
 
 # Start the local Web Dashboard & REST API server.
-npx --yes --package project-mgr@latest pmgr serve --port 3000 --no-open --json
+pmgr serve --port 3000 --no-open --json
 
-# Add an agent-authored status snapshot (status defaults to completed if omitted).
-npx --yes --package project-mgr@latest pmgr add --project my-project --summary "Implemented the CLI" \
+# Record a completed milestone while the project remains active.
+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@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
+pmgr current --project my-project --json
+pmgr history --project my-project --limit 20 --json
+pmgr history --limit 20 --json
+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@latest pmgr import statuses.jsonl --json
-npx --yes --package project-mgr@latest pmgr export --project my-project --format jsonl > statuses.jsonl
+pmgr import statuses.jsonl --json
+pmgr export --project my-project --format jsonl > statuses.jsonl
 ```
 
-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.
+Use `PMGR_DB_PATH=/absolute/path/test.sqlite 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