project-mgr 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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

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.1",
+  "version": "0.3.2",
   "description": "Local-first append-only project status ledger",
   "type": "module",
   "bin": {

package/skills/project-mgr/SKILL.md

@@ -7,7 +7,7 @@ description: Manage project status with the local-first project-mgr CLI. Use whe
 
 ## 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. The current CLI does not implement `--help` or `--version`; do not use those flags as health checks. In a source checkout, use `pnpm pmgr` only when the local dependencies are already installed and the package manager is available without downloading it.
+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.