@unbrained/pm-cli 2026.3.9

package/dist/serialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.js","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC"}

package/dist/settings.d.ts

@@ -0,0 +1 @@
+export * from "./core/store/settings.js";

package/dist/settings.js

@@ -0,0 +1,2 @@
+export * from "./core/store/settings.js";
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}

package/dist/time.d.ts

@@ -0,0 +1 @@
+export * from "./core/shared/time.js";

package/dist/time.js

@@ -0,0 +1,2 @@
+export * from "./core/shared/time.js";
+//# sourceMappingURL=time.js.map

package/dist/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export * from "../types.js";

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export * from "../types.js";
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,179 @@
+export declare const ITEM_TYPE_VALUES: readonly ["Epic", "Feature", "Task", "Chore", "Issue"];
+export type ItemType = (typeof ITEM_TYPE_VALUES)[number];
+export declare const STATUS_VALUES: readonly ["draft", "open", "in_progress", "blocked", "closed", "canceled"];
+export type ItemStatus = (typeof STATUS_VALUES)[number];
+export declare const DEPENDENCY_KIND_VALUES: readonly ["blocks", "parent", "child", "related", "discovered_from"];
+export type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];
+export declare const SCOPE_VALUES: readonly ["project", "global"];
+export type LinkScope = (typeof SCOPE_VALUES)[number];
+export declare const RISK_VALUES: readonly ["low", "medium", "high", "critical"];
+export type RiskLevel = (typeof RISK_VALUES)[number];
+export declare const ISSUE_SEVERITY_VALUES: readonly ["low", "medium", "high", "critical"];
+export type IssueSeverity = (typeof ISSUE_SEVERITY_VALUES)[number];
+export declare const CONFIDENCE_TEXT_VALUES: readonly ["low", "medium", "high"];
+export type ConfidenceTextLevel = (typeof CONFIDENCE_TEXT_VALUES)[number];
+export type ConfidenceValue = number | ConfidenceTextLevel;
+export interface Dependency {
+    id: string;
+    kind: DependencyKind;
+    created_at: string;
+    author?: string;
+}
+export interface Comment {
+    created_at: string;
+    author: string;
+    text: string;
+}
+export interface LogNote {
+    created_at: string;
+    author: string;
+    text: string;
+}
+export interface LinkedFile {
+    path: string;
+    scope: LinkScope;
+    note?: string;
+}
+export interface LinkedTest {
+    command?: string;
+    path?: string;
+    scope: LinkScope;
+    timeout_seconds?: number;
+    note?: string;
+}
+export interface LinkedDoc {
+    path: string;
+    scope: LinkScope;
+    note?: string;
+}
+export interface ItemFrontMatter {
+    id: string;
+    title: string;
+    description: string;
+    type: ItemType;
+    status: ItemStatus;
+    priority: 0 | 1 | 2 | 3 | 4;
+    tags: string[];
+    created_at: string;
+    updated_at: string;
+    deadline?: string;
+    assignee?: string;
+    author?: string;
+    estimated_minutes?: number;
+    acceptance_criteria?: string;
+    definition_of_ready?: string;
+    order?: number;
+    goal?: string;
+    objective?: string;
+    value?: string;
+    impact?: string;
+    outcome?: string;
+    why_now?: string;
+    parent?: string;
+    reviewer?: string;
+    risk?: "low" | "medium" | "high" | "critical";
+    confidence?: ConfidenceValue;
+    sprint?: string;
+    release?: string;
+    blocked_by?: string;
+    blocked_reason?: string;
+    unblock_note?: string;
+    reporter?: string;
+    severity?: IssueSeverity;
+    environment?: string;
+    repro_steps?: string;
+    resolution?: string;
+    expected_result?: string;
+    actual_result?: string;
+    affected_version?: string;
+    fixed_version?: string;
+    component?: string;
+    regression?: boolean;
+    customer_impact?: string;
+    dependencies?: Dependency[];
+    comments?: Comment[];
+    notes?: LogNote[];
+    learnings?: LogNote[];
+    files?: LinkedFile[];
+    tests?: LinkedTest[];
+    docs?: LinkedDoc[];
+    close_reason?: string;
+}
+export interface ItemDocument {
+    front_matter: ItemFrontMatter;
+    body: string;
+}
+export interface HistoryPatchOp {
+    op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+    path: string;
+    from?: string;
+    value?: unknown;
+}
+export interface HistoryEntry {
+    ts: string;
+    author: string;
+    op: string;
+    patch: HistoryPatchOp[];
+    before_hash: string;
+    after_hash: string;
+    message?: string;
+}
+export interface PmSettings {
+    version: number;
+    id_prefix: string;
+    author_default: string;
+    locks: {
+        ttl_seconds: number;
+    };
+    output: {
+        default_format: "toon" | "json";
+    };
+    workflow: {
+        definition_of_done: string[];
+    };
+    extensions: {
+        enabled: string[];
+        disabled: string[];
+    };
+    search: {
+        score_threshold: number;
+        hybrid_semantic_weight: number;
+        max_results: number;
+        embedding_model: string;
+        embedding_batch_size: number;
+        scanner_max_batch_retries: number;
+        tuning?: {
+            title_exact_bonus?: number;
+            title_weight?: number;
+            description_weight?: number;
+            tags_weight?: number;
+            status_weight?: number;
+            body_weight?: number;
+            comments_weight?: number;
+            notes_weight?: number;
+            learnings_weight?: number;
+            dependencies_weight?: number;
+            linked_content_weight?: number;
+        };
+    };
+    providers: {
+        openai: {
+            base_url: string;
+            api_key: string;
+            model: string;
+        };
+        ollama: {
+            base_url: string;
+            model: string;
+        };
+    };
+    vector_store: {
+        qdrant: {
+            url: string;
+            api_key: string;
+        };
+        lancedb: {
+            path: string;
+        };
+    };
+}

