opencode-lookout 0.0.0-stage → 0.1.2

package/src/controller.mjs

@@ -0,0 +1,199 @@
+import { open, rename, unlink } from "node:fs/promises";
+import { constants } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { change, owned, parseConfig, validateID } from "./config.mjs";
+
+/** @param {string} text Exact file bytes decoded as UTF-8. @returns {string} SHA-256 fingerprint. */
+export const fingerprint = (text) =>
+  createHash("sha256").update(text).digest("hex");
+/**
+ * Read one fixed config file without following a final-component symlink.
+ * @param {string} file Trusted configuration path, never supplied by an RPC caller.
+ * @returns {Promise<{text: string, mode: number}>} Validated text and original mode.
+ */
+export async function readConfig(file) {
+  const limit = 1024 * 1024;
+  const invalid =
+    "Configuration must be a regular, unlinked file at most 1 MiB.";
+  // Validate the descriptor, not the path before open. NONBLOCK prevents a FIFO
+  // substituted at this path from hanging before we can reject its file type.
+  const handle = await open(
+    file,
+    constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+  ).catch((error) => {
+    if (error.code === "ELOOP") throw new Error(invalid, { cause: error });
+    throw error;
+  });
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > limit)
+      throw new Error(invalid);
+    // A file may grow after fstat. Bound allocation and reads even in that case.
+    const bytes = Buffer.alloc(limit + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const { bytesRead } = await handle.read(
+        bytes,
+        length,
+        bytes.length - length,
+        length,
+      );
+      if (bytesRead === 0) break;
+      length += bytesRead;
+    }
+    if (length > limit) throw new Error(invalid);
+    const after = await handle.stat();
+    if (
+      length !== stat.size ||
+      after.size !== stat.size ||
+      after.nlink !== 1 ||
+      after.mode !== stat.mode ||
+      after.mtimeMs !== stat.mtimeMs ||
+      after.ctimeMs !== stat.ctimeMs
+    )
+      throw new Error("Configuration changed; refresh and retry.");
+    const text = bytes.toString("utf8", 0, length);
+    parseConfig(text);
+    return { text, mode: stat.mode & 0o777 };
+  } finally {
+    await handle.close();
+  }
+}
+/**
+ * Serialize extension writers and replace the config atomically.
+ * Recheck before rename to detect external editors. A portable filesystem cannot
+ * compare-and-swap against an uncooperative external writer; see the threat model.
+ * @param {string} file Trusted config path.
+ * @param {string|null} expected Required fingerprint, or null for an offline command.
+ * @param {(text: string) => string} transform Pure transformation that returns valid JSONC.
+ * @returns {Promise<void>}
+ */
+export async function atomicUpdate(file, expected, transform) {
+  const lockPath = file + ".lookout-lock";
+  let lock;
+  try {
+    lock = await open(lockPath, "wx", 0o600);
+  } catch {
+    throw new Error(
+      "Another Lookout write is in progress; retry or inspect the stale lock.",
+    );
+  }
+  const temp = file + `.lookout-${randomUUID()}.tmp`;
+  try {
+    const { text, mode } = await readConfig(file);
+    if (expected && fingerprint(text) !== expected)
+      throw new Error(
+        "Configuration changed since preview; refresh and retry.",
+      );
+    const next = transform(text);
+    parseConfig(next);
+    if (next === text) return;
+    const output = await open(temp, "wx", mode);
+    try {
+      await output.writeFile(next);
+      await output.sync();
+    } finally {
+      await output.close();
+    }
+    if (fingerprint((await readConfig(file)).text) !== fingerprint(text))
+      throw new Error("Configuration changed during write; nothing replaced.");
+    await rename(temp, file);
+  } finally {
+    await unlink(temp).catch((e) => {
+      if (e.code !== "ENOENT") throw e;
+    });
+    await lock.close();
+    await unlink(lockPath);
+  }
+}
+/** Server-side preview/apply boundary. Tokens and history never contain config text. */
+export class Controller {
+  /**
+   * @param {string} file Trusted global configuration path.
+   * @param {() => Promise<Array<{kind:string,id:string,manageable:boolean}>>} catalog Fresh management eligibility.
+   * @param {() => number} now Clock injected for deterministic expiration tests.
+   */
+  constructor(file, catalog, now = Date.now) {
+    this.file = file;
+    this.catalog = catalog;
+    this.now = now;
+    /** @type {Map<string, {input: import('./types').ChangeRequest, hash: string, expires: number}>} */
+    this.pending = new Map();
+    /** @type {Array<import('./types').ChangeRequest & {time:string}>} */
+    this.history = [];
+  }
+  /** Recheck both the requested kind and current ownership or eligibility.
+   * @param {import('./types').ChangeRequest} input Candidate change, revalidated at runtime.
+   * @param {string} text Current configuration.
+   */
+  async authorize(input, text) {
+    const { kind, id, enabled } = input;
+    validateID(id);
+    if (
+      !["skill", "mcp", "plugin"].includes(kind) ||
+      typeof enabled !== "boolean"
+    )
+      throw new Error("Unsupported control.");
+    if (enabled) {
+      if (!owned(text).some((r) => r.kind === kind && r.id === id))
+        throw new Error("No owned restriction; this entry is read-only.");
+    } else {
+      const row = (await this.catalog()).find(
+        (r) => r.kind === kind && r.id === id,
+      );
+      if (!row?.manageable)
+        throw new Error(
+          "Resource is missing or read-only; refresh before changing it.",
+        );
+    }
+  }
+  /** Validate without writing; issue one token bound to the request and file version.
+   * @param {import('./types').ChangeRequest} input Requested resource restriction.
+   */
+  async preview(input) {
+    const { text } = await readConfig(this.file);
+    await this.authorize(input, text);
+    change(text, input.kind, input.id, input.enabled); // Validate the exact prospective edit.
+    this.pending.clear(); // A single outstanding preview per instance; bounded and short-lived.
+    const token = randomUUID();
+    this.pending.set(token, {
+      input: { ...input },
+      hash: fingerprint(text),
+      expires: this.now() + 60_000,
+    });
+    return {
+      token,
+      summary: `${input.enabled ? "Remove Lookout restriction for" : "Disable"} ${input.kind} ${input.id}. Scope: global, every project using this server.\n${input.enabled ? "Other restrictions remain in force; this does not grant access." : "Existing conversations retain previously loaded content. Changes may affect other sessions."}\nOnly an exact-ID ${input.kind === "plugin" ? "plugin entry" : "deny policy"} is changed. OpenCode reloads configuration automatically.`,
+    };
+  }
+  /** Consume a preview once, revalidate eligibility, and save only that change.
+   * @param {string} token One-use preview token.
+   */
+  async apply(token) {
+    const request = this.pending.get(token);
+    this.pending.delete(token);
+    if (!request || request.expires <= this.now())
+      throw new Error("Preview expired or already used; preview again.");
+    const { text } = await readConfig(this.file);
+    if (fingerprint(text) !== request.hash)
+      throw new Error("Configuration changed since preview; nothing changed.");
+    await this.authorize(request.input, text);
+    await atomicUpdate(this.file, request.hash, (s) =>
+      change(s, request.input.kind, request.input.id, request.input.enabled),
+    );
+    this.history.push({
+      ...request.input,
+      time: new Date(this.now()).toISOString(),
+    });
+    this.history = this.history.slice(-20);
+    return {
+      saved: true,
+      message:
+        "Saved. Refresh to verify the effective state; higher-priority policies may override it.",
+    };
+  }
+  /** Invalidate outstanding previews when the server plugin unloads. */
+  dispose() {
+    this.pending.clear();
+  }
+}

