opencode-rules-md 0.6.5

package/tui/data/rules.ts

@@ -0,0 +1,230 @@
+// tui/data/rules.ts
+import { discoverRuleFiles, getCachedRule } from '../../src/rule-discovery';
+import type { RuleMetadata } from '../../src/rule-metadata';
+import { readActiveRulesState } from '../../src/active-rules-state';
+import path from 'path';
+
+/** Represents a rule as displayed in the sidebar */
+export interface SidebarRuleEntry {
+  /** Display name (filename stem, disambiguated if needed) */
+  name: string;
+  /** Relative file path from the rules directory root */
+  path: string;
+  /** Whether this rule came from global or project-local rules dir */
+  source: 'global' | 'project';
+  /** Whether the rule has any conditional metadata */
+  isConditional: boolean;
+  /** Human-readable condition summary */
+  conditionSummary: string;
+  /** Full metadata for expanded view */
+  metadata: RuleMetadata;
+  /**
+   * Active state of the rule.
+   * - true: rule is active (matched by evaluation or unconditional without state file)
+   * - false: rule is not active (not matched by evaluation)
+   * - null: state not yet determined (conditional rule without state file)
+   */
+  isActive: boolean | null;
+}
+
+export interface LoadSidebarRulesResult {
+  rules: SidebarRuleEntry[];
+  skippedCount: number;
+  /** Whether active rules state was successfully read from disk */
+  hasEvaluationState: boolean;
+}
+
+/**
+ * Load all discovered rules formatted for sidebar display.
+ * Reuses discoverRuleFiles/getCachedRule from the server plugin.
+ *
+ * @param projectDir - Project directory or null (global rules only)
+ * @param sessionId - Optional session ID to read active rules state
+ */
+export async function loadSidebarRules(
+  projectDir: string | null,
+  sessionId?: string
+): Promise<LoadSidebarRulesResult> {
+  // discoverRuleFiles accepts string | undefined, not null
+  const discovered = await discoverRuleFiles(projectDir ?? undefined);
+
+  // Read active rules state if sessionId provided
+  const activeState = sessionId ? await readActiveRulesState(sessionId) : null;
+  const hasEvaluationState = activeState !== null;
+  const matchedPathsSet = hasEvaluationState
+    ? new Set(activeState.matchedRulePaths)
+    : null;
+
+  const entries: SidebarRuleEntry[] = [];
+  let skippedCount = 0;
+
+  for (const rule of discovered) {
+    const cached = await getCachedRule(rule.filePath);
+    if (!cached) {
+      // getCachedRule() already logs a warning for read failures,
+      // so we only increment the counter here — no duplicate log.
+      skippedCount++;
+      continue;
+    }
+
+    const meta = cached.metadata;
+    const source = ruleSource(rule.filePath, projectDir);
+    const isConditional = hasConditions(meta);
+    const conditionSummary = isConditional
+      ? formatConditionSummary(meta!)
+      : 'always active';
+
+    // Determine isActive based on state file or fallback logic
+    let isActive: boolean | null;
+    if (matchedPathsSet !== null) {
+      // With state file: check if this rule's absolute path is in matchedPaths
+      isActive = matchedPathsSet.has(rule.filePath);
+    } else {
+      // Without state file: unconditional = true, conditional = null
+      isActive = isConditional ? null : true;
+    }
+
+    entries.push({
+      name: '', // placeholder — set in disambiguation pass
+      path: rule.relativePath,
+      source,
+      isConditional,
+      conditionSummary,
+      metadata: meta ?? {},
+      isActive,
+    });
+  }
+
+  disambiguateNames(entries);
+
+  // Sort: project first, then global. Active rules to top, then alpha by name.
+  const activeOrder = (v: boolean | null): number =>
+    v === true ? 0 : v === null ? 1 : 2;
+  entries.sort((a, b) => {
+    if (a.source !== b.source) return a.source === 'project' ? -1 : 1;
+    const activeCmp = activeOrder(a.isActive) - activeOrder(b.isActive);
+    if (activeCmp !== 0) return activeCmp;
+    const nameCompare = a.name.localeCompare(b.name);
+    if (nameCompare !== 0) return nameCompare;
+    return a.path.localeCompare(b.path);
+  });
+
+  return { rules: entries, skippedCount, hasEvaluationState };
+}
+
+/**
+ * Determine if a rule file is project-local or global.
+ * Uses path.sep boundary check to avoid matching partial prefixes
+ * (e.g., /project/.opencode/rules-extra/ should not match).
+ */
+export function ruleSource(
+  filePath: string,
+  projectDir: string | null
+): 'global' | 'project' {
+  if (!projectDir) return 'global';
+  const projectRulesPrefix =
+    path.join(projectDir, '.opencode', 'rules') + path.sep;
+  return filePath.startsWith(projectRulesPrefix) ? 'project' : 'global';
+}
+
+/**
+ * Check if metadata has any conditional fields set.
+ */
+export function hasConditions(meta: RuleMetadata | undefined): boolean {
+  if (!meta) return false;
+  return !!(
+    meta.globs ||
+    meta.keywords ||
+    meta.tools ||
+    meta.model ||
+    meta.agent ||
+    meta.command ||
+    meta.project ||
+    meta.branch ||
+    meta.os ||
+    meta.ci !== undefined
+  );
+}
+
+/**
+ * Build a human-readable, comma-separated summary of active conditions.
+ * E.g., "globs: src/*.ts, keywords: auth, security"
+ */
+export function formatConditionSummary(meta: RuleMetadata): string {
+  const parts: string[] = [];
+
+  const arrayFields: Array<[keyof RuleMetadata, string]> = [
+    ['globs', 'globs'],
+    ['keywords', 'keywords'],
+    ['tools', 'tools'],
+    ['model', 'model'],
+    ['agent', 'agent'],
+    ['command', 'command'],
+    ['project', 'project'],
+    ['branch', 'branch'],
+    ['os', 'os'],
+  ];
+
+  for (const [field, label] of arrayFields) {
+    const value = meta[field];
+    if (Array.isArray(value) && value.length > 0) {
+      parts.push(`${label}: ${(value as string[]).join(', ')}`);
+    }
+  }
+
+  if (meta.ci !== undefined) {
+    parts.push(`ci: ${String(meta.ci)}`);
+  }
+
+  if (meta.match) {
+    parts.push(`match: ${meta.match}`);
+  }
+
+  return parts.join(', ');
+}
+
+/**
+ * Three-pass name disambiguation.
+ * Pass 1: Extract filename stem from each entry's path.
+ * Pass 2: For duplicate stems, prefix with parent directory.
+ * Pass 3: If still ambiguous (same parent or root-level), use full relative
+ *         path (including extension) as the display name.
+ *
+ * Mutates entries[].name in place.
+ */
+export function disambiguateNames(entries: SidebarRuleEntry[]): void {
+  // Pass 1: assign stem names (filename without extension, using last dot)
+  for (const entry of entries) {
+    const basename = path.basename(entry.path);
+    const dotIndex = basename.lastIndexOf('.');
+    entry.name = dotIndex > 0 ? basename.substring(0, dotIndex) : basename;
+  }
+
+  // Pass 2: detect and resolve collisions with parent directory prefix
+  const stemCounts = new Map<string, number>();
+  for (const entry of entries) {
+    stemCounts.set(entry.name, (stemCounts.get(entry.name) ?? 0) + 1);
+  }
+
+  for (const entry of entries) {
+    if ((stemCounts.get(entry.name) ?? 0) <= 1) continue;
+
+    const dir = path.dirname(entry.path);
+    if (dir && dir !== '.') {
+      const parent = path.basename(dir);
+      entry.name = `${parent}/${entry.name}`;
+    }
+  }
+
+  // Pass 3: if still ambiguous, use full relative path WITH extension
+  const nameCounts = new Map<string, number>();
+  for (const entry of entries) {
+    nameCounts.set(entry.name, (nameCounts.get(entry.name) ?? 0) + 1);
+  }
+
+  for (const entry of entries) {
+    if ((nameCounts.get(entry.name) ?? 0) > 1) {
+      entry.name = entry.path;
+    }
+  }
+}

