opencode-lookout 0.0.0-stage → 0.1.2

package/src/catalog.mjs

@@ -0,0 +1,278 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { ID, validateID } from "./config.mjs";
+
+/** Stable RPC categories, including MCP for compatibility and restriction recovery. */
+export const KINDS = [
+  "agent",
+  "skill",
+  "plugin",
+  "mcp",
+  "command",
+  "provider",
+  "model",
+];
+/** Leave MCP browsing to the native sidebar and /mcps dialog. */
+export const BROWSE_KINDS = KINDS.filter((kind) => kind !== "mcp");
+
+/**
+ * Limit all Lookout views, including search and saved pins, to its categories.
+ * @param {Array<import('./types').Row>} rows Unmodified server snapshot.
+ * @returns {Array<import('./types').Row>} Rows for the sidebar and browser.
+ */
+export function displayRows(rows) {
+  return rows.filter((row) => BROWSE_KINDS.includes(row.kind));
+}
+
+/**
+ * Select native semantic colors without treating catalog availability as health.
+ * @param {{status:string}} row Normalized catalog status.
+ * @param {boolean} stale Whether the current snapshot is incomplete or unavailable.
+ * @returns {'success'|'warning'|'error'|'muted'} Theme role for the status dot.
+ */
+export function statusTone(row, stale = false) {
+  if (stale) return "warning";
+  if (row.status === "failed") return "error";
+  if (["active", "available", "connected"].includes(row.status))
+    return "success";
+  if (
+    [
+      "unknown",
+      "stale",
+      "pending",
+      "needs_auth",
+      "restricted; still listed",
+    ].includes(row.status)
+  )
+    return "warning";
+  return "muted";
+}
+/**
+ * Remove terminal control characters and bound untrusted display strings.
+ * @param {unknown} value Untrusted display value.
+ * @param {number} limit Maximum number of UTF-16 code units to display.
+ * @returns {string} Plain text with no C0/C1 control characters.
+ */
+export function text(value, limit = 400) {
+  return (
+    String(value ?? "")
+      // ANSI and C0/C1 removal is intentional security filtering, not a regex typo.
+      // eslint-disable-next-line no-control-regex
+      .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+      // eslint-disable-next-line no-control-regex
+      .replace(/[\x00-\x1f\x7f-\x9f]/g, " ")
+      .slice(0, limit)
+  );
+}
+/** @param {string | undefined} file Catalog path. @param {string} root Trusted source root. */
+function inside(file, root) {
+  if (!file || !isAbsolute(file) || !isAbsolute(root)) return false;
+  const r = relative(root, file);
+  return !r.startsWith("..") && !isAbsolute(r);
+}
+/** @param {string} id Catalog ID, validated before use in a policy. */
+function exact(id) {
+  try {
+    validateID(id);
+    return true;
+  } catch {
+    return false;
+  }
+}
+/**
+ * Produce a display allowlist, never a copy of an API response. In particular,
+ * omit prompts, skill bodies, credentials, request headers, and MCP commands.
+ * Management is limited to resources explicitly sourced from this user's config.
+ * @param {string} kind Catalog category from KINDS.
+ * @param {import('./types').CatalogEntry[]} entries Minimal public V2 record projection.
+ * @param {{configDir:string,home:string,config?:Record<string, unknown>}} scope Trusted local source boundaries.
+ * @returns {Array<import('./types').Row>} Sanitized display and management metadata.
+ */
+export function normalize(kind, entries, { configDir, home, config = {} }) {
+  const skills = config.skills;
+  const paths = Array.isArray(skills)
+    ? skills
+    : skills &&
+        typeof skills === "object" &&
+        "paths" in skills &&
+        Array.isArray(skills.paths)
+      ? skills.paths
+      : [];
+  const roots = [
+    resolve(configDir, "skills"),
+    resolve(home, ".agents/skills"),
+    resolve(home, ".claude/skills"),
+    ...paths
+      .filter(
+        (/** @type {string} */ p) =>
+          typeof p === "string" && (isAbsolute(p) || p.startsWith("~/")),
+      )
+      .map((/** @type {string} */ p) =>
+        p.startsWith("~/") ? resolve(home, p.slice(2)) : p,
+      ),
+  ];
+  const mcp = config.mcp && typeof config.mcp === "object" ? config.mcp : {};
+  const localMcp =
+    "servers" in mcp && mcp.servers && typeof mcp.servers === "object"
+      ? mcp.servers
+      : mcp;
+  return entries.map((item, index) => {
+    const id =
+      kind === "model"
+        ? `${item.providerID}/${item.id}`
+        : (item.id ?? item.name ?? `unidentified-${index}`);
+    /** @type {import('./types').Row} */
+    const row = {
+      kind,
+      id,
+      label: text(item.name ?? item.title ?? id),
+      description: text(item.description),
+      status: "available",
+      source: "Server catalog",
+      manageable: false,
+      owned: false,
+      reason: "Read-only. Use native OpenCode controls.",
+      details: [],
+    };
+    if (kind === "agent") {
+      row.status = item.hidden ? "hidden" : "available";
+      row.details = [
+        `Mode: ${text(item.mode)}`,
+        `Model: ${item.model ? text(`${item.model.providerID}/${item.model.id}#${item.model.variant ?? "default"}`) : "inherited"}`,
+      ];
+      row.reason =
+        "Agents have no enabled flag. Use /agents to select an agent.";
+    } else if (kind === "skill") {
+      row.source = roots.some((r) => inside(item.path, r))
+        ? "Local skill source"
+        : "Other or managed source";
+      row.manageable = row.source === "Local skill source" && exact(id);
+      row.details = [
+        `Auto-invocation: ${item.autoinvoke === false ? "off" : "on when described"}`,
+      ];
+    } else if (kind === "plugin") {
+      // The server replaces this only with metadata read from the plugin's files.
+      row.description = "missing description";
+      row.source = text(item.source?.type ?? "unknown");
+      row.status = item.state?.status ?? "unknown";
+      row.details = [
+        `Parts: ${
+          Object.keys(item.features ?? {})
+            .filter((k) => item.features?.[k])
+            .join(", ") || "unknown"
+        }`,
+      ];
+      row.manageable =
+        item.source?.type === "local" &&
+        inside(item.source.path, configDir) &&
+        exact(id) &&
+        id !== ID &&
+        !id.startsWith("opencode.");
+      if (item.source?.type === "builtin")
+        row.reason = "Built-in plugins are protected in this extension.";
+    } else if (kind === "mcp") {
+      row.status =
+        typeof item.status === "object" ? item.status.status : "unknown";
+      row.source =
+        Object.hasOwn(localMcp, id) && !item.integrationID
+          ? "Global configuration"
+          : "Other or managed source";
+      row.manageable =
+        row.source === "Global configuration" &&
+        exact(id) &&
+        row.status !== "disabled";
+    } else if (kind === "provider") {
+      row.status = item.activation ?? "available";
+      row.details = [`Integration: ${text(item.integrationID ?? "unknown")}`];
+    } else if (kind === "model") {
+      row.status = item.enabled === false ? "disabled" : "available";
+      row.details = [
+        `Variants: ${(item.variants ?? []).map((/** @type {{id:string}} */ v) => text(v.id)).join(", ") || "default"}`,
+        `Context: ${item.limit?.context ?? "unknown"}; output: ${item.limit?.output ?? "unknown"}`,
+        `Tools: ${item.capabilities?.tools ? "yes" : "no"}`,
+      ];
+    }
+    if (row.manageable)
+      row.reason =
+        "Exact-ID global restriction; confirmation required. Other sessions can be affected.";
+    return row;
+  });
+}
+/**
+ * Restore disabled rows that policy filtering removes from the live catalog.
+ * @param {Array<import('./types').Row>} rows Current normalized inventory.
+ * @param {{kind:string,id:string}[]} restrictions Validated owned config entries.
+ * @returns {Array<import('./types').Row>} Inventory including re-enable controls.
+ */
+export function mergeOwned(rows, restrictions) {
+  const result = rows.map((r) => ({ ...r, details: [...r.details] }));
+  for (const { kind, id } of restrictions) {
+    let row = result.find((r) => r.kind === kind && r.id === id);
+    if (!row) {
+      row = {
+        kind,
+        id,
+        label: text(id),
+        description: kind === "plugin" ? "missing description" : "",
+        status: "not listed",
+        source: "Lookout restriction",
+        details: [],
+        manageable: true,
+        owned: true,
+        reason: "",
+      };
+      result.push(row);
+    }
+    row.owned = true;
+    row.manageable = true;
+    row.status = ["not listed", "disabled"].includes(row.status)
+      ? "disabled (Lookout)"
+      : "restricted; still listed";
+    row.reason =
+      "Enable removes only the Lookout restriction. Other rules or unavailable sources may still block this item.";
+  }
+  return result;
+}
+/**
+ * Filter by kind, state, and literal search terms; never evaluate a user regex.
+ * @param {Array<import('./types').Row>} rows Normalized inventory.
+ * @param {{kind?:string,state?:string,query?:string}} options Composable filters.
+ * @returns {Array<import('./types').Row>} Stable label/ID order, owned entries first.
+ */
+export function filterRows(
+  rows,
+  { kind = "all", state = "all", query = "" } = {},
+) {
+  const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  return rows
+    .filter(
+      (r) =>
+        (kind === "all" || r.kind === kind) &&
+        (state === "all" ||
+          (state === "managed"
+            ? r.manageable
+            : state === "disabled"
+              ? r.owned || r.status.includes("disabled")
+              : state === "errors"
+                ? ["failed", "unknown", "stale"].includes(r.status)
+                : state === "local"
+                  ? [
+                      "local",
+                      "Local skill source",
+                      "Global configuration",
+                    ].includes(r.source)
+                  : false)) &&
+        terms.every((term) =>
+          [r.id, r.label, r.description, r.source, r.status, ...r.details]
+            .join(" ")
+            .toLowerCase()
+            .includes(term),
+        ),
+    )
+    .sort(
+      (a, b) =>
+        Number(b.owned) - Number(a.owned) ||
+        Number(b.manageable) - Number(a.manageable) ||
+        a.label.localeCompare(b.label) ||
+        a.id.localeCompare(b.id),
+    );
+}

