opencode-clm 0.1.1 → 0.3.0

package/src/overrides.ts

@@ -0,0 +1,205 @@
+/**
+ * Per-session settings changes on disk: `<session dir>/overrides.json` =
+ * `{ version: 1, overrides }`, holding only what differs from the base (the plugin options,
+ * environment and defaults; for `editing`, state.json's `enabled`). A separate file because
+ * state.json belongs to the server's save queue: the TUI writes this file and never state.json.
+ *
+ * Writers (the TUI panel, typed `/clm config` in the TUI, and the server's `/clm config`)
+ * all go through `changeSetting`: parse → merge → drop base-equal keys → stage (resolve the
+ * policies, load a steering document or compact prompt strictly) → write atomically. A
+ * change that fails any step is reported and not written. The server reads the file before
+ * each request (`ClmSession.refreshSettings`). Staging follows pi-clm src/index.ts
+ * `changeSetting` / `stageSettings` (MIT, Copyright 2026 Emanuel Casco); written for this package.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import { writeJsonAtomic } from "./atomic.ts";
+import { loadCompactPrompt } from "./compact.ts";
+import {
+	applyOverrides,
+	describeSetting,
+	mergeOverrides,
+	sanitizeOverrides,
+	settingDescriptor,
+	unknownSettingText,
+	type ClmOverrides,
+	type FormatContext,
+	type SettingsValues,
+} from "./settings-table.ts";
+import type { ClmSettings } from "./settings.ts";
+import { loadSteeringDocument, type SteeringDocument } from "./steering.ts";
+
+export const OVERRIDES_FILE = "overrides.json";
+export const OVERRIDES_VERSION = 1;
+
+export interface OverridesRead {
+	overrides: ClmOverrides;
+	/** Keys dropped as invalid, or a description of why the whole file was unusable. */
+	warning?: string;
+}
+
+export function overridesPath(sessionDirectory: string): string {
+	return join(sessionDirectory, OVERRIDES_FILE);
+}
+
+/** Reads and sanitizes overrides.json. Missing → no overrides. Never throws. */
+export async function readOverrides(sessionDirectory: string): Promise<OverridesRead> {
+	const path = overridesPath(sessionDirectory);
+	let text: string;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return { overrides: {} };
+		return { overrides: {}, warning: `could not read ${path}: ${describe(error)}` };
+	}
+	return parseOverridesText(text, path);
+}
+
+export function parseOverridesText(text: string, path = OVERRIDES_FILE): OverridesRead {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		return { overrides: {}, warning: `${path} is not valid JSON (${describe(error)}); using the defaults` };
+	}
+	if (!parsed || typeof parsed !== "object" || (parsed as { version?: unknown }).version !== OVERRIDES_VERSION) {
+		return { overrides: {}, warning: `${path} has an unknown format; using the defaults` };
+	}
+	const { overrides, ignored } = sanitizeOverrides((parsed as { overrides?: unknown }).overrides);
+	return ignored.length > 0 ? { overrides, warning: `ignored invalid saved settings: ${ignored.join(", ")}` } : { overrides };
+}
+
+export async function writeOverrides(sessionDirectory: string, overrides: ClmOverrides): Promise<void> {
+	await writeJsonAtomic(overridesPath(sessionDirectory), { version: OVERRIDES_VERSION, overrides });
+}
+
+export interface StagedSettings {
+	settings: ClmSettings;
+	steering?: SteeringDocument;
+	/** Set when the steering document could not be loaded (non-strict staging only). */
+	steeringError?: string;
+}
+
+/**
+ * Resolves base + overrides without activating anything. Strict (an interactive change):
+ * a steering document or compact prompt that does not load rejects the change. Not strict
+ * (reading the file before a request): a steering failure is recorded and the session runs
+ * protocol-only. `loaded` reuses an already loaded document for the same path.
+ */
+export function stageSettings(
+	base: ClmSettings,
+	overrides: ClmOverrides,
+	options: { strict: boolean; loaded?: SteeringDocument },
+): StagedSettings {
+	const settings = applyOverrides(base, overrides);
+	const staged: StagedSettings = { settings };
+	const path = settings.steeringPath;
+	if (path) {
+		if (options.loaded && !options.strict && options.loaded.path === path) {
+			staged.steering = options.loaded;
+		} else {
+			try {
+				staged.steering = loadSteeringDocument(path);
+			} catch (error) {
+				if (options.strict) throw new Error(`steering document not loaded: ${describe(error)}`);
+				staged.steeringError = describe(error);
+			}
+		}
+	}
+	if (options.strict && settings.compactPromptPath && settings.compactPromptPath !== base.compactPromptPath) {
+		loadCompactPrompt(settings.compactPromptPath);
+	}
+	return staged;
+}
+
+export interface ChangeRequest {
+	/** The session directory (`<mirrorDir>/clm-<id>`). */
+	sessionDirectory: string;
+	/** Settings at load (options, environment, defaults). */
+	base: ClmSettings;
+	/** `editing` base: state.json's `enabled`. */
+	baseEditing: boolean;
+	/** Relative paths resolve against the project directory. */
+	projectDirectory: string;
+	format?: FormatContext;
+}
+
+export interface ChangeResult {
+	overrides: ClmOverrides;
+	values: SettingsValues;
+	/** `Budget: 20k`. */
+	text: string;
+}
+
+function valuesOf(base: ClmSettings, baseEditing: boolean, overrides: ClmOverrides, settings?: ClmSettings): SettingsValues {
+	return { editing: overrides.editing ?? baseEditing, settings: settings ?? applyOverrides(base, overrides) };
+}
+
+/**
+ * `/clm config <setting> <value>` and the panel's apply: validate, then write. Throws a
+ * user-facing message; nothing is written then.
+ */
+export async function changeSetting(request: ChangeRequest, name: string, text: string): Promise<ChangeResult> {
+	const descriptor = settingDescriptor(name);
+	if (!descriptor) throw new Error(unknownSettingText(name));
+	const parsed = descriptor.parse(text, { directory: request.projectDirectory });
+	const current = await readOverrides(request.sessionDirectory);
+	const baseValues = valuesOf(request.base, request.baseEditing, {}, request.base);
+	const overrides = mergeOverrides(baseValues, current.overrides, parsed);
+	const staged = stageSettings(request.base, overrides, { strict: true });
+	try {
+		await writeOverrides(request.sessionDirectory, overrides);
+	} catch (error) {
+		throw new Error(`Settings unchanged: saving ${overridesPath(request.sessionDirectory)} failed (${describe(error)}).`);
+	}
+	const values = valuesOf(request.base, request.baseEditing, overrides, staged.settings);
+	return { overrides, values, text: `${descriptor.label}: ${descriptor.format(values, request.format)}` };
+}
+
+/** `/clm config reset`: drop this session's changes. */
+export async function resetSettings(sessionDirectory: string): Promise<void> {
+	try {
+		await writeOverrides(sessionDirectory, {});
+	} catch (error) {
+		throw new Error(`Settings unchanged: saving ${overridesPath(sessionDirectory)} failed (${describe(error)}).`);
+	}
+}
+
+/**
+ * Current values of one session, read from its overrides.json (non-strict, never throws for
+ * bad files). `mtimeMs`: when overrides.json was last written, if it exists.
+ */
+export async function sessionValues(sessionDirectory: string, base: ClmSettings, baseEditing: boolean): Promise<SessionValues> {
+	const read = await readOverrides(sessionDirectory);
+	const mtimeMs = await stat(overridesPath(sessionDirectory)).then((info) => info.mtimeMs, () => undefined);
+	return overridesValues(read, base, baseEditing, mtimeMs);
+}
+
+export interface SessionValues {
+	values: SettingsValues;
+	warning?: string;
+	overrides: ClmOverrides;
+	mtimeMs?: number;
+}
+
+/** `sessionValues` for overrides already read (e.g. through the server's file API). */
+export function overridesValues(read: OverridesRead, base: ClmSettings, baseEditing: boolean, mtimeMs?: number): SessionValues {
+	const at = mtimeMs !== undefined ? { mtimeMs } : {};
+	try {
+		return { values: valuesOf(base, baseEditing, read.overrides), overrides: read.overrides, ...(read.warning ? { warning: read.warning } : {}), ...at };
+	} catch (error) {
+		return { values: valuesOf(base, baseEditing, {}, base), overrides: {}, warning: `ignored saved settings: ${describe(error)}`, ...at };
+	}
+}
+
+/** `/clm config <setting>`: `Label: value — description`. */
+export function showSetting(name: string, values: SettingsValues, format?: FormatContext): string {
+	const descriptor = settingDescriptor(name);
+	if (!descriptor) throw new Error(unknownSettingText(name));
+	return describeSetting(descriptor, values, format);
+}
+
+function describe(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/panel/command.ts

@@ -0,0 +1,75 @@
+// Parses a typed `/clm …` line into what the TUI should do with it. Pure; written for
+// this package (the subcommands follow pi-clm's `/clm` and `/clm config`).
+
+export type Page = "overview" | "input" | "edits" | "settings";
+export const PAGES: readonly Page[] = ["overview", "input", "edits", "settings"];
+
+export type ClmCommand =
+	/** Open the panel on a page. */
+	| { kind: "open"; page: Page }
+	/** `/clm config <setting>`: show one setting. */
+	| { kind: "config-show"; setting: string }
+	/** `/clm config <setting> <value…>`: change one setting. */
+	| { kind: "config-set"; setting: string; value: string }
+	| { kind: "config-reset" }
+	| { kind: "status" }
+	| { kind: "path" }
+	| { kind: "enable"; enabled: boolean }
+	/** Must reach the server command (it rewrites state.json): let the line through. */
+	| { kind: "server"; args: string }
+	| { kind: "usage"; text: string };
+
+export const CLM_USAGE = "Usage: /clm [overview | input | edits | settings | status | path | on | off | reset | budget [value] | config [setting [value]]]";
+
+/** Page names and the short forms pi accepts. */
+const PAGE_ALIASES: Record<string, Page> = {
+	overview: "overview",
+	timeline: "overview",
+	input: "input",
+	edits: "edits",
+	edit: "edits",
+	settings: "settings",
+};
+
+/**
+ * `undefined` when the text is not a `/clm` line (e.g. `/clm-compact` or plain text);
+ * otherwise the action. Leading and trailing whitespace is ignored; subcommand names are
+ * case-insensitive, values keep their case (paths).
+ */
+export function parseClmCommand(text: string): ClmCommand | undefined {
+	const match = /^\/clm(?:\s+([\s\S]*))?$/.exec(text.trim());
+	if (!match) return undefined;
+	const args = (match[1] ?? "").trim();
+	if (args === "") return { kind: "open", page: "overview" };
+	const [head = "", ...rest] = args.split(/\s+/);
+	const word = head.toLowerCase();
+	const page = PAGE_ALIASES[word];
+	if (page && rest.length === 0) return { kind: "open", page };
+	switch (word) {
+		case "status":
+			return rest.length === 0 ? { kind: "status" } : { kind: "usage", text: CLM_USAGE };
+		case "path":
+			return rest.length === 0 ? { kind: "path" } : { kind: "usage", text: CLM_USAGE };
+		case "on":
+		case "off":
+			return rest.length === 0 ? { kind: "enable", enabled: word === "on" } : { kind: "usage", text: CLM_USAGE };
+		case "reset":
+			// Extra words are a typo, not a reset: dropping the revision cannot be undone.
+			return rest.length === 0 ? { kind: "server", args } : { kind: "usage", text: CLM_USAGE };
+		case "budget": {
+			// pi's shorthand for `/clm config budget …`.
+			const value = args.replace(/^\S+\s*/, "");
+			return value === "" ? { kind: "config-show", setting: "budget" } : { kind: "config-set", setting: "budget", value };
+		}
+		case "config": {
+			if (rest.length === 0) return { kind: "open", page: "settings" };
+			const setting = rest[0]!.toLowerCase();
+			if (setting === "reset" && rest.length === 1) return { kind: "config-reset" };
+			// The value is the rest of the line as typed, inner spaces kept.
+			const value = args.replace(/^\S+\s+\S+\s*/, "");
+			return value === "" ? { kind: "config-show", setting } : { kind: "config-set", setting, value };
+		}
+		default:
+			return { kind: "usage", text: CLM_USAGE };
+	}
+}