package/dist/types.js

@@ -0,0 +1,21 @@
+export const ITEM_TYPE_VALUES = ["Epic", "Feature", "Task", "Chore", "Issue"];
+export const STATUS_VALUES = [
+    "draft",
+    "open",
+    "in_progress",
+    "blocked",
+    "closed",
+    "canceled",
+];
+export const DEPENDENCY_KIND_VALUES = [
+    "blocks",
+    "parent",
+    "child",
+    "related",
+    "discovered_from",
+];
+export const SCOPE_VALUES = ["project", "global"];
+export const RISK_VALUES = ["low", "medium", "high", "critical"];
+export const ISSUE_SEVERITY_VALUES = ["low", "medium", "high", "critical"];
+export const CONFIDENCE_TEXT_VALUES = ["low", "medium", "high"];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAGvF,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,OAAO;IACP,MAAM;IACN,aAAa;IACb,SAAS;IACT,QAAQ;IACR,UAAU;CACF,CAAC;AAGX,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,SAAS;IACT,iBAAiB;CACT,CAAC;AAGX,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAU,CAAC;AAG3D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AAG1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AAGpF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,246 @@
+# pm-cli Architecture
+
+This document describes the internal architecture of `pm-cli` for contributors and maintainers.
+
+## Overview
+
+`pm-cli` is a TypeScript ESM CLI built on Node.js 20+. It follows a clean separation between CLI wiring and domain logic:
+
+```
+src/
+  cli/            CLI layer: command registration, option parsing, output rendering
+  core/           Domain logic: storage, locking, history, search, extensions
+  extensions/     Built-in extension implementations (beads, todos)
+  types/          Shared TypeScript type definitions
+```
+
+## Source Tree
+
+```
+src/
+  cli.ts                         Main CLI entry (shim that imports cli/main.ts)
+  cli/
+    main.ts                      Command registration with commander; global option wiring
+    commands/
+      init.ts                    pm init
+      create.ts                  pm create (full schema flag surface)
+      get.ts                     pm get
+      update.ts                  pm update
+      append.ts                  pm append
+      close.ts                   pm close
+      delete.ts                  pm delete
+      claim.ts                   pm claim / release
+      release.ts                 (re-exports from claim.ts)
+      list.ts                    pm list (active-only: excludes closed/canceled) / list-all / list-* commands
+      comments.ts                pm comments
+      files.ts                   pm files
+      docs.ts                    pm docs
+      test.ts                    pm test (add/remove/run linked tests)
+      test-all.ts                pm test-all (orchestration)
+      search.ts                  pm search (keyword / semantic / hybrid)
+      reindex.ts                 pm reindex
+      history.ts                 pm history
+      activity.ts                pm activity
+      restore.ts                 pm restore
+      stats.ts                   pm stats
+      health.ts                  pm health
+      gc.ts                      pm gc
+      config.ts                  pm config
+      install.ts                 pm install pi
+      completion.ts              pm completion
+      beads.ts                   pm beads (subcommand router to built-in extension)
+      index.ts                   barrel re-export
+    extension-command-options.ts Loose option parser for dynamic extension commands
+  core/
+    extensions/
+      loader.ts                  Extension manifest discovery, load, activate
+      builtins.ts                Built-in extension registrations
+      index.ts                   barrel
+    fs/
+      fs-utils.ts                Atomic write, path existence, mkdirp
+      index.ts                   barrel
+    history/
+      history.ts                 RFC6902 patch generation, history append, replay
+      index.ts                   barrel
+    item/
+      id.ts                      ID generation (cryptographic random base36) and normalization
+      item-format.ts             Item front-matter serializer (canonical key order, determinism)
+      parse.ts                   Markdown item file parser (JSON front-matter + body)
+      index.ts                   barrel
+    lock/
+      lock.ts                    Exclusive lock acquire/release with TTL and stale detection
+      index.ts                   barrel
+    output/
+      output.ts                  TOON / JSON output rendering
+    search/
+      cache.ts                   Keyword index artifact read/write (manifest.json + embeddings.jsonl)
+      embedding-batches.ts       Deterministic batch embedding generation with retry
+      providers.ts               OpenAI / Ollama embedding provider abstraction
+      vector-stores.ts           Qdrant / LanceDB vector store abstraction
+    shared/
+      command-types.ts           GlobalOptions, shared command type definitions
+      constants.ts               Exit codes, required directory names
+      errors.ts                  PmCliError with exit code
+      serialization.ts           Deterministic JSON serialization (stable key order)
+      time.ts                    ISO timestamp helpers, relative deadline parsing
+      index.ts                   barrel
+    store/
+      item-store.ts              File-backed item CRUD with lock/atomic write contract
+      paths.ts                   PM root resolution (PM_PATH, --path, cwd)
+      settings.ts                settings.json read/write
+      index.ts                   barrel
+  types/
+    index.ts                     ItemFrontMatter, ItemType, ItemStatus, Dependency, etc.
+  extensions/
+    builtins/
+      beads/
+        index.ts                 Beads JSONL import extension
+      todos/
+        index.ts                 todos extension activate()
+        import-export.ts         todos import/export logic
+  command-types.ts               (re-export shim)
+  constants.ts                   (re-export shim)
+  errors.ts                      (re-export shim)
+  ... (other re-export shims for backward compat)
+```
+
+## Item Storage
+
+Each item is stored as a Markdown file:
+
+```
+.agents/pm/
+  <type-plural>/<id>.md     e.g. tasks/pm-a1b2.md
+  history/<id>.jsonl        append-only RFC6902 patch log
+  locks/<id>.lock           exclusive lock metadata (JSON)
+  settings.json             project configuration
+  index/manifest.json       keyword index cache (optional, rebuildable)
+  search/embeddings.jsonl   keyword corpus records (optional, rebuildable)
+  extensions/               project-local extensions
+```
+
+### Item File Format
+
+```
+{
+  "id": "pm-a1b2",
+  "title": "...",
+  ...
+}
+
+Optional markdown body here.
+```
+
+Fields are serialized in canonical key order (defined in `item-format.ts`).
+
+## Mutation Contract
+
+Every item mutation follows this sequence:
+
+1. **Acquire lock** — exclusive open on `locks/<id>.lock`; reject if stale and no `--force`
+2. **Read current item** — parse front-matter + body
+3. **Compute `before_hash`** — SHA-256 of canonical `{ front_matter, body }` JSON
+4. **Apply mutation** — in-memory model update
+5. **Update `updated_at`** — every mutation must change this timestamp
+6. **Compute patch + `after_hash`** — RFC6902 diff; SHA-256 of new canonical state
+7. **Atomic write** — write to temp file; `rename` to target (single syscall, OS-atomic)
+8. **Append history line** — JSONL append to `history/<id>.jsonl`
+9. **Release lock** — unlink lock file
+
+If step 7 or 8 fails, the item file is rolled back (if write succeeded) before returning failure.
+
+## History and Restore
+
+Each history entry is a JSONL line:
+
+```json
+{
+  "ts": "ISO timestamp",
+  "author": "string",
+  "op": "create|update|append|...|restore",
+  "patch": [ /* RFC6902 ops */ ],
+  "before_hash": "sha256-hex",
+  "after_hash": "sha256-hex",
+  "message": "optional"
+}
+```
+
+`pm restore <ID> <TIMESTAMP|VERSION>` replays patches from `op=create` through the target entry, rebuilding exact canonical state.
+
+## Extension System
+
+Extensions are Node.js modules with an `activate(api)` export:
+
+```ts
+export function activate(api: ExtensionApi): void {
+  api.registerCommand({ name: "my command", run: async (args, opts, global) => { ... } });
+  api.hooks.beforeCommand((ctx) => { ... });
+}
+```
+
+Load order: **core built-ins → global (`~/.pm-cli/extensions/`) → project (`.agents/pm/extensions/`)**.
+
+Project-local extensions override global by default. See [EXTENSIONS.md](./EXTENSIONS.md) for the full API reference.
+
+## Search Architecture
+
+- **Keyword mode** (always available): multi-factor lexical scoring with configurable field weights
+- **Semantic mode** (requires provider + vector store config): embedding-based vector similarity
+- **Hybrid mode** (default when semantic available): blended lexical + semantic ranking
+
+Providers: OpenAI-compatible, Ollama
+Vector stores: Qdrant, LanceDB
+
+### Keyword Scoring
+
+Each item is scored across: `title` (8×), `description` (5×), `tags` (6×), `status` (2×), `body` (1×), `comments`/`notes`/`learnings` (1× each), `dependencies` (3×). Exact title token matches add a bonus (10×).
+
+Weights are configurable via `settings.json` under `search.tuning`.
+
+## Configuration
+
+`settings.json` is read from the PM root at startup. Key sections:
+
+| Key | Description |
+|-----|-------------|
+| `id_prefix` | Prefix for generated IDs (default `pm-`) |
+| `author_default` | Default author for mutations |
+| `locks.ttl_seconds` | Lock TTL (default 1800) |
+| `output.default_format` | `toon` or `json` |
+| `search.*` | Search provider and tuning settings |
+| `providers.openai` / `providers.ollama` | Embedding provider config |
+| `vector_store.qdrant` / `vector_store.lancedb` | Vector store config |
+
+Precedence: CLI flags > env vars (`PM_PATH`, `PM_AUTHOR`, etc.) > `settings.json` > hard defaults.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Generic failure |
+| 2 | Usage / invalid args |
+| 3 | Not found |
+| 4 | Conflict (lock / ownership) |
+| 5 | Dependency failed (test-all) |
+
+## Testing
+
+Tests live in `tests/`:
+
+```
+tests/
+  unit/           Unit tests (item format, lock, search, commands, extensions, etc.)
+  integration/    Integration tests (CLI subprocess spawn, CI contract, README contract)
+```
+
+All tests run in sandboxed temp directories (`PM_PATH` + `PM_GLOBAL_PATH` isolated per suite). Coverage is enforced at 100% for lines, branches, functions, and statements.
+
+Run all tests:
+
+```bash
+node scripts/run-tests.mjs test       # sandbox-safe, tests only
+node scripts/run-tests.mjs coverage  # sandbox-safe, with coverage gate
+```
+
+The `scripts/run-tests.mjs` wrapper creates a temp directory, sets `PM_PATH` and `PM_GLOBAL_PATH`, runs Vitest, then cleans up.