package/src/compatibility.mjs

@@ -0,0 +1,17 @@
+/**
+ * Require the public skill.use/mcp.use policy API introduced in OpenCode 2.2.3.
+ * Unknown version strings fail closed. Prereleases qualify only above that floor;
+ * release validation still requires their actual integration tests to pass.
+ * @param {string} version Host-reported CLI/server version, not user configuration.
+ * @returns {boolean} Whether resource controls may use the current policy API.
+ */
+export function supportsPolicyAPI(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/.exec(version);
+  if (!match) return false;
+  const [major, minor, patch] = match.slice(1).map(Number);
+  return (
+    major === 2 &&
+    (minor > 2 ||
+      (minor === 2 && (patch > 3 || (patch === 3 && !version.includes("-")))))
+  );
+}

package/src/config.mjs

@@ -0,0 +1,250 @@
+import {
+  parseTree,
+  getNodeValue,
+  findNodeAtLocation,
+  modify,
+  applyEdits,
+} from "jsonc-parser";
+
+/** Shared server/TUI plugin ID, also used by the offline unload command. */
+export const ID = "opencode-lookout";
+/** @param {string} key Owned array name. */
+const begin = (key) => `/* lookout:begin:${key} */`;
+/** @param {string} key Owned array name. */
+const end = (key) => `/* lookout:end:${key} */`;
+/**
+ * Reject policy wildcards and control characters instead of escaping them.
+ * @param {string} id Exact catalog resource ID.
+ * @throws {Error} If the ID cannot safely be used in an exact policy rule.
+ */
+export function validateID(id) {
+  if (
+    typeof id !== "string" ||
+    !/^[a-zA-Z0-9_][a-zA-Z0-9_.:/@-]{0,199}$/.test(id)
+  )
+    throw new Error("Only exact resource IDs without wildcards are supported.");
+}
+/** Validate syntax and duplicate keys before any transformation.
+ * @param {string} text Candidate JSONC.
+ */
+function tree(text) {
+  /** @type {import('jsonc-parser').ParseError[]} */
+  const errors = [];
+  const root = parseTree(text, errors, { allowTrailingComma: true });
+  if (errors.length || root?.type !== "object")
+    throw new Error("Invalid JSONC configuration; nothing changed.");
+  /** @param {import('jsonc-parser').Node} node Parsed syntax node. */
+  function visit(node) {
+    if (node.type === "object") {
+      const keys = (node.children ?? []).map((p) => p.children?.[0].value);
+      if (new Set(keys).size !== keys.length)
+        throw new Error("Duplicate configuration keys; nothing changed.");
+    }
+    node.children?.forEach(visit);
+  }
+  visit(root);
+  for (const key of ["plugins", "policies"]) {
+    const node = findNodeAtLocation(root, [key]);
+    if (node && node.type !== "array")
+      throw new Error(`${key} must be an array; nothing changed.`);
+  }
+  return root;
+}
+/** @param {string} text JSONC source. @returns {Record<string, unknown>} Syntax-validated configuration; narrow individual values before use. */
+export const parseConfig = (text) => getNodeValue(tree(text));
+
+/** Parse only our canonical tail block. Hand-edited blocks must fail closed.
+ * @param {string} text Validated JSONC.
+ * @param {string} key Owned array name.
+ */
+function block(text, key) {
+  const root = tree(text),
+    start = text.indexOf(begin(key)),
+    stop = text.indexOf(end(key));
+  if (start === -1 && stop === -1) return { values: [], start: -1, stop: -1 };
+  if (
+    start < 0 ||
+    stop < start ||
+    text.indexOf(begin(key), start + 1) !== -1 ||
+    text.indexOf(end(key), stop + 1) !== -1
+  )
+    throw new Error("Damaged Lookout markers; nothing changed.");
+  const array = findNodeAtLocation(root, [key]);
+  if (
+    !array ||
+    start <= array.offset ||
+    stop >= array.offset + array.length ||
+    text.slice(stop + end(key).length, array.offset + array.length - 1).trim()
+  )
+    throw new Error("Moved Lookout block; nothing changed.");
+  const values = (array.children ?? [])
+    .filter((n) => n.offset > start && n.offset < stop)
+    .map(getNodeValue);
+  for (const v of values) {
+    if (key === "plugins") {
+      if (typeof v !== "string" || !v.startsWith("-"))
+        throw new Error("Modified owned plugin entry.");
+      validateID(v.slice(1));
+    } else {
+      if (
+        !["skill.use", "mcp.use"].includes(v.action) ||
+        v.effect !== "deny" ||
+        Object.keys(v).sort().join() !== "action,effect,resource"
+      )
+        throw new Error("Modified owned policy entry.");
+      validateID(v.resource);
+    }
+  }
+  // Only whitespace, our comma and owned values are allowed inside the block.
+  const fragment = text
+    .slice(start + begin(key).length, stop)
+    .trim()
+    .replace(/^,/, "")
+    .trim();
+  if (fragment !== values.map((v) => JSON.stringify(v)).join(", "))
+    throw new Error("Edited Lookout block; nothing changed.");
+  return { values, start, stop: stop + end(key).length };
+}
+/**
+ * Recover exact-ID restrictions without needing the filtered server catalog.
+ * @param {string} text Global JSONC configuration.
+ * @returns {{kind: string, id: string}[]} Restrictions owned by this extension.
+ */
+export function owned(text) {
+  return [
+    ...block(text, "policies").values.map((v) => ({
+      kind: v.action === "skill.use" ? "skill" : "mcp",
+      id: v.resource,
+    })),
+    ...block(text, "plugins").values.map((v) => ({
+      kind: "plugin",
+      id: v.slice(1),
+    })),
+  ];
+}
+/** Replace only marked bytes; leave external entries and comments intact.
+ * @param {string} text Validated JSONC.
+ * @param {string} key Owned array name.
+ * @param {Array<string | {action:string,resource:string,effect:string}>} values Canonical owned entries.
+ */
+function replaceBlock(text, key, values) {
+  const current = block(text, key);
+  if (current.start !== -1)
+    text = text.slice(0, current.start) + text.slice(current.stop);
+  if (!values.length) {
+    tree(text);
+    return text;
+  }
+  if (!findNodeAtLocation(tree(text), [key]))
+    text = applyEdits(
+      text,
+      modify(text, [key], [], {
+        formattingOptions: { insertSpaces: true, tabSize: 2 },
+      }),
+    );
+  const array = findNodeAtLocation(tree(text), [key]);
+  if (!array?.children)
+    throw new Error("Missing configuration array; nothing changed.");
+  const offset = array.offset + array.length - 1;
+  const last = array.children.at(-1);
+  // Check trailing comma via scanner-free parsing of the between-nodes region.
+  const tail = last
+    ? text
+        .slice(last.offset + last.length, offset)
+        .replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, "")
+    : "";
+  const comma = last && !tail.includes(",") ? ", " : "";
+  const content = `${begin(key)}${comma}${values.map((v) => JSON.stringify(v)).join(", ")}${end(key)}`;
+  const next = text.slice(0, offset) + content + text.slice(offset);
+  tree(next);
+  return next;
+}
+/**
+ * Compute a reversible restriction change; this function performs no I/O.
+ * @param {string} text Current global JSONC configuration.
+ * @param {string} kind One of skill, mcp, or plugin.
+ * @param {string} id Exact resource ID from a validated inventory.
+ * @param {boolean} enabled True removes our denial; false adds one.
+ * @returns {string} Valid JSONC with only the owned array block changed.
+ * @throws {Error} For unsupported controls, protected IDs, or edited blocks.
+ */
+export function change(text, kind, id, enabled) {
+  validateID(id);
+  if (
+    !["skill", "mcp", "plugin"].includes(kind) ||
+    typeof enabled !== "boolean"
+  )
+    throw new Error("Unsupported control.");
+  if (kind === "plugin" && (id === ID || id.startsWith("opencode.")))
+    throw new Error(
+      "Protected plugin; use the external lifecycle command for Lookout.",
+    );
+  const key = kind === "plugin" ? "plugins" : "policies";
+  const all = owned(text);
+  const exists = all.some((v) => v.kind === kind && v.id === id);
+  if (enabled && !exists)
+    throw new Error(
+      "No Lookout restriction to remove. Existing external rules remain authoritative.",
+    );
+  const next = all.filter((v) => !(v.kind === kind && v.id === id));
+  if (!enabled) next.push({ kind, id });
+  next.sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
+  const values =
+    key === "plugins"
+      ? next.filter((v) => v.kind === "plugin").map((v) => `-${v.id}`)
+      : next
+          .filter((v) => v.kind !== "plugin")
+          .map((v) => ({
+            action: `${v.kind}.use`,
+            resource: v.id,
+            effect: "deny",
+          }));
+  return replaceBlock(text, key, values);
+}
+
+/**
+ * Update the separate lifecycle entry without touching resource restrictions.
+ * @param {string} text Existing global JSONC configuration.
+ * @param {string} packagePath Trusted path derived from the installed CLI file.
+ * @param {boolean} enable Whether to load this package.
+ * @returns {string} Updated configuration; the caller owns atomic persistence.
+ */
+export function lifecycle(text, packagePath, enable) {
+  const marker = "/* lookout:lifecycle */";
+  tree(text);
+  if (!findNodeAtLocation(tree(text), ["plugins"]))
+    text = applyEdits(
+      text,
+      modify(text, ["plugins"], [], {
+        formattingOptions: { insertSpaces: true, tabSize: 2 },
+      }),
+    );
+  const array = findNodeAtLocation(tree(text), ["plugins"]);
+  if (!array?.children)
+    throw new Error("Missing plugin array; nothing changed.");
+  const desired = enable ? packagePath : `-${ID}`;
+  const index = text.indexOf(marker);
+  if (index !== -1) {
+    if (text.indexOf(marker, index + 1) !== -1)
+      throw new Error("Duplicate lifecycle marker.");
+    const node = array.children.find(
+      (n) =>
+        n.offset + n.length <= index &&
+        !text.slice(n.offset + n.length, index).trim(),
+    );
+    if (!node || ![packagePath, `-${ID}`].includes(node.value))
+      throw new Error("Edited lifecycle entry; nothing changed.");
+    return (
+      text.slice(0, node.offset) +
+      JSON.stringify(desired) +
+      text.slice(node.offset + node.length)
+    );
+  }
+  const pos = array.offset + 1;
+  // Inserting at the front leaves the resource-control block at the end untouched.
+  return (
+    text.slice(0, pos) +
+    `${JSON.stringify(desired)} ${marker}${array.children.length ? ", " : ""}` +
+    text.slice(pos)
+  );
+}