@chemx/starter-kit 26.10.26-386 → 26.10.29-360

package/AGENTS.md

@@ -9,7 +9,7 @@
 | Standard Reflex | `chemx` Equivalent | Token & Architecture Advantage |
 | :--- | :--- | :--- |
 | `grep -rn "pattern" .` | `chemx q -g "pattern" --bare` or `chemx q -g "pattern" -C 3 --bare` | Fixed-string search matching rg token-for-token (57 chars / 14 tokens per hit); add `-C <N>` to inspect surrounding code in a single turn without a second read call. `a\|b` is literal text: add `--regex` for alternation (RE2 subset). `-l` prints the matching files once, `-o --unique` prints the distinct matched text (a `--gs-[a-z-]+` token list in one call), paths after the pattern scope it (`--glob <path>` is `--dir`; `--max <N>` is `-n`), dot-directories such as `.github` and `.claude` are searched (only git-ignored paths are left out; `--hidden` adds them), and `chemx q <text>` with no symbol hit runs this search for you. See [docs/search.md](docs/search.md). |
-| `sed -n 'N,Mp' <file>` | `chemx read <file>:N-M --bare` | Verbatim slice matching sed byte-for-byte; 0 header, box or line number tokens. |
+| `sed -n 'N,Mp' <file>` | `chemx read <file>:N-M --bare` (or `--lines a-b`, `--lines=a-b`, `--start=N --end=M`; `--full` for whole file) | Verbatim slice matching sed byte-for-byte; 0 header, box or line number tokens. `--bare` never substitutes an outline on long files. `--full` returns the whole file without truncation. |
 | `git diff` | `chemx d` | Zero-context (`-U0`), auto-collapses to `--stat` if > 80 lines, micro-syncs index. |
 | Editing `docs/CHANGELOG.md` for your change | write `docs/changelog.d/<ticket>.md` (first line `### Fixed`, `### Added` or a title with the ticket id, then bullets); `chemx changelog --check` validates, `chemx changelog` folds the fragments into Unreleased and deletes them | One file per change, so parallel tickets never edit the same lines. Never edit `docs/CHANGELOG.md` directly. See [docs/changelog.d/README.md](docs/changelog.d/README.md). |
 | `git log` | `chemx log -n 5` | One-line commit history (5 commits measured about 140 tokens on 2026-10-09, roughly 28 per commit). |

package/cli/audit/history.js

@@ -198,7 +198,8 @@ export const saveAuditSnapshot = (report, cwd = process.cwd(), scopeInfo = {}) =
   const history = getAuditHistory(cwd);
 
   // Prevent duplicate snapshots if the same scope is saved again within 5 seconds with same metrics
