project-mgr 0.1.0

package/dist/db.js

@@ -0,0 +1,131 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { validateStatusEntry, ValidationError, } from "./domain.js";
+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() {
+    return (process.env.PMGR_DB_PATH ||
+        resolve(process.cwd(), "data", "project-mgr.sqlite"));
+}
+export function openLedger(path = databasePath()) {
+    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) {
+    return {
+        id: row.id,
+        project: row.project,
+        status: row.status,
+        summary: row.summary,
+        ...(row.progress ? { progress: row.progress } : {}),
+        blockers: JSON.parse(row.blockers_json),
+        nextSteps: JSON.parse(row.next_steps_json),
+        decisions: JSON.parse(row.decisions_json),
+        tags: JSON.parse(row.tags_json),
+        occurredAt: row.occurred_at,
+        recordedAt: row.recorded_at,
+        source: row.source,
+        ...(row.external_ref ? { externalRef: row.external_ref } : {}),
+    };
+}
+const select = `SELECT e.*, p.slug AS project FROM status_entries e JOIN projects p ON p.id = e.project_id`;
+function one(db, sql, ...params) {
+    const row = db.prepare(sql).get(...params);
+    return row && entryFromRow(row);
+}
+export function addStatus(db, value, defaultSource = "human") {
+    const input = validateStatusEntry(value, defaultSource);
+    return db.transaction(() => addValidatedStatus(db, input))();
+}
+function addValidatedStatus(db, input) {
+    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);
+    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),
+        inserted: true,
+    };
+}
+export function importStatuses(db, values) {
+    const inputs = values.map((value) => validateStatusEntry(value, "import"));
+    return db.transaction(() => inputs.map((input) => addValidatedStatus(db, input)))();
+}
+export function current(db, project) {
+    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] : []));
+    return rows.map(entryFromRow);
+}
+export function history(db, project, options = {}) {
+    const clauses = [];
+    const params = [];
+    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);
+    return rows.map(entryFromRow);
+}
+export function at(db, project, occurredAt) {
+    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/dist/domain.d.ts

@@ -0,0 +1,30 @@
+export declare const statuses: readonly ["idea", "planned", "active", "blocked", "paused", "completed", "archived"];
+export declare const sources: readonly ["human", "agent", "import"];
+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">;
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+export declare function parseTime(value: unknown, field: string): string;
+export declare function validateStatusEntry(value: unknown, defaultSource?: Source): StatusEntryInput & Required<Pick<StatusEntryInput, "occurredAt" | "source">>;
+export declare function toPortableStatusEntry(entry: StatusEntry): PortableStatusEntry;

package/dist/domain.js

@@ -0,0 +1,106 @@
+export const statuses = [
+    "idea",
+    "planned",
+    "active",
+    "blocked",
+    "paused",
+    "completed",
+    "archived",
+];
+export const sources = ["human", "agent", "import"];
+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) {
+        super(message);
+        this.name = "ValidationError";
+    }
+}
+function text(value, field, required = false) {
+    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, field) {
+    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));
+}
+export function parseTime(value, field) {
+    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, defaultSource = "human") {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new ValidationError("entry must be an object");
+    const input = value;
+    for (const key of Object.keys(input))
+        if (!keys.has(key))
+            throw new ValidationError(`unknown field: ${key}`);
+    const project = text(input.project, "project", true);
+    if (!projectName.test(project))
+        throw new ValidationError("project must use letters, numbers, dots, underscores, or hyphens");
+    if (!statuses.includes(input.status))
+        throw new ValidationError("status is invalid");
+    const source = input.source === undefined ? defaultSource : input.source;
+    if (!sources.includes(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,
+        summary: text(input.summary, "summary", true),
+        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,
+        externalRef,
+    };
+}
+export function toPortableStatusEntry(entry) {
+    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/dist/index.d.ts

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

package/dist/index.js

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

package/docs/architecture.md

@@ -0,0 +1,95 @@
+# Architecture
+
+## Design goals
+
+`project-mgr` is a local, single-machine, append-only project status ledger. The first release follows four principles:
+
+- History is never overwritten: every write appends a status snapshot.
+- One source of truth: the CLI and any future interfaces must reuse the same domain and database logic.
+- Clear time semantics: distinguish when a status occurred from when the system recorded it.
+- Portable: exports can be imported into a new database to restore the status timeline.
+
+The first release has no work that needs to run continuously, so it provides neither an HTTP API nor PM2 configuration. Consider a service layer only when other local processes need a stable interface or background jobs.
+
+## Module boundaries
+
+```text
+User / script
+    │
+    ▼
+src/cli.ts       Argument parsing, file input, output formatting, command-level constraints
+    │
+    ├──────────────► src/domain.ts
+    │                 Types, field validation, time normalization, portable record conversion
+    ▼
+src/db.ts        SQLite connection, migrations, transactions, idempotent writes, and queries
+    │
+    ▼
+SQLite file
+```
+
+`src/index.ts` exports only public types and functions. Business validation does not depend on the CLI, so bulk imports and direct database API calls use the same rules.
+
+The CLI accepts `pmgr <action>` for `add`, `import`, `current`, `history`, `at`, and `export`; `pmgr status <action>` remains a compatible form. Both forms share the same validation and execution path.
+
+## Data model
+
+The database contains three structures:
+
+- `schema_migrations`: Applied migration versions.
+- `projects`: Project slug, display name, and creation time.
+- `status_entries`: Immutable status snapshots and their project foreign keys.
+
+Key `status_entries` fields:
+
+| Field                                                             | Meaning                                                                                  |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `status`, `summary`, `progress`                                   | Status enum, summary, and completed work                                                 |
+| `blockers_json`, `next_steps_json`, `decisions_json`, `tags_json` | JSON-encoded string arrays                                                               |
+| `occurred_at`                                                     | When the status actually occurred, supplied by the caller or generated during validation |
+| `recorded_at`                                                     | When the database actually wrote the entry                                               |
+| `source`                                                          | `human`, `agent`, or `import`                                                            |
+| `external_ref`                                                    | Optional globally unique idempotency key                                                 |
+
+The `project_id, occurred_at DESC, id DESC` index supports current-status and history queries.
+
+## 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.
+
+The database path is read from `PMGR_DB_PATH` first; otherwise, it uses `data/project-mgr.sqlite` in the process working directory. Non-memory databases create their parent directory automatically.
+
+## Write flow
+
+A single write proceeds as follows:
+
+1. Reject unknown fields and validate the project name, status, source, string arrays, and time.
+2. Normalize all timestamps to UTC ISO 8601 strings.
+3. In a transaction, check `externalRef`: repeated calls for the same project return the existing entry; cross-project conflicts fail.
+4. Create the project when needed, then append a status snapshot.
+5. Read and return the final entry from the database.
+
+Bulk import validates all input first, then executes the same write logic for each entry in one transaction. A database constraint or any failed write rolls back the entire batch.
+
+## Query semantics
+
+- Current status: take the first entry for each project ordered by `occurred_at DESC, id DESC`.
+- History: use the same occurrence-time and ID descending order, with inclusive `since` / `until` bounds and `limit` / `offset`.
+- Status at a time: take the first entry with `occurred_at <=` the specified time.
+- Same occurrence time: the later-written, larger `id` wins, keeping results deterministic.
+
+All ISO 8601 timestamps are converted to UTC on write, so SQLite string ordering matches time ordering.
+
+## Import and export
+
+Complete records returned by database queries include the internal `id` and `recordedAt`. The export layer removes these read-only fields while preserving business fields, original source, and the idempotency key, so JSON and JSONL can pass strict input validation when imported again.
+
+Exports have no record limit and reverse descending history results into oldest-to-newest order. When restoring to an empty database, entries with the same `occurredAt` receive IDs in their original append order, so the current status remains the same.
+
+## Consistency and limits
+
+- SQLite transactions guarantee atomic single writes and bulk imports.
+- `externalRef` is unique across the entire database; cross-project reuse is explicitly rejected.
+- Current status is derived from history; no separate cache table can drift.
+- Version 1 is for trusted local users and includes no authentication, authorization, multi-user synchronization, or encryption.
+- JSON arrays are stored as text. Evaluate a normalized schema only when cross-field full-text search or complex tag statistics are needed.

package/eslint.config.js

@@ -0,0 +1,12 @@
+import plugin from "@typescript-eslint/eslint-plugin";
+import parser from "@typescript-eslint/parser";
+
+export default [
+  {
+    files: ["src/**/*.ts", "test/**/*.ts"],
+    ignores: ["dist/**", "coverage/**", "node_modules/**"],
+    languageOptions: { parser },
+    plugins: { "@typescript-eslint": plugin },
+    rules: { "@typescript-eslint/no-unused-vars": "error" },
+  },
+];

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "project-mgr",
+  "version": "0.1.0",
+  "description": "Local-first append-only project status ledger",
+  "type": "module",
+  "bin": {
+    "pmgr": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node --env-file-if-exists=.env dist/cli.js",
+    "pmgr": "node --env-file-if-exists=.env --import tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format-check": "prettier --check .",
+    "test": "tsx --test test/**/*.test.ts",
+    "coverage": "c8 --all --extension .ts --exclude 'dist/**' --exclude 'test/**' --check-coverage --statements 100 --branches 100 --functions 100 --lines 100 pnpm test"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.6.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.15.3",
+    "@typescript-eslint/eslint-plugin": "^8.35.0",
+    "@typescript-eslint/parser": "^8.35.0",
+    "c8": "^10.1.3",
+    "eslint": "^9.30.0",
+    "prettier": "^3.6.2",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.30.2"
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+onlyBuiltDependencies:
+  - better-sqlite3
+  - esbuild