omo-slim-plan 0.1.0

package/plugin/planflow-notify.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// omo-slim-plan — planflow-notify CLI wrapper around planflow-providers.mjs
+//
+// node planflow-notify.mjs --event plan-ready --plan .plans/foo.md \
+//   [--title T] [--message M] [--remaining N] [--session ID] \
+//   [--config PATH] [--dry-run]
+//
+// Exit codes:
+//   0 = ok / skipped / not_configured / dry-run (workflow must not break)
+//   1 = unexpected crash / usage error
+
+import { loadConfig, resolveConfigPath, send, PROVIDERS } from "./planflow-providers.mjs";
+
+const USAGE = `planflow-notify — omo-slim-plan notification CLI
+
+Usage:
+  node planflow-notify.mjs --event <event> --plan <path> [options]
+
+Options:
+  --event <event>       plan-ready | awaiting-review | task-done | awaiting-acceptance | custom
+  --plan <path>         plan file path (e.g. .plans/foo.md)
+  --title <text>        optional notification title
+  --message <text>      optional notification message
+  --remaining <n>       remaining todos count (optional)
+  --session <id>        session id (optional)
+  --config <path>       planflow.json path (default: OPencode_CONFIG or ~/.config/opencode/planflow.json)
+  --dry-run             print resolved provider + payload, do not send
+  -h, --help            show this help
+
+Exit 0 on ok/skipped/not_configured/dry-run; exit 1 only on unexpected crash.
+`;
+
+function parseArgs(argv) {
+  const args = {
+    event: "",
+    plan: "",
+    title: "",
+    message: "",
+    remaining: "",
+    session: "",
+    config: "",
+    dryRun: false,
+  };
+  const takesValue = new Set(["--event", "--plan", "--title", "--message", "--remaining", "--session", "--config"]);
+  for (let i = 0; i < argv.length; i++) {
+    let a = argv[i];
+    if (a === "-h" || a === "--help") {
+      process.stdout.write(USAGE);
+      process.exit(0);
+    }
+    if (a === "--dry-run") {
+      args.dryRun = true;
+      continue;
+    }
+    if (a.startsWith("--") && a.includes("=")) {
+      const eq = a.indexOf("=");
+      const key = a.slice(0, eq);
+      const val = a.slice(eq + 1);
+      if (key === "--dry-run") continue;
+      if (takesValue.has(key)) {
+        args[key.slice(2)] = val;
+        continue;
+      }
+      continue;
+    }
+    if (takesValue.has(a)) {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        process.stderr.write(`planflow-notify: missing value for ${a}\n`);
+        process.exit(1);
+      }
+      args[a.slice(2)] = next;
+      i++;
+    } else {
+      process.stderr.write(`planflow-notify: unknown argument ${a}\n`);
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+function coerceRemaining(v) {
+  if (v === "" || v === undefined || v === null) return undefined;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : v;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.event || !args.plan) {
+    process.stderr.write(USAGE);
+    process.exit(1);
+  }
+
+  const configPath = resolveConfigPath(args.config || undefined);
+  const cfg = loadConfig(configPath);
+  const providerName = cfg?.webhook?.provider || "telegram";
+  const payload = {
+    event: args.event,
+    plan: args.plan,
+    title: args.title || `Plan ${args.event}: ${args.plan}`,
+    message: args.message || "",
+    remaining: coerceRemaining(args.remaining),
+    session: args.session || "",
+  };
+
+  if (args.dryRun) {
+    const safe = {
+      event: payload.event,
+      plan: payload.plan,
+      title: payload.title,
+      message: payload.message,
+      remaining: payload.remaining === undefined ? null : payload.remaining,
+      session: payload.session,
+      source: "omo-slim-plan",
+    };
+    process.stdout.write(
+      [
+        "planflow-notify dry-run",
+        `config:  ${configPath}`,
+        `provider: ${providerName}${PROVIDERS[providerName] ? "" : " (UNKNOWN)"}`,
+        `events:  ${JSON.stringify(cfg?.webhook?.events || {})}`,
+        `payload: ${JSON.stringify(safe, null, 2)}`,
+      ].join("\n") + "\n"
+    );
+    return 0;
+  }
+
+  const result = await send(cfg, payload);
+  const reason = result?.reason || "";
+  const notConfigured = !result?.ok && /_not_configured$/.test(reason);
+
+  // Print outcome to stderr (never stdout for machine use of stdout).
+  if (result?.ok && !result?.skipped) {
+    // providers.send already printed "planflow: notified ..." on success
+  } else if (result?.skipped) {
+    process.stderr.write(`planflow: skipped ${payload.event} (event disabled in config)\n`);
+  } else if (notConfigured) {
+    process.stderr.write(
+      `planflow: not configured (${reason}) — continuing workflow, configure ~/.config/opencode/planflow.json to enable notifications\n`
+    );
+  } else {
+    process.stderr.write(
+      `planflow: notify failed for ${payload.event} — ${reason || result?.error || "unknown"}\n`
+    );
+  }
+
+  // Exit 0 for ok / skipped / not_configured / provider errors (never break workflow).
+  // Exit 1 only on unexpected crash (caught below) or usage errors.
+  return 0;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stderr.write(`planflow-notify: unexpected error: ${err?.message || err}\n`);
+    process.exit(1);
+  });