-  const last = history.findLast((s) => scopeKey(s) === scopeKey(snapshot));
+  const targetScope = scopeKey(snapshot);
+  const last = [...history].reverse().find((s) => scopeKey(s) === targetScope);
   if (last) {
     const timeDiff = Math.abs(Date.now() - new Date(last.timestamp).getTime());
     const isSameMetrics = hasMatchingAuditMetrics(last, snapshot);

package/cli/audit/rules-predicates.js

@@ -14,8 +14,9 @@ const COMPONENT_EXTENSIONS = new Set(['.vue', '.tsx', '.jsx']);
 const TEMPLATE_EXTENSIONS = new Set(['.vue', '.html', '.svelte']);
 const COMMENT_PREFIXES = ['//', '*', '/*'];
 const CONSOLE_LOG_METHODS = ['log', 'info', 'warn'];
-const NON_INTERACTIVE_FLAGS = ['--non-interactive', '--no-interactive', '--ci', '--headless', '--yes', '-y'];
-const FORMAT_FLAGS = ['--markdown', '--md', '--json'];
+const NON_INTERACTIVE_FLAGS = ['--non-interactive', '--no-interactive', '--ci', '--headless', '--yes', '-y', '--strict'];
+const FORMAT_FLAGS = ['--markdown', '--md', '--json', '--unroll', '--all'];
+const AGENT_ENV_KEYS = ['CI', 'GIT_DIR', 'ANTIGRAVITY_CSRF_TOKEN', 'ANTIGRAVITY_AGENT', 'CLAUDECODE', 'CLAUDE_CODE', 'CURSOR_TRACE_ID', 'CODEX_SANDBOX', 'AIDER_MODEL'];
 const GRADE_RANKS = { 'A+': 5, 'A': 4, 'B': 3, 'C': 2, 'D': 1, 'F': 0 };
 
 export const isComponentPath = (path) => {
@@ -157,7 +158,7 @@ export const isNonInteractiveSession = (rawArgs, env = process.env) => {
   const hasCliFlag = NON_INTERACTIVE_FLAGS.some((flag) => rawArgs.includes(flag));
   const hasOutputFlag = rawArgs.some((arg) => arg.startsWith('--output=') || arg.startsWith('-o='));
   const hasFormatFlag = FORMAT_FLAGS.some((flag) => rawArgs.includes(flag));
-  const hasCiEnv = Boolean(env.CI || env.GIT_DIR);
+  const hasCiEnv = AGENT_ENV_KEYS.some((key) => Boolean(env[key]));
   const isNotTTY = !isStdoutTty();
   return [hasCliFlag, hasOutputFlag, hasFormatFlag, hasCiEnv, isNotTTY].some(Boolean);
 };

package/cli/commands/unknown-flags.js

@@ -207,8 +207,9 @@ export const findUnknownFlag = (command, rawArgs) => {
       if (isPattern) i++;
       continue;
     }
+    const rangeNote = entry.name === 'read' ? ' Range forms: <file>:N-M, --lines a-b, or --start=N --end=M.' : '';
     const isBadShort = shorts !== null && /^-[A-Za-z](=.*)?$/.test(arg) && !shorts.has(arg.slice(0, 2));
-    if (isBadShort) return `chemx ${entry.name}: unknown flag ${arg.slice(0, 2)}. Run \`chemx ${entry.name} --help\`.`;
+    if (isBadShort) return `chemx ${entry.name}: unknown flag ${arg.slice(0, 2)}.${rangeNote} Run \`chemx ${entry.name} --help\`.`;
     const isLongFlag = arg.startsWith('--') && arg.length > 2;
     if (!isLongFlag) continue;
     const hasInlineValue = arg.includes('=');
@@ -223,8 +224,13 @@ export const findUnknownFlag = (command, rawArgs) => {
     const closest = suggestFlag(name, candidates);
     const isPassedOn = isTypoOnly && !closest;
     if (isPassedOn) continue;
-    const hint = closest ? `; did you mean ${closest}?` : '';
-    return `chemx ${entry.name}: unknown flag ${name}${hint} Run \`chemx ${entry.name} --help\`.`;
+    let hint = '';
+    if (closest) {
+      hint = `; did you mean ${closest}?`;
+    } else if (rangeNote) {
+      hint = '.';
+    }
+    return `chemx ${entry.name}: unknown flag ${name}${hint}${rangeNote} Run \`chemx ${entry.name} --help\`.`;
   }
   return null;
 };

package/cli/commands-schema-search.js

@@ -64,7 +64,7 @@ export const SEARCH_COMMANDS = [
     brief: 'Read a file by outline, symbol or lines',
     usage: 'chemx read <file>|<rev>:<file>[:N-M] [options]',
     summary: 'Token-minified file reader with AST outline and logic extraction.',
-    description: 'Extracts structural outlines, logic skeletons, line ranges, or targeted symbol declarations, from the working tree or (rev:file) at a git revision. A file over the 100-line window reads as an outline; one with nothing to outline (yaml, json, txt, shell) reads as its first 100 lines of text with the next range named.',
+    description: 'Extracts structural outlines, logic skeletons, line ranges, or targeted symbol declarations, from the working tree or (rev:file) at a git revision. A file over the 100-line window reads as an outline; --full returns the whole file; --bare reads text without substituting an outline; range forms are <file>:N-M, --lines a-b, or --start=N --end=M.',
     flags: [
       { flag: '--outline, -o', desc: 'Signatures only' },
       { flag: '--logic, -l', desc: 'AST logic skeleton: control flow, guards and mutations' },
@@ -76,6 +76,8 @@ export const SEARCH_COMMANDS = [
       { flag: '--connections', desc: 'Include caller graph and dependent references alongside symbol' },
       { flag: '--strip-comments', desc: 'Remove all code comments' },
       { flag: '--compact', desc: 'Remove blank lines and indentation' },
+      { flag: '--lines=<range>', desc: 'Line range a-b (alias of :a-b)' },
+      { flag: '--full', desc: 'Read the whole file without truncation' },
       { flag: '--start=<N>', desc: 'Starting line number (1-indexed)' },
       { flag: '--end=<N>', desc: 'Ending line number (1-indexed)' },
       { flag: '--bare, -b', desc: 'Raw content without headers or line numbers' },
@@ -83,6 +85,8 @@ export const SEARCH_COMMANDS = [
     ],
     examples: [
       'chemx read src/store.ts --outline',
+      'chemx read src/store.ts --lines 10-50',
+      'chemx read src/store.ts --full',
       'chemx read HEAD~1:src/store.ts --symbol=save',
       'chemx read src/controller.ts --logic',
       'chemx read api.ts --symbol=login',

package/cli/mcp/tools-read.js

@@ -17,6 +17,20 @@ export const handleChemxRead = (args = {}, cwd = process.cwd()) => {
   let startLine = args.startLine;
   let endLine = args.endLine;
 
+  const hasArgsLines = Boolean(args.lines);
+  const isStartLineMissing = startLine === undefined;
+  const isEndLineMissing = endLine === undefined;
+  const shouldParseLinesArg = hasArgsLines && (isStartLineMissing || isEndLineMissing);
+  if (shouldParseLinesArg) {
+    const linesMatch = String(args.lines).match(/^(\d+)(?:[-:](\d+))?$/);
+    if (linesMatch) {
+      if (isStartLineMissing) startLine = parseInt(linesMatch[1], 10);
+      const hasEndInMatch = Boolean(linesMatch[2]);
+      const shouldSetEnd = isEndLineMissing && hasEndInMatch;
+      if (shouldSetEnd) endLine = parseInt(linesMatch[2], 10);
+    }
+  }
+
   const colonMatch = typeof rawPath === 'string' && rawPath.match(/^([^:]+):(\d+)(?:[-:](\d+))?$/);
   const hasColonRange = Boolean(colonMatch);
   if (hasColonRange) {
@@ -39,7 +53,10 @@ export const handleChemxRead = (args = {}, cwd = process.cwd()) => {
     compact: args.compact === true,
     startLine,
     endLine,
-    rev: args.rev
+    full: args.full === true,
+    bare: Boolean(args.bare),
+    rev: args.rev,
+    hintSyntax: 'mcp'
   });
   const relFile = path.relative(targetCwd, targetPath) || res.file;
   res.file = args.rev ? `${args.rev}:${relFile}` : relFile;
@@ -54,7 +71,7 @@ export const handleChemxRead = (args = {}, cwd = process.cwd()) => {
 
   const isBare = Boolean(args.bare);
   if (isBare) {
-    return res.content;
+    return res.trailer ? `${res.content}\n${res.trailer}` : res.content;
   }
 
   const ext = path.extname(targetPath).toLowerCase();

package/cli/reader-cli.js

@@ -32,15 +32,20 @@ export const runReaderCli = (args, isCli = false) => {
         `  --backtrace=<name>       Reverse caller chain card (uses the .chemx index)`,
         `  --connections            References and blast radius card for the file or --symbol`,
         `  --symbol=<name>          Declaration by AST range (also Class.method, store.action)`,
+        `  --lines=<range>          Line range a-b (alias of :a-b)`,
+        `  --full                   Read the whole file without truncation`,
         `  --start=<N>              Start line number (1-indexed)`,
         `  --end=<N>                End line number (1-indexed)`,
         `  --strip-comments         Blank out comments (token based; line numbers stay true)`,
         `  --compact                Drop repeated blank lines (original numbers still shown)`,
+        `  --bare, -b               Raw content without headers or line numbers`,
         `  --json                   Output result as minified JSON`,
         `  -h, --help               Show this help message`,
         '',
         `${ANSI.BOLD}EXAMPLES${ANSI.RESET}`,
         `  chemx read src/store.ts --outline`,
+        `  chemx read src/store.ts --lines 10-50`,
+        `  chemx read src/store.ts --full`,
         `  chemx read src/controller.ts --outline --enrich`,
         `  chemx read src/card.vue --outline --enrich --trace=handleSubmit`,
         `  chemx read src/controller.ts --logic`,
@@ -52,7 +57,20 @@ export const runReaderCli = (args, isCli = false) => {
     return { help: true, success: true };
   }
 
-  const nonFlagArgs = args.filter((a) => !a.startsWith('-'));
+  const skipIndices = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const isValFlag = a === '-s' || a === '--symbol' || a === '--lines';
+    const nextArg = args[i + 1];
+    const hasNextNonFlag = Boolean(nextArg) && !nextArg.startsWith('-');
+    const shouldSkipNext = isValFlag && hasNextNonFlag;
+    if (shouldSkipNext) {
+      skipIndices.add(i + 1);
+    }
+  }
+
+  const isNonFlagCandidate = (a, idx) => !a.startsWith('-') && !skipIndices.has(idx);
+  const nonFlagArgs = args.filter(isNonFlagCandidate);
   let filePath = nonFlagArgs[0];
 
   if (!filePath) {
@@ -64,16 +82,46 @@ export const runReaderCli = (args, isCli = false) => {
   let startLine;
   let endLine;
 
+  let linesRange = null;
+  const linesEq = args.find((a) => a.startsWith('--lines='));
+  if (linesEq) {
+    linesRange = linesEq.slice('--lines='.length);
+  } else {
+    const linesIdx = args.findIndex((a) => a === '--lines');
+    const nextToken = linesIdx === -1 ? undefined : args[linesIdx + 1];
+    const hasSpacedLines = Boolean(nextToken) && !nextToken.startsWith('-');
+    if (hasSpacedLines) {
+      linesRange = nextToken;
+    }
+  }
+
+  const hasLinesRange = Boolean(linesRange);
+  if (hasLinesRange) {
+    const rangeMatch = linesRange.match(/^(\d+)(?:[-:](\d+))?$/);
+    if (rangeMatch) {
+      const isStartLineMissing = startLine === undefined;
+      if (isStartLineMissing) startLine = parseInt(rangeMatch[1], 10);
+      const hasEndInMatch = Boolean(rangeMatch[2]);
+      const isEndLineMissing = endLine === undefined;
+      const shouldSetEnd = isEndLineMissing && hasEndInMatch;
+      if (shouldSetEnd) endLine = parseInt(rangeMatch[2], 10);
+    }
+  }
+
   const colonMatch = filePath.match(/^([^:]+):(\d+)(?:[-:](\d+))?$/);
   if (colonMatch) {
     filePath = colonMatch[1];
-    startLine = parseInt(colonMatch[2], 10);
+    const isStartLineMissing = startLine === undefined;
+    if (isStartLineMissing) startLine = parseInt(colonMatch[2], 10);
     const hasEndLineSuffix = Boolean(colonMatch[3]);
-    if (hasEndLineSuffix) endLine = parseInt(colonMatch[3], 10);
+    const isEndLineMissing = endLine === undefined;
+    const shouldSetEnd = hasEndLineSuffix && isEndLineMissing;
+    if (shouldSetEnd) endLine = parseInt(colonMatch[3], 10);
   }
 
   const isJson = args.includes('--json') || args.includes('-j');
   const isBare = args.includes('--bare') || args.includes('-b');
+  const isFull = args.includes('--full');
   const isOutline = args.includes('--outline') || args.includes('-o');
   const isLogic = args.includes('--logic') || args.includes('-l');
   const isTemplate = args.includes('--template') || args.includes('-t');
@@ -137,6 +185,8 @@ export const runReaderCli = (args, isCli = false) => {
       symbol,
       startLine,
       endLine,
+      full: isFull,
+      bare: isBare,
       hintSyntax: 'cli',
     });
 
@@ -152,7 +202,8 @@ export const runReaderCli = (args, isCli = false) => {
     if (isJson) {
       process.stdout.write(JSON.stringify(res, null, 2) + '\n');
     } else if (isBare) {
-      process.stdout.write((res.content || '') + '\n');
+      const output = res.trailer ? `${res.content || ''}\n${res.trailer}` : (res.content || '');
+      process.stdout.write(output + '\n');
     } else {
       const hasConflict = Boolean(res.conflict);
       if (hasConflict) process.stdout.write(`${ANSI.GOLD}⚠ ${res.conflict}${ANSI.RESET}\n`);

package/cli/reader-format.js

@@ -3,7 +3,7 @@
  * content, and a header that states where the slice sits in the file.
  */
 
-const VERBATIM_MODES = new Set(['range', 'symbol', 'template']);
+const VERBATIM_MODES = new Set(['range', 'symbol', 'template', 'full']);
 
 export const isVerbatimMode = (mode) => VERBATIM_MODES.has(mode);
 

package/cli/reader.js

@@ -222,6 +222,21 @@ export const readTokenOptimized = (targetPath, options = {}) => {
   let startLine = options.startLine;
   let endLine = options.endLine;
 
+  const hasOptionsLines = Boolean(options.lines);
+  const isStartLineMissing = startLine === undefined;
+  const isEndLineMissing = endLine === undefined;
+  const shouldParseOptionsLines = hasOptionsLines && (isStartLineMissing || isEndLineMissing);
+  if (shouldParseOptionsLines) {
+    const linesMatch = String(options.lines).match(/^(\d+)(?:[-:](\d+))?$/);
+    if (linesMatch) {
+      const needsStart = startLine === undefined;
+      if (needsStart) startLine = parseInt(linesMatch[1], 10);
+      const hasEndMatch = Boolean(linesMatch[2]);
+      const needsEnd = endLine === undefined && hasEndMatch;
+      if (needsEnd) endLine = parseInt(linesMatch[2], 10);
+    }
+  }
+
   const colonMatch = typeof targetPath === 'string' && targetPath.match(/^([^:]+):(\d+)(?:[-:](\d+))?$/);
   if (colonMatch) {
     rawPath = colonMatch[1];
@@ -326,12 +341,15 @@ export const readTokenOptimized = (targetPath, options = {}) => {
 
   const hasLineRange = typeof startLine === 'number' || typeof endLine === 'number';
   const autoThreshold = typeof options.autoOutlineThreshold === 'number' ? options.autoOutlineThreshold : 100;
+  const isFull = Boolean(options.full);
+  const isBare = Boolean(options.bare);
 
   // Read window: files longer than autoThreshold read without a symbol or slice return an AST
   // outline to protect context. A tool budget, not an architecture rule (AGENTS.md owns those).
   // A file with no outline to give (yaml, json, txt) falls through to the first window of text.
+  // --full and --bare (without explicit --outline) never substitute an outline.
   const isOverWindow = !hasLineRange && totalLines > autoThreshold;
-  const canAutoOutline = isOverWindow && !conflictNote && hasOutlineExtractor(rawPath);
+  const canAutoOutline = isOverWindow && !conflictNote && !isFull && (!isBare || wantsOutline) && hasOutlineExtractor(rawPath);
   const autoOutline = canAutoOutline ? generateAstOutline(rawContent, rawPath) : '';
   const shouldAutoOutline = !isEmptyOutline(autoOutline);
   if (shouldAutoOutline) {
@@ -374,7 +392,7 @@ export const readTokenOptimized = (targetPath, options = {}) => {
 
   // Cap each slice to the read window (a tool budget, not an architecture rule)
   const maxLines = autoThreshold;
-  const isCapped = (endIdx - startIdx) > maxLines;
+  const isCapped = !isFull && (endIdx - startIdx) > maxLines;
   if (isCapped) {
     endIdx = startIdx + maxLines;
   }
@@ -382,19 +400,21 @@ export const readTokenOptimized = (targetPath, options = {}) => {
   const slice = sliceWithTransforms(rawContent, resolvedPath, startIdx, endIdx, options);
   const isCliHint = options.hintSyntax === 'cli';
   const nextEnd = Math.min(totalLines, endIdx + maxLines);
+  const remaining = totalLines - endIdx;
   const formatTruncationHint = () => {
     if (!isCapped) return null;
+    const remainMsg = `${remaining} ${remaining === 1 ? 'line remains' : 'lines remain'}`;
     if (isCliHint) {
-      return `// [Truncated at the ${maxLines}-line chemx read window. Use chemx read ${rawPath}:${endIdx + 1}-${nextEnd} to inspect subsequent lines]`;
+      return `// [Truncated at the ${maxLines}-line chemx read window. ${remainMsg}; use chemx read ${rawPath}:${endIdx + 1}-${nextEnd} to inspect subsequent lines]`;
     }
-    return `// [Truncated at the ${maxLines}-line chemx read window. Use startLine=${endIdx + 1} to inspect subsequent lines]`;
+    return `// [Truncated at the ${maxLines}-line chemx read window. ${remainMsg}; use startLine=${endIdx + 1} to inspect subsequent lines]`;
   };
   const trailer = formatTruncationHint();
 
   return {
     file: rawPath,
     totalLines,
-    mode: 'range',
+    mode: isFull ? 'full' : 'range',
     startLine: startIdx + 1,
     endLine: endIdx,
     lineCount: slice.lines.length,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chemx/starter-kit",
-  "version": "26.10.26-386",
+  "version": "26.10.29-360",
   "description": "Chemical X Protocol: Private drop-in architecture starter kit and capsule generator",
   "type": "module",
   "bin": {