project-mgr 0.1.0

package/src/cli.ts

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  addStatus,
+  at,
+  current,
+  history,
+  importStatuses,
+  openLedger,
+  parseTime,
+  toPortableStatusEntry,
+  ValidationError,
+} from "./index.js";
+
+type Flags = Record<string, string | string[] | boolean>;
+const repeats = new Set(["next", "blocker", "decision", "tag"]);
+
+function parse(argv: string[]): { command: string[]; flags: Flags } {
+  const command: string[] = [];
+  const flags: Flags = Object.create(null) as Flags;
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      command.push(token);
+      continue;
+    }
+    const key = token.slice(2);
+    if (key === "json") {
+      if (flags[key] !== undefined)
+        throw new ValidationError(`--${key} may only be supplied once`);
+      flags[key] = true;
+      continue;
+    }
+    const value = argv[++index];
+    if (!value || value.startsWith("--"))
+      throw new ValidationError(`--${key} requires a value`);
+    if (repeats.has(key))
+      flags[key] = [...((flags[key] as string[] | undefined) ?? []), value];
+    else if (flags[key] !== undefined)
+      throw new ValidationError(`--${key} may only be supplied once`);
+    else flags[key] = value;
+  }
+  return { command, flags };
+}
+
+const allowedFlags = new Map<string, ReadonlySet<string>>([
+  [
+    "add",
+    new Set([
+      "project",
+      "status",
+      "summary",
+      "progress",
+      "blocker",
+      "next",
+      "decision",
+      "tag",
+      "at",
+      "source",
+      "external-ref",
+      "json",
+    ]),
+  ],
+  ["import", new Set(["file", "json"])],
+  ["current", new Set(["project", "json"])],
+  [
+    "history",
+    new Set(["project", "since", "until", "limit", "offset", "json"]),
+  ],
+  ["at", new Set(["project", "at", "json"])],
+  ["export", new Set(["project", "format"])],
+]);
+
+function validateInvocation(command: string[], flags: Flags): string {
+  const statusCommand = command[0] === "status";
+  const action = command[statusCommand ? 1 : 0];
+  const allowed =
+    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>)",
+    );
+  const positional = command.slice(statusCommand ? 2 : 1);
+  if (action === "import") {
+    if (positional.length > 1)
+      throw new ValidationError("import accepts at most one file argument");
+    if (positional.length === 1 && flags.file !== undefined)
+      throw new ValidationError(
+        "import file must be positional or --file, not both",
+      );
+  } else if (positional.length) {
+    throw new ValidationError(`${action} does not accept positional arguments`);
+  }
+  for (const key of Object.keys(flags))
+    if (!allowed.has(key))
+      throw new ValidationError(`unknown flag for ${action}: --${key}`);
+  return action;
+}
+
+function stringFlag(
+  flags: Flags,
+  name: string,
+  required = false,
+): string | undefined {
+  const value = flags[name];
+  if (required && typeof value !== "string")
+    throw new ValidationError(`--${name} is required`);
+  return typeof value === "string" ? value : undefined;
+}
+
+function listFlag(flags: Flags, name: string): string[] {
+  return (flags[name] as string[] | undefined) ?? [];
+}
+function numberFlag(flags: Flags, name: string, fallback: number): number {
+  const value = stringFlag(flags, name);
+  if (!value) return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0)
+    throw new ValidationError(`--${name} must be a non-negative integer`);
+  return number;
+}
+
+function output(
+  value: unknown,
+  json: boolean,
+  write: (text: string) => void,
+): void {
+  if (json) write(`${JSON.stringify(value)}\n`);
+  else if (Array.isArray(value)) {
+    const rows = value
+      .map(
+        (entry) =>
+          `${entry.project}\t${entry.status}\t${entry.occurredAt}\t${entry.summary}`,
+      )
+      .join("\n");
+    write(`${rows || "No entries found."}\n`);
+  } else write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function imported(file: string): unknown[] {
+  if (!file) throw new ValidationError("import file is required");
+  const content = readFileSync(file, "utf8").trim();
+  if (!content) throw new ValidationError(`${basename(file)} is empty`);
+  if (file.endsWith(".jsonl"))
+    return content.split(/\r?\n/).map((line, index) => {
+      try {
+        return JSON.parse(line) as unknown;
+      } catch {
+        throw new ValidationError(
+          `${basename(file)} line ${index + 1} is not JSON`,
+        );
+      }
+    });
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content) as unknown;
+  } catch {
+    throw new ValidationError(`${basename(file)} is not JSON`);
+  }
+  return Array.isArray(parsed) ? parsed : [parsed];
+}
+
+export function run(
+  argv: string[],
+  write = process.stdout.write.bind(process.stdout),
+): void {
+  const { command, flags } = parse(argv);
+  const action = validateInvocation(command, flags);
+  const db = openLedger();
+  const json = flags.json === true;
+  try {
+    switch (action) {
+      case "add":
+        output(
+          addStatus(db, {
+            project: stringFlag(flags, "project", true),
+            status: stringFlag(flags, "status", true),
+            summary: stringFlag(flags, "summary", true),
+            progress: stringFlag(flags, "progress"),
+            blockers: listFlag(flags, "blocker"),
+            nextSteps: listFlag(flags, "next"),
+            decisions: listFlag(flags, "decision"),
+            tags: listFlag(flags, "tag"),
+            occurredAt: stringFlag(flags, "at"),
+            source: stringFlag(flags, "source"),
+            externalRef: stringFlag(flags, "external-ref"),
+          }).entry,
+          json,
+          write,
+        );
+        break;
+      case "import":
+        output(
+          importStatuses(
+            db,
+            imported(
+              stringFlag(flags, "file") ??
+                command[command[0] === "status" ? 2 : 1] ??
+                "",
+            ),
+          ).map((result) => result.entry),
+          json,
+          write,
+        );
+        break;
+      case "current":
+        output(current(db, stringFlag(flags, "project")), json, write);
+        break;
+      case "history":
+        output(
+          history(db, stringFlag(flags, "project", true), {
+            since:
+              stringFlag(flags, "since") &&
+              parseTime(stringFlag(flags, "since"), "since"),
+            until:
+              stringFlag(flags, "until") &&
+              parseTime(stringFlag(flags, "until"), "until"),
+            limit: numberFlag(flags, "limit", 100),
+            offset: numberFlag(flags, "offset", 0),
+          }),
+          json,
+          write,
+        );
+        break;
+      case "at":
+        output(
+          at(
+            db,
+            stringFlag(flags, "project", true) as string,
+            parseTime(stringFlag(flags, "at", true), "at"),
+          ) ?? null,
+          json,
+          write,
+        );
+        break;
+      case "export": {
+        const entries = history(db, stringFlag(flags, "project"), {
+          limit: -1,
+        })
+          .reverse()
+          .map(toPortableStatusEntry);
+        const format = stringFlag(flags, "format") ?? "json";
+        if (format === "jsonl")
+          write(
+            entries.map((entry) => JSON.stringify(entry)).join("\n") +
+              (entries.length ? "\n" : ""),
+          );
+        else if (format === "json") output(entries, true, write);
+        else throw new ValidationError("--format must be json or jsonl");
+        break;
+      }
+    }
+  } finally {
+    db.close();
+  }
+}
+
+/* c8 ignore start -- process entry glue is covered by the CLI integration tests through run(). */
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
+  try {
+    run(process.argv.slice(2));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+/* c8 ignore stop */

package/src/db.ts

@@ -0,0 +1,220 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  type Source,
+  type StatusEntry,
+  type StatusEntryInput,
+  validateStatusEntry,
+  ValidationError,
+} from "./domain.js";
+
+export type Ledger = Database.Database;
+export type InsertResult = { entry: StatusEntry; inserted: boolean };
+export type HistoryOptions = {
+  since?: string;
+  until?: string;
+  limit?: number;
+  offset?: number;
+};
+
+const migration = `
+CREATE TABLE IF NOT EXISTS projects (
+  id INTEGER PRIMARY KEY,
+  slug TEXT NOT NULL UNIQUE,
+  display_name TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS status_entries (
+  id INTEGER PRIMARY KEY,
+  project_id INTEGER NOT NULL REFERENCES projects(id),
+  status TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  progress TEXT,
+  blockers_json TEXT NOT NULL DEFAULT '[]',
+  next_steps_json TEXT NOT NULL DEFAULT '[]',
+  decisions_json TEXT NOT NULL DEFAULT '[]',
+  tags_json TEXT NOT NULL DEFAULT '[]',
+  occurred_at TEXT NOT NULL,
+  recorded_at TEXT NOT NULL,
+  source TEXT NOT NULL,
+  external_ref TEXT UNIQUE
+);
+CREATE INDEX IF NOT EXISTS idx_status_entries_project_occurred ON status_entries(project_id, occurred_at DESC, id DESC);
+`;
+
+export function databasePath(): string {
+  return (
+    process.env.PMGR_DB_PATH ||
+    resolve(process.cwd(), "data", "project-mgr.sqlite")
+  );
+}
+
+export function openLedger(path = databasePath()): Ledger {
+  if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+  const db = new Database(path);
+  db.pragma("foreign_keys = ON");
+  db.exec(
+    "CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY)",
+  );
+  db.transaction(() => {
+    if (
+      !db.prepare("SELECT 1 FROM schema_migrations WHERE version = 1").get()
+    ) {
+      db.exec(migration);
+      db.prepare("INSERT INTO schema_migrations(version) VALUES (1)").run();
+    }
+  }).immediate();
+  return db;
+}
+
+function entryFromRow(row: Record<string, unknown>): StatusEntry {
+  return {
+    id: row.id as number,
+    project: row.project as string,
+    status: row.status as StatusEntry["status"],
+    summary: row.summary as string,
+    ...(row.progress ? { progress: row.progress as string } : {}),
+    blockers: JSON.parse(row.blockers_json as string) as string[],
+    nextSteps: JSON.parse(row.next_steps_json as string) as string[],
+    decisions: JSON.parse(row.decisions_json as string) as string[],
+    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"],
+    ...(row.external_ref ? { externalRef: row.external_ref as string } : {}),
+  };
+}
+
+const select = `SELECT e.*, p.slug AS project FROM status_entries e JOIN projects p ON p.id = e.project_id`;
+function one(
+  db: Ledger,
+  sql: string,
+  ...params: unknown[]
+): StatusEntry | undefined {
+  const row = db.prepare(sql).get(...params) as
+    Record<string, unknown> | undefined;
+  return row && entryFromRow(row);
+}
+
+export function addStatus(
+  db: Ledger,
+  value: unknown,
+  defaultSource: Source = "human",
+): InsertResult {
+  const input = validateStatusEntry(value, defaultSource);
+  return db.transaction(() => addValidatedStatus(db, input))();
+}
+
+function addValidatedStatus(
+  db: Ledger,
+  input: StatusEntryInput & { occurredAt: string; source: Source },
+): InsertResult {
+  if (input.externalRef) {
+    const existing = one(
+      db,
+      `${select} WHERE e.external_ref = ?`,
+      input.externalRef,
+    );
+    if (existing) {
+      if (existing.project !== input.project)
+        throw new ValidationError(
+          `externalRef is already used by project ${existing.project}`,
+        );
+      return { entry: existing, inserted: false };
+    }
+  }
+  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);
+  const project = db
+    .prepare("SELECT id FROM projects WHERE slug = ?")
+    .get(input.project) as { id: number };
+  const result = db
+    .prepare(
+      `INSERT INTO status_entries(project_id, status, summary, progress, blockers_json, next_steps_json, decisions_json, tags_json, occurred_at, recorded_at, source, external_ref)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      project.id,
+      input.status,
+      input.summary,
+      input.progress ?? null,
+      JSON.stringify(input.blockers),
+      JSON.stringify(input.nextSteps),
+      JSON.stringify(input.decisions),
+      JSON.stringify(input.tags),
+      input.occurredAt,
+      now,
+      input.source,
+      input.externalRef ?? null,
+    );
+  return {
+    entry: one(
+      db,
+      `${select} WHERE e.id = ?`,
+      result.lastInsertRowid,
+    ) as StatusEntry,
+    inserted: true,
+  };
+}
+
+export function importStatuses(db: Ledger, values: unknown[]): InsertResult[] {
+  const inputs = values.map((value) => validateStatusEntry(value, "import"));
+  return db.transaction(() =>
+    inputs.map((input) => addValidatedStatus(db, input)),
+  )();
+}
+
+export function current(db: Ledger, project?: string): StatusEntry[] {
+  const where = project ? " AND p.slug = ?" : "";
+  const rows = db
+    .prepare(
+      `${select} WHERE e.id IN (SELECT id FROM (SELECT id, ROW_NUMBER() OVER (PARTITION BY project_id ORDER BY occurred_at DESC, id DESC) AS position FROM status_entries) WHERE position = 1)${where} ORDER BY e.occurred_at DESC, e.id DESC`,
+    )
+    .all(...(project ? [project] : [])) as Record<string, unknown>[];
+  return rows.map(entryFromRow);
+}
+
+export function history(
+  db: Ledger,
+  project?: string,
+  options: HistoryOptions = {},
+): StatusEntry[] {
+  const clauses: string[] = [];
+  const params: unknown[] = [];
+  if (project) {
+    clauses.push("p.slug = ?");
+    params.push(project);
+  }
+  if (options.since) {
+    clauses.push("e.occurred_at >= ?");
+    params.push(options.since);
+  }
+  if (options.until) {
+    clauses.push("e.occurred_at <= ?");
+    params.push(options.until);
+  }
+  const limit = options.limit ?? 100;
+  const offset = options.offset ?? 0;
+  const rows = db
+    .prepare(
+      `${select}${clauses.length ? ` WHERE ${clauses.join(" AND ")}` : ""} ORDER BY e.occurred_at DESC, e.id DESC LIMIT ? OFFSET ?`,
+    )
+    .all(...params, limit, offset) as Record<string, unknown>[];
+  return rows.map(entryFromRow);
+}
+
+export function at(
+  db: Ledger,
+  project: string,
+  occurredAt: string,
+): StatusEntry | undefined {
+  return one(
+    db,
+    `${select} WHERE p.slug = ? AND e.occurred_at <= ? ORDER BY e.occurred_at DESC, e.id DESC LIMIT 1`,
+    project,
+    occurredAt,
+  );
+}

package/src/domain.ts

@@ -0,0 +1,153 @@
+export const statuses = [
+  "idea",
+  "planned",
+  "active",
+  "blocked",
+  "paused",
+  "completed",
+  "archived",
+] as const;
+export const sources = ["human", "agent", "import"] as const;
+
+export type ProjectStatus = (typeof statuses)[number];
+export type Source = (typeof sources)[number];
+
+export type StatusEntryInput = {
+  project: string;
+  status: ProjectStatus;
+  summary: string;
+  progress?: string;
+  blockers?: string[];
+  nextSteps?: string[];
+  decisions?: string[];
+  tags?: string[];
+  occurredAt?: string;
+  source?: Source;
+  externalRef?: string;
+};
+
+export type StatusEntry = Required<
+  Omit<StatusEntryInput, "progress" | "externalRef">
+> & {
+  id: number;
+  progress?: string;
+  externalRef?: string;
+  recordedAt: string;
+};
+
+export type PortableStatusEntry = Omit<StatusEntry, "id" | "recordedAt">;
+
+const keys = new Set([
+  "project",
+  "status",
+  "summary",
+  "progress",
+  "blockers",
+  "nextSteps",
+  "decisions",
+  "tags",
+  "occurredAt",
+  "source",
+  "externalRef",
+]);
+const projectName = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ValidationError";
+  }
+}
+
+function text(
+  value: unknown,
+  field: string,
+  required = false,
+): string | undefined {
+  if (value === undefined && !required) return undefined;
+  if (typeof value !== "string" || !value.trim())
+    throw new ValidationError(`${field} must be a non-empty string`);
+  const normalized = value.trim();
+  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)
+    throw new ValidationError(
+      `${field} must be an array of at most 100 strings`,
+    );
+  return value.map((item) => text(item, field, true) as string);
+}
+
+export function parseTime(value: unknown, field: string): string {
+  if (
+    typeof value !== "string" ||
+    !/^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(value) ||
+    Number.isNaN(Date.parse(value))
+  ) {
+    throw new ValidationError(`${field} must be a valid ISO 8601 timestamp`);
+  }
+  return new Date(value).toISOString();
+}
+
+export function validateStatusEntry(
+  value: unknown,
+  defaultSource: Source = "human",
+): StatusEntryInput &
+  Required<Pick<StatusEntryInput, "occurredAt" | "source">> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new ValidationError("entry must be an object");
+  const input = value as Record<string, unknown>;
+  for (const key of Object.keys(input))
+    if (!keys.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",
+    );
+  if (!statuses.includes(input.status as ProjectStatus))
+    throw new ValidationError("status is invalid");
+  const source = input.source === undefined ? defaultSource : input.source;
+  if (!sources.includes(source as Source))
+    throw new ValidationError("source is invalid");
+  const externalRef = text(input.externalRef, "externalRef");
+  if (externalRef && externalRef.length > 200)
+    throw new ValidationError("externalRef must be at most 200 characters");
+  return {
+    project,
+    status: input.status as ProjectStatus,
+    summary: text(input.summary, "summary", true) as string,
+    progress: text(input.progress, "progress"),
+    blockers: textList(input.blockers, "blockers"),
+    nextSteps: textList(input.nextSteps, "nextSteps"),
+    decisions: textList(input.decisions, "decisions"),
+    tags: textList(input.tags, "tags"),
+    occurredAt:
+      input.occurredAt === undefined
+        ? new Date().toISOString()
+        : parseTime(input.occurredAt, "occurredAt"),
+    source: source as Source,
+    externalRef,
+  };
+}
+
+export function toPortableStatusEntry(entry: StatusEntry): PortableStatusEntry {
+  return {
+    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 }),
+  };
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./db.js";
+export * from "./domain.js";