project-mgr 0.1.5 → 0.1.7

package/package.json

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

package/skills/project-mgr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Manage project status with the local-first project-mgr CLI. Use when an AI agent needs to add an append-only project update, set project descriptions/notes, list or fuzzy-search projects, import status records, query current or historical project state, or export a status ledger.
 ---
 
 # project-mgr
@@ -19,13 +19,23 @@ Use `npx --yes --package project-mgr pmgr`. In a source checkout, use `pnpm pmgr
 Prefer `--json` for data that must be interpreted or reported programmatically.
 
 ```bash
-# Add an agent-authored status snapshot.
+# Set, update, or clear project metadata (description, notes, display name).
+npx --yes --package project-mgr pmgr set-project --project my-project --description "Project summary" --notes "Internal notes" --json
+npx --yes --package project-mgr 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 pmgr projects --json
+npx --yes --package project-mgr pmgr list --query "keyword" --json
+
+# Add an agent-authored status snapshot (optionally with project description or notes).
 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
+  --description "Project description" --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 history --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.

package/src/cli.ts

@@ -8,8 +8,11 @@ import {
   current,
   history,
   importStatuses,
+  listProjects,
   openLedger,
   parseTime,
+  type ProjectOverview,
+  setProjectMetadata,
   toPortableStatusEntry,
   ValidationError,
 } from "./index.js";
@@ -27,7 +30,11 @@ function parse(argv: string[]): { command: string[]; flags: Flags } {
       continue;
     }
     const key = token.slice(2);