package/src/plugin-description.mjs

@@ -0,0 +1,90 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { extname, isAbsolute, join } from "node:path";
+import { text } from "./catalog.mjs";
+
+const missing = "missing description";
+
+/** Read only bounded regular files; never execute plugin code or follow a file symlink.
+ * @param {string} file Catalog-selected local file.
+ * @param {number} limit Maximum bytes to read.
+ * @param {boolean} prefixOnly Allow reading just a bounded header from a larger source.
+ */
+async function readMetadata(file, limit, prefixOnly = false) {
+  const handle = await open(
+    file,
+    constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+  );
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || (!prefixOnly && stat.size > limit)) return "";
+    const buffer = Buffer.alloc(limit);
+    const { bytesRead } = await handle.read(buffer, 0, limit, 0);
+    return buffer.subarray(0, bytesRead).toString("utf8");
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Read an explicit description tag from the leading JSDoc block, not tool metadata.
+ * @param {string} source Bounded file prefix; never evaluated.
+ */
+function headerDescription(source) {
+  const header = source.match(
+    /^\uFEFF?(?:#![^\n]*\n)?\s*\/\*\*([\s\S]*?)\*\//,
+  )?.[1];
+  if (!header) return "";
+  const lines = header
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^\s*\*?\s?/, "").trim());
+  const start = lines.findIndex((line) => /^@description(?:\s|$)/.test(line));
+  if (start < 0) return "";
+  const description = [lines[start].replace(/^@description\s*/, "")];
+  for (const line of lines.slice(start + 1)) {
+    if (line.startsWith("@")) break;
+    description.push(line);
+  }
+  return description.filter(Boolean).join(" ");
+}
+
+/**
+ * Read a description from the catalog's exact local plugin source. Directories
+ * use package.json; single-file plugins use a leading JSDoc @description tag.
+ * No ancestor lookup, registry requests, imports, or ID-to-description table.
+ * @param {{type?:string,path?:string}|undefined} source Server-owned source metadata.
+ * @returns {Promise<string>} Sanitized description or the literal fallback.
+ */
+export async function pluginDescription(source) {
+  if (
+    source?.type !== "local" ||
+    typeof source.path !== "string" ||
+    !isAbsolute(source.path)
+  )
+    return missing;
+  try {
+    const stat = await lstat(source.path);
+    let description;
+    if (stat.isDirectory()) {
+      const manifest = await readMetadata(
+        join(source.path, "package.json"),
+        64 * 1024,
+      );
+      description = JSON.parse(manifest).description;
+    } else if (
+      stat.isFile() &&
+      [".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"].includes(
+        extname(source.path),
+      )
+    ) {
+      description = headerDescription(
+        await readMetadata(source.path, 16 * 1024, true),
+      );
+    }
+    return typeof description === "string"
+      ? text(description.trim()).trim() || missing
+      : missing;
+  } catch {
+    // Missing/unreadable metadata must not break inventory or disclose local paths.
+    return missing;
+  }
+}

