opencode-rules-md 0.6.5

package/src/cli/main.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * CLI entrypoint for opencode-rules-md installer.
+ *
+ * Supports:
+ *   install   — add opencode-rules-md to the global opencode config
+ *   status    — report whether opencode-rules-md is installed
+ *
+ * Flags:
+ *   --version <v>  — specify a plugin version to install
+ *   --latest       — install the latest version (default)
+ *   --dry-run      — show what would be written, without changing files
+ *   --yes          — skip confirmation prompts (future use)
+ *   -h, --help     — show this help text
+ */
+
+import { parseArgs } from 'node:util';
+import { runInstall } from './install.js';
+import { runStatus } from './status.js';
+import type { CliFs } from './real-fs.js';
+import { realFs } from './real-fs.js';
+
+// ---------------------------------------------------------------------------
+// Help text
+// ---------------------------------------------------------------------------
+
+const HELP_TEXT = `opencode-rules-md CLI
+
+Usage: opencode-rules-md <command> [options]
+
+Commands:
+  install   Add opencode-rules-md to the global opencode config
+  status    Report whether opencode-rules-md is installed
+
+Options:
+  --version <v>  Specify a plugin version to install
+  --latest       Install the latest version (default)
+  --dry-run      Show what would be written, without changing files
+  --yes          Skip confirmation prompts (future use)
+  -h, --help     Show this help text
+`.trim();
+
+const USAGE_ERROR_TEXT = `Error: unknown command. Run 'opencode-rules-md --help' for usage.
+`.trim();
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+interface CliOptions {
+  version?: string;
+  latest?: boolean;
+  dryRun?: boolean;
+  yes?: boolean;
+  help?: boolean;
+}
+
+function parseCliArgs(argv: string[]): { command: string | null; options: CliOptions; unknownFlags: string[] } {
+  const { positionals, values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      version: { type: 'string' },
+      latest: { type: 'boolean' },
+      'dry-run': { type: 'boolean' },
+      yes: { type: 'boolean' },
+      h: { type: 'boolean' },
+      help: { type: 'boolean' },
+    },
+  });
+
+  // Extract command (first positional)
+  const command = positionals[0] ?? null;
+
+  // Extract options from parsed values
+  // Note: -h sets key 'h', --help sets key 'help'
+  const options: CliOptions = {
+    ...(values.version !== undefined && { version: values.version as string }),
+    ...(values.latest && { latest: true }),
+    ...(values['dry-run'] && { dryRun: true }),
+    ...(values.yes && { yes: true }),
+    ...((values.help || values.h) && { help: true }),
+  };
+
+  // Detect unknown flags (tokens that look like flags but aren't recognized)
+  // parseArgs already filters known tokens, so we check if any positional
+  // looks like an unknown option
+  const unknownFlags: string[] = [];
+
+  return { command, options, unknownFlags };
+}
+
+// ---------------------------------------------------------------------------
+// Dispatcher
+// ---------------------------------------------------------------------------
+
+export type ExitCode = 0 | 1 | 2;
+
+export async function runMain(argv: string[], fs: CliFs = realFs): Promise<ExitCode> {
+  try {
+    const { command, options, unknownFlags } = parseCliArgs(argv);
+
+    // Handle help flag at top level (before command dispatch)
+    if (options.help) {
+      console.log(HELP_TEXT);
+      return 0;
+    }
+
+    // Handle unknown flags
+    if (unknownFlags.length > 0) {
+      console.error(`Error: unknown option(s): ${unknownFlags.join(', ')}`);
+      console.error(USAGE_ERROR_TEXT);
+      return 2;
+    }
+
+    // No command given
+    if (!command) {
+      console.error(USAGE_ERROR_TEXT);
+      return 2;
+    }
+
+    switch (command) {
+      case 'install': {
+        const installOpts: { version?: string; dryRun?: boolean } = {};
+        if (options.version !== undefined) installOpts.version = options.version;
+        if (options.dryRun) installOpts.dryRun = true;
+        const installResult = runInstall(installOpts, fs);
+        // Map install status to exit code
+        if (installResult.status === 'error') {
+          return 1;
+        }
+        return 0;
+      }
+
+      case 'status': {
+        const statusResult = runStatus(fs);
+        // Print status to stdout
+        if (statusResult.installed) {
+          console.log(`opencode-rules-md is installed (${statusResult.specifier})`);
+        } else {
+          console.log('opencode-rules-md is not installed');
+        }
+        // Exit code 0 regardless of install state (status is read-only)
+        return 0;
+      }
+
+      default: {
+        console.error(`Error: unknown command '${command}'`);
+        console.error(USAGE_ERROR_TEXT);
+        return 2;
+      }
+    }
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+// Only run if executed directly (not imported as a module)
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const exitCode = await runMain(process.argv.slice(2));
+  process.exit(exitCode);
+}

package/src/cli/real-fs.ts

@@ -0,0 +1,65 @@
+/**
+ * Thin synchronous adapter over node:fs that implements the CliFs interface.
+ * All production CLI disk I/O flows through this module — no direct node:fs
+ * calls outside this file.
+ */
+
+import * as fs from 'node:fs';
+import * as nodePath from 'node:path';
+
+/**
+ * Synchronous filesystem interface used by the CLI.
+ * Tests supply an in-memory implementation; production uses this adapter.
+ */
+export interface CliFs {
+  readFileSync(path: string): string;
+  writeFileSync(path: string, content: string, encoding?: string): void;
+  renameSync(from: string, to: string): void;
+  copyFileSync(from: string, to: string): void;
+  unlinkSync(path: string): void;
+  mkdirSync(path: string, opts?: { recursive?: boolean }): void;
+  readdirSync(path: string): string[];
+  existsSync(path: string): boolean;
+}
+
+/**
+ * Production CliFs implementation backed by node:fs (synchronous).
+ */
+export const realFs: CliFs = {
+  readFileSync(filePath: string): string {
+    return fs.readFileSync(filePath, 'utf-8');
+  },
+
+  writeFileSync(filePath: string, content: string, _encoding?: string): void {
+    // Ensure parent directory exists before writing
+    const dir = nodePath.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content, 'utf-8');
+  },
+
+  renameSync(from: string, to: string): void {
+    fs.renameSync(from, to);
+  },
+
+  copyFileSync(from: string, to: string): void {
+    fs.copyFileSync(from, to);
+  },
+
+  unlinkSync(filePath: string): void {
+    fs.unlinkSync(filePath);
+  },
+
+  mkdirSync(filePath: string, opts?: { recursive?: boolean }): void {
+    fs.mkdirSync(filePath, opts);
+  },
+
+  readdirSync(filePath: string): string[] {
+    return fs.readdirSync(filePath);
+  },
+
+  existsSync(filePath: string): boolean {
+    return fs.existsSync(filePath);
+  },
+};