-    if (key === "json") {
+    if (
+      key === "json" ||
+      key === "clear-description" ||
+      key === "clear-notes"
+    ) {
       if (flags[key] !== undefined)
         throw new ValidationError(`--${key} may only be supplied once`);
       flags[key] = true;
@@ -52,6 +59,8 @@ const allowedFlags = new Map<string, ReadonlySet<string>>([
       "project",
       "status",
       "summary",
+      "description",
+      "notes",
       "progress",
       "blocker",
       "next",
@@ -65,6 +74,20 @@ const allowedFlags = new Map<string, ReadonlySet<string>>([
   ],
   ["import", new Set(["file", "json"])],
   ["current", new Set(["project", "json"])],
+  ["projects", new Set(["query", "json"])],
+  ["list", new Set(["query", "json"])],
+  [
+    "set-project",
+    new Set([
+      "project",
+      "display-name",
+      "description",
+      "notes",
+      "clear-description",
+      "clear-notes",
+      "json",
+    ]),
+  ],
   [
     "history",
     new Set(["project", "since", "until", "limit", "offset", "json"]),
@@ -80,7 +103,7 @@ function validateInvocation(command: string[], flags: Flags): string {
     typeof action === "string" ? allowedFlags.get(action) : undefined;
   if (typeof action !== "string" || !allowed)
     throw new ValidationError(
-      "usage: pmgr <add|import|current|history|at|export> (or: pmgr status <action>)",
+      "usage: pmgr <add|import|current|projects|list|set-project|history|at|export> (or: pmgr status <action>)",
     );
   const positional = command.slice(statusCommand ? 2 : 1);
   if (action === "import") {
@@ -139,6 +162,30 @@ function output(
   } else write(`${JSON.stringify(value, null, 2)}\n`);
 }
 
+function formatProjectOverview(item: ProjectOverview): string {
+  const lines = [`${item.project}\t${item.displayName}`];
+  if (item.description) lines.push(`  Description: ${item.description}`);
+  if (item.notes) lines.push(`  Notes: ${item.notes}`);
+  if (item.latestStatus) {
+    lines.push(
+      `  Latest Status: ${item.latestStatus.status}\t${item.latestStatus.occurredAt}\t${item.latestStatus.summary}`,
+    );
+  } else {
+    lines.push(`  Latest Status: (none)`);
+  }
+  return lines.join("\n");
+}
+
+function outputProjects(
+  items: ProjectOverview[],
+  json: boolean,
+  write: (text: string) => void,
+): void {
+  if (json) write(`${JSON.stringify(items)}\n`);
+  else if (items.length === 0) write("No projects found.\n");
+  else write(`${items.map(formatProjectOverview).join("\n")}\n`);
+}
+
 function imported(file: string): unknown[] {
   if (!file) throw new ValidationError("import file is required");
   const content = readFileSync(file, "utf8").trim();
@@ -172,10 +219,16 @@ export function run(
   const json = flags.json === true;
   try {
     switch (action) {
-      case "add":
+      case "add": {
+        const project = stringFlag(flags, "project", true) as string;
+        const description = stringFlag(flags, "description");
+        const notes = stringFlag(flags, "notes");
+        if (description !== undefined || notes !== undefined) {
+          setProjectMetadata(db, { project, description, notes });
+        }
         output(
           addStatus(db, {
-            project: stringFlag(flags, "project", true),
+            project,
             status: stringFlag(flags, "status", true),
             summary: stringFlag(flags, "summary", true),
             progress: stringFlag(flags, "progress"),
@@ -191,6 +244,8 @@ export function run(
           write,
         );
         break;
+      }
+
       case "import":
         output(
           importStatuses(
@@ -208,9 +263,55 @@ export function run(
       case "current":
         output(current(db, stringFlag(flags, "project")), json, write);
         break;
+      case "projects":
+      case "list":
+        outputProjects(
+          listProjects(db, { query: stringFlag(flags, "query") }),
+          json,
+          write,
+        );
+        break;
+      case "set-project": {
+        const project = stringFlag(flags, "project", true) as string;
+        const displayName = stringFlag(flags, "display-name");
+        let description: string | null | undefined = undefined;
+        if (flags["clear-description"] === true) {
+          if (flags.description !== undefined)
+            throw new ValidationError(
+              "cannot specify both --description and --clear-description",
+            );
+          description = null;
+        } else if (flags.description !== undefined) {
+          description = stringFlag(flags, "description");
+        }
+
+        let notes: string | null | undefined = undefined;
+        if (flags["clear-notes"] === true) {
+          if (flags.notes !== undefined)
+            throw new ValidationError(
+              "cannot specify both --notes and --clear-notes",
+            );
+          notes = null;
+        } else if (flags.notes !== undefined) {
+          notes = stringFlag(flags, "notes");
+        }
+
+        output(
+          setProjectMetadata(db, {
+            project,
+            displayName,
+            description,
+            notes,
+          }),
+          json,
+          write,
+        );
+        break;
+      }
+
       case "history":
         output(
-          history(db, stringFlag(flags, "project", true), {
+          history(db, stringFlag(flags, "project"), {
             since:
               stringFlag(flags, "since") &&
               parseTime(stringFlag(flags, "since"), "since"),

package/src/db.ts

@@ -3,9 +3,12 @@ import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import {
+  type ProjectMetadata,
+  type ProjectOverview,
   type Source,
   type StatusEntry,
   type StatusEntryInput,
+  validateProjectMetadataInput,
   validateStatusEntry,
   ValidationError,
 } from "./domain.js";
@@ -19,7 +22,7 @@ export type HistoryOptions = {
   offset?: number;
 };
 
-const migration = `
+const migration1 = `
 CREATE TABLE IF NOT EXISTS projects (
   id INTEGER PRIMARY KEY,
   slug TEXT NOT NULL UNIQUE,
@@ -44,6 +47,11 @@ CREATE TABLE IF NOT EXISTS status_entries (
 CREATE INDEX IF NOT EXISTS idx_status_entries_project_occurred ON status_entries(project_id, occurred_at DESC, id DESC);
 `;
 
+const migration2 = `
+ALTER TABLE projects ADD COLUMN description TEXT;
+ALTER TABLE projects ADD COLUMN notes TEXT;
+`;
+
 export function databasePath(): string {
   return (
     process.env.PMGR_DB_PATH ||
@@ -62,9 +70,15 @@ export function openLedger(path = databasePath()): Ledger {
     if (
       !db.prepare("SELECT 1 FROM schema_migrations WHERE version = 1").get()
     ) {
-      db.exec(migration);
+      db.exec(migration1);
       db.prepare("INSERT INTO schema_migrations(version) VALUES (1)").run();
     }
+    if (
+      !db.prepare("SELECT 1 FROM schema_migrations WHERE version = 2").get()
+    ) {
+      db.exec(migration2);
+      db.prepare("INSERT INTO schema_migrations(version) VALUES (2)").run();
+    }
   }).immediate();
   return db;
 }
@@ -82,7 +96,7 @@ function entryFromRow(row: Record<string, unknown>): StatusEntry {
     tags: JSON.parse(row.tags_json as string) as string[],
     occurredAt: row.occurred_at as string,
     recordedAt: row.recorded_at as string,
-    source: row.source as StatusEntry["source"],
+    source: row.source as Source,
     ...(row.external_ref ? { externalRef: row.external_ref as string } : {}),
   };
 }
@@ -98,6 +112,124 @@ function one(
   return row && entryFromRow(row);
 }
 
+function upsertProjectMetadata(
+  db: Ledger,
+  input: {
+    project: string;
+    displayName?: string;
+    description?: string | null;
+    notes?: string | null;
+  },
+): void {
+  const existing = db
+    .prepare("SELECT 1 FROM projects WHERE slug = ?")
+    .get(input.project);
+  if (!existing) {
+    const now = new Date().toISOString();
+    db.prepare(
+      "INSERT INTO projects(slug, display_name, description, notes, created_at) VALUES (?, ?, ?, ?, ?)",
+    ).run(
+      input.project,
+      input.displayName ?? input.project,
+      input.description ?? null,
+      input.notes ?? null,
+      now,
+    );
+  } else {
+    const updates: string[] = [];
+    const params: unknown[] = [];
+    if (input.displayName !== undefined) {
+      updates.push("display_name = ?");
+      params.push(input.displayName);
+    }
+    if (input.description !== undefined) {
+      updates.push("description = ?");
+      params.push(input.description);
+    }
+    if (input.notes !== undefined) {
+      updates.push("notes = ?");
+      params.push(input.notes);
+    }
+    if (updates.length > 0) {
+      params.push(input.project);
+      db.prepare(
+        `UPDATE projects SET ${updates.join(", ")} WHERE slug = ?`,
+      ).run(...params);
+    }
+  }
+}
+
+export function setProjectMetadata(
+  db: Ledger,
+  value: unknown,
+): ProjectMetadata {
+  const input = validateProjectMetadataInput(value);
+  return db.transaction(() => {
+    upsertProjectMetadata(db, input);
+    const row = db
+      .prepare("SELECT * FROM projects WHERE slug = ?")
+      .get(input.project) as Record<string, unknown>;
+    return {
+      project: row.slug as string,
+      displayName: row.display_name as string,
+      ...(row.description ? { description: row.description as string } : {}),
+      ...(row.notes ? { notes: row.notes as string } : {}),
+      createdAt: row.created_at as string,
+    };
+  })();
+}
+
+export function listProjects(
+  db: Ledger,
+  options: { query?: string } = {},
+): ProjectOverview[] {
+  const query = options.query?.trim().toLowerCase();
+  const projects = db
+    .prepare("SELECT * FROM projects ORDER BY slug ASC")
+    .all() as Record<string, unknown>[];
+
+  const latestStatuses = current(db);
+  const statusMap = new Map<string, StatusEntry>();
+  for (const entry of latestStatuses) {
+    statusMap.set(entry.project, entry);
+  }
+
+  const overviews: ProjectOverview[] = projects.map((row) => {
+    const slug = row.slug as string;
+    const latestStatus = statusMap.get(slug);
+    return {
+      project: slug,
+      displayName: row.display_name as string,
+      ...(row.description ? { description: row.description as string } : {}),
+      ...(row.notes ? { notes: row.notes as string } : {}),
+      createdAt: row.created_at as string,
+      ...(latestStatus ? { latestStatus } : {}),
+    };
+  });
+
+  if (!query) return overviews;
+
+  return overviews.filter((overview) => {
+    if (overview.project.toLowerCase().includes(query)) return true;
+    if (overview.displayName.toLowerCase().includes(query)) return true;
+    if (overview.description?.toLowerCase().includes(query)) return true;
+    if (overview.notes?.toLowerCase().includes(query)) return true;
+    if (overview.latestStatus) {
+      if (overview.latestStatus.status.toLowerCase().includes(query))
+        return true;
+      if (overview.latestStatus.summary.toLowerCase().includes(query))
+        return true;
+      if (overview.latestStatus.progress?.toLowerCase().includes(query))
+        return true;
+      if (
+        overview.latestStatus.tags.some((t) => t.toLowerCase().includes(query))
+      )
+        return true;
+    }
+    return false;
+  });
+}
+
 export function addStatus(
   db: Ledger,
   value: unknown,
@@ -126,9 +258,8 @@ function addValidatedStatus(
     }
   }
   const now = new Date().toISOString();
-  db.prepare(
-    "INSERT INTO projects(slug, display_name, created_at) VALUES (?, ?, ?) ON CONFLICT(slug) DO NOTHING",
-  ).run(input.project, input.project, now);
+  upsertProjectMetadata(db, { project: input.project });
+
   const project = db
     .prepare("SELECT id FROM projects WHERE slug = ?")
     .get(input.project) as { id: number };

package/src/domain.ts

@@ -12,6 +12,25 @@ export const sources = ["human", "agent", "import"] as const;
 export type ProjectStatus = (typeof statuses)[number];
 export type Source = (typeof sources)[number];
 
+export type ProjectMetadata = {
+  project: string;
+  displayName: string;
+  description?: string;
+  notes?: string;
+  createdAt: string;
+};
+
+export type ProjectOverview = ProjectMetadata & {
+  latestStatus?: StatusEntry;
+};
+
+export type ProjectMetadataInput = {
+  project: string;
+  displayName?: string;
+  description?: string | null;
+  notes?: string | null;
+};
+
 export type StatusEntryInput = {
   project: string;
   status: ProjectStatus;
@@ -50,6 +69,12 @@ const keys = new Set([
   "source",
   "externalRef",
 ]);
+const projectMetadataKeys = new Set([
+  "project",
+  "displayName",
+  "description",
+  "notes",
+]);
 const projectName = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 
 export class ValidationError extends Error {
@@ -73,6 +98,21 @@ function text(
   return normalized;
 }
 
+function nullableText(
+  value: unknown,
+  field: string,
+): string | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (typeof value !== "string")
+    throw new ValidationError(`${field} must be a string or null`);
+  const normalized = value.trim();
+  if (normalized === "") return null;
+  if (normalized.length > 2_000)
+    throw new ValidationError(`${field} must be at most 2000 characters`);
+  return normalized;
+}
+
 function textList(value: unknown, field: string): string[] {
   if (value === undefined) return [];
   if (!Array.isArray(value) || value.length > 100)
@@ -93,6 +133,31 @@ export function parseTime(value: unknown, field: string): string {
   return new Date(value).toISOString();
 }
 
+export function validateProjectMetadataInput(
+  value: unknown,
+): ProjectMetadataInput {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new ValidationError("project metadata must be an object");
+  const input = value as Record<string, unknown>;
+  for (const key of Object.keys(input))
+    if (!projectMetadataKeys.has(key))
+      throw new ValidationError(`unknown field: ${key}`);
+  const project = text(input.project, "project", true) as string;
+  if (!projectName.test(project))
+    throw new ValidationError(
+      "project must use letters, numbers, dots, underscores, or hyphens",
+    );
+  const displayName = text(input.displayName, "displayName");
+  const description = nullableText(input.description, "description");
+  const notes = nullableText(input.notes, "notes");
+  return {
+    project,
+    ...(displayName !== undefined ? { displayName } : {}),
+    ...(description !== undefined ? { description } : {}),
+    ...(notes !== undefined ? { notes } : {}),
+  };
+}
+
 export function validateStatusEntry(
   value: unknown,
   defaultSource: Source = "human",
@@ -135,19 +200,18 @@ export function validateStatusEntry(
 }
 
 export function toPortableStatusEntry(entry: StatusEntry): PortableStatusEntry {
-  return {
+  const result: PortableStatusEntry = {
     project: entry.project,
     status: entry.status,
     summary: entry.summary,
-    ...(entry.progress === undefined ? {} : { progress: entry.progress }),
     blockers: entry.blockers,
     nextSteps: entry.nextSteps,
     decisions: entry.decisions,
     tags: entry.tags,
     occurredAt: entry.occurredAt,
     source: entry.source,
-    ...(entry.externalRef === undefined
-      ? {}
-      : { externalRef: entry.externalRef }),
   };
+  if (entry.progress !== undefined) result.progress = entry.progress;
+  if (entry.externalRef !== undefined) result.externalRef = entry.externalRef;
+  return result;
 }