package/plugin/planflow-providers.mjs

@@ -0,0 +1,305 @@
+// omo-slim-plan — notification providers (zero deps, Node 18+ builtins only)
+// Extensible provider interface. Import from planflow.js / planflow-notify.mjs.
+//
+// PROVIDERS contract:
+//   async (config, payload) => { ok, skipped?, reason?, status?, error? }
+// payload: { event, plan, title, message, remaining, session, source }
+
+import { spawn } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const TIMEOUT_MS = 10_000;
+
+export const DEFAULT_CONFIG = {
+  version: 1,
+  plansDir: ".plans",
+  webhook: {
+    provider: "telegram",
+    telegram: {
+      botToken: "",
+      chatId: "",
+    },
+    generic: {
+      url: "",
+      headers: {},
+    },
+    command: {
+      cmd: "",
+    },
+    events: {
+      "plan-ready": true,
+      "awaiting-review": true,
+      "task-done": false,
+      "awaiting-acceptance": true,
+    },
+    titlePrefix: "[omo-slim-plan]",
+  },
+};
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** Deep-merge override onto base. Arrays/scalars replace; plain objects merge. */
+export function deepMerge(base, override) {
+  if (override === undefined) return base;
+  if (!isPlainObject(base) || !isPlainObject(override)) return override;
+  const out = { ...base };
+  for (const key of Object.keys(override)) {
+    out[key] = key in base ? deepMerge(base[key], override[key]) : override[key];
+  }
+  return out;
+}
+
+/**
+ * Resolve planflow.json path.
+ * Priority: explicit > OPencode_CONFIG env (config root OR .json path) > ~/.config/opencode
+ */
+export function resolveConfigPath(explicit) {
+  if (explicit) return path.resolve(explicit);
+  const env = process.env.OPencode_CONFIG;
+  const base = env ? path.resolve(env) : path.join(os.homedir(), ".config", "opencode");
+  if (base.endsWith(".json")) return base;
+  return path.join(base, "planflow.json");
+}
+
+function safeReadJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load config: defaults <- planflow.json (explicit path) <- project-local .planflow.json
+ * projectDir: optional project root for local override merge (cwd by default when omitted).
+ */
+export function loadConfig(configPath, projectDir) {
+  const cfgPath = resolveConfigPath(configPath);
+  let cfg = deepMerge(DEFAULT_CONFIG, {});
+  const user = safeReadJson(cfgPath);
+  if (user) cfg = deepMerge(cfg, user);
+  const projRoot = projectDir || process.cwd();
+  const localPath = path.join(projRoot, ".planflow.json");
+  const local = safeReadJson(localPath);
+  if (local) cfg = deepMerge(cfg, local);
+  return cfg;
+}
+
+function payloadFor(cfg, payload) {
+  return {
+    event: String(payload?.event ?? ""),
+    plan: String(payload?.plan ?? ""),
+    title: String(payload?.title ?? ""),
+    message: String(payload?.message ?? ""),
+    remaining:
+      payload?.remaining === undefined || payload?.remaining === null || payload?.remaining === ""
+        ? null
+        : Number(payload.remaining),
+    session: payload?.session === undefined || payload?.session === null ? "" : String(payload.session),
+    source: "omo-slim-plan",
+  };
+}
+
+function formatText(cfg, p) {
+  const prefix = (cfg?.webhook?.titlePrefix || "[omo-slim-plan]").trim();
+  const rem = p.remaining === null || p.remaining === undefined ? "" : ` | remaining: ${p.remaining}`;
+  const lines = [
+    `${prefix} ${p.title || p.event}`,
+    p.message ? `message: ${p.message}` : "",
+    `plan: ${p.plan}${rem}`,
+    `event: ${p.event}`,
+  ].filter(Boolean);
+  return lines.join("\n");
+}
+
+async function postJson(url, body, headers, timeoutMs) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs || TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...(headers || {}) },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    const status = res.status;
+    let text = "";
+    try {
+      text = await res.text();
+    } catch {
+      /* ignore body read errors */
+    }
+    if (status >= 200 && status < 300) return { ok: true, status };
+    return { ok: false, status, error: text.slice(0, 300) || `HTTP ${status}` };
+  } catch (err) {
+    const aborted = err?.name === "AbortError" || err?.name === "TimeoutError";
+    return { ok: false, error: aborted ? "timeout" : err?.message || String(err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Strip any accidental token leakage from error text. */
+function redactToken(text, token) {
+  if (!text || !token) return text;
+  return String(text).split(token).join("<redacted>");
+}
+
+async function telegramProvider(cfg, p) {
+  const tg = cfg?.webhook?.telegram || {};
+  const token = tg.botToken || "";
+  const chatId = tg.chatId || "";
+  if (!token || !chatId) {
+    return { ok: false, reason: "telegram_not_configured" };
+  }
+  const url = `https://api.telegram.org/bot${token}/sendMessage`;
+  const text = formatText(cfg, p);
+  const res = await postJson(url, { chat_id: chatId, text }, null, TIMEOUT_MS);
+  if (res.ok) return { ok: true, status: res.status };
+  return {
+    ok: false,
+    status: res.status,
+    error: redactToken(res.error, token),
+  };
+}
+
+async function genericProvider(cfg, p) {
+  const g = cfg?.webhook?.generic || {};
+  const url = g.url || "";
+  if (!url) return { ok: false, reason: "generic_not_configured" };
+  const res = await postJson(url, p, g.headers || {}, TIMEOUT_MS);
+  if (res.ok) return { ok: true, status: res.status };
+  return { ok: false, status: res.status, error: res.error };
+}
+
+/** POSIX single-quote shell escaping for placeholder substitution values. */
+function shellEscape(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+const PLACEHOLDER_RE = /\{\{\s*(event|plan|title|message|remaining)\s*\}\}/g;
+
+function runCommand(cmd, env, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    let child;
+    try {
+      child = spawn(cmd, {
+        shell: true,
+        stdio: ["ignore", "ignore", "pipe"],
+        env: { ...process.env, ...env },
+      });
+    } catch (err) {
+      done({ ok: false, error: err?.message || String(err) });
+      return;
+    }
+    let stderr = "";
+    try {
+      child.stderr?.on("data", (d) => {
+        if (stderr.length < 400) stderr += String(d);
+      });
+    } catch {
+      /* ignore */
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        /* ignore */
+      }
+      done({ ok: false, error: "timeout" });
+    }, timeoutMs || TIMEOUT_MS);
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      done({ ok: false, error: err?.message || String(err) });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) done({ ok: true });
+      else done({ ok: false, error: `exit ${code}${stderr ? `: ${stderr.trim().slice(0, 200)}` : ""}` });
+    });
+  });
+}
+
+async function commandProvider(cfg, p) {
+  const c = cfg?.webhook?.command || {};
+  let cmd = (c.cmd || "").trim();
+  if (!cmd) return { ok: false, reason: "command_not_configured" };
+
+  // Safe values the caller (workflow) controls — same strings that go into env.
+  const safe = {
+    event: p.event,
+    plan: p.plan,
+    title: p.title,
+    message: p.message,
+    remaining: p.remaining === null || p.remaining === undefined ? "" : String(p.remaining),
+  };
+
+  // Prefer env-only (PLANFLOW_*). If cmd contains placeholders, substitute ONLY
+  // from these already-built safe strings, shell-escaped.
+  if (PLACEHOLDER_RE.test(cmd)) {
+    PLACEHOLDER_RE.lastIndex = 0;
+    cmd = cmd.replace(PLACEHOLDER_RE, (_, key) => shellEscape(safe[key]));
+  }
+
+  return runCommand(
+    cmd,
+    {
+      PLANFLOW_EVENT: safe.event,
+      PLANFLOW_PLAN: safe.plan,
+      PLANFLOW_TITLE: safe.title,
+      PLANFLOW_MESSAGE: safe.message,
+      PLANFLOW_REMAINING: safe.remaining,
+    },
+    TIMEOUT_MS
+  );
+}
+
+export const PROVIDERS = {
+  telegram: telegramProvider,
+  generic: genericProvider,
+  command: commandProvider,
+};
+
+/**
+ * Resolve provider from config, apply event filter, send.
+ * Never throws. Returns { ok, skipped?, reason?, status?, error? }.
+ */
+export async function send(config, { event, plan, title, message, remaining, session } = {}) {
+  try {
+    const cfg = config || loadConfig();
+    const hook = cfg?.webhook || {};
+    const providerName = hook.provider || "telegram";
+    const provider = PROVIDERS[providerName];
+    const p = payloadFor(cfg, { event, plan, title, message, remaining, session });
+
+    const events = hook.events || {};
+    if (events[p.event] === false) {
+      return { ok: true, skipped: true, provider: providerName };
+    }
+    if (!provider) {
+      return { ok: false, reason: `unknown_provider:${providerName}` };
+    }
+    const result = await provider(cfg, p);
+    const out = result || { ok: false, error: "empty_result" };
+    if (out.ok && !out.skipped) {
+      try {
+        process.stderr.write(`planflow: notified ${p.event} via ${providerName}\n`);
+      } catch {
+        /* ignore */
+      }
+    }
+    return out;
+  } catch (err) {
+    return { ok: false, error: err?.message || String(err) };
+  }
+}

