@getpipher/armory-todo 0.5.3 → 0.5.5

package/README.md

@@ -21,6 +21,17 @@
 
 ---
 
+## Public API
+
+The package `exports` entry (`./src/index.ts`) is the **stable public surface** —
+`addTodo`, `listTodos`, `updateTodo`, `getTodo`, `completeTodo`, `parkTodo`,
+`deleteTodo`, and the `Todo` / `AddInput` / `UpdateInput` / `ListFilter` /
+`Priority` / `Status` / `Store` types (plus `TodoError`). Other `src/*` paths
+are internal and may change without notice. Depend on `@getpipher/armory-todo`
+(the public entry), never deep-import `src/*`.
+
+---
+
 ## The problem
 
 pi sessions are ephemeral conversation branches. A TODO you tell to session A is invisible to session B unless you manually write it to a notes file *and* remember to read it next time. Every existing pi todo extension (`@juicesharp/rpiv-todo`, `@xynogen/pix-todo`, `@gonrocca/zero-pi-todo`, …) is **conversation-branch-scoped** — they persist via pi's `appendEntry()` and survive compaction + `/reload` *within a single session*. None bridge across separate sessions, and none make a fresh session aware of pending work on its own.
@@ -210,6 +221,23 @@ Full design + decisions:
 |---|---|---|
 | `TODO_DIR` | `~/.pi/agent/todo/` | override the store folder (tests / multiple profiles) |
 
+`todo.config.json` (in `TODO_DIR`) holds prune ages, health thresholds, and notify toggles. All values are optional — missing fields are merged with defaults on load.
+
+```jsonc
+{
+  "version": 1,
+  "prune":  { "defaultAgeDays": 7, "hardAgeDays": 180, "statuses": ["done", "cancelled"] },
+  "health": { "activeMaxOpen": 15, "activeStaleDays": 30, "parkedMax": 10,
+              "parkedStaleDays": 60, "archiveMax": 200, "archiveOldDays": 180,
+              "perProjectDefaultMax": 8, "maxNotesBytes": 8192 },
+  "notify": { "sessionStartCount": true }
+}
+```
+
+| `notify.*` | default | purpose |
+|---|---|---|
+| `sessionStartCount` | `true` | Show the `armory-todo: N open TODOs` startup line. Set `false` to silence it — safety messages (wipe-recovery alert, auto-prune undo info) still surface. |
+
 Run the store tests: `npm test` (315/315 across 11 suites).
 
 ## Known issues

package/extensions/todo.ts

@@ -39,7 +39,7 @@ import { healthReport } from "../src/health";
 import { hardPrune } from "../src/hard-prune";
 import { TodoPanel } from "../src/panel";
 import { autoPruneOnSessionStart } from "../src/auto-prune";
-import { loadConfig } from "../src/config";
+import { loadConfig, type TodoConfig } from "../src/config";
 import { projectsOverview } from "../src/projects";
 import { renameProject } from "../src/registry";
 import { readAndClearWipeAlert } from "../src/backup";
@@ -90,10 +90,12 @@ export default function (pi: ExtensionAPI) {
       } catch {
         // alert optional
       }
+      // One config load reused for the prune age + the notify-suppress flag.
+      let cfg: TodoConfig | undefined;
+      try { cfg = loadConfig(); } catch { /* config optional */ }
       let autoMsg = "";
