causly-server 0.0.0-stage → 1.5.0

package/tools/projectOps.js

@@ -0,0 +1,192 @@
+import fs from "fs";
+import path from "path";
+import { simpleGit } from "simple-git";
+import { runCommand } from "./commandOps.js";
+
+function exists(p) {
+  try {
+    return fs.existsSync(p);
+  } catch {
+    return false;
+  }
+}
+
+function readJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Inspect a directory and identify the project type: language, framework,
+ * and package manager. Used by other project_* / run_* tools to decide
+ * which commands to run.
+ */
+export function detectProject(repo_path) {
+  const pkgPath = path.join(repo_path, "package.json");
+  if (exists(pkgPath)) {
+    const pkg = readJson(pkgPath) || {};
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    let framework = "Node.js";
+    if (deps.next) framework = "Next.js";
+    else if (deps.react) framework = "React";
+    else if (deps.vue) framework = "Vue";
+    else if (deps.express) framework = "Express";
+    else if (deps["@nestjs/core"]) framework = "NestJS";
+
+    let package_manager = "npm";
+    if (exists(path.join(repo_path, "pnpm-lock.yaml"))) package_manager = "pnpm";
+    else if (exists(path.join(repo_path, "yarn.lock"))) package_manager = "yarn";
+    else if (exists(path.join(repo_path, "bun.lockb"))) package_manager = "bun";
+
+    return { language: "JavaScript/TypeScript", framework, package_manager, manifest: "package.json", scripts: pkg.scripts || {} };
+  }
+
+  if (exists(path.join(repo_path, "pyproject.toml"))) {
+    const content = fs.readFileSync(path.join(repo_path, "pyproject.toml"), "utf8");
+    let framework = "Python";
+    if (content.includes("fastapi")) framework = "FastAPI";
+    else if (content.includes("django")) framework = "Django";
+    else if (content.includes("flask")) framework = "Flask";
+    return { language: "Python", framework, package_manager: "pip/poetry", manifest: "pyproject.toml", scripts: {} };
+  }
+
+  if (exists(path.join(repo_path, "requirements.txt"))) {
+    const content = fs.readFileSync(path.join(repo_path, "requirements.txt"), "utf8").toLowerCase();
+    let framework = "Python";
+    if (content.includes("django")) framework = "Django";
+    else if (content.includes("fastapi")) framework = "FastAPI";
+    else if (content.includes("flask")) framework = "Flask";
+    return { language: "Python", framework, package_manager: "pip", manifest: "requirements.txt", scripts: {} };
+  }
+
+  return { language: "unknown", framework: "unknown", package_manager: "unknown", manifest: null, scripts: {} };
+}
+
+export async function projectDetect({ repo_path }) {
+  return { repo_path, ...detectProject(repo_path) };
+}
+
+/** Resolve the concrete command to run for a semantic action (test/lint/typecheck/build). */
+function resolveCommand(repo_path, action) {
+  const info = detectProject(repo_path);
+
+  if (info.manifest === "package.json") {
+    const scriptMap = {
+      test: ["test"],
+      lint: ["lint"],
+      typecheck: ["typecheck", "type-check"],
+      build: ["build"],
+    };
+    const candidates = scriptMap[action] || [];
+    const found = candidates.find((name) => info.scripts[name]);
+    if (found) {
+      const runner = info.package_manager === "npm" ? "npm run" : info.package_manager;
+      return `${runner} ${found}`;
+    }
+    return null;
+  }
+
+  if (info.language === "Python") {
+    const pyDefaults = {
+      test: "pytest",
+      lint: "ruff check .",
+      typecheck: "mypy .",
+      build: "python -m build",
+    };
+    return pyDefaults[action] || null;
+  }
+
+  return null;
+}
+
+async function runSemantic({ repo_path, action, timeout_ms }) {
+  const command = resolveCommand(repo_path, action);
+  if (!command) {
+    return {
+      repo_path,
+      action,
+      ran: false,
+      reason: `Could not detect a '${action}' command for this project. Add a matching script to package.json (or the relevant config) and retry.`,
+    };
+  }
+  const result = await runCommand({ command, cwd: repo_path, timeout_ms });
+  return { repo_path, action, ran: true, command, ...result };
+}
+
+export async function runTests({ repo_path, timeout_ms }) {
+  return runSemantic({ repo_path, action: "test", timeout_ms });
+}
+
+export async function runLint({ repo_path, timeout_ms }) {
+  return runSemantic({ repo_path, action: "lint", timeout_ms });
+}
+
+export async function runTypecheck({ repo_path, timeout_ms }) {
+  return runSemantic({ repo_path, action: "typecheck", timeout_ms });
+}
+
+export async function runBuild({ repo_path, timeout_ms }) {
+  return runSemantic({ repo_path, action: "build", timeout_ms });
+}
+
+/** Structured project info: detection + git branch/remote + resolved commands. */
+export async function projectInfo({ repo_path }) {
+  const detection = detectProject(repo_path);
+  let git = null;
+  try {
+    const g = simpleGit({ baseDir: repo_path });
+    const branchSummary = await g.branch();
+    const remotes = await g.getRemotes(true);
+    git = { current_branch: branchSummary.current, remotes: remotes.map((r) => ({ name: r.name, url: r.refs?.fetch })) };
+  } catch {
+    git = { error: "not a git repository or git not available" };
+  }
+
+  return {
+    repo_path,
+    ...detection,
+    test_command: resolveCommand(repo_path, "test"),
+    lint_command: resolveCommand(repo_path, "lint"),
+    typecheck_command: resolveCommand(repo_path, "typecheck"),
+    build_command: resolveCommand(repo_path, "build"),
+    git,
+  };
+}
+
+/** High-level health snapshot: git cleanliness, dependency install status, config presence. */
+export async function projectHealth({ repo_path }) {
+  const detection = detectProject(repo_path);
+
+  let git_status = null;
+  try {
+    const g = simpleGit({ baseDir: repo_path });
+    const status = await g.status();
+    git_status = { is_clean: status.isClean(), current_branch: status.current, ahead: status.ahead, behind: status.behind };
+  } catch {
+    git_status = { error: "not a git repository or git not available" };
+  }
+
+  let dependencies_installed = null;
+  if (detection.manifest === "package.json") {
+    dependencies_installed = exists(path.join(repo_path, "node_modules"));
+  } else if (detection.language === "Python") {
+    dependencies_installed = exists(path.join(repo_path, ".venv")) || exists(path.join(repo_path, "venv"));
+  }
+
+  const env_files = ["env", "example"]
+    .map((suffix) => `.env${suffix === "example" ? ".example" : ""}`)
+    .filter((f) => exists(path.join(repo_path, f)));
+
+  return {
+    repo_path,
+    language: detection.language,
+    framework: detection.framework,
+    package_manager: detection.package_manager,
+    dependencies_installed,
+    env_files_present: env_files,
+    git_status,
+  };
+}

