sweet-search 2.5.12 → 2.5.14

package/eval/agent-read-workflows/bin/_ss-argparse.mjs

@@ -0,0 +1,194 @@
+// Pure argument-parsing helpers for the ss-* CLI wrappers.
+//
+// Extracted from _ss-helpers.mjs so they can be unit-tested without triggering
+// the CLI's top-level IIFE (which runs on import). NOTHING here touches
+// process.* or the filesystem — every function is a pure transform over an
+// args array (some mutate the array in place, by design, and return a value).
+
+// --- value-flag parsers (mutate `args`, returning the consumed value) --------
+
+export function parseFlag(args, name, fallback) {
+  const i = args.indexOf(name);
+  if (i === -1) return fallback;
+  const v = args[i + 1];
+  args.splice(i, 2);
+  return v;
+}
+
+export function parseShortFlag(args, names, fallback) {
+  for (const n of names) {
+    const i = args.indexOf(n);
+    if (i !== -1) { const v = args[i + 1]; args.splice(i, 2); return v; }
+  }
+  return fallback;
+}
+
+// Boolean (value-less) flag: remove every occurrence, return whether any present.
+export function parseBoolFlag(args, names) {
+  let present = false;
+  for (const n of names) {
+    let i;
+    while ((i = args.indexOf(n)) !== -1) { args.splice(i, 1); present = true; }
+  }
+  return present;
+}
+
+// --- pattern construction ----------------------------------------------------
+
+export function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Translate the grep-family pattern flags into a single regex — no engine change
+// needed. `-F` escapes the pattern so metacharacters are literal; `-w` wraps it
+// in word boundaries; `-i` prepends the `(?i)` inline flag the planner already
+// honours end-to-end (hasCaseInsensitiveRegexFlag → ripgrep prefilter + Rust
+// gram+grep). Order matters: escape (literal) → word-wrap → case flag.
+export function buildGrepPattern(pattern, { ignoreCase = false, wordBound = false, fixedString = false } = {}) {
+  if (!pattern) return pattern;
+  let p = fixedString ? escapeRegex(pattern) : pattern;
+  if (wordBound) p = `\\b(?:${p})\\b`;
+  if (ignoreCase && !/^\(\?[a-z-]*i[a-z-]*[:)]/.test(p)) p = `(?i)${p}`;
+  return p;
+}
+
+// --- inert flags (always true for ss-*, safe to accept as no-ops) ------------
+// These never change which lines match: we always print file:line, always
+// search the whole index, never colourise. Stripping them lets reflexive grep
+// muscle-memory pass without a wasted call — UNLIKE semantic flags (-w/-F/-v/
+// -C…), which we either implement or reject, never silently drop.
+export const INERT_FLAGS = new Set([
+  '-n', '--line-number', '-H', '--with-filename', '--no-filename',
+  '-r', '-R', '--recursive', '--color', '--colour',
+]);
+
+export function stripInertFlags(args) {
+  for (let i = args.length - 1; i >= 0; i--) {
+    const a = args[i];
+    if (typeof a === 'string' && (INERT_FLAGS.has(a) || /^--colou?r=/.test(a))) {
+      args.splice(i, 1);
+    }
+  }
+}
+
+// --- normalisation: make agent-typed forms canonical before parsing ----------
+// Short flags that consume a following value, and value-less boolean shorts.
+// Used to split attached/bundled forms (-k5, -iw, -iwk5) the way getopt would,
+// so they parse instead of being mistaken for an unknown flag or the pattern.
+export const VALUE_SHORTS = new Set(['k']);
+export const BOOL_SHORTS = new Set(['i', 'w', 'F']);
+export const VALUE_LONGS = new Set([
+  '--top', '--regex', '--mode', '--max-tokens',
+  '--in', '--file', '--query', '--hint', '--depth', '--budget',
+]);
+
+export function normalizeArgs(args) {
+  const out = [];
+  let positionalOnly = false;
+  for (const tok of args) {
+    if (positionalOnly || typeof tok !== 'string') { out.push(tok); continue; }
+    if (tok === '--') { out.push(tok); positionalOnly = true; continue; }
+
+    // --name=value  →  --name value, but only for known value flags. Unknown
+    // long options stay intact so the guard can reject the whole token, and
+    // optional-value no-ops like --color=always can be stripped atomically.
+    let m = /^(--[A-Za-z][\w-]*)=(.*)$/.exec(tok);
+    if (m && VALUE_LONGS.has(m[1])) { out.push(m[1], m[2]); continue; }
+
+    // attached short value or boolean bundle:  -k5, -iw, -iwk5
+    m = /^-([A-Za-z])(.+)$/.exec(tok);
+    if (m) {
+      const first = m[1];
+      if (VALUE_SHORTS.has(first)) { out.push('-' + first, m[2]); continue; } // -k5 → -k 5
+      if (BOOL_SHORTS.has(first)) {
+        const chars = tok.slice(1);
+        const expanded = [];
+        let i = 0, ok = true;
+        while (i < chars.length) {
+          const ch = chars[i];
+          if (BOOL_SHORTS.has(ch)) { expanded.push('-' + ch); i++; }
+          else if (VALUE_SHORTS.has(ch)) {                 // value short ends the bundle
+            const val = chars.slice(i + 1);
+            expanded.push('-' + ch);
+            if (val) expanded.push(val);
+            i = chars.length;
+          } else { ok = false; break; }                    // unknown char → leave token intact
+        }
+        if (ok) { out.push(...expanded); continue; }
+      }
+    }
+    out.push(tok);
+  }
+  return out;
+}
+
+// A token that looks like a real CLI option, as opposed to a regex/query that
+// merely begins with '-' (e.g. `-?\d+`, `-->`). Narrow on purpose: single short
+// letter, pure-letter bundle, or GNU long flag. Anything containing regex
+// metacharacters falls through and is treated as the positional pattern, so a
+// dash-leading pattern works WITHOUT the agent needing to know about `--`.
+export function looksLikeOption(tok) {
+  if (typeof tok !== 'string' || tok === '-' || tok === '--') return false;
+  return /^-[A-Za-z][A-Za-z0-9]*$/.test(tok)      // -i, -iw, -C2
+    || /^--[A-Za-z][\w-]*(?:=.*)?$/.test(tok);    // --ignore-case, --foo=bar
+}
+
+export function parseValueFlag(args, names, fallback, { allowOptionValue = false } = {}) {
+  const allNames = Array.isArray(names) ? names : [names];
+  for (const n of allNames) {
+    const i = args.indexOf(n);
+    if (i === -1) continue;
+    const v = args[i + 1];
+    if (v == null || (!allowOptionValue && looksLikeOption(v))) {
+      return { value: fallback, flag: n, error: `${n} requires a value` };
+    }
+    args.splice(i, 2);
+    return { value: v, flag: n, error: null };
+  }
+  return { value: fallback, flag: null, error: null };
+}
+
+export function parsePositiveIntFlag(args, names, fallback, { min = 1 } = {}) {
+  const parsed = parseValueFlag(args, names, fallback);
+  if (parsed.error) return parsed;
+  if (parsed.flag == null) return { ...parsed, value: fallback };
+  const n = Number(parsed.value);
+  if (!Number.isInteger(n) || n < min) {
+    return { value: fallback, flag: parsed.flag, error: `${parsed.flag} must be an integer >= ${min}` };
+  }
+  return { value: n, flag: parsed.flag, error: null };
+}
+
+// Parse a line range supplied as a single positional token — `10-20`, `10:20`
+// or `10,20` (sed/bat/"lines 10-20" muscle memory). Returns { start, end } only
+// for a well-formed ascending range; null otherwise (so the caller falls back to
+// the plain numeric path or its own validation). Deliberately strict: both ends
+// required, no open-ended `10-` (which previously caused accidental over-reads).
+export function parseLineRange(token) {
+  if (typeof token !== 'string') return null;
+  const m = /^(\d+)[-:,](\d+)$/.exec(token);
+  if (!m) return null;
+  const start = +m[1];
+  const end = +m[2];
+  if (start < 1 || end < start) return null;
+  return { start, end };
+}
+
+// After known flags are consumed, resolve the positional pattern. `--` ends
+// option parsing (everything after is positional). Any remaining option-shaped
+// token is an unsupported flag → reported, not silently dropped and not
+// mistaken for the pattern. Returns { pattern, unknownFlag }; the caller decides
+// how to surface the error (kept side-effect-free for testability).
+export function extractPositional(args) {
+  const sep = args.indexOf('--');
+  if (sep !== -1) {
+    const before = args.slice(0, sep);
+    const after = args.slice(sep + 1);
+    const bad = before.find(looksLikeOption);
+    if (bad) return { pattern: undefined, unknownFlag: bad };
+    return { pattern: after[0], unknownFlag: null };
+  }
+  const bad = args.find(looksLikeOption);
+  if (bad) return { pattern: undefined, unknownFlag: bad };
+  return { pattern: args[0], unknownFlag: null };
+}