package/tui/index.tsx

@@ -0,0 +1,23 @@
+// tui/index.tsx
+/** @jsxImportSource @opentui/solid */
+import type { TuiPlugin } from '@opencode-ai/plugin/tui';
+import { SidebarContent } from './slots/sidebar-content';
+
+const id = 'opencode-rules-md' as const;
+
+const tui: TuiPlugin = async api => {
+  api.slots.register({
+    order: 350,
+    slots: {
+      sidebar_content: (ctx, props) => (
+        <SidebarContent
+          sessionId={props.session_id}
+          api={api}
+          theme={ctx.theme}
+        />
+      ),
+    },
+  });
+};
+
+export default { id, tui };

package/tui/slots/sidebar-content.tsx

@@ -0,0 +1,364 @@
+// tui/slots/sidebar-content.tsx
+/** @jsxImportSource @opentui/solid */
+import {
+  createSignal,
+  createEffect,
+  createMemo,
+  onCleanup,
+  Show,
+  For,
+  type JSX,
+} from 'solid-js';
+import type { TuiPluginApi, TuiTheme } from '@opencode-ai/plugin/tui';
+import { loadSidebarRules, type SidebarRuleEntry } from '../data/rules';
+
+interface SidebarContentProps {
+  sessionId: string;
+  api: TuiPluginApi;
+  theme: TuiTheme;
+}
+
+type ThemeColor = string | import('@opentui/core').RGBA;
+
+interface ThemeColors {
+  text: ThemeColor;
+  textMuted: ThemeColor;
+  success: ThemeColor;
+  [key: string]: unknown;
+}
+
+interface RuleSectionProps {
+  title: string;
+  rules: SidebarRuleEntry[];
+  theme: ThemeColors;
+  open: boolean;
+  onToggle: () => void;
+  expandedIndex: number | null;
+  globalOffset: number;
+  onExpandToggle: (globalIndex: number) => void;
+  hasEvaluationState: boolean;
+}
+
+function RuleSection(props: RuleSectionProps): JSX.Element {
+  const activeCount = createMemo(
+    () => props.rules.filter(r => r.isActive === true).length
+  );
+
+  const headerCount = createMemo(() => {
+    if (props.hasEvaluationState) {
+      return `(${activeCount()}/${props.rules.length})`;
+    }
+    return `(${props.rules.length})`;
+  });
+
+  const bulletColor = (rule: SidebarRuleEntry): ThemeColor => {
+    return rule.isActive === true ? props.theme.success : props.theme.textMuted;
+  };
+
+  return (
+    <Show when={props.rules.length > 0}>
+      <box>
+        <box flexDirection="row" gap={1} onMouseDown={() => props.onToggle()}>
+          <text fg={props.theme.text}>{props.open ? '▼' : '▶'}</text>
+          <text fg={props.theme.text}>
+            {props.title}
+            <Show when={!props.open}>
+              <span style={{ fg: props.theme.textMuted }}>
+                {' '}
+                {headerCount()}
+              </span>
+            </Show>
+          </text>
+        </box>
+        <Show when={props.open}>
+          <For each={props.rules}>
+            {(rule, localIndex) => {
+              const globalIndex = () => props.globalOffset + localIndex();
+              return (
+                <box
+                  flexDirection="column"
+                  onMouseDown={() => props.onExpandToggle(globalIndex())}
+                >
+                  <box flexDirection="row" gap={1}>
+                    <text fg={bulletColor(rule)}>•</text>
+                    <text fg={props.theme.text}>{rule.name}</text>
+                  </box>
+                  <Show when={props.expandedIndex === globalIndex()}>
+                    <box flexDirection="column" paddingLeft={4}>
+                      <text fg={props.theme.textMuted}>{rule.path}</text>
+                      <Show when={(rule.metadata.globs?.length ?? 0) > 0}>
+                        <text fg={props.theme.textMuted}>
+                          Globs: {rule.metadata.globs!.join(', ')}
+                        </text>
+                      </Show>
+                      <Show when={(rule.metadata.keywords?.length ?? 0) > 0}>
+                        <text fg={props.theme.textMuted}>
+                          Keywords: {rule.metadata.keywords!.join(', ')}
+                        </text>
+                      </Show>
+                      <Show when={(rule.metadata.tools?.length ?? 0) > 0}>
+                        <text fg={props.theme.textMuted}>
+                          Tools: {rule.metadata.tools!.join(', ')}
+                        </text>
+                      </Show>
+                      <Show when={(rule.metadata.model?.length ?? 0) > 0}>
+                        <text fg={props.theme.textMuted}>
+                          Model: {rule.metadata.model!.join(', ')}
+                        </text>
+                      </Show>
+                      <Show when={(rule.metadata.agent?.length ?? 0) > 0}>
+                        <text fg={props.theme.textMuted}>
+                          Agent: {rule.metadata.agent!.join(', ')}
+                        </text>
+                      </Show>
+                      <Show when={(rule.metadata.command?.length ?? 0) > 0}>
+                        <text fg={props.theme.textMuted}>
+                          Command: {rule.metadata.command!.join(', ')}
+                        </text>
+                      </Show>
+                      <Show when={(rule.metadata.project?.length ?? 0) > 0}>
+                        <text fg={props.theme.textMuted}>
+                          Project: {rule.metadata.project!.join(', ')}
+                        </text>
+                      </Show>
+                      <Show when={(rule.metadata.branch?.length ?? 0) > 0}>
+                        <text fg={props.theme.textMuted}>
+                          Branch: {rule.metadata.branch!.join(', ')}
+                        </text>
+                      </Show>
+                      <Show when={(rule.metadata.os?.length ?? 0) > 0}>
+                        <text fg={props.theme.textMuted}>
+                          OS: {rule.metadata.os!.join(', ')}
+                        </text>
+                      </Show>
+                      <Show when={rule.metadata.ci !== undefined}>
+                        <text fg={props.theme.textMuted}>
+                          CI: {String(rule.metadata.ci)}
+                        </text>
+                      </Show>
+                      <Show when={rule.metadata.match}>
+                        <text fg={props.theme.textMuted}>
+                          Match: {rule.metadata.match}
+                        </text>
+                      </Show>
+                    </box>
+                  </Show>
+                </box>
+              );
+            }}
+          </For>
+        </Show>
+      </box>
+    </Show>
+  );
+}
+
+export function SidebarContent(props: SidebarContentProps): JSX.Element {
+  const [rules, setRules] = createSignal<SidebarRuleEntry[]>([]);
+  const [status, setStatus] = createSignal<'loading' | 'loaded' | 'error'>(
+    'loading'
+  );
+  const [skippedCount, setSkippedCount] = createSignal(0);
+  const [hasEvaluationState, setHasEvaluationState] = createSignal(false);
+  const [expandedIndex, setExpandedIndex] = createSignal<number | null>(null);
+  const [lastDir, setLastDir] = createSignal<string | null | undefined>(
+    undefined
+  );
+  const [lastSessionId, setLastSessionId] = createSignal<string | undefined>(
+    undefined
+  );
+  const [projectOpen, setProjectOpen] = createSignal(false);
+  const [globalOpen, setGlobalOpen] = createSignal(false);
+  const [refreshCounter, setRefreshCounter] = createSignal(0);
+
+  const theme = (): ThemeColors => props.theme.current as ThemeColors;
+
+  const resolveProjectDir = (): string | null => {
+    return props.api.state.path.directory ?? null;
+  };
+
+  // Monotonic counter to detect stale async results
+  let requestId = 0;
+  // Debounce timer for event-driven refresh
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // Initial load: triggered by session/directory change, resets all UI state
+  const loadRulesInitial = async (): Promise<void> => {
+    const thisRequest = ++requestId;
+    const dir = resolveProjectDir();
+    const sessionId = props.sessionId;
+
+    setLastDir(dir);
+    setLastSessionId(sessionId);
+    setStatus('loading');
+
+    try {
+      const result = await loadSidebarRules(dir, sessionId);
+      // Discard if a newer request started
+      if (requestId !== thisRequest) return;
+      setRules(result.rules);
+      setSkippedCount(result.skippedCount);
+      setHasEvaluationState(result.hasEvaluationState);
+      setStatus('loaded');
+    } catch (err) {
+      // Discard if a newer request started
+      if (requestId !== thisRequest) return;
+      console.error('[opencode-rules-md] Failed to load rules:', err);
+      setStatus('error');
+    }
+  };
+
+  // Refresh load: triggered by events, only updates rule data (no UI state reset)
+  const loadRulesRefresh = async (): Promise<void> => {
+    // Skip refresh if initial load is still in flight
+    if (status() === 'loading') return;
+
+    const thisRequest = ++requestId;
+    const dir = resolveProjectDir();
+    const sessionId = props.sessionId;
+
+    try {
+      const result = await loadSidebarRules(dir, sessionId);
+      // Discard if a newer request started
+      if (requestId !== thisRequest) return;
+      setRules(result.rules);
+      setSkippedCount(result.skippedCount);
+      setHasEvaluationState(result.hasEvaluationState);
+      setStatus('loaded');
+    } catch (err) {
+      // Discard if a newer request started
+      if (requestId !== thisRequest) return;
+      console.error('[opencode-rules-md] Failed to refresh rules:', err);
+    }
+  };
+
+  // Effect 1: Initial load on session/directory change
+  createEffect(() => {
+    const currentSessionId = props.sessionId;
+    const currentDir = resolveProjectDir();
+
+    // Check if session or directory changed
+    if (currentSessionId !== lastSessionId() || currentDir !== lastDir()) {
+      // Clear pending debounce from previous session
+      if (debounceTimer !== null) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      // Reset UI state on session/directory change
+      setExpandedIndex(null);
+      setProjectOpen(false);
+      setGlobalOpen(false);
+      void loadRulesInitial();
+    }
+  });
+
+  // Effect 2: Refresh on event-driven updates (refreshCounter changes)
+  createEffect(() => {
+    const counter = refreshCounter();
+    if (counter > 0) {
+      void loadRulesRefresh();
+    }
+  });
+
+  // Subscribe to OpenCode events with debounce
+  const triggerRefresh = (event: {
+    type: string;
+    properties: Record<string, unknown>;
+  }): void => {
+    // Filter events to current sessionId before debouncing
+    // OpenCode SDK events nest sessionID inside properties: { type, properties: { sessionID, ... } }
+    const eventSessionID = event.properties.sessionID;
+    if (
+      typeof eventSessionID === 'string' &&
+      eventSessionID !== props.sessionId
+    ) {
+      return;
+    }
+
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      setRefreshCounter(c => c + 1);
+    }, 150);
+  };
+
+  const unsubMessageUpdated = props.api.event.on(
+    'message.updated',
+    triggerRefresh
+  );
+  const unsubSessionStatus = props.api.event.on(
+    'session.status',
+    triggerRefresh
+  );
+
+  onCleanup(() => {
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer);
+    }
+    unsubMessageUpdated();
+    unsubSessionStatus();
+  });
+
+  const toggleExpand = (index: number): void => {
+    setExpandedIndex(prev => (prev === index ? null : index));
+  };
+
+  const projectRules = createMemo(() =>
+    rules().filter(r => r.source === 'project')
+  );
+  const globalRules = createMemo(() =>
+    rules().filter(r => r.source === 'global')
+  );
+
+  return (
+    <box>
+      <text fg={theme().text}>
+        <b>Rules</b>
+      </text>
+
+      <Show when={status() === 'loading'}>
+        <text fg={theme().textMuted}>Loading...</text>
+      </Show>
+      <Show when={status() === 'error'}>
+        <text fg={theme().textMuted}>Failed to load rules</text>
+      </Show>
+
+      <Show when={status() === 'loaded'}>
+        <Show
+          when={rules().length > 0}
+          fallback={<text fg={theme().textMuted}>No rules found</text>}
+        >
+          <RuleSection
+            title="Project"
+            rules={projectRules()}
+            theme={theme()}
+            open={projectOpen()}
+            onToggle={() => setProjectOpen(x => !x)}
+            expandedIndex={expandedIndex()}
+            globalOffset={0}
+            onExpandToggle={toggleExpand}
+            hasEvaluationState={hasEvaluationState()}
+          />
+          <RuleSection
+            title="Global"
+            rules={globalRules()}
+            theme={theme()}
+            open={globalOpen()}
+            onToggle={() => setGlobalOpen(x => !x)}
+            expandedIndex={expandedIndex()}
+            globalOffset={projectRules().length}
+            onExpandToggle={toggleExpand}
+            hasEvaluationState={hasEvaluationState()}
+          />
+        </Show>
+        <Show when={skippedCount() > 0}>
+          <text fg={theme().textMuted}>
+            {skippedCount()} rules skipped (unreadable)
+          </text>
+        </Show>
+      </Show>
+    </box>
+  );
+}