package/tools/reminderAlerts.js

@@ -0,0 +1,48 @@
+// Makes due reminders reach the user.
+//
+// The reminder job (every minute, while a server process is running) marks a reminder as announced
+// and emits "reminder.due". This module starts that job and, when Telegram is set up, sends the
+// reminder to the owner's chat. Several processes (Claude, Cursor, a custom agent) can run at once:
+// the reminder is claimed atomically in the database, so exactly one of them announces it.
+//
+// Turn off the Telegram message with CAUSLY_REMINDER_NOTIFY=off.
+import { events, runJob } from "./scheduler.js";
+import { startReminderJob } from "./reminderOps.js";
+import * as telegramOps from "./telegramOps.js";
+
+let started = false;
+
+export const alertsEnabled = (env = process.env) => !/^(off|false|0|no)$/i.test(env.CAUSLY_REMINDER_NOTIFY || "") && Boolean(env.TELEGRAM_BOT_TOKEN && env.TELEGRAM_CHAT_ID);
+
+export function reminderText(row) {
+  return [`Reminder: ${row.title}`, row.note || null, row.deal_id ? `(deal #${row.deal_id})` : null].filter(Boolean).join("\n");
+}
+
+/** Send one due reminder. Never throws: a failed message must not stop the job. */
+export async function deliverReminder(row, deps = {}) {
+  const env = deps.env ?? process.env;
+  if (!alertsEnabled(env)) return false;
+  try {
+    await (deps.notify ?? telegramOps.notify)({ text: reminderText(row) });
+    return true;
+  } catch (err) {
+    console.error(`causly-server: could not send reminder #${row.id} to Telegram: ${err.message}`);
+    return false;
+  }
+}
+
+/** Start the reminder job once per process, and announce anything already overdue shortly after start. */
+export function ensureReminders() {
+  if (started) return;
+  started = true;
+  startReminderJob();
+  events.on("reminder.due", (row) => void deliverReminder(row));
+  const first = setTimeout(() => void runJob("reminders-due"), 3000);
+  first.unref?.();
+}
+
+/** For tests. */
+export function resetReminderAlerts() {
+  started = false;
+  events.removeAllListeners("reminder.due");
+}