package/src/rpc.ts

@@ -0,0 +1,46 @@
+import { Rpc } from "@opencode/plugin/rpc";
+import { ID } from "./config.mjs";
+
+const rejected = {
+  rejected: { type: "object", properties: {}, additionalProperties: false },
+} as const;
+/** Authenticated server RPC only. No agent tool or arbitrary-path write endpoint. */
+export const Lookout = Rpc.define({
+  id: ID,
+  events: {},
+  methods: {
+    snapshot: {
+      input: { type: "object", properties: {}, additionalProperties: false },
+      output: { type: "object" },
+      errors: rejected,
+    },
+    preview: {
+      input: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          kind: { enum: ["skill", "mcp", "plugin"] },
+          id: { type: "string", maxLength: 200 },
+          enabled: { type: "boolean" },
+        },
+        required: ["kind", "id", "enabled"],
+      },
+      output: {
+        type: "object",
+        properties: { token: { type: "string" }, summary: { type: "string" } },
+        required: ["token", "summary"],
+      },
+      errors: rejected,
+    },
+    apply: {
+      input: {
+        type: "object",
+        additionalProperties: false,
+        properties: { token: { type: "string", maxLength: 100 } },
+        required: ["token"],
+      },
+      output: { type: "object" },
+      errors: rejected,
+    },
+  },
+});

package/src/server.ts