package/tui/types/opencode-plugin-tui.d.ts

@@ -0,0 +1,78 @@
+// tui/types/opencode-plugin-tui.d.ts
+//
+// Vendored type declarations for @opencode-ai/plugin/tui.
+// Allows tsc to compile TUI code without requiring the optional
+// peer dependency to be installed at compile time.
+//
+// Source: @opencode-ai/plugin v1.3.7 (packages/plugin/src/tui.ts)
+// If bumping @opencode-ai/plugin, re-verify these types match.
+
+declare module '@opencode-ai/plugin/tui' {
+  export interface TuiTheme {
+    [key: string]: unknown;
+  }
+
+  export interface TuiSlotMap {
+    sidebar_content: { session_id: string };
+  }
+
+  export interface TuiSlotContext {
+    theme: TuiTheme;
+  }
+
+  export type SlotRenderer<K extends keyof TuiSlotMap> = (
+    ctx: Readonly<TuiSlotContext>,
+    props: TuiSlotMap[K]
+  ) => JSX.Element;
+
+  export interface TuiSlotPlugin {
+    id?: never;
+    order?: number;
+    setup?: (ctx: Readonly<TuiSlotContext>, renderer: unknown) => void;
+    dispose?: () => void;
+    slots: {
+      [K in keyof TuiSlotMap]?: SlotRenderer<K>;
+    };
+  }
+
+  export interface TuiSlots {
+    register: (plugin: TuiSlotPlugin) => string;
+  }
+
+  export interface TuiWorkspace {
+    current: () => string | undefined;
+    set: (id?: string) => void;
+  }
+
+  export interface TuiState {
+    readonly path: {
+      state: string;
+      config: string;
+      worktree: string;
+      directory: string;
+    };
+    workspace: {
+      get: (id: string) => { directory: string | null } | undefined;
+    };
+  }
+
+  export interface TuiEventBus {
+    on: (
+      type: string,
+      handler: (event: {
+        type: string;
+        properties: Record<string, unknown>;
+      }) => void
+    ) => () => void;
+  }
+
+  export interface TuiPluginApi {
+    slots: TuiSlots;
+    workspace: TuiWorkspace;
+    state: TuiState;
+    kv: unknown;
+    event: TuiEventBus;
+  }
+
+  export type TuiPlugin = (api: TuiPluginApi) => Promise<void> | void;
+}