package/tools/reminderOps.js

@@ -0,0 +1,129 @@
+// Reminders and follow-ups, stored locally in SQLite. First consumer of the
+// shared store and scheduler. Times are stored as ISO 8601 UTC strings.
+import { getDb, registerMigrations } from "./store.js";
+import { events, schedule } from "./scheduler.js";
+
+registerMigrations("reminders", [
+  `CREATE TABLE reminders (
+     id INTEGER PRIMARY KEY AUTOINCREMENT,
+     title TEXT NOT NULL,
+     note TEXT,
+     due_at TEXT NOT NULL,
+     status TEXT NOT NULL DEFAULT 'pending',
+     notified_at TEXT,
+     created_at TEXT NOT NULL,
+     updated_at TEXT NOT NULL
+   )`,
+  `CREATE INDEX idx_reminders_status_due ON reminders (status, due_at)`,
+  `ALTER TABLE reminders ADD COLUMN deal_id INTEGER`,
+  `CREATE INDEX idx_reminders_deal ON reminders (deal_id)`,
+]);
+
+const STATUSES = ["pending", "done", "cancelled"];
+
+const plain = (row) => (row ? { ...row } : row);
+
+function resolveDue({ due_at, in_hours }) {
+  if (due_at !== undefined && in_hours !== undefined) {
+    throw new Error("Pass either due_at or in_hours, not both.");
+  }
+  if (in_hours !== undefined) {
+    if (!Number.isFinite(in_hours)) throw new Error("in_hours must be a number.");
+    return new Date(Date.now() + in_hours * 3_600_000).toISOString();
+  }
+  if (due_at !== undefined) {
+    const ms = Date.parse(due_at);
+    if (Number.isNaN(ms)) throw new Error(`due_at "${due_at}" is not a valid ISO 8601 date-time.`);
+    return new Date(ms).toISOString();
+  }
+  return undefined;
+}
+
+/** Create a reminder. Give due_at (ISO 8601) or in_hours. */
+export async function reminderCreate({ title, due_at, in_hours, note, deal_id }) {
+  if (deal_id !== undefined && !Number.isInteger(deal_id)) throw new Error("deal_id must be a whole number.");
+  if (!title || !title.trim()) throw new Error("title is required.");
+  const due = resolveDue({ due_at, in_hours });
+  if (!due) throw new Error("Pass due_at (ISO 8601) or in_hours.");
+  const db = await getDb();
+  const now = new Date().toISOString();
+  const { lastInsertRowid } = db
+    .prepare(
+      "INSERT INTO reminders (title, note, due_at, status, created_at, updated_at, deal_id) VALUES (?, ?, ?, 'pending', ?, ?, ?)"
+    )
+    .run(title.trim(), note ?? null, due, now, now, deal_id ?? null);
+  return plain(db.prepare("SELECT * FROM reminders WHERE id = ?").get(Number(lastInsertRowid)));
+}
+
+/** List reminders, soonest first. due_only returns only those whose time has come. */
+export async function reminderList({ status = "pending", due_only = false, limit = 50 } = {}) {
+  if (status !== "all" && !STATUSES.includes(status)) {
+    throw new Error(`status must be one of: ${[...STATUSES, "all"].join(", ")}.`);
+  }
+  const db = await getDb();
+  const now = new Date().toISOString();
+  const clauses = [];
+  const params = [];
+  if (status !== "all") {
+    clauses.push("status = ?");
+    params.push(status);
+  }
+  if (due_only) {
+    clauses.push("due_at <= ?");
+    params.push(now);
+  }
+  const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+  const capped = Math.min(Math.max(Math.trunc(limit) || 50, 1), 200);
+  const rows = db.prepare(`SELECT * FROM reminders ${where} ORDER BY due_at ASC LIMIT ?`).all(...params, capped);
+  return { now, count: rows.length, reminders: rows.map(plain) };
+}
+
+/** Mark done/cancelled, snooze (new due_at or in_hours), or edit title/note. */
+export async function reminderUpdate({ id, status, due_at, in_hours, title, note }) {
+  const db = await getDb();
+  const existing = db.prepare("SELECT * FROM reminders WHERE id = ?").get(id);
+  if (!existing) throw new Error(`No reminder with id ${id}.`);
+  if (status !== undefined && !STATUSES.includes(status)) {
+    throw new Error(`status must be one of: ${STATUSES.join(", ")}.`);
+  }
+  const due = resolveDue({ due_at, in_hours });
+  if (status === undefined && due === undefined && title === undefined && note === undefined) {
+    throw new Error("Nothing to update: pass status, due_at/in_hours, title or note.");
+  }
+  // A new time, or reopening, should be able to fire again.
+  const rearm = due !== undefined || status === "pending";
+  db.prepare("UPDATE reminders SET title = ?, note = ?, status = ?, due_at = ?, notified_at = ?, updated_at = ? WHERE id = ?").run(
+    title !== undefined && title.trim() ? title.trim() : existing.title,
+    note !== undefined ? note : existing.note,
+    status ?? existing.status,
+    due ?? existing.due_at,
+    rearm ? null : existing.notified_at,
+    new Date().toISOString(),
+    id
+  );
+  return plain(db.prepare("SELECT * FROM reminders WHERE id = ?").get(id));
+}
+
+/** Scheduler job: announce each pending reminder once when it becomes due. */
+export async function checkDueReminders() {
+  const db = await getDb();
+  const now = new Date().toISOString();
+  const due = db
+    .prepare("SELECT * FROM reminders WHERE status = 'pending' AND notified_at IS NULL AND due_at <= ? ORDER BY due_at")
+    .all(now);
+  let claimed = 0;
+  for (const row of due) {
+    // Claim it atomically: with several server processes sharing one database, only the one whose UPDATE
+    // changes the row announces it.
+    const claim = db.prepare("UPDATE reminders SET notified_at = ?, updated_at = ? WHERE id = ? AND notified_at IS NULL").run(now, now, row.id);
+    if (Number(claim.changes) !== 1) continue;
+    claimed++;
+    console.error(`causly-server: reminder due: #${row.id} ${row.title}`);
+    events.emit("reminder.due", { ...row, notified_at: now });
+  }
+  return claimed;
+}
+
+export function startReminderJob(intervalMs = 60_000) {
+  schedule("reminders-due", intervalMs, checkDueReminders);
+}

