@druumen/sessions-db 0.1.0

package/cli/sweep.mjs

@@ -0,0 +1,171 @@
+/**
+ * `sessions-db sweep` — compute and apply activity_state transitions
+ * (active → idle → archived) by recency.
+ *
+ * Day 3 refactor: the planning + commit loop lives in
+ * `lib/operations.runSweep`. This handler is a thin wrapper that handles
+ * argparse, output rendering (human / JSON / quiet), and exit code mapping.
+ *
+ * Threshold validation (positive numbers; archive >= idle) stays in the
+ * CLI as exit-2 argparse errors so the test suite can pin both message
+ * and code without a library prefix in the message.
+ */
+
+import { runSweep } from '../lib/operations.mjs';
+import { ArgparseError, formatHelp, parseArgs } from './argparse.mjs';
+import { formatJSON } from './format.mjs';
+
+const SPEC = {
+  positional: [],
+  flags: {
+    '--dry-run': { type: 'boolean' },
+    '--idle-threshold-days': { type: 'number' },
+    '--archive-threshold-days': { type: 'number' },
+    '--json': { type: 'boolean' },
+    '--root': { type: 'string' },
+    '--quiet': { type: 'boolean' },
+  },
+};
+
+export const HELP = formatHelp({
+  usage: 'sessions-db sweep [--dry-run] [--idle-threshold-days N] [--archive-threshold-days N]',
+  summary: 'Compute activity_state transitions (active → idle → archived) and write sweep events.',
+  flags: [
+    { name: '--dry-run',                   desc: 'print planned transitions without writing events' },
+    { name: '--idle-threshold-days <N>',   desc: 'override idle threshold (default: _meta.idle_threshold_days || 14)' },
+    { name: '--archive-threshold-days <N>', desc: 'override archive threshold (default: _meta.archive_threshold_days || 30)' },
+    { name: '--json',                      desc: 'JSON output (machine-readable)' },
+    { name: '--root <p>',                  desc: 'override storage root (default cwd)' },
+    { name: '--quiet',                     desc: 'silent stdout (exit code only)' },
+  ],
+  examples: [
+    'sessions-db sweep --dry-run                  # preview transitions',
+    'sessions-db sweep                            # apply transitions',
+    'sessions-db sweep --idle-threshold-days 7    # one-off override',
+  ],
+});
+
+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 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 threshold validation. parseArgs already rejected
+  // non-numeric values; we additionally reject 0 / negative so a typo
+  // like `--idle-threshold-days 0` does not silently disable the
+  // threshold (which would auto-archive every session). These exit codes
+  // (2, "must be a positive number" / "must be >= --idle-threshold-days")
+  // are what the test suite pins against.
+  const idleThresholdDays = parsed.flags['--idle-threshold-days'];
+  if (idleThresholdDays !== undefined
+      && (!Number.isFinite(idleThresholdDays) || idleThresholdDays <= 0)) {
+    process.stderr.write(
+      `error: --idle-threshold-days must be a positive number (got: ${idleThresholdDays})\n`,
+    );
+    process.exit(2);
+  }
+  const archiveThresholdDays = parsed.flags['--archive-threshold-days'];
+  if (archiveThresholdDays !== undefined
+      && (!Number.isFinite(archiveThresholdDays) || archiveThresholdDays <= 0)) {
+    process.stderr.write(
+      `error: --archive-threshold-days must be a positive number (got: ${archiveThresholdDays})\n`,
+    );
+    process.exit(2);
+  }
+  if (idleThresholdDays !== undefined
+      && archiveThresholdDays !== undefined
+      && archiveThresholdDays < idleThresholdDays) {
+    process.stderr.write(
+      `error: --archive-threshold-days (${archiveThresholdDays}) must be >= --idle-threshold-days (${idleThresholdDays})\n`,
+    );
+    process.exit(2);
+  }
+
+  const opts = {
+    idleThresholdDays,
+    archiveThresholdDays,
+    dryRun,
+    ...(root ? { root } : {}),
+  };
+  const result = await runSweep(opts);
+
+  // Dry-run path — print plan and bail. ok is always true for dry-run.
+  if (dryRun) {
+    const transitions = result.transitions || [];
+    if (json) {
+      process.stdout.write(formatJSON({
+        ok: true,
+        dry_run: true,
+        transitions,
+        count: transitions.length,
+      }));
+    } else if (!quiet) {
+      if (transitions.length === 0) {
+        process.stdout.write('ok: sweep dry-run — no transitions needed\n');
+      } else {
+        process.stdout.write(
+          `ok: sweep dry-run — ${transitions.length} transition${transitions.length === 1 ? '' : 's'} planned:\n`,
+        );
+        for (const t of transitions) {
+          process.stdout.write(
+            `  ${t.stable_id}  ${t.from_state} → ${t.to_state}  (age ${t.age_days}d, last_progress ${t.effective_last_progress})\n`,
+          );
+        }
+      }
+    }
+    return;
+  }
+
+  const applied = result.applied || [];
+  const failed = result.failed || [];
+  const summary = result.summary || {
+    total: 0, applied: 0, failed: 0, to_idle: 0, to_archived: 0,
+  };
+
+  if (json) {
+    process.stdout.write(formatJSON({
+      ok: failed.length === 0,
+      applied,
+      failed,
+      summary,
+    }));
+  } else if (!quiet) {
+    if (summary.total === 0) {
+      process.stdout.write('ok: sweep — no transitions needed\n');
+    } else {
+      process.stdout.write(
+        `ok: sweep — ${applied.length} of ${summary.total} transition${summary.total === 1 ? '' : 's'} applied (${summary.to_idle} to idle, ${summary.to_archived} to archived)\n`,
+      );
+      for (const a of applied) {
+        process.stdout.write(
+          `  ${a.stable_id}  ${a.from_state} → ${a.to_state}  (age ${a.age_days}d)\n`,
+        );
+      }
+      if (failed.length > 0) {
+        process.stderr.write(`error: ${failed.length} transition${failed.length === 1 ? '' : 's'} failed:\n`);
+        for (const f of failed) {
+          process.stderr.write(`  ${f.stable_id}  ${f.from_state} → ${f.to_state}: ${f.error}\n`);
+        }
+      }
+    }
+  }
+
+  if (failed.length > 0) process.exit(1);
+}