package/plugin/planflow.js

@@ -0,0 +1,217 @@
+// omo-slim-plan — OpenCode plugin
+// Conservative planflow plugin: observes .plans/*.md status transitions and
+// sends webhook notifications via ./planflow-providers.mjs.
+// NEVER edits product code; NEVER fetches anything except through providers.
+//
+// Plugin API assumptions (best-effort, defensive):
+// - Factory receives { directory, project, worktree, client, $ }
+// - Returns a hooks object; hook names observed in this environment:
+//     "chat.headers": async (input, output) => {}
+//     event: async ({ event }) => {}   // event.type e.g. "session.updated"
+// - Unknown event payloads are tolerated; every hook body try/catches.
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { loadConfig, resolveConfigPath, send } from "./planflow-providers.mjs";
+
+const NOTIFY_MIN_INTERVAL_MS = 60_000;
+
+function isPlanPath(p) {
+  return typeof p === "string" && p.includes(".plans/") && p.endsWith(".md");
+}
+
+function joinPlanPath(dir, p) {
+  return path.isAbsolute(p) ? p : path.join(dir, p);
+}
+
+/** Read plan metadata + open checkbox count. Returns null on any failure. */
+async function readPlanMeta(absPath) {
+  try {
+    const raw = await readFile(absPath, "utf8");
+    const statusMatch = raw.match(/^\s*-\s*status:\s*(\S+)\s*$/m);
+    const status = statusMatch ? statusMatch[1] : "";
+    const openBoxes = (raw.match(/^\s*-\s*\[\s\]\s+/gm) || []).length;
+    return { status, openBoxes, raw };
+  } catch {
+    return null;
+  }
+}
+
+/** Collect candidate file-path strings from an unknown event shape (bounded depth). */
+function collectPaths(node, out, depth) {
+  if (!node || typeof node !== "object" || depth > 4 || out.length >= 8) return out;
+  for (const [k, v] of Object.entries(node)) {
+    if (out.length >= 8) break;
+    if (typeof v === "string") {
+      const key = k.toLowerCase();
+      if (
+        key === "path" ||
+        key === "filepath" ||
+        key === "file_path" ||
+        key === "filename" ||
+        key === "file" ||
+        key === "file_path"
+      ) {
+        out.push(v);
+      } else if (v.includes(".plans/") && v.endsWith(".md")) {
+        out.push(v);
+      }
+    } else if (v && typeof v === "object") {
+      collectPaths(v, out, depth + 1);
+    }
+  }
+  return out;
+}
+
+function toolNameOf(event) {
+  const props = event?.properties || event?.data || event?.payload || {};
+  const cands = [event?.tool, event?.name, props?.tool, props?.name, props?.toolName];
+  for (const c of cands) if (typeof c === "string" && c) return c.toLowerCase();
+  return "";
+}
+
+function eventLooksLikeFileWrite(type, tool) {
+  const t = String(type || "").toLowerCase();
+  if (t.includes("tool") || t.includes("edit") || t.includes("write") || t.includes("patch")) return true;
+  return tool === "edit" || tool === "write" || tool === "patch" || tool === "apply_patch";
+}
+
+function eventLooksLikeIdle(type) {
+  const t = String(type || "").toLowerCase();
+  return (
+    t === "session.idle" ||
+    t === "idle" ||
+    t.includes("idle") ||
+    t === "message.updated" ||
+    t === "message.completed" ||
+    t === "session.updated" ||
+    t === "session.completed"
+  );
+}
+
+export const PlanflowPlugin = async ({ directory, project, worktree, client, $ }) => {
+  // Resolve project root; "/" is not a useful scan root.
+  const rawDir = directory || worktree || project?.worktree || process.cwd();
+  const dir = rawDir && rawDir !== "/" ? path.resolve(rawDir) : null;
+
+  /** plan abs path -> last notify timestamp */
+  const debounced = new Map();
+
+  async function notifyPlan(relPath, event, title, message, remaining) {
+    if (!dir) return;
+    const abs = joinPlanPath(dir, relPath);
+    const now = Date.now();
+    const last = debounced.get(abs) || 0;
+    if (now - last < NOTIFY_MIN_INTERVAL_MS) return;
+    debounced.set(abs, now);
+    try {
+      const cfg = loadConfig(resolveConfigPath(undefined), dir);
+      await send(cfg, {
+        event,
+        plan: relPath,
+        title,
+        message,
+        remaining,
+        session: "",
+      });
+    } catch {
+      // Notification must never break the host tool call.
+    }
+  }
+
+  async function handlePlanFile(absPath, relPath) {
+    const meta = await readPlanMeta(absPath);
+    if (!meta) return;
+    const name = path.basename(absPath);
+    if (meta.status === "ready") {
+      await notifyPlan(
+        relPath,
+        "plan-ready",
+        `Plan ready: ${name}`,
+        `Plan ${relPath} status: ready`,
+        meta.openBoxes
+      );
+    } else if (meta.status === "done") {
+      await notifyPlan(
+        relPath,
+        "awaiting-acceptance",
+        `Plan done: ${name}`,
+        `Plan ${relPath} status: done — awaiting acceptance`,
+        meta.openBoxes
+      );
+    }
+    // status in-progress / accepted / draft: notify nothing
+  }
+
+  /** Idle-time best-effort scan: only remind on status: ready, debounce 60s. */
+  async function scanPlansForReady() {
+    if (!dir) return;
+    try {
+      const plansDir = path.join(dir, ".plans");
+      const st = await stat(plansDir);
+      if (!st.isDirectory()) return;
+      const entries = await readdir(plansDir);
+      for (const name of entries) {
+        if (!name.endsWith(".md")) continue;
+        const abs = path.join(plansDir, name);
+        const rel = path.posix.join(".plans", name);
+        const meta = await readPlanMeta(abs);
+        if (!meta) continue;
+        if (meta.status === "ready") {
+          await handlePlanFile(abs, rel);
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  /** Handle edit/write tool events touching .plans/*.md */
+  async function handleToolEvent(event) {
+    if (!dir) return;
+    const type = event?.type || "";
+    const tool = toolNameOf(event);
+    if (!eventLooksLikeFileWrite(type, tool)) return;
+    const paths = collectPaths(event, [], 0);
+    for (const p of paths) {
+      if (!isPlanPath(p)) continue;
+      const abs = joinPlanPath(dir, p);
+      const rel = path.isAbsolute(p) ? path.relative(dir, abs) : p;
+      await handlePlanFile(abs, rel);
+    }
+  }
+
+  return {
+    // Defensive: some plugin hosts expose a config hook to announce capabilities.
+    config: async () => {
+      return { planflow: "installed" };
+    },
+
+    // Defensive: if a host exposes tool.call/edit/write hooks directly, accept them.
+    "tool.call": async (input) => {
+      try {
+        if (!input) return;
+        await handleToolEvent(input.event || input);
+      } catch {
+        /* never break */
+      }
+    },
+
+    event: async ({ event } = {}) => {
+      try {
+        if (!event) return;
+        const type = event.type || "";
+        if (eventLooksLikeFileWrite(type, toolNameOf(event))) {
+          await handleToolEvent(event);
+        }
+        if (eventLooksLikeIdle(type)) {
+          // Debounce lives inside notifyPlan (60s per plan path).
+          await scanPlansForReady();
+        }
+      } catch {
+        /* never break the host session */
+      }
+    },
+  };
+};
+
+export default PlanflowPlugin;