@@ -0,0 +1,159 @@
+/** @description A native-style resource sidebar with reversible local controls. */
+import { Plugin } from "@opencode/plugin";
+import type { PluginInfo } from "@opencode/client";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { access } from "node:fs/promises";
+import { Lookout } from "./rpc";
+import { ID, owned, parseConfig } from "./config.mjs";
+import { Controller, readConfig } from "./controller.mjs";
+import { KINDS, normalize, mergeOwned } from "./catalog.mjs";
+import { pluginDescription } from "./plugin-description.mjs";
+import { supportsPolicyAPI } from "./compatibility.mjs";
+import type { ChangeRequest, Row, Snapshot } from "./types";
+
+/** Never return filesystem errors with paths, or provider errors with payloads. */
+function safeError(error: unknown): string {
+  if (error instanceof Error && !("code" in error))
+    return error.message.slice(0, 300);
+  return "Cannot access the global configuration safely. Check file permissions and run the external status command.";
+}
+
+export default Plugin.define({
+  id: ID,
+  async setup(ctx) {
+    const home = homedir();
+    const configDir = join(
+      process.env.XDG_CONFIG_HOME || join(home, ".config"),
+      "opencode",
+    );
+    const candidates = await Promise.all(
+      ["opencode.jsonc", "opencode.json"].map(async (name) => {
+        const file = join(configDir, name);
+        return await access(file).then(
+          () => file,
+          () => null,
+        );
+      }),
+    );
+    const files = candidates.filter((p): p is string => p !== null);
+    const file = files[0] ?? join(configDir, "opencode.jsonc");
+    let disposed = false;
+    const cache = new Map<string, Row[]>();
+
+    /** Independent collection failures retain stale rows, but never permit edits. */
+    async function snapshot(): Promise<Snapshot> {
+      const errors: string[] = [];
+      if (!supportsPolicyAPI(ctx.app.version))
+        errors.push(
+          "Resource controls require OpenCode 2.2.3 or later (current policy API). This host is read-only.",
+        );
+      let config = {},
+        restrictions: { kind: string; id: string }[] = [];
+      try {
+        if (files.length !== 1)
+          throw new Error(
+            "Use exactly one global opencode.json or opencode.jsonc to enable controls.",
+          );
+        const { text } = await readConfig(file);
+        config = parseConfig(text);
+        restrictions = owned(text);
+      } catch (e) {
+        errors.push(safeError(e));
+      }
+      const scope = { configDir, home, config };
+      const sources = [
+        ctx.agent,
+        ctx.skill,
+        ctx.plugin,
+        ctx.mcp,
+        ctx.command,
+        ctx.provider,
+        ctx.model,
+      ];
+      const results = await Promise.allSettled(
+        sources.map((source) => source.list()),
+      );
+      const rows: Row[] = [];
+      for (const [index, result] of results.entries()) {
+        const kind = KINDS[index];
+        if (result.status === "fulfilled") {
+          const batch = normalize(kind, result.value.data, scope) as Row[];
+          if (kind === "plugin") {
+            await Promise.all(
+              batch.map(async (row, index) => {
+                row.description = await pluginDescription(
+                  (result.value.data[index] as PluginInfo).source,
+                );
+              }),
+            );
+          }
+          if (!disposed) cache.set(kind, batch);
+          rows.push(...batch);
+        } else {
+          errors.push(
+            `${kind} inventory unavailable; showing last snapshot, if any.`,
+          );
+          rows.push(
+            ...(cache.get(kind) ?? []).map((r) => ({
+              ...r,
+              status: "stale",
+              manageable: false,
+            })),
+          );
+        }
+      }
+      const merged = mergeOwned(rows, restrictions) as Row[];
+      if (errors.length)
+        merged.forEach((r) => {
+          r.manageable = false;
+          r.reason = "Refresh successfully before changing configuration.";
+        });
+      return {
+        rows: merged,
+        errors,
+        location: ctx.location.directory,
+        refreshedAt: new Date().toISOString(),
+      };
+    }
+    const controller = new Controller(file, async () => {
+      const result = await snapshot();
+      if (result.errors.length)
+        throw new Error(
+          "Inventory incomplete; configuration controls are read-only.",
+        );
+      return result.rows;
+    });
+    const registration = await ctx.rpc.register(Lookout, {
+      snapshot: async () => snapshot(),
+      preview: async (input, call) => {
+        try {
+          if (
+            disposed ||
+            files.length !== 1 ||
+            !supportsPolicyAPI(ctx.app.version)
+          )
+            throw new Error("Configuration controller is unavailable.");
+          return await controller.preview(input as ChangeRequest);
+        } catch (e) {
+          return call.error("rejected", safeError(e), {});
+        }
+      },
+      apply: async (input, call) => {
+        try {
+          if (disposed)
+            throw new Error("Configuration controller was unloaded; refresh.");
+          return await controller.apply((input as { token: string }).token);
+        } catch (e) {
+          return call.error("rejected", safeError(e), {});
+        }
+      },
+    });
+    return async () => {
+      disposed = true;
+      controller.dispose();
+      cache.clear();
+      await registration.dispose();
+    };
+  },
+});