package/src/cli/status.ts

@@ -0,0 +1,80 @@
+/**
+ * status command: read-only probe that reports install state.
+ *
+ * Reports:
+ *   - installed: yes/no
+ *   - specifier: the registered opencode-rules-md entry (or undefined)
+ *   - path: config file path
+ *   - version: bundled CLI version from package.json
+ */
+
+import { loadGlobalConfig } from './config.js';
+import type { CliFs } from './real-fs.js';
+import { realFs } from './real-fs.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+export interface StatusResult {
+  installed: boolean;
+  path: string;
+  specifier?: string;
+  version: string;
+  parseError?: Error;
+}
+
+// ---------------------------------------------------------------------------
+// Run status
+// ---------------------------------------------------------------------------
+
+export function runStatus(fs: CliFs = realFs): StatusResult {
+  const loadResult = loadGlobalConfig(fs);
+  const configPath = loadResult.path;
+
+  // Surface parse errors as installed=false
+  if (loadResult.parseError) {
+    return {
+      installed: false,
+      path: configPath,
+      version: getVersion(),
+      parseError: loadResult.parseError,
+    };
+  }
+
+  const config = loadResult.config;
+  const pluginList: string[] = Array.isArray(config['plugin']) ? (config['plugin'] as string[]) : [];
+
+  // Find the opencode-rules-md entry (exact match for idempotency)
+  const specifier = pluginList.find(p => p.startsWith('opencode-rules-md'));
+
+  const result: StatusResult = {
+    installed: specifier !== undefined,
+    path: configPath,
+    version: getVersion(),
+  };
+
+  if (specifier) {
+    result.specifier = specifier;
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function getVersion(): string {
+  try {
+    // Read package.json relative to the project root
+    const pkgPath = path.resolve(process.cwd(), 'package.json');
+    const content = fs.readFileSync(pkgPath, 'utf-8');
+    const pkg = JSON.parse(content) as { version?: string };
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}

package/src/debug.ts

@@ -0,0 +1,9 @@
+export type DebugLog = (message: string) => void;
+
+export function createDebugLog(prefix = '[opencode-rules-md]'): DebugLog {
+  return (message: string): void => {
+    if (process.env.OPENCODE_RULES_DEBUG) {
+      console.debug(`${prefix} ${message}`);
+    }
+  };
+}

package/src/git-branch.ts

@@ -0,0 +1,37 @@
+import { execFile, type ExecFileOptions } from 'child_process';
+
+const GIT_TIMEOUT_MS = 5000;
+
+export async function getGitBranch(
+  projectDir: string
+): Promise<string | undefined> {
+  try {
+    const branch = await new Promise<string | undefined>(resolve => {
+      const opts: ExecFileOptions = {
+        cwd: projectDir,
+        timeout: GIT_TIMEOUT_MS,
+        killSignal: 'SIGTERM',
+      };
+      execFile(
+        'git',
+        ['rev-parse', '--abbrev-ref', 'HEAD'],
+        opts,
+        (error, stdout) => {
+          if (error) {
+            resolve(undefined);
+            return;
+          }
+          const trimmed = String(stdout).trim();
+          if (!trimmed || trimmed === 'HEAD') {
+            resolve(undefined);
+            return;
+          }
+          resolve(trimmed);
+        }
+      );
+    });
+    return branch;
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * OpenCode Rules Plugin
+ *
+ * Discovers markdown rule files and injects them into the system prompt.
+ */
+
+import type { Plugin, PluginInput } from '@opencode-ai/plugin';
+import { discoverRuleFiles } from './utils.js';
+import { OpenCodeRulesRuntime } from './runtime.js';
+import { createSessionStore, type SessionState } from './session-store.js';
+
+const sessionStore = createSessionStore();
+import { createDebugLog } from './debug.js';
+
+const debugLog = createDebugLog();
+
+const openCodeRulesPlugin = async (pluginInput: PluginInput) => {
+  const ruleFiles = await discoverRuleFiles(pluginInput.directory);
+  debugLog(`Discovered ${ruleFiles.length} rule file(s)`);
+
+  const runtime = new OpenCodeRulesRuntime({
+    client: pluginInput.client,
+    directory: pluginInput.directory,
+    projectDirectory: pluginInput.directory,
+    ruleFiles,
+    sessionStore,
+    debugLog,
+  });
+
+  return runtime.createHooks();
+};
+
+/**
+ * Test-only exports for accessing internal state and functions.
+ * @internal - Test utilities only. Not part of public API.
+ */
+// NOTE: OpenCode's plugin loader calls every named export as a plugin initializer.
+// To avoid runtime crashes, __testOnly must be callable.
+const __testOnly = Object.freeze(
+  Object.assign(async () => ({}), {
+    setSessionStateLimit: (limit: number): void => {
+      sessionStore.setMax(limit);
+    },
+    getSessionStateIDs: (): string[] => {
+      return sessionStore.ids();
+    },
+    getSessionStateSnapshot: (sessionID: string): SessionState | undefined => {
+      return sessionStore.snapshot(sessionID);
+    },
+    upsertSessionState: (
+      sessionID: string,
+      mutator: (state: SessionState) => void
+    ): void => {
+      sessionStore.upsert(sessionID, mutator);
+    },
+    resetSessionState: (): void => {
+      sessionStore.reset();
+    },
+    getSeedCount: (sessionID: string): number => {
+      return sessionStore.get(sessionID)?.seedCount ?? 0;
+    },
+  })
+);
+
+const id = 'opencode-rules-md' as const;
+const server = openCodeRulesPlugin satisfies Plugin;
+export default { id, server };
+export { __testOnly };

package/src/mcp-tools.ts

@@ -0,0 +1,24 @@
+interface McpStatusMap {
+  [clientName: string]: { status?: string } | undefined;
+}
+
+function sanitizeMcpClientName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+
+export function extractConnectedMcpCapabilityIDs(
+  status: McpStatusMap | null | undefined
+): string[] {
+  if (!status || typeof status !== 'object' || Array.isArray(status)) return [];
+
+  const out: string[] = [];
+  for (const [clientName, clientStatus] of Object.entries(status)) {
+    if (clientStatus?.status === 'connected') {
+      const sanitized = sanitizeMcpClientName(clientName);
+      if (sanitized) {
+        out.push(`mcp_${sanitized}`);
+      }
+    }
+  }
+  return out;
+}

package/src/message-context.ts

@@ -0,0 +1,139 @@
+import path from 'path';
+import type { Message, MessagePart } from './message-paths.js';
+
+export interface MessagePartWithSession {
+  type?: string;
+  text?: string;
+  sessionID?: string;
+  synthetic?: boolean;
+}
+
+export interface MessageWithInfo {
+  role?: string;
+  parts?: MessagePartWithSession[];
+  info?: {
+    sessionID?: string;
+  };
+}
+
+/**
+ * Extract and join text content from message parts.
+ * Skips synthetic parts and parts without text content.
+ * Returns an empty string if no text is extracted.
+ */
+export function extractTextFromParts(
+  parts: Array<{ type?: string; text?: string; synthetic?: boolean }>
+): string {
+  const textParts: string[] = [];
+  for (const part of parts) {
+    if (part.synthetic) continue;
+
+    if (part.type === 'text' && part.text) {
+      textParts.push(part.text);
+    } else if (typeof part.text === 'string' && !part.type) {
+      textParts.push(part.text);
+    }
+  }
+
+  return textParts
+    .map(t => t.trim())
+    .filter(Boolean)
+    .join(' ')
+    .trim();
+}
+
+/**
+ * Normalize paths to repo-relative POSIX format.
+ * If path is absolute and under baseDir, convert to relative POSIX path.
+ * Otherwise return path as-is.
+ */
+export function normalizeContextPath(p: string, baseDir: string): string {
+  if (!path.isAbsolute(p)) return p;
+  const rel = path.relative(baseDir, p);
+  return rel.split(path.sep).join('/');
+}
+
+/**
+ * Sanitize a file path for safe inclusion in context strings.
+ * Prevents prompt injection by removing control characters and limiting length.
+ */
+export function sanitizePathForContext(p: string): string {
+  return p.replace(/[\r\n\t]/g, ' ').slice(0, 300);
+}
+
+/**
+ * Extract sessionID from messages array.
+ */
+export function extractSessionID(
+  messages: MessageWithInfo[]
+): string | undefined {
+  for (const message of messages) {
+    if (message.info?.sessionID) {
+      return message.info.sessionID;
+    }
+    if (message.parts) {
+      for (const part of message.parts) {
+        if (part.sessionID) {
+          return part.sessionID;
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Extract the latest user message text from messages array.
+ */
+export function extractLatestUserPrompt(
+  messages: MessageWithInfo[]
+): string | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role && message.role !== 'user') continue;
+    const parts = message.parts || [];
+
+    const userPrompt = extractTextFromParts(parts);
+    if (userPrompt) {
+      return userPrompt;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Convert MessageWithInfo[] to Message[] by filtering out messages
+ * that lack required fields (role, non-empty parts array).
+ */
+export function toExtractableMessages(messages: MessageWithInfo[]): Message[] {
+  const result: Message[] = [];
+  for (const msg of messages) {
+    if (
+      typeof msg.role === 'string' &&
+      Array.isArray(msg.parts) &&
+      msg.parts.length > 0
+    ) {
+      result.push({
+        role: msg.role,
+        parts: msg.parts as MessagePart[],
+      });
+    }
+  }
+  return result;
+}
+
+/**
+ * Extract the leading slash command from a user prompt.
+ * Returns the first whitespace-delimited token if it starts with '/'
+ * and contains at least one non-slash character after the leading slash.
+ */
+export function extractSlashCommand(prompt?: string): string | undefined {
+  if (!prompt) return undefined;
+  const first = prompt.trim().split(/\s+/, 1)[0];
+  // Must start with '/' and have at least one additional character
+  if (first.length > 1 && first.startsWith('/')) {
+    return first;
+  }
+  return undefined;
+}