project-mgr 0.1.6 → 0.2.0

package/docs/architecture.md

@@ -36,8 +36,8 @@ The CLI accepts `pmgr <action>` for `add`, `import`, `current`, `history`, `at`,
 
 The database contains three structures:
 
-- `schema_migrations`: Applied migration versions.
-- `projects`: Project slug, display name, and creation time.
+- `schema_migrations`: Applied migration versions (1: base tables, 2: project description & notes columns).
+- `projects`: Project slug, display name, description, notes, and creation time.
 - `status_entries`: Immutable status snapshots and their project foreign keys.
 
 Key `status_entries` fields:
@@ -55,7 +55,7 @@ The `project_id, occurred_at DESC, id DESC` index supports current-status and hi
 
 ## Initialization and migrations
 
-After opening the database, `openLedger()` enables foreign keys, creates the migration table, and checks for and applies migration 1 within a `BEGIN IMMEDIATE` transaction. The immediate transaction prevents migration checks and writes from interleaving when several local processes open the database for the first time at once.
+After opening the database, `openLedger()` enables foreign keys, creates the migration table, and checks for and applies migrations 1 and 2 within a `BEGIN IMMEDIATE` transaction. The immediate transaction prevents migration checks and writes from interleaving when several local processes open the database for the first time at once.
 
 The database path is read from `PMGR_DB_PATH` first; otherwise, it uses the absolute path `~/.local/share/project-mgr/project-mgr.sqlite`, resolved from the current user's home directory. Non-memory databases create their parent directory automatically.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-mgr",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "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
@@ -13,15 +13,25 @@ Use `npx --yes --package project-mgr pmgr`. In a source checkout, use `pnpm pmgr
 - 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.
 - 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.
 
 ## Operations
 
 Prefer `--json` for data that must be interpreted or reported programmatically.
 
 ```bash
-# Add an agent-authored status snapshot.
-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
+# 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 (status defaults to completed if omitted).
+npx --yes --package project-mgr pmgr add --project my-project --summary "Implemented the CLI" \
+  --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

package/src/cli.ts

@@ -8,8 +8,13 @@ import {
   current,
   history,
   importStatuses,
+  listProjects,
   openLedger,
   parseTime,
+  type ProjectOverview,
+  type ProjectStatus,
+  setProjectMetadata,
+  startServer,
   toPortableStatusEntry,
   ValidationError,
 } from "./index.js";
@@ -27,7 +32,13 @@ 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" ||
+      key === "open" ||
+      key === "no-open"
+    ) {
       if (flags[key] !== undefined)
         throw new ValidationError(`--${key} may only be supplied once`);
       flags[key] = true;
@@ -52,6 +63,8 @@ const allowedFlags = new Map<string, ReadonlySet<string>>([
       "project",
       "status",
       "summary",
+      "description",
+      "notes",
       "progress",
       "blocker",
       "next",
@@ -65,12 +78,27 @@ 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"]),
   ],
   ["at", new Set(["project", "at", "json"])],
   ["export", new Set(["project", "format"])],
+  ["serve", new Set(["port", "host", "open", "no-open", "json"])],
 ]);
 
 function validateInvocation(command: string[], flags: Flags): string {
@@ -80,7 +108,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|serve> (or: pmgr status <action>)",
     );
   const positional = command.slice(statusCommand ? 2 : 1);
   if (action === "import") {
@@ -139,6 +167,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();
@@ -165,18 +217,24 @@ function imported(file: string): unknown[] {
 export function run(
   argv: string[],
   write = process.stdout.write.bind(process.stdout),
-): void {
+): unknown {
   const { command, flags } = parse(argv);
   const action = validateInvocation(command, flags);
   const db = openLedger();
   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),
-            status: stringFlag(flags, "status", true),
+            project,
+            status: stringFlag(flags, "status") as unknown as ProjectStatus,
             summary: stringFlag(flags, "summary", true),
             progress: stringFlag(flags, "progress"),
             blockers: listFlag(flags, "blocker"),
@@ -191,6 +249,8 @@ export function run(
           write,
         );
         break;
+      }
+
       case "import":
         output(
           importStatuses(
@@ -208,6 +268,52 @@ 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"), {
@@ -251,9 +357,30 @@ export function run(
         else throw new ValidationError("--format must be json or jsonl");
         break;
       }
+
+      case "serve": {
+        const port =
+          flags.port !== undefined
+            ? numberFlag(flags, "port", 3000)
+            : undefined;
+        const host = stringFlag(flags, "host");
+        const open = flags["no-open"] === true ? false : true;
+        return startServer({ port, host, open, db }).then((instance) => {
+          if (json) {
+            write(
+              `${JSON.stringify({ url: instance.url, port: instance.port, host: instance.host })}\n`,
+            );
+          } else {
+            write(`Server running at ${instance.url}\n`);
+          }
+          return instance;
+        });
+      }
     }
   } finally {
-    db.close();
+    if (action !== "serve") {
+      db.close();
+    }
   }
 }
 
