@druumen/sessions-db 0.1.0

package/cli/argparse.mjs

@@ -0,0 +1,296 @@
+/**
+ * Minimal hand-rolled argparse for sessions-db CLI subcommands.
+ *
+ * Why not `node:util.parseArgs`? Three reasons:
+ *  - We want subcommand-local exit codes (2 for argparse error) with custom
+ *    error messages that point at the offending flag — `parseArgs` throws
+ *    generic TypeError which is hard to surface as a CLI banner without
+ *    adding a wrapping layer anyway.
+ *  - We want to support both `--flag value` AND `--flag=value` AND repeated
+ *    flags (collected as arrays) without each handler reimplementing the
+ *    same plumbing.
+ *  - Zero-dependency per the P4 ticket constraint, and parseArgs API has
+ *    differed across Node versions (we're testing on the same major used by
+ *    hooks/tests). A locally-owned 100-line parser is easier to debug than a
+ *    wire-up around a stdlib that occasionally changes shape.
+ *
+ * Spec object shape:
+ *   {
+ *     positional: [
+ *       { name: 'stable_id', required: true },
+ *       { name: 'alias', required: false },
+ *     ],
+ *     // Opt-in: when true, accept any number of extra positionals beyond the
+ *     // declared slots and stash them in `positionalArray` for the caller.
+ *     // Default false: extra positionals are an argparse error (exit 2).
+ *     restPositional: false,
+ *     flags: {
+ *       '--task':    { type: 'string',  alias: '-t' },
+ *       '--remove':  { type: 'boolean' },
+ *       '--limit':   { type: 'number', default: 50 },
+ *       '--label':   { type: 'string', repeatable: true }, // collected as array
+ *       '--json':    { type: 'boolean' },
+ *       '--root':    { type: 'string' },
+ *       '--dry-run': { type: 'boolean' },
+ *       '--quiet':   { type: 'boolean' },
+ *     },
+ *     help: 'subcommand-specific help text',
+ *   }
+ *
+ * Boolean flag value semantics (P4 round-1 review fix):
+ *   `--flag` (no value)        → true
+ *   `--flag=true|1|yes`        → true
+ *   `--flag=false|0|no`        → false
+ *   `--flag value` (spaced)    → REJECTED (would silently swallow value as
+ *                                an extra positional, masking user intent).
+ *   This is consistent with `parseArgs` in node:util and avoids the trap
+ *   where `link --remove false` was previously parsed as `--remove=true`
+ *   plus a stray `false` token that got dropped on the floor.
+ *
+ * Returns:
+ *   {
+ *     positional: { stable_id: 'sess_...', alias: 'foo' },
+ *     positionalArray: ['sess_...', 'foo'],   // raw order
+ *     flags: { '--task': 'T-1', '--limit': 50, ... },
+ *     helpRequested: false,
+ *   }
+ *
+ * Errors throw `ArgparseError` with `.exitCode = 2` and `.message` ready for
+ * stderr. The CLI dispatcher catches these and exits 2 — handlers themselves
+ * never need to think about exit codes for parse failures.
+ */
+
+const TRUE_BOOL_VALUES = new Set(['true', '1', 'yes']);
+const FALSE_BOOL_VALUES = new Set(['false', '0', 'no']);
+
+export class ArgparseError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ArgparseError';
+    this.exitCode = 2;
+  }
+}
+
+/**
+ * Parse argv tokens against `spec`. Throws ArgparseError on any violation.
+ *
+ * @param {string[]} argv
+ * @param {object} spec
+ * @returns {{
+ *   positional: Record<string, string>,
+ *   positionalArray: string[],
+ *   flags: Record<string, any>,
+ *   helpRequested: boolean,
+ * }}
+ */
+export function parseArgs(argv, spec = {}) {
+  const positionalSpec = Array.isArray(spec.positional) ? spec.positional : [];
+  const flagsSpec = (spec.flags && typeof spec.flags === 'object') ? spec.flags : {};
+
+  // Build alias→canonical map so `-t` resolves to `--task`.
+  const aliasMap = {};
+  for (const [name, def] of Object.entries(flagsSpec)) {
+    if (def && typeof def.alias === 'string' && def.alias.length > 0) {
+      aliasMap[def.alias] = name;
+    }
+  }
+
+  const out = {
+    positional: {},
+    positionalArray: [],
+    flags: {},
+    helpRequested: false,
+  };
+
+  // Pre-fill defaults for declared flags.
+  for (const [name, def] of Object.entries(flagsSpec)) {
+    if (def && Object.prototype.hasOwnProperty.call(def, 'default')) {
+      out.flags[name] = def.default;
+    }
+  }
+
+  // Walk argv. Stop if we see `--` (POSIX double-dash separator) — anything
+  // after it is treated as positional even if it looks like a flag. This lets
+  // callers pass aliases / IDs that begin with `-` without ambiguity.
+  let i = 0;
+  let sawDoubleDash = false;
+  while (i < argv.length) {
+    const tok = argv[i];
+
+    if (!sawDoubleDash && tok === '--') {
+      sawDoubleDash = true;
+      i += 1;
+      continue;
+    }
+
+    if (!sawDoubleDash && (tok === '-h' || tok === '--help')) {
+      out.helpRequested = true;
+      i += 1;
+      continue;
+    }
+
+    // Flag form: `--name`, `--name=value`, or short alias `-x`.
+    if (!sawDoubleDash && tok.startsWith('-') && tok !== '-') {
+      const eqIdx = tok.indexOf('=');
+      let rawName;
+      let inlineValue;
+      if (eqIdx !== -1) {
+        rawName = tok.slice(0, eqIdx);
+        inlineValue = tok.slice(eqIdx + 1);
+      } else {
+        rawName = tok;
+        inlineValue = undefined;
+      }
+
+      // Resolve short alias to canonical.
+      const canonical = aliasMap[rawName] || rawName;
+      const def = flagsSpec[canonical];
+      if (!def) {
+        throw new ArgparseError(`unknown flag: ${rawName}`);
+      }
+
+      const type = def.type || 'string';
+
+      if (type === 'boolean') {
+        let value;
+        if (inlineValue !== undefined) {
+          if (TRUE_BOOL_VALUES.has(inlineValue.toLowerCase())) value = true;
+          else if (FALSE_BOOL_VALUES.has(inlineValue.toLowerCase())) value = false;
+          else {
+            throw new ArgparseError(
+              `boolean flag ${canonical} got non-boolean value: ${inlineValue}`,
+            );
+          }
+        } else {
+          // P4 round-1 review fix: reject `--flag value` (spaced) form for
+          // booleans. Previously `--remove false` parsed as `--remove=true`
+          // with `false` silently consumed as an extra positional — masking
+          // user intent. The acceptable forms are `--flag` and `--flag=value`.
+          const next = argv[i + 1];
+          if (
+            next !== undefined
+            && (TRUE_BOOL_VALUES.has(next.toLowerCase())
+              || FALSE_BOOL_VALUES.has(next.toLowerCase()))
+          ) {
+            throw new ArgparseError(
+              `boolean flag ${canonical} does not accept a positional value: ${next} `
+              + `(use ${canonical}=${next} if you meant to set it explicitly)`,
+            );
+          }
+          value = true;
+        }
+        out.flags[canonical] = value;
+        i += 1;
+        continue;
+      }
+
+      // string / number — need a value (either inline or next token).
+      let raw;
+      if (inlineValue !== undefined) {
+        raw = inlineValue;
+        i += 1;
+      } else {
+        if (i + 1 >= argv.length) {
+          throw new ArgparseError(`flag ${canonical} requires a value`);
+        }
+        raw = argv[i + 1];
+        // Don't allow the next token to be another flag if it looks like one.
+        // This catches typos like `--task --json` where the user forgot the
+        // task value — better to fail than silently consume `--json` as the
+        // task identifier.
+        if (raw.startsWith('-') && raw !== '-' && !/^-?\d/.test(raw)) {
+          throw new ArgparseError(
+            `flag ${canonical} requires a value (got next flag ${raw})`,
+          );
+        }
+        i += 2;
+      }
+
+      let value;
+      if (type === 'number') {
+        const n = Number(raw);
+        if (!Number.isFinite(n)) {
+          throw new ArgparseError(`flag ${canonical} expects a number, got: ${raw}`);
+        }
+        value = n;
+      } else {
+        // string (default)
+        value = raw;
+      }
+
+      if (def.repeatable === true) {
+        const cur = out.flags[canonical];
+        if (Array.isArray(cur)) cur.push(value);
+        else out.flags[canonical] = [value];
+      } else {
+        out.flags[canonical] = value;
+      }
+      continue;
+    }
+
+    // Positional.
+    out.positionalArray.push(tok);
+    i += 1;
+  }
+
+  // Map positionalArray → named positional slots.
+  for (let p = 0; p < positionalSpec.length; p++) {
+    const ps = positionalSpec[p];
+    if (!ps || typeof ps.name !== 'string') continue;
+    if (p < out.positionalArray.length) {
+      out.positional[ps.name] = out.positionalArray[p];
+    }
+  }
+
+  // Validate required positionals (skip if --help was requested — caller
+  // should print help and bail before we ever validate).
+  if (!out.helpRequested) {
+    for (const ps of positionalSpec) {
+      if (ps && ps.required === true && !(ps.name in out.positional)) {
+        throw new ArgparseError(`missing required positional: ${ps.name}`);
+      }
+    }
+    // P4 round-1 review fix: reject extra positionals unless the spec
+    // opts in via `restPositional: true`. Previously `tree <id> garbage`
+    // silently dropped the trailing token — an operator typo would not
+    // surface and they'd get unexpected output.
+    if (spec.restPositional !== true && out.positionalArray.length > positionalSpec.length) {
+      const extras = out.positionalArray.slice(positionalSpec.length);
+      throw new ArgparseError(
+        `unexpected extra positional argument(s): ${extras.join(' ')}`,
+      );
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Render a help banner for a subcommand. Composed by the subcommand handler
+ * (passes its own usage line + flag descriptions). Returns a string ending
+ * with a newline so the caller can `process.stdout.write()` directly.
+ *
+ * @param {{ usage: string, summary?: string, flags?: Array<{ name: string, desc: string }>, examples?: string[] }} parts
+ */
+export function formatHelp(parts) {
+  const lines = [];
+  lines.push(`Usage: ${parts.usage}`);
+  if (parts.summary) {
+    lines.push('');
+    lines.push(parts.summary);
+  }
+  if (Array.isArray(parts.flags) && parts.flags.length > 0) {
+    lines.push('');
+    lines.push('Flags:');
+    const width = parts.flags.reduce((m, f) => Math.max(m, f.name.length), 0);
+    for (const f of parts.flags) {
+      lines.push(`  ${f.name.padEnd(width)}  ${f.desc}`);
+    }
+  }
+  if (Array.isArray(parts.examples) && parts.examples.length > 0) {
+    lines.push('');
+    lines.push('Examples:');
+    for (const ex of parts.examples) lines.push(`  ${ex}`);
+  }
+  return lines.join('\n') + '\n';
+}

package/cli/close.mjs

@@ -0,0 +1,116 @@
+/**
+ * `sessions-db close <stable_id> --outcome X [--reason "..."]` — mark a
+ * session closed with a terminal outcome.
+ *
+ * Day 3 refactor: routes through `lib/operations.closeSession`. The CLI
+ * keeps the historical exit-2 path for missing / invalid `--outcome`
+ * (an argparse-class error) so the test suite can pin both the message
+ * and the code without depending on operations' return shape for those
+ * pre-call validations.
+ *
+ * Outcome enum is enforced (matches projection schema):
+ *   open | done | blocked | abandoned | merged | superseded
+ */
+
+import { closeSession } from '../lib/operations.mjs';
+import { ArgparseError, formatHelp, parseArgs } from './argparse.mjs';
+import { renderDryRun, reportResult, reportStableIdNotFound } from './_write-helpers.mjs';
+
+const VALID_OUTCOMES = new Set(['open', 'done', 'blocked', 'abandoned', 'merged', 'superseded']);
+
+const SPEC = {
+  positional: [{ name: 'stable_id', required: true }],
+  flags: {
+    '--outcome': { type: 'string' },
+    '--reason': { type: 'string' },
+    '--dry-run': { type: 'boolean' },
+    '--json': { type: 'boolean' },
+    '--root': { type: 'string' },
+    '--quiet': { type: 'boolean' },
+  },
+};
+
+export const HELP = formatHelp({
+  usage: 'sessions-db close <stable_id> --outcome <outcome> [--reason "..."]',
+  summary: 'Close (or reopen) a session with a terminal outcome.',
+  flags: [
+    { name: '--outcome <s>', desc: 'open | done | blocked | abandoned | merged | superseded' },
+    { name: '--reason <s>',  desc: 'human-readable reason (free text)' },
+    { name: '--dry-run',     desc: 'print event but do not write' },
+    { name: '--json',        desc: 'JSON output' },
+    { name: '--root <p>',    desc: 'override storage root' },
+  ],
+  examples: [
+    'sessions-db close sess_01970000-... --outcome done --reason "merged into master"',
+    'sessions-db close sess_01970000-... --outcome blocked --reason "waiting on infra"',
+  ],
+});
+
+export async function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv, SPEC);
+  } catch (err) {
+    if (err instanceof ArgparseError) {
+      process.stderr.write(`error: ${err.message}\n\n${HELP}`);
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+
+  if (parsed.helpRequested) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  const stableId = parsed.positional.stable_id;
+  const outcome = parsed.flags['--outcome'];
+  const reason = parsed.flags['--reason'];
+  const root = parsed.flags['--root'];
+  const dryRun = parsed.flags['--dry-run'] === true;
+  const json = parsed.flags['--json'] === true;
+  const quiet = parsed.flags['--quiet'] === true;
+
+  // Argparse-class checks (exit 2). The library would also reject these,
+  // but routing through CLI keeps the historical message + exit code that
+  // tests pin against.
+  if (!outcome) {
+    process.stderr.write(`error: --outcome is required\n`);
+    process.exit(2);
+  }
+  if (!VALID_OUTCOMES.has(outcome)) {
+    process.stderr.write(`error: --outcome must be one of: ${[...VALID_OUTCOMES].join(', ')}\n`);
+    process.exit(2);
+  }
+
+  if (dryRun) {
+    const payload = { outcome };
+    if (reason !== undefined) payload.closed_reason = reason;
+    renderDryRun({ op: 'close', stableId, payload, json });
+    return;
+  }
+
+  const opts = root ? { root } : {};
+  const result = await closeSession({
+    stableId,
+    outcome,
+    reason,
+    ...opts,
+  });
+
+  if (!result.ok && typeof result.error === 'string'
+      && result.error.startsWith('stable_id not found:')) {
+    if (!quiet) {
+      const code = reportStableIdNotFound(result.error);
+      process.exit(code);
+    }
+    process.exit(1);
+  }
+
+  const extra = { outcome };
+  if (reason !== undefined) extra.reason = reason;
+  const code = reportResult({
+    result, op: 'close', stableId, json, quiet, extra,
+  });
+  if (code !== 0) process.exit(code);
+}

package/cli/find.mjs

@@ -0,0 +1,185 @@
+/**
+ * `sessions-db find` — filter sessions by task / project / alias / branch /
+ * cwd / state / outcome. Read-only: never appends to events.jsonl.
+ *
+ * Filter semantics:
+ *   - All flags AND together (intersection).
+ *   - String filters are exact match. cwd uses substring match because the
+ *     stored cwd is an absolute path and operators usually remember the
+ *     trailing dir name only.
+ *   - state / outcome are validated against the projection's enum
+ *     (active|idle|archived for state, open|done|blocked|abandoned|
+ *      merged|superseded for outcome). Invalid values exit 2 (argparse-class).
+ *   - --limit defaults to 50 to keep a `find` with no filters readable. Sort
+ *     is last_progress_at DESC (most recent first) — matches the UX where
+ *     ops staff want to see "what's been touched lately" by default.
+ *
+ * Output:
+ *   - default: ASCII table (formatSessionTable)
+ *   - --json: array of full session records
+ */
+
+import { loadProjection } from '../lib/storage.mjs';
+import { ArgparseError, formatHelp, parseArgs } from './argparse.mjs';
+import { formatJSON, formatSessionTable, shouldUseColor } from './format.mjs';
+
+const VALID_STATES = new Set(['active', 'idle', 'archived']);
+const VALID_OUTCOMES = new Set(['open', 'done', 'blocked', 'abandoned', 'merged', 'superseded']);
+
+const SPEC = {
+  positional: [],
+  flags: {
+    '--task': { type: 'string' },
+    '--project': { type: 'string' },
+    '--alias': { type: 'string' },
+    '--branch': { type: 'string' },
+    '--cwd': { type: 'string' },
+    '--state': { type: 'string' },
+    '--outcome': { type: 'string' },
+    '--limit': { type: 'number', default: 50 },
+    '--json': { type: 'boolean' },
+    '--no-color': { type: 'boolean' },
+    '--root': { type: 'string' },
+    '--quiet': { type: 'boolean' },
+  },
+};
+
+export const HELP = formatHelp({
+  usage: 'sessions-db find [filters] [--limit N] [--json]',
+  summary: 'Filter sessions by task / project / alias / branch / cwd / state / outcome.',
+  flags: [
+    { name: '--task <id>',    desc: 'task filename match (e.g. feat-foo-DDMMYYYY.md)' },
+    { name: '--project <id>', desc: 'project key/dirname match' },
+    { name: '--alias <s>',    desc: 'exact alias match' },
+    { name: '--branch <b>',   desc: 'branch_current or branch_at_start exact match' },
+    { name: '--cwd <s>',      desc: 'cwd / worktree_path substring match' },
+    { name: '--state <s>',    desc: 'active | idle | archived' },
+    { name: '--outcome <s>',  desc: 'open | done | blocked | abandoned | merged | superseded' },
+    { name: '--limit <N>',    desc: 'cap result count (default 50)' },
+    { name: '--json',         desc: 'machine-readable JSON output' },
+    { name: '--no-color',     desc: 'disable ANSI color' },
+    { name: '--root <path>',  desc: 'override storage root (default cwd)' },
+  ],
+  examples: [
+    'sessions-db find --task feat-pricing-overhaul-04052026.md',
+    'sessions-db find --state active --limit 10',
+    'sessions-db find --branch master --outcome open --json',
+  ],
+});
+
+/**
+ * Pure filter — exposed so the integration test (and tree-style debugging
+ * tools) can drive the same query plane without the CLI shell.
+ *
+ * @param {object} projection
+ * @param {{ task?: string, project?: string, alias?: string, branch?: string,
+ *   cwd?: string, state?: string, outcome?: string, limit?: number }} filters
+ * @returns {Array<object>}
+ */
+export function searchSessions(projection, filters = {}) {
+  const sessions = projection && projection.sessions ? projection.sessions : {};
+  const limit = typeof filters.limit === 'number' && filters.limit > 0 ? filters.limit : 50;
+
+  const out = [];
+  for (const s of Object.values(sessions)) {
+    if (!matches(s, filters)) continue;
+    out.push(s);
+  }
+  // Sort by last_progress_at DESC (string compare on ISO 8601 is lexically
+  // correct for descending recency).
+  out.sort((a, b) => {
+    const la = a.last_progress_at || '';
+    const lb = b.last_progress_at || '';
+    if (la === lb) return 0;
+    return la < lb ? 1 : -1;
+  });
+  return out.slice(0, limit);
+}
+
+function matches(session, filters) {
+  if (!session || typeof session !== 'object') return false;
+
+  if (filters.task) {
+    if (!Array.isArray(session.tasks) || !session.tasks.includes(filters.task)) return false;
+  }
+  if (filters.project) {
+    if (!Array.isArray(session.projects) || !session.projects.includes(filters.project)) return false;
+  }
+  if (filters.alias) {
+    if (session.alias !== filters.alias) return false;
+  }
+  if (filters.branch) {
+    if (session.branch_current !== filters.branch
+        && session.branch_at_start !== filters.branch) return false;
+  }
+  if (filters.cwd) {
+    const candidates = [session.cwd, session.worktree_path_observed, session.worktree_realpath]
+      .filter((v) => typeof v === 'string' && v.length > 0);
+    if (!candidates.some((v) => v.includes(filters.cwd))) return false;
+  }
+  if (filters.state) {
+    if (session.activity_state !== filters.state) return false;
+  }
+  if (filters.outcome) {
+    if (session.outcome !== filters.outcome) return false;
+  }
+  return true;
+}
+
+export async function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv, SPEC);
+  } catch (err) {
+    if (err instanceof ArgparseError) {
+      process.stderr.write(`error: ${err.message}\n\n${HELP}`);
+      process.exit(err.exitCode);
+    }
+    throw err;
+  }
+
+  if (parsed.helpRequested) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  // Validate enum-typed flags.
+  if (parsed.flags['--state'] !== undefined && !VALID_STATES.has(parsed.flags['--state'])) {
+    process.stderr.write(`error: --state must be one of: ${[...VALID_STATES].join(', ')}\n`);
+    process.exit(2);
+  }
+  if (parsed.flags['--outcome'] !== undefined && !VALID_OUTCOMES.has(parsed.flags['--outcome'])) {
+    process.stderr.write(`error: --outcome must be one of: ${[...VALID_OUTCOMES].join(', ')}\n`);
+    process.exit(2);
+  }
+
+  const root = parsed.flags['--root'];
+  const projection = await loadProjection(root ? { root } : {});
+
+  const filters = {
+    task: parsed.flags['--task'],
+    project: parsed.flags['--project'],
+    alias: parsed.flags['--alias'],
+    branch: parsed.flags['--branch'],
+    cwd: parsed.flags['--cwd'],
+    state: parsed.flags['--state'],
+    outcome: parsed.flags['--outcome'],
+    limit: parsed.flags['--limit'],
+  };
+
+  const matched = searchSessions(projection, filters);
+
+  if (parsed.flags['--quiet']) return;
+
+  if (parsed.flags['--json']) {
+    process.stdout.write(formatJSON(matched));
+    return;
+  }
+
+  const useColor = shouldUseColor(
+    process.stdout.isTTY,
+    process.env,
+    parsed.flags['--no-color'] === true,
+  );
+  process.stdout.write(formatSessionTable(matched, { useColor }));
+}