package/cli/tree.mjs

@@ -0,0 +1,127 @@
+/**
+ * `sessions-db tree <stable_id>` — render the hub-spoke subtree rooted at
+ * `stable_id` (parent + recursive children). Read-only.
+ *
+ * The tree is built by inverting `parent_session_id` across all sessions in
+ * the projection. Depth is capped (formatTree internals) to defend against
+ * accidental circular chains.
+ *
+ * Exit codes:
+ *   0 — root rendered
+ *   1 — root stable_id not found in projection
+ *   2 — argparse error (missing positional, etc.)
+ */
+
+import { loadProjection } from '../lib/storage.mjs';
+import { ArgparseError, formatHelp, parseArgs } from './argparse.mjs';
+import { formatJSON, formatTree, shouldUseColor } from './format.mjs';
+
+const SPEC = {
+  positional: [{ name: 'stable_id', required: true }],
+  flags: {
+    '--json': { type: 'boolean' },
+    '--no-color': { type: 'boolean' },
+    '--root': { type: 'string' },
+    '--quiet': { type: 'boolean' },
+  },
+};
+
+export const HELP = formatHelp({
+  usage: 'sessions-db tree <stable_id> [--json]',
+  summary: 'Render the hub-spoke parent → children subtree rooted at stable_id.',
+  flags: [
+    { name: '--json',        desc: 'JSON output: { root, children: [{stable_id, alias, ...}] }' },
+    { name: '--no-color',    desc: 'disable ANSI color' },
+    { name: '--root <path>', desc: 'override storage root (default cwd)' },
+  ],
+  examples: [
+    'sessions-db tree sess_01970000-0000-7000-8000-00000000000a',
+  ],
+});
+
+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 root = parsed.flags['--root'];
+  const projection = await loadProjection(root ? { root } : {});
+
+  if (!projection.sessions || !projection.sessions[stableId]) {
+    process.stderr.write(`error: stable_id not found: ${stableId}\n`);
+    process.exit(1);
+  }
+
+  if (parsed.flags['--quiet']) return;
+
+  if (parsed.flags['--json']) {
+    process.stdout.write(formatJSON(buildTreeJSON(stableId, projection)));
+    return;
+  }
+
+  const useColor = shouldUseColor(
+    process.stdout.isTTY,
+    process.env,
+    parsed.flags['--no-color'] === true,
+  );
+  process.stdout.write(formatTree(stableId, projection, { useColor }));
+}
+
+/**
+ * Build a JSON-friendly tree object. Exposed for tests.
+ */
+export function buildTreeJSON(rootId, projection) {
+  const sessions = projection && projection.sessions ? projection.sessions : {};
+  const childIdx = new Map();
+  for (const [sid, s] of Object.entries(sessions)) {
+    const parent = s && s.parent_session_id;
+    if (parent && parent !== sid) {
+      if (!childIdx.has(parent)) childIdx.set(parent, []);
+      childIdx.get(parent).push(sid);
+    }
+  }
+  const visited = new Set();
+  const MAX_DEPTH = 32;
+
+  function build(sid, depth) {
+    if (depth > MAX_DEPTH) return { stable_id: sid, truncated: 'max-depth' };
+    if (visited.has(sid)) return { stable_id: sid, truncated: 'circular' };
+    visited.add(sid);
+    const s = sessions[sid];
+    const kids = (childIdx.get(sid) || [])
+      .slice()
+      .sort((a, b) => {
+        const ca = sessions[a] && sessions[a].created_at;
+        const cb = sessions[b] && sessions[b].created_at;
+        if (!ca && !cb) return 0;
+        if (!ca) return 1;
+        if (!cb) return -1;
+        return ca < cb ? -1 : ca > cb ? 1 : 0;
+      })
+      .map((kid) => build(kid, depth + 1));
+    return {
+      stable_id: sid,
+      alias: s ? s.alias : null,
+      activity_state: s ? s.activity_state : null,
+      outcome: s ? s.outcome : null,
+      last_progress_at: s ? s.last_progress_at : null,
+      branch_current: s ? s.branch_current : null,
+      children: kids,
+    };
+  }
+
+  return build(rootId, 0);
+}