-      let ageDays = 7;
+      let ageDays = cfg?.prune.defaultAgeDays ?? 7;
       try {
-        ageDays = loadConfig().prune.defaultAgeDays;
         const ap = autoPruneOnSessionStart();
         if (ap) {
           const lines = ap.items.map((i) => `  [${i.id}] ${i.status}  ${i.title}`);
@@ -102,17 +104,27 @@ export default function (pi: ExtensionAPI) {
       } catch {
         // auto-prune optional — don't crash the session notify
       }
+      const showCount = cfg?.notify?.sessionStartCount !== false;
       const open = listTodos();
-      let msg = `armory-todo: ${open.length} open TODO${open.length === 1 ? "" : "s"}${autoMsg}`;
-      try {
-        const report = healthReport();
-        if (report.flags.length > 0) {
-          msg += `${autoMsg ? "\n" : " — "}` + `⚠ ${report.flags.length} bloat signal${report.flags.length === 1 ? "" : "s"} (run /todo health)`;
+      let msg = "";
+      if (showCount) {
+        msg = `armory-todo: ${open.length} open TODO${open.length === 1 ? "" : "s"}${autoMsg}`;
+        try {
+          const report = healthReport();
+          if (report.flags.length > 0) {
+            msg += `${autoMsg ? "\n" : " — "}` + `⚠ ${report.flags.length} bloat signal${report.flags.length === 1 ? "" : "s"} (run /todo health)`;
+          }
+        } catch {
+          // health check optional
         }
-      } catch {
-        // health check optional
+      } else if (autoMsg) {
+        // Count line suppressed; still surface the auto-prune undo info.
+        msg = `armory-todo${autoMsg}`;
+      }
+      if (ctx.hasUI) {
+        const out = (wipeMsg ? wipeMsg + "\n" : "") + msg;
+        if (out) ctx.ui.notify(out, "info");
       }
-      if (ctx.hasUI) ctx.ui.notify((wipeMsg ? wipeMsg + "\n" : "") + msg, "info");
     } catch {
       // store unavailable — never crash the session
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-todo",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Global, cross-session TODO for pi \u2014 persists across all sessions and is auto-injected into every prompt. The disk-backed counterpart to branch-scoped pi todo extensions.",
   "keywords": [
     "pi-package",
@@ -21,6 +21,12 @@
   "bugs": {
     "url": "https://github.com/getpipher/armory-todo/issues"
   },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
   "files": [
     "extensions",
     "src",
@@ -35,7 +41,7 @@
     ]
   },
   "scripts": {
-    "test": "for t in todo-store todo-title-notes todo-archive todo-config todo-migrate todo-health todo-hard-prune todo-auto-prune registry projects panel-data todo-caps todo-backup; do node test/$t.test.mts || exit 1; done"
+    "test": "for t in todo-store todo-title-notes todo-archive todo-config todo-migrate todo-health todo-hard-prune todo-auto-prune registry projects panel-data todo-caps todo-backup public-api; do node test/$t.test.mts || exit 1; done"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -53,4 +59,4 @@
       "optional": true
     }
   }
-}
+}

package/src/config.ts

@@ -28,10 +28,18 @@ export interface HealthConfig {
   maxNotesBytes: number;         // v0.5.0: per-todo notes byte cap (hard-reject at add/update)
 }
 
+export interface NotifyConfig {
+  /** Show the `armory-todo: N open TODOs` session-start count line.
+   *  Safety messages (wipe-recovery alert, auto-prune undo info) still surface
+   *  when this is false. Default true. */
+  sessionStartCount: boolean;
+}
+
 export interface TodoConfig {
   version: 1;
   prune: PruneConfig;
   health: HealthConfig;
+  notify: NotifyConfig;
 }
 
 export const DEFAULT_CONFIG: TodoConfig = {
@@ -51,6 +59,9 @@ export const DEFAULT_CONFIG: TodoConfig = {
     perProjectDefaultMax: 8,
     maxNotesBytes: 8192,
   },
+  notify: {
+    sessionStartCount: true,
+  },
 };
 
 /** Deep clone of DEFAULT_CONFIG (so callers can't mutate the constant). */
@@ -77,10 +88,13 @@ export function loadConfig(): TodoConfig {
     if (health.maxNotesBytes === undefined || typeof health.maxNotesBytes !== "number" || Number.isNaN(health.maxNotesBytes) || health.maxNotesBytes < 0) {
       health.maxNotesBytes = DEFAULT_CONFIG.health.maxNotesBytes;
     }
+    const notify = { ...DEFAULT_CONFIG.notify, ...(parsed.notify ?? {}) };
+    if (typeof notify.sessionStartCount !== "boolean") notify.sessionStartCount = true;
     return {
       version: 1,
       prune: { ...DEFAULT_CONFIG.prune, ...parsed.prune },
       health,
+      notify,
     };
   } catch {
     try {

package/src/index.d.ts

@@ -0,0 +1,78 @@
+// src/index.d.ts
+/**
+ * Typed declarations for the public stable API of @getpipher/armory-todo.
+ *
+ * Consumed via the package `exports` `types` condition (see package.json) so
+ * that TypeScript consumers type-check against this declaration instead of
+ * pulling the raw `.ts` implementation source. Runtime (tsx/jiti/node) uses the
+ * `default` condition (`./src/index.ts`).
+ *
+ * Hand-written (no build step — getpipher convention). Keep in sync with
+ * src/index.ts re-exports.
+ */
+export type Priority = "low" | "med" | "high" | "critical";
+export type Status = "open" | "in_progress" | "parked" | "done" | "cancelled";
+
+export interface Todo {
+  id: string;
+  title: string;
+  notes: string;
+  project: string;
+  tags: string[];
+  priority: Priority;
+  status: Status;
+  source: string;
+  createdAt: string;
+  updatedAt: string;
+  closedAt: string | null;
+}
+
+export interface AddInput {
+  title: string;
+  notes?: string;
+  project?: string;
+  tags?: string[];
+  priority?: Priority;
+  source?: string;
+}
+
+export interface UpdateInput {
+  title?: string;
+  notes?: string;
+  project?: string;
+  tags?: string[];
+  priority?: Priority;
+  status?: Status;
+}
+
+export interface ListFilter {
+  status?: Status | "all";
+  project?: string;
+  tag?: string;
+  text?: string;
+  since?: string;
+  before?: string;
+  limit?: number;
+  page?: number;
+}
+
+export interface Store {
+  version: 3;
+  updatedAt: string;
+  todos: Todo[];
+}
+
+export class TodoError extends Error {}
+
+export function addTodo(input: AddInput): Todo;
+export function listTodos(filter?: ListFilter): Todo[];
+export function updateTodo(id: string, patch: UpdateInput): Todo;
+export function getTodo(id: string): Todo;
+export function completeTodo(id: string): Todo;
+export function parkTodo(id: string): Todo;
+export function deleteTodo(id: string): Todo;
+export function clearTodos(status?: Status): number;
+export function renderOpenBlock(max?: number): string;
+export function getStorePath(): string;
+export function loadStore(): Store;
+export function saveStore(store: Store): void;

package/src/index.ts

@@ -0,0 +1,39 @@
+// src/index.ts
+/**
+ * Public stable API of @getpipher/armory-todo.
+ *
+ * This `exports` entry (see package.json) is the stable surface — the functions
+ * and types re-exported here. Other `src/*` paths are internal and may change
+ * without notice. Depend on `@getpipher/armory-todo` (this public entry), never
+ * deep-import `src/*`.
+ *
+ * Consumers (e.g. @getpipher/armory-fleet) import from here so that evolution
+ * of armory-todo is decoupled: a breaking change can only touch a consumer's
+ * adapter, never its core, and the version pin + CI typecheck catch drift.
+ */
+export {
+  addTodo,
+  listTodos,
+  updateTodo,
+  getTodo,
+  completeTodo,
+  parkTodo,
+  deleteTodo,
+  clearTodos,
+  renderOpenBlock,
+  getStorePath,
+  loadStore,
+  saveStore,
+} from "./todo-store.ts";
+
+export type {
+  Todo,
+  AddInput,
+  UpdateInput,
+  ListFilter,
+  Priority,
+  Status,
+  Store,
+} from "./todo-store.ts";
+
+export { TodoError } from "./todo-store.ts";