opencode-rules-md 0.8.5 → 0.9.0

package/src/cli/update.ts

@@ -1,85 +1,183 @@
 // ---------------------------------------------------------------------------
 // src/cli/update.ts — `omd update` command implementation.
 //
-// Fetches latest from npm, compares to installed version, purges the
-// ~/.cache/opencode/node_modules/opencode-rules-md cache, and prints the
-// reinstall instruction when stale. No auto-reinstall.
+// Like install, update is now a thin wrapper around OpenCode's own CLI.
+// We compare the installed version (read from `data['plugin']` — singular —
+// with a backward-compat fallback to the legacy `data['plugins']`) against
+// the latest npm version. When stale we purge the on-disk cache under
+// ~/.cache/opencode/packages/ (the actual location OpenCode uses) and
+// invoke `opencode plugin opencode-rules-md --global --force` to refresh
+// the registration.
+//
+// The cache purge matters because OpenCode caches the resolved package
+// by specifier — once a cached copy exists, `--force` re-registers without
+// re-fetching unless we first remove the stale entry.
 // ---------------------------------------------------------------------------
 
 import { homedir } from 'os';
 import { join } from 'path';
 import { fetchLatestVersion, isStale } from './registry.js';
-import { loadGlobalConfig, matchesPlugin, normalizePlugin } from './config.js';
-import type { CliFs } from './config.js';
+import {
+  loadGlobalConfig,
+  matchesPlugin,
+  readInstalledPlugins,
+  type CliFs,
+  type LoadedConfig,
+} from './config.js';
+import { spawnOpencodePlugin } from './spawn.js';
+
+const CONFIG_BASENAMES = ['opencode', 'tui'] as const;
+
+/** Package directory used by OpenCode to cache plugin installs. */
+export const PACKAGES_DIR_BASENAME = ['.cache', 'opencode', 'packages'] as const;
+
+/** Exact cache directory name we look for (bare specifier, no version suffix). */
+export const CACHE_DIR_BASENAME = 'opencode-rules-md';
 
-// ─── Constants ───────────────────────────────────────────────────────────────
+/**
+ * Resolve the user's home directory, honoring a custom HOME env var.
+ * Used by both resolveCachePaths and the config loader.
+ */
+export function resolveHome(env: NodeJS.ProcessEnv = process.env): string {
+  return env.HOME ?? homedir();
+}
 
-export const CACHE_PATH = join(
-  homedir(),
-  '.cache',
-  'opencode',
-  'node_modules',
-  'opencode-rules-md',
-);
+/**
+ * Return the absolute path of the OpenCode packages cache directory.
+ */
+export function resolvePackagesDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveHome(env), ...PACKAGES_DIR_BASENAME);
+}
 
-// ─── Types ───────────────────────────────────────────────────────────────────
+/**
+ * Return the cache directories that match the opencode-rules-md prefix.
+ *
+ * Real-world layout under ~/.cache/opencode/packages/ looks like:
+ *   opencode-rules-md/
+ *   opencode-rules-md@latest/
+ *   some-other-plugin/
+ *
+ * We glob-match anything starting with `opencode-rules-md` (exact or with
+ * an `@<version>` suffix). When an injected fs is provided we list the
+ * directory and filter; without one we return the two most common shapes
+ * so callers can pre-check existence cheaply.
+ */
+export function resolveCachePaths(
+  env: NodeJS.ProcessEnv = process.env,
+  fs?: CliFs,
+): string[] {
+  const packagesDir = resolvePackagesDir(env);
+  if (fs && fs.existsSync(packagesDir)) {
+    try {
+      const entries = fs.readdirSync(packagesDir);
+      return entries
+        .filter(
+          (name) => name === CACHE_DIR_BASENAME || name.startsWith(`${CACHE_DIR_BASENAME}@`),
+        )
+        .map((name) => join(packagesDir, name));
+    } catch {
+      return [];
+    }
+  }
+  // No fs injection — return the conventional candidates. Callers that care
+  // about existence should still check with existsSync().
+  return [
+    join(packagesDir, CACHE_DIR_BASENAME),
+    join(packagesDir, `${CACHE_DIR_BASENAME}@latest`),
+  ];
+}
 
 export interface UpdateOptions {
+  /** Injected latest version (test seam). Defaults to a real npm lookup. */
   latestVersion?: string | null | undefined;
+  /** Print the plan without writing or spawning. */
   dryRun?: boolean;
+  /** Injected spawn function (test seam). Defaults to spawnOpencodePlugin. */
+  spawn?: typeof spawnOpencodePlugin;
 }
 
 export interface UpdateResult {
   status: 'stale' | 'current' | 'unreachable';
-  cachePath: string;
+  cachePaths: string[];
+  /** Re-install instruction; empty when status === 'current'. */
   instruction: string;
 }
 