package/tools/scheduler.js

@@ -0,0 +1,46 @@
+// Tiny in-process job runner. Jobs run only while the server is running.
+// Packs call schedule() when they load; timers never keep the process alive.
+//
+// `events` is the seam for alerts: a job emits an event (e.g. "reminder.due")
+// and any pack can listen, such as a future Telegram pack that pings you.
+import { EventEmitter } from "events";
+
+export const events = new EventEmitter();
+
+const jobs = new Map(); // name -> { fn, timer, running }
+
+export function schedule(name, intervalMs, fn) {
+  unschedule(name);
+  const job = { fn, timer: null, running: false };
+  job.timer = setInterval(() => runJob(name), intervalMs);
+  job.timer.unref?.();
+  jobs.set(name, job);
+}
+
+/** Run one job now. Skips if it is already running; errors are logged, never thrown. */
+export async function runJob(name) {
+  const job = jobs.get(name);
+  if (!job || job.running) return;
+  job.running = true;
+  try {
+    await job.fn();
+  } catch (err) {
+    console.error(`causly-server: scheduled job "${name}" failed: ${err.message}`);
+  } finally {
+    job.running = false;
+  }
+}
+
+export function unschedule(name) {
+  const job = jobs.get(name);
+  if (job) clearInterval(job.timer);
+  jobs.delete(name);
+}
+
+export function stopScheduler() {
+  for (const name of [...jobs.keys()]) unschedule(name);
+}
+
+export function listJobs() {
+  return [...jobs.keys()];
+}

package/tools/secretsOps.js