package/eval/agent-read-workflows/bin/_ss-helpers.mjs

@@ -13,6 +13,11 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import {
+  parseBoolFlag, parseValueFlag, parsePositiveIntFlag,
+  buildGrepPattern, stripInertFlags, normalizeArgs, extractPositional,
+  parseLineRange, looksLikeOption,
+} from './_ss-argparse.mjs';
 
 // 8-char SHA1 prefix is enough for grouping identical queries across
 // benchmark runs without bloating artifacts.
@@ -40,19 +45,39 @@ process.env.SWEET_SEARCH_PROJECT_ROOT = PROJECT_ROOT;
 const subcommand = process.argv[2];
 const rest = process.argv.slice(3);
 
-function parseFlag(args, name, fallback) {
-  const i = args.indexOf(name);
-  if (i === -1) return fallback;
-  const v = args[i + 1];
-  args.splice(i, 2);
-  return v;
-}
-function parseShortFlag(args, names, fallback) {
-  for (const n of names) {
-    const i = args.indexOf(n);
-    if (i !== -1) { const v = args[i + 1]; args.splice(i, 2); return v; }
+// Pure arg-parsing helpers (parseFlag/parseShortFlag/parseBoolFlag/
+// buildGrepPattern/stripInertFlags/normalizeArgs/extractPositional) live in
+// ./_ss-argparse.mjs so they can be unit-tested without this file's top-level
+// IIFE firing. resolvePositional wraps the side-effect-free extractPositional
+// with the CLI's loud-error exit.
+function resolvePositional(args, usage) {
+  const { pattern, unknownFlag } = extractPositional(args);
+  if (unknownFlag) {
+    failUsage(`unrecognised option "${unknownFlag}"`, usage);
   }
-  return fallback;
+  return pattern;
+}
+
+function failUsage(message, usage) {
+  process.stderr.write(`[ss] ${message}\n${usage}\n`);
+  process.exit(2);
+}
+
+function readPositiveIntFlag(args, names, fallback, usage) {
+  const parsed = parsePositiveIntFlag(args, names, fallback);
+  if (parsed.error) failUsage(parsed.error, usage);
+  return parsed.value;
+}
+
+function readValueFlag(args, names, fallback, usage, opts = {}) {
+  const parsed = parseValueFlag(args, names, fallback, opts);
+  if (parsed.error) failUsage(parsed.error, usage);
+  return parsed.value;
+}
+
+function rejectUnknownOptions(args, usage) {
+  const bad = args.find(looksLikeOption);
+  if (bad) failUsage(`unrecognised option "${bad}"`, usage);
 }
 
 async function getSweetSearch() {
@@ -79,11 +104,17 @@ async function ensureWarmServerReady({ timeoutMs = 60000, intervalMs = 500 } = {
 
 // --- subcommands ----------------------------------------------------------
 
-async function cmdGrep(args) {
-  const k = +parseShortFlag(args, ['-k', '--top'], 20);
-  const regex = args[0];
+const GREP_USAGE = 'Usage: ss-grep <regex> [-i|--ignore-case] [-w|--word-regexp] [-F|--fixed-strings] [-k N]';
+async function cmdGrep(rawArgs) {
+  const args = normalizeArgs(rawArgs);
+  const ignoreCase = parseBoolFlag(args, ['-i', '--ignore-case']);
+  const wordBound = parseBoolFlag(args, ['-w', '--word-regexp']);
+  const fixedString = parseBoolFlag(args, ['-F', '--fixed-strings']);
+  const k = readPositiveIntFlag(args, ['-k', '--top'], 20, GREP_USAGE);
+  stripInertFlags(args);
+  const regex = buildGrepPattern(resolvePositional(args, GREP_USAGE), { ignoreCase, wordBound, fixedString });
   if (!regex) {
-    process.stderr.write('Usage: ss-grep <regex> [-k N]\n');
+    process.stderr.write(GREP_USAGE + '\n');
     process.exit(2);
   }
   const s = await getSweetSearch();
@@ -109,27 +140,34 @@ async function cmdGrep(args) {
   process.exit(0);
 }
 
-async function cmdFind(args) {
+async function cmdFind(rawArgs) {
+  const args = normalizeArgs(rawArgs);
   // ColGrep pattern search with token-budgeted agent packaging — returns the
   // FULL useful answer (ranked code blocks + confidence + sufficiency), the same
   // agent packaging ss-search emits. ss-grep is the short/locator counterpart, so
   // ss-find defaults to the full answer: it saves the follow-up read entirely.
   // (Mirrors the agent-in-the-loop H2H adapter eval/agent-eval/tools/
   // pattern-agent-tools.js, which calls search(...,{format:'agent'}).)
+  const FIND_USAGE = 'Usage: ss-find "<query>" --regex "<regex>" [-i|--ignore-case] [-w|--word-regexp] [-F|--fixed-strings] [--full|--xl] [-k N]';
   let format = 'agent';
   if (args.includes('--full')) { format = 'agent_full'; args.splice(args.indexOf('--full'), 1); }
   if (args.includes('--xl'))   { format = 'agent_full_xl'; args.splice(args.indexOf('--xl'), 1); }
-  const k = +parseShortFlag(args, ['-k', '--top'], 6);
-  const regex = parseFlag(args, '--regex', '');
-  const query = args[0];
+  const ignoreCase = parseBoolFlag(args, ['-i', '--ignore-case']);
+  const wordBound = parseBoolFlag(args, ['-w', '--word-regexp']);
+  const fixedString = parseBoolFlag(args, ['-F', '--fixed-strings']);
+  const k = readPositiveIntFlag(args, ['-k', '--top'], 6, FIND_USAGE);
+  const regex = readValueFlag(args, '--regex', '', FIND_USAGE, { allowOptionValue: true });
+  stripInertFlags(args);
+  const query = resolvePositional(args, FIND_USAGE);
   if (!query) {
-    process.stderr.write('Usage: ss-find "<query>" --regex "<regex>" [--full|--xl] [-k N]\n');
+    process.stderr.write(FIND_USAGE + '\n');
     process.exit(2);
   }
   // Budget-sweep experiment hook: lets the bench pin the response token budget
   // per-process without changing the agent-visible tool surface.
   const envFindBudget = Number(process.env.SS_SMOKE_FIND_BUDGET || '') || null;
-  const effectiveRegex = regex || '';
+  // Pattern flags apply to the regex candidate generator; the NL query is untouched.
+  const effectiveRegex = buildGrepPattern(regex || '', { ignoreCase, wordBound, fixedString });
   const s = await getSweetSearch();
   if (!s.hasLateInteractionIndex) {
     process.stderr.write(`[ss-find] no late-interaction index — falling back to ss-grep\n`);
@@ -172,12 +210,26 @@ async function cmdFind(args) {
   process.exit(0);
 }
 
+// ss-read takes NO flags — only positional <file> [start] [end] (or a single
+// "start-end" / "start:end" / "start,end" range token). Unlike ss-grep, a stray
+// flag here can never silently corrupt the result: the line slots are validated
+// as numbers, so a misuse is already a loud error. These hints exist only to
+// turn that error into a self-correcting one (the M++ prompt, which we may not
+// touch, documents the positional form, not these recovery messages).
+const READ_USAGE =
+  'Usage: ss-read <file>            # whole file\n' +
+  '       ss-read <file> <start>    # ONE line\n' +
+  '       ss-read <file> <start> <end>\n' +
+  '       ss-read <file> 10-20      # range (also 10:20, 10,20)\n' +
+  'Note: ss-read has no flags (no -n/--limit/-r); line selection is positional.';
 async function cmdRead(args) {
   const file = args[0];
   if (!file) {
-    process.stderr.write('Usage: ss-read <file>             # whole file\n');
-    process.stderr.write('       ss-read <file> <start>     # ONE line\n');
-    process.stderr.write('       ss-read <file> <start> <end>\n');
+    process.stderr.write(READ_USAGE + '\n');
+    process.exit(2);
+  }
+  if (looksLikeOption(file)) {
+    process.stderr.write(`[ss-read] "${file}" looks like a flag, but ss-read takes a file path first.\n${READ_USAGE}\n`);
     process.exit(2);
   }
   // If start is provided and end is omitted, read EXACTLY that one line —
@@ -185,19 +237,27 @@ async function cmdRead(args) {
   // caused accidental over-reading on large files).
   let start = null, end = null;
   if (args[1] != null) {
-    start = +args[1];
-    if (!Number.isFinite(start) || start < 1) {
-      process.stderr.write(`[ss-read] invalid start line: "${args[1]}"\n`);
-      process.exit(2);
-    }
-    if (args[2] != null) {
-      end = +args[2];
-      if (!Number.isFinite(end) || end < start) {
-        process.stderr.write(`[ss-read] invalid end line: "${args[2]}" (must be ≥ start ${start})\n`);
+    // Accept a single-token range (10-20 / 10:20 / 10,20) before the plain
+    // numeric path, so "lines 10-20" muscle memory works without a wasted call.
+    const range = parseLineRange(args[1]);
+    if (range && args[2] == null) {
+      start = range.start;
+      end = range.end;
+    } else {
+      start = +args[1];
+      if (!Number.isFinite(start) || start < 1) {
+        process.stderr.write(`[ss-read] invalid start line: "${args[1]}" (expected a line number, e.g. 10, or a range like 10-20)\n${READ_USAGE}\n`);
         process.exit(2);
       }
-    } else {
-      end = start;     // single-line read
+      if (args[2] != null) {
+        end = +args[2];
+        if (!Number.isFinite(end) || end < start) {
+          process.stderr.write(`[ss-read] invalid end line: "${args[2]}" (must be ≥ start ${start})\n`);
+          process.exit(2);
+        }
+      } else {
+        end = start;     // single-line read
+      }
     }
   }
   const { readFile } = await import(path.join(REPO_ROOT, 'core/search/search-read.js'));
@@ -212,7 +272,9 @@ async function cmdRead(args) {
   process.exit(0);
 }
 
-async function cmdAgentSearch(args) {
+const SEARCH_USAGE = 'Usage: ss-search "<query>" [--full|--xl] [-k N] [--mode auto|lexical|semantic|hybrid]';
+async function cmdAgentSearch(rawArgs) {
+  const args = normalizeArgs(rawArgs);
   // Main sweet-search auto/CatBoost search with token-budgeted agent packaging.
   //
   // Usage:
@@ -229,11 +291,11 @@ async function cmdAgentSearch(args) {
   let format = 'agent';
   if (args.includes('--full')) { format = 'agent_full'; args.splice(args.indexOf('--full'), 1); }
   if (args.includes('--xl'))   { format = 'agent_full_xl'; args.splice(args.indexOf('--xl'), 1); }
-  const k = +parseShortFlag(args, ['-k', '--top'], 5);
-  const mode = parseFlag(args, '--mode', 'auto');
-  const query = args[0];
+  const k = readPositiveIntFlag(args, ['-k', '--top'], 5, SEARCH_USAGE);
+  const mode = readValueFlag(args, '--mode', 'auto', SEARCH_USAGE);
+  const query = resolvePositional(args, SEARCH_USAGE);
   if (!query) {
-    process.stderr.write('Usage: ss-search "<query>" [--full|--xl] [-k N] [--mode auto|lexical|semantic|hybrid]\n');
+    process.stderr.write(SEARCH_USAGE + '\n');
     process.exit(2);
   }
 
@@ -383,18 +445,21 @@ async function cmdAgentSearch(args) {
   process.exit(0);
 }
 
-async function cmdSemantic(args) {
+const SEMANTIC_USAGE = 'Usage: ss-semantic <file> "<question>" [--max-tokens N]';
+async function cmdSemantic(rawArgs) {
+  const args = normalizeArgs(rawArgs);
+  // Default 600 (was 800) per the 2026-06 budget sweep — scaled with the 3k
+  // preview tier. Env hook overrides the default for sweeps; an explicit
+  // --max-tokens flag from the agent always wins.
+  const maxTokens = readPositiveIntFlag(args, '--max-tokens',
+    Number(process.env.SS_SMOKE_SEMANTIC_MAXTOKENS || '') || 600, SEMANTIC_USAGE);
+  rejectUnknownOptions(args, SEMANTIC_USAGE);
   const file = args[0];
   const query = args[1];
   if (!file || !query) {
-    process.stderr.write('Usage: ss-semantic <file> "<question>" [--max-tokens N]\n');
+    process.stderr.write(SEMANTIC_USAGE + '\n');
     process.exit(2);
   }
-  // Default 600 (was 800) per the 2026-06 budget sweep — scaled with the 3k
-  // preview tier. Env hook overrides the default for sweeps; an explicit
-  // --max-tokens flag from the agent always wins.
-  const maxTokens = +parseFlag(args.slice(2), '--max-tokens',
-    Number(process.env.SS_SMOKE_SEMANTIC_MAXTOKENS || '') || 600);
   const { readSemantic } = await import(path.join(REPO_ROOT, 'core/search/search-read-semantic.js'));
   const r = await readSemantic({
     path: file, query, projectRoot: PROJECT_ROOT,
@@ -413,29 +478,31 @@ async function cmdSemantic(args) {
   process.exit(0);
 }
 
-async function cmdTrace(args) {
+const TRACE_USAGE = 'Usage: ss-trace <symbol> [--in <file>] [--query <hint>] [--depth N] [--budget N]';
+async function cmdTrace(rawArgs) {
+  const args = normalizeArgs(rawArgs);
   let json = false;
   if (args.includes('--json')) {
     json = true;
     args.splice(args.indexOf('--json'), 1);
   }
-  const symbol = args[0];
-  if (!symbol) {
-    process.stderr.write('Usage: ss-trace <symbol> [--in <file>] [--query <hint>] [--depth N] [--budget N]\n');
-    process.exit(2);
-  }
   const { traceSymbol, formatStructuralContext } = await import(path.join(REPO_ROOT, 'core/search/search-trace.js'));
 
   const opts = { projectRoot: PROJECT_ROOT };
-  const file = parseFlag(args, '--in', null) || parseFlag(args, '--file', null);
-  const queryHint = parseFlag(args, '--query', '') || parseFlag(args, '--hint', '');
-  const depth = parseFlag(args, '--depth', null);
-  const budget = parseFlag(args, '--budget', null);
+  const file = readValueFlag(args, ['--in', '--file'], null, TRACE_USAGE);
+  const queryHint = readValueFlag(args, ['--query', '--hint'], '', TRACE_USAGE, { allowOptionValue: true });
+  const depth = readPositiveIntFlag(args, '--depth', null, TRACE_USAGE);
+  const budget = readPositiveIntFlag(args, '--budget', null, TRACE_USAGE);
+  const symbol = resolvePositional(args, TRACE_USAGE);
+  if (!symbol) {
+    process.stderr.write(TRACE_USAGE + '\n');
+    process.exit(2);
+  }
   if (file) opts.filePath = file;
   if (queryHint) opts.queryHint = queryHint;
-  if (depth != null) opts.maxDepth = +depth;
+  if (depth != null) opts.maxDepth = depth;
   // Budget-sweep experiment hook: env sets the default; explicit --budget wins.
-  if (budget != null) opts.tokenBudget = +budget;
+  if (budget != null) opts.tokenBudget = budget;
   else if (Number(process.env.SS_SMOKE_TRACE_BUDGET || '') > 0) opts.tokenBudget = Number(process.env.SS_SMOKE_TRACE_BUDGET);
 
   const response = traceSymbol(symbol, opts);

package/eval/agent-read-workflows/bin/ss-find

@@ -5,7 +5,7 @@
 # Use for behavioural / semantic questions where lexical alone won't pinpoint the
 # chunk. (ss-grep is the short file:line locator.)
 #
-# Usage:  ss-find "<query>" --regex "<regex>" [--full|--xl] [-k N]
+# Usage:  ss-find "<query>" --regex "<regex>" [-i|--ignore-case] [--full|--xl] [-k N]
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 TMPERR=$(mktemp)
 node "$DIR/_ss-helpers.mjs" find "$@" 2>"$TMPERR"

package/eval/agent-read-workflows/bin/ss-grep

@@ -2,7 +2,7 @@
 # ss-grep: indexed bare grep (gram-prefiltered) over the cwd's Sweet Search index.
 # Compact agent-friendly output: file:line  matchText
 #
-# Usage:  ss-grep <regex> [-k N]
+# Usage:  ss-grep <regex> [-i|--ignore-case] [-k N]
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 TMPERR=$(mktemp)
 node "$DIR/_ss-helpers.mjs" grep "$@" 2>"$TMPERR"

package/eval/agent-read-workflows/bin/ss-read

@@ -3,6 +3,8 @@
 #   ss-read <file>                  # whole file
 #   ss-read <file> <start>          # ONE line (NOT start-to-EOF)
 #   ss-read <file> <start> <end>    # explicit range
+#   ss-read <file> 10-20            # range token (also 10:20, 10,20)
+# No flags: ss-read takes no -n/--limit/-r — line selection is positional.
 # Open-ended start-to-EOF is intentionally not supported in the bench wrapper
 # to prevent accidental over-reading. To pull a span, give an explicit end.
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sweet-search",
-  "version": "2.5.12",
+  "version": "2.5.14",
   "description": "Sweet Search - SOTA Hybrid Code Search Engine with WASM CatBoost Query Router, Semantic/Lexical/Structural Search, and Multilingual Support",
   "type": "module",
   "main": "core/search/sweet-search.js",
@@ -76,6 +76,7 @@
     "eval/agent-read-workflows/bin/ss-trace",
     "eval/agent-read-workflows/bin/ss-read",
     "eval/agent-read-workflows/bin/_ss-helpers.mjs",
+    "eval/agent-read-workflows/bin/_ss-argparse.mjs",
     "crates/wasm-router/pkg/",
     "LICENSE",
     "NOTICE"
@@ -164,12 +165,12 @@
   },
   "optionalDependencies": {
     "usearch": "^2.21.4",
-    "@sweet-search/native-darwin-arm64": "2.5.12",
-    "@sweet-search/native-darwin-x64": "2.5.12",
-    "@sweet-search/native-linux-arm64-gnu": "2.5.12",
-    "@sweet-search/native-linux-arm64-gnu-cuda": "2.5.12",
-    "@sweet-search/native-linux-x64-gnu": "2.5.12",
-    "@sweet-search/native-linux-x64-gnu-cuda": "2.5.12"
+    "@sweet-search/native-darwin-arm64": "2.5.14",
+    "@sweet-search/native-darwin-x64": "2.5.14",
+    "@sweet-search/native-linux-arm64-gnu": "2.5.14",
+    "@sweet-search/native-linux-arm64-gnu-cuda": "2.5.14",
+    "@sweet-search/native-linux-x64-gnu": "2.5.14",
+    "@sweet-search/native-linux-x64-gnu-cuda": "2.5.14"
   },
   "engines": {
     "node": ">=18.0.0"