@@ -263,7 +390,7 @@ if (
   import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href
 ) {
   try {
-    run(process.argv.slice(2));
+    await run(process.argv.slice(2));
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;

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,130 @@ 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 } : {}),
+    };
+  });
+
+  overviews.sort((a, b) => {
+    const timeA = a.latestStatus?.occurredAt ?? a.createdAt;
+    const timeB = b.latestStatus?.occurredAt ?? b.createdAt;
+    if (timeA !== timeB) {
+      return timeB.localeCompare(timeA);
+    }
+    return a.project.localeCompare(b.project);
+  });
+
+  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) {
+      const st = overview.latestStatus;
+      const match =
+        st.status.toLowerCase().includes(query) ||
+        st.summary.toLowerCase().includes(query) ||
+        (st.progress && st.progress.toLowerCase().includes(query)) ||
+        st.tags.some((t) => t.toLowerCase().includes(query));
+      if (match) return true;
+    }
+    return false;
+  });
+}
+
 export function addStatus(
   db: Ledger,
   value: unknown,
@@ -126,9 +264,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 };
@@ -219,3 +356,18 @@ export function at(
     occurredAt,
   );
 }
+
+export function countEntries(db: Ledger, project?: string): number {
+  if (project) {
+    const row = db
+      .prepare(
+        "SELECT COUNT(*) AS count FROM status_entries e JOIN projects p ON p.id = e.project_id WHERE p.slug = ?",
+      )
+      .get(project) as { count: number };
+    return row.count;
+  }
+  const row = db
+    .prepare("SELECT COUNT(*) AS count FROM status_entries")
+    .get() as { count: number };
+  return row.count;
+}

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",
@@ -108,7 +173,16 @@ export function validateStatusEntry(
     throw new ValidationError(
       "project must use letters, numbers, dots, underscores, or hyphens",
     );
-  if (!statuses.includes(input.status as ProjectStatus))
+  let statusInput = input.status;
+  if (statusInput === undefined || statusInput === null) {
+    statusInput = "completed";
+  } else if (
+    typeof statusInput === "string" &&
+    statusInput.trim().toLowerCase() === "done"
+  ) {
+    statusInput = "completed";
+  }
+  if (!statuses.includes(statusInput as ProjectStatus))
     throw new ValidationError("status is invalid");
   const source = input.source === undefined ? defaultSource : input.source;
   if (!sources.includes(source as Source))
@@ -118,7 +192,7 @@ export function validateStatusEntry(
     throw new ValidationError("externalRef must be at most 200 characters");
   return {
     project,
-    status: input.status as ProjectStatus,
+    status: statusInput as ProjectStatus,
     summary: text(input.summary, "summary", true) as string,
     progress: text(input.progress, "progress"),
     blockers: textList(input.blockers, "blockers"),
@@ -135,19 +209,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;
 }

package/src/index.ts

@@ -1,2 +1,5 @@
+export * from "./cli.js";
 export * from "./db.js";
 export * from "./domain.js";
+export * from "./server.js";
+export * from "./web/ui.js";