@@ -0,0 +1,133 @@
+import crypto from "crypto";
+import fs from "fs/promises";
+import path from "path";
+import { dataDir } from "./paths.js";
+
+const ALGO = "aes-256-gcm";
+// Fixed folder (the repo in a checkout, ~/.causly when installed from npm), whatever directory the server was launched from.
+const DEFAULT_STORE_PATH = path.join(dataDir(), ".causly-secrets.enc");
+
+function getMasterKey() {
+  const key = process.env.SECRETS_MASTER_KEY;
+  if (!key) {
+    throw new Error(
+      "SECRETS_MASTER_KEY not set. Generate one with `node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"` and add it to your .env file."
+    );
+  }
+  const buf = Buffer.from(key, "hex");
+  if (buf.length !== 32) {
+    throw new Error("SECRETS_MASTER_KEY must be a 32-byte value encoded as a 64-character hex string.");
+  }
+  return buf;
+}
+
+function storePath(store_path) {
+  return store_path || DEFAULT_STORE_PATH;
+}
+
+async function loadStore(store_path) {
+  const p = storePath(store_path);
+  try {
+    const raw = await fs.readFile(p, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    throw err;
+  }
+}
+
+async function saveStore(store_path, data) {
+  const p = storePath(store_path);
+  await fs.writeFile(p, JSON.stringify(data, null, 2), "utf8");
+}
+
+function encrypt(plaintext, key) {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv(ALGO, key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return {
+    iv: iv.toString("hex"),
+    data: encrypted.toString("hex"),
+    tag: authTag.toString("hex"),
+  };
+}
+
+function decrypt(entry, key) {
+  const decipher = crypto.createDecipheriv(ALGO, key, Buffer.from(entry.iv, "hex"));
+  decipher.setAuthTag(Buffer.from(entry.tag, "hex"));
+  const decrypted = Buffer.concat([decipher.update(Buffer.from(entry.data, "hex")), decipher.final()]);
+  return decrypted.toString("utf8");
+}
+
+/** Store an encrypted secret by name. HIGH risk — requires confirm: true. */
+export async function secretsSet({ name, value, store_path, confirm }) {
+  const key = getMasterKey();
+  const store = await loadStore(store_path);
+  store[name] = {
+    ...encrypt(value, key),
+    updated_at: new Date().toISOString(),
+  };
+  await saveStore(store_path, store);
+  return { name, saved: true };
+}
+
+/** Retrieve and decrypt a secret by name. */
+export async function secretsGet({ name, store_path }) {
+  const key = getMasterKey();
+  const store = await loadStore(store_path);
+  const entry = store[name];
+  if (!entry) throw new Error(`Secret "${name}" not found.`);
+  return { name, value: decrypt(entry, key), updated_at: entry.updated_at };
+}
+
+/** List secret names in the store (never returns values). */
+export async function secretsList({ store_path }) {
+  const store = await loadStore(store_path);
+  return {
+    secrets: Object.entries(store).map(([name, entry]) => ({ name, updated_at: entry.updated_at })),
+  };
+}
+
+/** Delete a secret by name. DESTRUCTIVE — requires confirm: true. */
+export async function secretsDelete({ name, store_path, confirm }) {
+  const store = await loadStore(store_path);
+  if (!(name in store)) throw new Error(`Secret "${name}" not found.`);
+  delete store[name];
+  await saveStore(store_path, store);
+  return { name, deleted: true };
+}
+
+/**
+ * Re-encrypt every secret in the store under a new master key.
+ * Call this AFTER setting SECRETS_MASTER_KEY_NEW in your environment.
+ * On success, replace SECRETS_MASTER_KEY with the new key's value and remove SECRETS_MASTER_KEY_NEW.
+ * HIGH risk — requires confirm: true.
+ */
+export async function secretsRotateKey({ store_path, confirm }) {
+  const oldKey = getMasterKey();
+  const newKeyHex = process.env.SECRETS_MASTER_KEY_NEW;
+  if (!newKeyHex) {
+    throw new Error(
+      "SECRETS_MASTER_KEY_NEW not set. Generate a new key and add it to your .env before rotating."
+    );
+  }
+  const newKey = Buffer.from(newKeyHex, "hex");
+  if (newKey.length !== 32) {
+    throw new Error("SECRETS_MASTER_KEY_NEW must be a 32-byte value encoded as a 64-character hex string.");
+  }
+
+  const store = await loadStore(store_path);
+  const rotated = {};
+  for (const [name, entry] of Object.entries(store)) {
+    const plaintext = decrypt(entry, oldKey);
+    rotated[name] = { ...encrypt(plaintext, newKey), updated_at: entry.updated_at };
+  }
+  await saveStore(store_path, rotated);
+  return { rotated_count: Object.keys(rotated).length, note: "Now replace SECRETS_MASTER_KEY with SECRETS_MASTER_KEY_NEW's value in your .env, and remove SECRETS_MASTER_KEY_NEW." };
+}
+
+/** Generate a new random 32-byte master key (hex-encoded) — use to initialize SECRETS_MASTER_KEY or for rotation. */
+export async function secretsGenerateKey() {
+  return { key: crypto.randomBytes(32).toString("hex") };
+}