@polderlabs/bizar-plugin 0.5.4

package/src/settings.ts

@@ -0,0 +1,349 @@
+/**
+ * settings.ts
+ *
+ * v0.4.0 — Plan settings store.
+ *
+ * Persists user-controlled settings that drive the visual-plan flow
+ * (`/visual-plan on|off`, last-used plan slug, default template).
+ *
+ * Spec contract:
+ *   - §4.7 — corrupt-state fallback. A corrupt or missing file returns
+ *     `DEFAULT_PLAN_SETTINGS`. Never throws.
+ *   - §7.6 — no raw message content is logged. Only metadata strings.
+ *   - §8.2 — mkdirSync on init with EACCES/EROFS handling; if creation
+ *     fails the store returns defaults rather than throwing.
+ *
+ * The file is stored at `~/.cache/bizar/plan-settings.json`. We
+ * `expandHome` in the constructor, just like `StateStore` does.
+ *
+ * Atomic writes use the same `writeFileSync(tmp) + renameSync(tmp, final)`
+ * pattern as `state.ts`. We use a single in-memory mutex for write
+ * serialization (concurrent `update()` calls must not lose data).
+ *
+ * Validation:
+ *   - `visualPlanEnabled` — must be a boolean.
+ *   - `defaultTemplate`  — must be one of the four known literals.
+ *   - `lastUsedSlug`     — must be `string | null`.
+ *
+ * Invalid values are clamped to defaults (and a warning is logged).
+ * The store never throws on bad input.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+  existsSync,
+  mkdirSync,
+} from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+import type { Logger } from "./logger.js";
+
+// --- Public types --------------------------------------------------------
+
+export type DefaultTemplate =
+  | "blank"
+  | "feature-design"
+  | "bug-investigation"
+  | "decision-record";
+
+export const KNOWN_TEMPLATES: readonly DefaultTemplate[] = [
+  "blank",
+  "feature-design",
+  "bug-investigation",
+  "decision-record",
+] as const;
+
+export interface PlanSettings {
+  /** When true, the agent's first action on a complex task is to
+   *  call `bizar_plan_action` (e.g. with `action: "get_canvas"` or `add_element`)
+   *  and `bizar_wait_for_feedback` to coordinate with the visual plan. */
+  visualPlanEnabled: boolean;
+  /** Default template to use when `/plan new` is invoked without one. */
+  defaultTemplate: DefaultTemplate;
+  /** Last plan slug the user opened/created. Surfaces as a default suggestion. */
+  lastUsedSlug: string | null;
+}
+
+export const DEFAULT_PLAN_SETTINGS: PlanSettings = {
+  visualPlanEnabled: false,
+  defaultTemplate: "blank",
+  lastUsedSlug: null,
+};
+
+// --- Implementation -------------------------------------------------------
+
+/** Expand a leading `~` to the user's home directory. */
+export function expandHome(p: string): string {
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+/**
+ * Validates an unknown value as a `PlanSettings` shape. Returns either a
+ * fully-validated `PlanSettings` (with invalid fields clamped to the
+ * defaults) or `null` if the input is not an object at all.
+ *
+ * Validation rules:
+ *   - `visualPlanEnabled`: must be a boolean, else `false`.
+ *   - `defaultTemplate`:  must be one of `KNOWN_TEMPLATES`, else `"blank"`.
+ *   - `lastUsedSlug`:     must be `string` or `null`, else `null`.
+ */
+function validateSettings(raw: unknown): PlanSettings | null {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return null;
+  }
+  const obj = raw as Record<string, unknown>;
+
+  // visualPlanEnabled
+  const visualPlanEnabled =
+    typeof obj.visualPlanEnabled === "boolean" ? obj.visualPlanEnabled : false;
+
+  // defaultTemplate
+  let defaultTemplate: DefaultTemplate = "blank";
+  if (
+    typeof obj.defaultTemplate === "string" &&
+    (KNOWN_TEMPLATES as readonly string[]).includes(obj.defaultTemplate)
+  ) {
+    defaultTemplate = obj.defaultTemplate as DefaultTemplate;
+  }
+
+  // lastUsedSlug
+  let lastUsedSlug: string | null = null;
+  if (typeof obj.lastUsedSlug === "string" && obj.lastUsedSlug !== "") {
+    lastUsedSlug = obj.lastUsedSlug;
+  } else if (obj.lastUsedSlug === null) {
+    lastUsedSlug = null;
+  }
+
+  return { visualPlanEnabled, defaultTemplate, lastUsedSlug };
+}
+
+/**
+ * Recursive mkdirSync with EACCES/EROFS handling. Returns true if the
+ * directory is usable, false otherwise. Mirrors `state.ts`.
+ */
+function ensureDir(dir: string, logger: Logger): boolean {
+  try {
+    mkdirSync(dir, { recursive: true });
+    return true;
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "EACCES" || code === "EROFS") {
+      logger.log({
+        level: "error",
+        message: `bizar: cannot create settings directory ${dir}: ${String(err)}`,
+      });
+      return false;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Persist settings atomically: write to .tmp file then rename. Mirrors
+ * `state.ts` `writeStateAtomic`. Best-effort: never throws, logs on failure.
+ */
+function writeSettingsAtomic(
+  filePath: string,
+  settings: PlanSettings,
+  logger: Logger,
+): void {
+  const tmp = `${filePath}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(settings, null, 2), "utf8");
+    renameSync(tmp, filePath);
+  } catch (err: unknown) {
+    logger.log({
+      level: "warn",
+      message: `bizar: failed to write plan settings ${filePath}: ${String(err)}`,
+    });
+    try {
+      if (existsSync(tmp)) unlinkSync(tmp);
+    } catch {
+      // non-fatal
+    }
+  }
+}
+
+/**
+ * Read settings from disk. Returns DEFAULT_PLAN_SETTINGS on missing or
+ * corrupt file (with a warning logged). Never throws.
+ */
+function readSettings(filePath: string, logger: Logger): PlanSettings {
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw) as unknown;
+    } catch {
+      logger.log({
+        level: "warn",
+        message: `bizar: corrupt plan settings file at ${filePath}, using defaults`,
+      });
+      return { ...DEFAULT_PLAN_SETTINGS };
+    }
+    const validated = validateSettings(parsed);
+    if (validated === null) {
+      logger.log({
+        level: "warn",
+        message: `bizar: corrupt plan settings file at ${filePath}, using defaults`,
+      });
+      return { ...DEFAULT_PLAN_SETTINGS };
+    }
+    return validated;
+  } catch (err: unknown) {
+    // Missing file → ENOENT. Other read errors are surfaced.
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      logger.log({
+        level: "warn",
+        message: `bizar: failed to read plan settings ${filePath}: ${String(err)}`,
+      });
+    }
+    return { ...DEFAULT_PLAN_SETTINGS };
+  }
+}
+
+/**
+ * Per-store async mutex. Writes through this mutex so two concurrent
+ * `update()` calls don't lose data. Reads bypass the mutex (the file
+ * write is atomic via rename, and we always re-read after write).
+ */
+async function withLock<T>(
+  lock: { chain: Promise<unknown> },
+  fn: () => Promise<T>,
+): Promise<T> {
+  const prev = lock.chain ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  lock.chain = next.catch(() => {});
+  return next;
+}
+
+export class SettingsStore {
+  private filePath: string;
+  private settingsDir: string;
+  private logger: Logger;
+  private initialized = false;
+  /** Single-instance mutex (settings are global, not per-session). */
+  private lock = { chain: Promise.resolve() as Promise<unknown> };
+
+  /**
+   * @param settingsDir Directory containing the settings file. Typically
+   *                     `"~/.cache/bizar"`. The constructor
+   *                     expands `~` to the home directory.
+   */
+  constructor(settingsDir: string, logger: Logger) {
+    this.settingsDir = expandHome(settingsDir);
+    this.filePath = path.join(this.settingsDir, "plan-settings.json");
+    this.logger = logger;
+  }
+
+  /** Lazily ensure the settings directory exists. */
+  private ensureSettingsDir(): boolean {
+    if (this.initialized) return true;
+    this.initialized = true;
+    return ensureDir(this.settingsDir, this.logger);
+  }
+
+  /**
+   * Read the current settings. Returns DEFAULT_PLAN_SETTINGS if the
+   * file is missing or corrupt. Never throws.
+   */
+  async get(): Promise<PlanSettings> {
+    if (!this.ensureSettingsDir()) return { ...DEFAULT_PLAN_SETTINGS };
+    if (!existsSync(this.filePath)) return { ...DEFAULT_PLAN_SETTINGS };
+    return readSettings(this.filePath, this.logger);
+  }
+
+  /**
+   * Merge a partial patch into the current settings and persist. The
+   * returned value is the post-merge state.
+   *
+   * Invalid values in the patch are silently ignored — the existing
+   * field is preserved (we don't clamp it to a default). Use `set()`
+   * for type-checked setters that log a warning on rejection.
+   *
+   * Concurrent `update()` calls are serialized through the per-store
+   * mutex; the on-disk file is always consistent.
+   */
+  async update(patch: Partial<PlanSettings>): Promise<PlanSettings> {
+    if (!this.ensureSettingsDir()) return { ...DEFAULT_PLAN_SETTINGS };
+    return withLock(this.lock, async () => {
+      const current = await this.get();
+      const next: PlanSettings = { ...current };
+
+      // Validate each patch field independently. Invalid fields are
+      // skipped (the existing value is preserved).
+      if ("visualPlanEnabled" in patch) {
+        const v = patch.visualPlanEnabled;
+        if (typeof v === "boolean") {
+          next.visualPlanEnabled = v;
+        }
+      }
+      if ("defaultTemplate" in patch) {
+        const v = patch.defaultTemplate;
+        if (typeof v === "string" && (KNOWN_TEMPLATES as readonly string[]).includes(v)) {
+          next.defaultTemplate = v as DefaultTemplate;
+        }
+      }
+      if ("lastUsedSlug" in patch) {
+        const v = patch.lastUsedSlug;
+        if (v === null) {
+          next.lastUsedSlug = null;
+        } else if (typeof v === "string" && v !== "") {
+          next.lastUsedSlug = v;
+        }
+      }
+
+      writeSettingsAtomic(this.filePath, next, this.logger);
+      return next;
+    });
+  }
+
+  /**
+   * Typed setter for a single setting. Returns the post-set state.
+   * Unknown keys are rejected with a warning.
+   *
+   * If the value fails validation, the existing setting is preserved
+   * and a warning is logged. The store never throws.
+   */
+  async set<K extends keyof PlanSettings>(
+    setting: K,
+    value: PlanSettings[K],
+  ): Promise<PlanSettings> {
+    if (!this.ensureSettingsDir()) return { ...DEFAULT_PLAN_SETTINGS };
+    return withLock(this.lock, async () => {
+      const current = await this.get();
+      const candidate = validateSettings({ ...current, [setting]: value });
+      if (candidate === null) return current;
+
+      // validateSettings may clamp — only commit if the field actually changed
+      // (or if the user-supplied value was valid). This avoids spurious writes
+      // when someone calls `set("defaultTemplate", "nonsense")`.
+      const desired = candidate[setting];
+      if (desired !== value) {
+        this.logger.log({
+          level: "warn",
+          message: `bizar: rejected invalid value for ${String(setting)}: ${JSON.stringify(value)}, keeping ${JSON.stringify(desired)}`,
+        });
+        return current;
+      }
+
+      const next: PlanSettings = { ...current, [setting]: value };
+      writeSettingsAtomic(this.filePath, next, this.logger);
+      return next;
+    });
+  }
+
+  /** Absolute path of the settings file (for diagnostics/tests). */
+  getFilePath(): string {
+    return this.filePath;
+  }
+}

package/src/state.ts

@@ -0,0 +1,298 @@
+/**
+ * state.ts
+ *
+ * Per-session state management with atomic writes, per-session mutex,
+ * corrupt-state fallback, and stale-session cleanup. Per §4.
+ */
+
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+/**
+ * Minimal Logger interface compatible with opencode's client.app.log shape.
+ * Matches what Tyr defines in logger.ts.
+ */
+export interface Logger {
+  log(opts: { level: "debug" | "info" | "warn" | "error"; message: string }): void;
+}
+
+/** Per §4.1 schema + §4.7 empty-state shape */
+export interface SessionState {
+  sessionId: string;
+  parentAgent: string | null;
+  startedAt: number;
+  lastActivityAt: number;
+  turnCount: number;
+  toolCalls: Array<{
+    tool: string;
+    fingerprint: string;
+    at: number;
+    outcome?: "ok" | "error";
+  }>;
+  warningsIssued: number;
+  blocksTriggered: number;
+}
+
+/** Canonical empty-state per §4.7 */
+export const EMPTY_STATE: SessionState = {
+  sessionId: "",
+  parentAgent: null,
+  startedAt: 0,
+  lastActivityAt: 0,
+  turnCount: 0,
+  toolCalls: [],
+  warningsIssued: 0,
+  blocksTriggered: 0,
+};
+
+/** Maximum age in days before a state file is considered stale */
+const STALE_AGE_DAYS = 7;
+
+/** Maximum number of tool calls to retain in the rolling window */
+const MAX_TOOL_CALLS = 50;
+
+/**
+ * Per-session async mutex implemented as a Promise chain keyed by sessionId.
+ * Different sessions do not block each other. See §4.3.
+ * The lock map is an instance field so each StateStore has its own mutex domain.
+ */
+async function withLock<T>(
+  locks: Map<string, Promise<unknown>>,
+  sessionId: string,
+  fn: () => Promise<T>
+): Promise<T> {
+  const prev = locks.get(sessionId) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  locks.set(sessionId, next.catch(() => {}));
+  return next;
+}
+
+function stateFilePath(stateDir: string, sessionId: string): string {
+  return path.join(stateDir, `${sessionId}.json`);
+}
+
+function expandHome(p: string): string {
+  if (p.startsWith("~/") || p === "~") {
+    return path.join(os.homedir(), p.slice(1));
+  }
+  return p;
+}
+
+/**
+ * Recursive mkdirSync with EACCES/EROFS handling per §8.2.
+ * Returns true if the directory is usable, false if we hit a permission/readonly error.
+ */
+function ensureDir(dir: string, logger: Logger): boolean {
+  try {
+    mkdirSync(dir, { recursive: true });
+    return true;
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "EACCES" || code === "EROFS") {
+      logger.log({
+        level: "error",
+        message: `bizar: cannot create directory ${dir}: ${String(err)}`,
+      });
+      return false;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Persist session state atomically: write to .tmp file then rename.
+ * Prunes toolCalls to last MAX_TOOL_CALLS entries before writing.
+ */
+function writeStateAtomic(
+  filePath: string,
+  state: SessionState,
+  logger: Logger
+): void {
+  // prune rolling window
+  const pruned: SessionState = {
+    ...state,
+    toolCalls: state.toolCalls.slice(-MAX_TOOL_CALLS),
+  };
+
+  const tmp = `${filePath}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(pruned), "utf8");
+    renameSync(tmp, filePath);
+  } catch (err: unknown) {
+    logger.log({
+      level: "warn",
+      message: `bizar: failed to write state file ${filePath}: ${String(err)}`,
+    });
+    // best-effort: try to clean up the tmp file if it exists
+    try {
+      if (existsSync(tmp)) unlinkSync(tmp);
+    } catch {
+      // non-fatal
+    }
+  }
+}
+
+/**
+ * Load state from a session file. Returns EMPTY_STATE on missing or corrupt file.
+ * Does not throw. See §4.7 corrupt-state fallback.
+ */
+function readState(filePath: string, sessionId: string, logger: Logger): SessionState {
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(raw) as SessionState;
+
+    // Basic schema validation — ensure required fields exist
+    if (
+      typeof parsed.sessionId !== "string" ||
+      !Array.isArray(parsed.toolCalls)
+    ) {
+      throw new Error("schema mismatch");
+    }
+
+    return parsed;
+  } catch (err: unknown) {
+    logger.log({
+      level: "warn",
+      message: `bizar: corrupt state file for session ${sessionId}, starting empty`,
+    });
+    return { ...EMPTY_STATE, sessionId };
+  }
+}
+
+export class StateStore {
+  private stateDir: string;
+  private logger: Logger;
+  private initialized = false;
+  /** Per-session async mutex — instance-level so each store has independent locks */
+  private locks = new Map<string, Promise<unknown>>();
+
+  constructor(stateDir: string, logger: Logger) {
+    // Expand ~ to home directory
+    this.stateDir = expandHome(stateDir);
+    this.logger = logger;
+  }
+
+  /**
+   * Lazily ensure the state directory exists.
+   * Returns false if directory creation fails (EACCES/EROFS) — caller should
+   * disable the plugin for this session.
+   */
+  private ensureStateDir(): boolean {
+    if (this.initialized) return true;
+    this.initialized = true;
+    return ensureDir(this.stateDir, this.logger);
+  }
+
+  /**
+   * Load state for a session. Returns EMPTY_STATE if the file is missing or corrupt.
+   * @see §4.7 corrupt-state fallback
+   */
+  async load(sessionId: string): Promise<SessionState> {
+    if (!this.ensureStateDir()) return { ...EMPTY_STATE, sessionId };
+
+    const filePath = stateFilePath(this.stateDir, sessionId);
+
+    if (!existsSync(filePath)) {
+      return { ...EMPTY_STATE, sessionId };
+    }
+
+    return Promise.resolve(readState(filePath, sessionId, this.logger));
+  }
+
+  /**
+   * Persist session state. Atomic write via rename from .tmp file.
+   */
+  async save(state: SessionState): Promise<void> {
+    if (!this.ensureStateDir()) return;
+
+    const filePath = stateFilePath(this.stateDir, state.sessionId);
+    writeStateAtomic(filePath, state, this.logger);
+    return Promise.resolve();
+  }
+
+  /**
+   * Delete the state file for a session.
+   */
+  async delete(sessionId: string): Promise<void> {
+    const filePath = stateFilePath(this.stateDir, sessionId);
+    try {
+      if (existsSync(filePath)) {
+        unlinkSync(filePath);
+      }
+    } catch (err: unknown) {
+      this.logger.log({
+        level: "warn",
+        message: `bizar: failed to delete state file ${filePath}: ${String(err)}`,
+      });
+    }
+  }
+
+  /**
+   * Cleanup stale session files:
+   * 1. Files older than STALE_AGE_DAYS (by lastActivityAt)
+   * 2. Files whose sessionId is not in the validSessionIds set
+   *
+   * Returns the number of files deleted.
+   */
+  async cleanup(
+    maxAgeDays: number = STALE_AGE_DAYS,
+    validSessionIds: Set<string> = new Set()
+  ): Promise<number> {
+    if (!this.ensureStateDir()) return 0;
+
+    const { readdirSync, statSync } = await import("node:fs");
+    let deleted = 0;
+    const maxAgeMs = maxAgeDays * 24 * 60 * 60 * 1000;
+    const now = Date.now();
+
+    let files: string[];
+    try {
+      files = readdirSync(this.stateDir).filter((f) => f.endsWith(".json"));
+    } catch (err: unknown) {
+      this.logger.log({
+        level: "warn",
+        message: `bizar: failed to read state dir for cleanup: ${String(err)}`,
+      });
+      return 0;
+    }
+
+    for (const file of files) {
+      const filePath = path.join(this.stateDir, file);
+      let mtime: number;
+      let sessionId: string;
+
+      try {
+        const stat = statSync(filePath);
+        mtime = stat.mtimeMs;
+        // sessionId is the filename without .json
+        sessionId = file.replace(/\.json$/, "");
+      } catch {
+        // skip files we can't stat
+        continue;
+      }
+
+      const tooOld = now - mtime > maxAgeMs;
+      const orphaned = validSessionIds.size > 0 && !validSessionIds.has(sessionId);
+
+      if (tooOld || orphaned) {
+        try {
+          unlinkSync(filePath);
+          deleted++;
+        } catch {
+          // best-effort: leave files we can't delete
+        }
+      }
+    }
+
+    return deleted;
+  }
+
+  /**
+   * Acquire the per-session mutex for the given sessionId.
+   * The callback is serialized with all other state operations for the same session.
+   */
+  withLock<T>(sessionId: string, fn: () => Promise<T>): Promise<T> {
+    return withLock(this.locks, sessionId, fn);
+  }
+}