-// ─── Cache path helpers ───────────────────────────────────────────────────────
+/**
+ * Look up the installed specifier across both config files, returning the
+ * first one we find. Returns null when neither file registers the plugin.
+ */
+function findInstalledSpecifier(loaded: readonly LoadedConfig[]): string | null {
+  for (const cfg of loaded) {
+    const plugins = readInstalledPlugins(cfg);
+    const match = plugins.find((p) => matchesPlugin(p));
+    if (match) return match;
+  }
+  return null;
+}
 
 /**
- * Resolve the local cache directory, honoring a custom HOME environment.
- * Falls back to os.homedir() when HOME is not set, matching the
- * resolveConfigDir fallback strategy.
+ * Extract the version portion of an `opencode-rules-md@<version>` specifier.
+ * Returns null when the specifier has no `@version` segment.
  */
-export function resolveCachePath(env: NodeJS.ProcessEnv = process.env): string {
-  return join(
-    env.HOME ?? homedir(),
-    '.cache',
-    'opencode',
-    'node_modules',
-    'opencode-rules-md',
-  );
+export function extractVersion(specifier: string): string | null {
+  const at = specifier.lastIndexOf('@');
+  if (at < 0 || at === specifier.length - 1) return null;
+  return specifier.slice(at + 1);
 }
 
 /**
- * Read the cached package.json version, if determinable.
- * Returns null when the cache is missing or unreadable.
+ * Recursively delete a directory and all its contents using the injected fs.
+ * Best-effort — a failed purge is not fatal; we want the update to keep going.
  */
-function readCacheVersion(fs: CliFs, cachePath: string): string | null {
-  const pkgPath = join(cachePath, 'package.json');
+export function purgeDirectory(fs: CliFs, dirPath: string): void {
+  let entries: string[] = [];
   try {
-    if (!fs.existsSync(pkgPath)) {
-      return null;
-    }
-    const pkg = JSON.parse(fs.readFileSync(pkgPath)) as { version?: unknown };
-    return typeof pkg.version === 'string' ? pkg.version : null;
+    entries = fs.readdirSync(dirPath);
   } catch {
-    return null;
+    return;
   }
-}
 
-// ─── runUpdate ────────────────────────────────────────────────────────────────
+  for (const entry of entries) {
+    const entryPath = join(dirPath, entry);
+    try {
+      if (!fs.existsSync(entryPath)) continue;
+      // Probe to differentiate empty dirs / non-empty dirs / files. The injected
+      // fs interface does not expose stat, so we try readdir first and fall back
+      // to unlink for leaves.
+      try {
+        const subEntries = fs.readdirSync(entryPath);
+        if (subEntries.length === 0) {
+          fs.rmdirSync(entryPath);
+        } else {
+          purgeDirectory(fs, entryPath);
+          fs.rmdirSync(entryPath);
+        }
+      } catch {
+        // Not a directory (or unreadable) — best-effort unlink.
+        fs.unlinkSync(entryPath);
+      }
+    } catch {
+      // best-effort per entry
+    }
+  }
 
-const CONFIG_BASENAMES = ['opencode', 'tui'] as const;
+  try {
+    fs.rmdirSync(dirPath);
+  } catch {
+    // best-effort
+  }
+}
 
 /**
- * Run the update command:
- * 1. Fetch latest version from npm (or use provided mock)
- * 2. Compare to installed version in config
- * 3. If stale: purge cache, print reinstall instruction
- * 4. If current: print "already current"
- * 5. If unreachable: noop
+ * Run the update command.
+ *
+ * 1. Resolve the latest published version from npm (or use the injected mock).
+ * 2. Read the installed version from the user's opencode config.
+ * 3. If unreachable, log and return.
+ * 4. If current, log and return.
+ * 5. Otherwise: purge stale cache directories, then spawn
+ *    `opencode plugin opencode-rules-md --global --force`.
  */
 export const runUpdate = async (
   fs: CliFs,
@@ -88,133 +186,69 @@ export const runUpdate = async (
   _error: (s: string) => void,
   opts: UpdateOptions = {},
 ): Promise<UpdateResult> => {
-  // Use provided latestVersion for testing, otherwise fetch from npm
-  const latest = opts.latestVersion !== undefined
-    ? opts.latestVersion
-    : await fetchLatestVersion();
+  // 1. Resolve latest.
+  const latest = opts.latestVersion !== undefined ? opts.latestVersion : await fetchLatestVersion();
 
-  const cachePath = resolveCachePath(env);
+  const cachePaths = resolveCachePaths(env, fs);
+  const instruction = 'opencode plugin opencode-rules-md --global --force';
+  const spawnFn = opts.spawn ?? spawnOpencodePlugin;
 
+  // 2. Unreachable.
   if (latest === null) {
     log('omd: could not determine latest version from npm registry');
-    return {
-      status: 'unreachable',
-      cachePath,
-      instruction: 'npx opencode-rules-md@latest install',
-    };
+    return { status: 'unreachable', cachePaths, instruction };
   }
 
-  // Determine installed version from config (check both configs)
-  let installedVersion: string | null = null;
-  for (const basename of CONFIG_BASENAMES) {
-    const loaded = loadGlobalConfig(fs, env, basename);
-    const plugins = normalizePlugin(loaded.data['plugins']);
-    const match = plugins.find(p => matchesPlugin(p));
-    if (match) {
-      // Extract version from specifier (e.g. 'opencode-rules-md@2.0.0' -> '2.0.0')
-      const atIndex = match.lastIndexOf('@');
-      installedVersion = atIndex >= 0 ? match.slice(atIndex + 1) : null;
-      break; // use first config that has it
-    }
-  }
+  // 3. Installed version (read both configs).
+  const configs = CONFIG_BASENAMES.map((basename) => loadGlobalConfig(fs, env, basename));
+  const installedSpecifier = findInstalledSpecifier(configs);
+  const installedVersion = installedSpecifier ? extractVersion(installedSpecifier) : null;
 
-  const instruction = `npx opencode-rules-md@latest install`;
-
-  // Check staleness: only stale if installed version differs from latest
+  // 4. Current.
   if (installedVersion !== null && !isStale(installedVersion, latest)) {
     log(`omd: opencode-rules-md@${installedVersion} is already the latest`);
-    return {
-      status: 'current',
-      cachePath,
-      instruction,
-    };
+    return { status: 'current', cachePaths, instruction: '' };
   }
 
-  // Before purging, decide whether the cache is actually stale. When the cache
-  // version is already equal to the latest resolved version, skip the purge
-  // so we do not delete a valid cache. If the version cannot be determined,
-  // fall back to purging to be safe.
-  const cacheVersion = readCacheVersion(fs, cachePath);
-  const shouldPurge = cacheVersion === null || cacheVersion !== latest;
-
+  // 5. Stale — describe plan.
   if (opts.dryRun) {
-    log(`omd: update check (dry-run)`);
+    log('omd: update check (dry-run)');
     log(`  latest version: ${latest}`);
     log(`  installed version: ${installedVersion ?? 'not installed'}`);
-    log(`  would purge: ${shouldPurge ? cachePath : '(nothing to purge)'}`);
+    log(`  would purge: ${cachePaths.join(', ') || '(none found)'}`);
     log(`  would instruct: ${instruction}`);
-    return {
-      status: 'stale',
-      cachePath,
-      instruction,
-    };
+    return { status: 'stale', cachePaths, instruction };
   }
 
-  // Purge the cache directory using the injected fs (allows test faking)
-  if (shouldPurge) {
+  log(
+    installedVersion === null
+      ? `omd: opencode-rules-md is not installed; registering latest (${latest})`
+      : `omd: opencode-rules-md is stale (installed ${installedVersion}, latest ${latest})`,
+  );
+
+  // Purge each matching cache directory. Best-effort per path.
+  for (const cachePath of cachePaths) {
     try {
       if (fs.existsSync(cachePath)) {
-        // Recursively remove contents then the dir itself
         purgeDirectory(fs, cachePath);
+        log(`omd: purged cache ${cachePath}`);
       }
     } catch {
-      // best-effort — purge failure is non-fatal
+      // ignore individual purge failures
     }
   }
 
-  log(`omd: opencode-rules-md is stale (latest: ${latest})`);
-  log(`omd: cache purged at ${cachePath}`);
-  log(`omd: to reinstall, run:`);
-  log(`  ${instruction}`);
-
-  return {
-    status: 'stale',
-    cachePath,
-    instruction,
-  };
-};
-
-// ─── purgeDirectory ────────────────────────────────────────────────────────────
-
-/**
- * Recursively delete a directory and all its contents using the given fs.
- */
-export function purgeDirectory(fs: CliFs, dirPath: string): void {
-  let entries: string[] = [];
-  try {
-    entries = fs.readdirSync(dirPath);
-  } catch {
-    return;
-  }
+  // Re-register via OpenCode's CLI. Failure here is fatal — surface it.
+  const result = await spawnFn(['opencode-rules-md', '--global', '--force'], {
+    env: process.env,
+    stdio: 'inherit',
+  });
 
-  for (const entry of entries) {
-    const entryPath = join(dirPath, entry);
-    try {
-      if (fs.existsSync(entryPath)) {
-        // Check if it's a directory by trying to read it
-        try {
-          const subEntries = fs.readdirSync(entryPath);
-          if (subEntries.length === 0) {
-            // Empty directory
-            fs.rmdirSync(entryPath);
-          } else {
-            // Non-empty directory — recurse
-            purgeDirectory(fs, entryPath);
-            fs.rmdirSync(entryPath);
-          }
-        } catch {
-          // It's a file — unlink it
-          fs.unlinkSync(entryPath);
-        }
-      }
-    } catch {
-      // best-effort per entry
-    }
+  if ((result.status ?? 0) !== 0) {
+    throw new Error(
+      `opencode plugin opencode-rules-md --global --force exited with status ${String(result.status)}`,
+    );
   }
 
-  try {
-    fs.rmdirSync(dirPath);
-  } catch {
-    // best-effort
-  }
-}
+  return { status: 'stale', cachePaths, instruction: '' };
+};

package/src/rule-discovery.ts

@@ -173,33 +173,45 @@ export interface DiscoveredRule {
 export async function discoverRuleFiles(
   projectDir?: string
 ): Promise<DiscoveredRule[]> {
-  const files: DiscoveredRule[] = [];
+  // Keyed by relativePath; later insertions shadow earlier ones.
+  // Global rules are inserted first (lowest precedence); project-local rules
+  // are inserted after and overwrite any global entry sharing the same key.
+  const byRelativePath = new Map<string, DiscoveredRule>();
 
-  // Discover global rules (recursively)
+  // Discover global rules (recursively) — inserted first (lowest precedence).
   const globalRulesDir = getGlobalRulesDir();
   if (globalRulesDir) {
     const globalRules = await scanDirectoryRecursively(
       globalRulesDir,
       globalRulesDir
     );
-    for (const { filePath, relativePath } of globalRules) {
-      debugLog(`Discovered global rule: ${relativePath} (${filePath})`);
-      files.push({ filePath, relativePath });
+    for (const rule of globalRules) {
+      debugLog(
+        `Discovered global rule: ${rule.relativePath} (${rule.filePath})`
+      );
+      byRelativePath.set(rule.relativePath, rule);
     }
   }
 
-  // Discover project-local rules (recursively) if project directory is provided
+  // Discover project-local rules (recursively) — shadow global duplicates.
   if (projectDir) {
     const projectRulesDir = path.join(projectDir, '.opencode', 'rules');
     const projectRules = await scanDirectoryRecursively(
       projectRulesDir,
       projectRulesDir
     );
-    for (const { filePath, relativePath } of projectRules) {
-      debugLog(`Discovered project rule: ${relativePath} (${filePath})`);
-      files.push({ filePath, relativePath });
+    for (const rule of projectRules) {
+      const shadowed = byRelativePath.has(rule.relativePath);
+      debugLog(
+        `Discovered project rule: ${rule.relativePath} (${rule.filePath})` +
+          (shadowed ? ' [shadows global]' : '')
+      );
+      byRelativePath.set(rule.relativePath, rule);
     }
   }
 
-  return files;
+  // Map preserves insertion order in JS, so global rules keep their relative
+  // order and shadowed slots retain their original position but point at the
+  // project file.
+  return Array.from(byRelativePath.values());
 }

package/src/rule-filter.ts

@@ -59,12 +59,23 @@ export function toolsMatchAvailable(
   return requiredTools.some(tool => availableSet.has(tool));
 }
 
+/**
+ * Rough token estimate using the chars/4 heuristic.
+ * No external dependency; accurate enough for budget decisions.
+ */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+
 /**
  * Result of reading and formatting rules
  */
 export interface FilterResult {
   formattedRules: string;
   matchedPaths: string[];
+  /** Estimated token count of formattedRules (0 when empty) */
+  tokenEstimate: number;
 }
 
 /**
@@ -91,6 +102,8 @@ export interface RuleFilterContext {
   os?: string;
   /** Whether running in CI environment */
   ci?: boolean;
+  /** Optional hard token cap; lowest-priority rules are dropped when exceeded. */
+  maxTokens?: number;
 }
 
 /**
@@ -103,16 +116,26 @@ export async function readAndFormatRules(
   context: RuleFilterContext = {}
 ): Promise<FilterResult> {
   if (files.length === 0) {
-    return { formattedRules: '', matchedPaths: [] };
+    return { formattedRules: '', matchedPaths: [], tokenEstimate: 0 };
   }
 
-  const ruleContents: string[] = [];
-  const matchedPaths: string[] = [];
   const availableToolSet =
     context.availableToolIDs && context.availableToolIDs.length > 0
       ? new Set(context.availableToolIDs)
       : undefined;
 
+  // Collect matched entries with priority and token count
+  type MatchedEntry = {
+    filePath: string;
+    relativePath: string;
+    strippedContent: string;
+    priority: number;
+    tokenCount: number;
+    index: number;
+  };
+  const entries: MatchedEntry[] = [];
+  let entryIndex = 0;
+
   for (const { filePath, relativePath } of files) {
     // Use cached rule data with mtime-based invalidation
     const cachedRule = await getCachedRule(filePath);
@@ -250,20 +273,58 @@ export async function readAndFormatRules(
       );
     }
 
-    // Use cached stripped content for output
-    // Use relativePath for unique headings instead of just filename
-    ruleContents.push(`## ${relativePath}\n\n${strippedContent}`);
-    matchedPaths.push(filePath);
+    // Extract priority (default 0 for selection; undefined in metadata means absent)
+    const priority = metadata?.priority ?? 0;
+
+    // Build formatted chunk for token counting
+    const formattedChunk = `## ${relativePath}\n\n${strippedContent}`;
+    const tokenCount = estimateTokens(formattedChunk);
+
+    entries.push({ filePath, relativePath, strippedContent, priority, tokenCount, index: entryIndex++ });
   }
 
-  if (ruleContents.length === 0) {
-    return { formattedRules: '', matchedPaths: [] };
+  if (entries.length === 0) {
+    return { formattedRules: '', matchedPaths: [], tokenEstimate: 0 };
   }
 
+  // Determine which entries to include based on budget
+  const maxTokens = context.maxTokens;
+  const hasValidBudget = typeof maxTokens === 'number' && maxTokens > 0 && Number.isFinite(maxTokens);
+
+  let survivors: MatchedEntry[];
+  if (!hasValidBudget) {
+    // No budget: use discovery order (existing behavior)
+    survivors = entries;
+  } else {
+    // Valid budget: stable sort by priority desc, index asc
+    const sorted = [...entries].sort((a, b) =>
+      (b.priority - a.priority) || (a.index - b.index)
+    );
+
+    // Greedy selection: always keep first (≥1 survivor invariant), then add while within budget
+    survivors = [sorted[0]];
+    let runningTokens = sorted[0].tokenCount;
+    for (let i = 1; i < sorted.length; i++) {
+      if (runningTokens + sorted[i].tokenCount <= maxTokens) {
+        survivors.push(sorted[i]);
+        runningTokens += sorted[i].tokenCount;
+      }
+    }
+  }
+
+  // Build output from survivors
+  const ruleContents = survivors.map(
+    entry => `## ${entry.relativePath}\n\n${entry.strippedContent}`
+  );
+  const matchedPaths = survivors.map(entry => entry.filePath);
+
+  const formattedRules =
+    `# OpenCode Rules\n\nPlease follow the following rules:\n\n` +
+    ruleContents.join('\n\n---\n\n');
+
   return {
-    formattedRules:
-      `# OpenCode Rules\n\nPlease follow the following rules:\n\n` +
-      ruleContents.join('\n\n---\n\n'),
+    formattedRules,
     matchedPaths,
+    tokenEstimate: estimateTokens(formattedRules),
   };
 }

package/src/rule-metadata.ts

@@ -19,6 +19,8 @@ export interface RuleMetadata {
   os?: string[];
   ci?: boolean;
   match?: 'any' | 'all';
+  /** Higher priority is kept first when a token budget is enforced. Default 0. */
+  priority?: number;
 }
 
 /**
@@ -36,6 +38,7 @@ interface ParsedFrontmatter {
   os?: unknown;
   ci?: unknown;
   match?: unknown;
+  priority?: unknown;
 }
 
 /** Field names in ParsedFrontmatter that are string arrays */
@@ -129,6 +132,11 @@ export function parseRuleMetadata(content: string): RuleMetadata | undefined {
       metadata.match = parsed.match;
     }
 
+    // Extract priority (finite numbers only; non-finite or absent becomes undefined, treated as 0 downstream)
+    if (typeof parsed.priority === 'number' && Number.isFinite(parsed.priority)) {
+      metadata.priority = parsed.priority;
+    }
+
     // Return metadata only if it has content
     return Object.keys(metadata).length > 0 ? metadata : undefined;
   } catch (error) {

package/src/runtime-context.ts

@@ -62,6 +62,18 @@ export function detectCiEnvironment(): boolean {
   );
 }
 
+/**
+ * Resolve the active token budget from the OPENCODE_RULES_MAX_TOKENS env var.
+ * Returns undefined when the env var is absent, empty, zero, negative, or non-finite.
+ * Positive finite numbers enable budget enforcement.
+ */
+export function resolveMaxTokens(): number | undefined {
+  const raw = process.env.OPENCODE_RULES_MAX_TOKENS;
+  if (!raw) return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
 /**
  * Build the filter context object used for rule matching.
  * Assembles runtime information from various sources.
@@ -125,6 +137,10 @@ export async function buildFilterContext(
   if (gitBranch !== undefined) {
     context.gitBranch = gitBranch;
   }
+  const maxTokens = resolveMaxTokens();
+  if (maxTokens !== undefined) {
+    context.maxTokens = maxTokens;
+  }
 
   debugLog(
     `Filter context: model=${modelID ?? 'none'}, agent=${agentType ?? 'none'}, ` +

package/src/session-store.ts

@@ -108,6 +108,7 @@ export class SessionStore {
 
     this.upsert(sessionID, s => {
       s.isCompacting = false;
+      s.rulesInjected = false;
     });
 
     return false;