@polderlabs/bizar 6.2.4 → 6.3.0

package/plugins/bizar/src/settings.ts

@@ -1,349 +0,0 @@
-/**
- * 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/plugins/bizar/src/state.ts

@@ -1,298 +0,0 @@
-/**
- * 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 cline'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);
-  }
-}