td-ai-tools 1.3.2 → 1.3.4

package/bin/cli.js

@@ -4,6 +4,7 @@
  * command dispatch. All filesystem work lives in `../lib/`.
  */
 import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
@@ -14,6 +15,7 @@ import { readFrontmatterField } from '../lib/frontmatter.js';
 import {
   installSkill, installAgent, deleteSkill, deleteAgent, skillHasSetup,
 } from '../lib/installer.js';
+import { createGutterWriter } from '../lib/gutter.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -32,6 +34,14 @@ const { skillsDir: SKILLS_DIR, agentsDir: AGENTS_DIR } = ctx;
 
 const IS_TTY = Boolean(process.stdout.isTTY && process.stdin.isTTY);
 
+/** Matches `@clack/prompts`' own unicode fallback so gutters line up everywhere. */
+const IS_UNICODE = process.platform !== 'win32'
+  || Boolean(process.env.WT_SESSION)
+  || process.env.TERM_PROGRAM === 'vscode';
+
+/** The vertical gutter `@clack/prompts` draws between log lines. */
+const BAR = IS_UNICODE ? '│' : '|';
+
 /**
  * @typedef {import('../lib/catalog.js').ItemType} ItemType
  * @typedef {import('../lib/catalog.js').Ctx} Ctx
@@ -66,6 +76,43 @@ function status(kind, msg) {
   }
 }
 
+/**
+ * Runs a skill setup command. Under a TTY the child's output is streamed through
+ * a gutter writer so multi-stage setups (npm installs, package builds) stay
+ * inside the CLI's log flow, with stderr folded into the same stream; elsewhere
+ * stdio is inherited unchanged so logs and CI see the raw output.
+ *
+ * @type {import('../lib/installer.js').SetupRunner}
+ */
+function runSetupCommand({ command, args, cwd }) {
+  if (!IS_TTY) {
+    const result = spawnSync(command, args, { cwd, stdio: 'inherit', shell: false });
+    return Promise.resolve({ status: result.status, error: result.error });
+  }
+
+  return new Promise(resolve => {
+    // One writer for both streams: a shared line buffer keeps stdout and stderr
+    // in the order the child produced them and stops half-written lines from
+    // interleaving through the gutter.
+    const log = createGutterWriter({ stream: process.stdout, bar: BAR });
+    const child = spawn(command, args, {
+      cwd,
+      stdio: ['inherit', 'pipe', 'pipe'],
+      shell: false,
+    });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', chunk => log.write(chunk, 'stdout'));
+    child.stderr.on('data', chunk => log.write(chunk, 'stderr'));
+    const finish = result => {
+      log.end();
+      resolve(result);
+    };
+    child.on('error', error => finish({ status: null, error }));
+    child.on('close', status => finish({ status }));
+  });
+}
+
 /**
  * Display string for an installed item's version state, e.g.
  * `"v1.0.0 → v1.2.0  ⬆ outdated"` or `"v1.2.0 (up to date)"`.
@@ -139,14 +186,16 @@ function hintFor(type, name) {
  *
  * @param {MenuItem[]} items - Items to install.
  * @param {{replaceExisting?: boolean}} [options] - Forwarded to the installer.
- * @returns {boolean} Whether every installer reported success.
+ * @returns {Promise<boolean>} Whether every installer reported success.
  */
-function installItems(items, options = {}) {
+async function installItems(items, options = {}) {
   const { runSetup = false, ...installOptions } = options;
   let ok = true;
   for (const item of items) {
     const installed = item.type === 'skill'
-      ? installSkill(ctx, item.name, { ...installOptions, runSetup, report: status })
+      ? await installSkill(ctx, item.name, {
+        ...installOptions, runSetup, runner: runSetupCommand, report: status,
+      })
       : installAgent(ctx, item.name, { ...installOptions, report: status });
     if (!installed) ok = false;
   }
@@ -447,7 +496,7 @@ async function interactiveInstall(mode = 'install') {
   }
 
   const runSetup = await confirmSetup(items);
-  const ok = installItems(items, { replaceExisting: mode === 'update', runSetup });
+  const ok = await installItems(items, { replaceExisting: mode === 'update', runSetup });
   if (!ok) {
     p.outro(pc.red(`${mode === 'update' ? 'Update' : 'Install'} completed with errors.`));
     process.exitCode = 1;
@@ -644,9 +693,9 @@ async function main() {
   if (cmd === 'install') {
     const { rest, runSetup } = parseInstallFlags(args.slice(1));
     if (rest[0] === '--all') {
-      if (!installItems(buildMenu(), { runSetup })) process.exitCode = 1;
+      if (!await installItems(buildMenu(), { runSetup })) process.exitCode = 1;
     } else {
-      if (!installItems(resolveNames(rest), { runSetup })) process.exitCode = 1;
+      if (!await installItems(resolveNames(rest), { runSetup })) process.exitCode = 1;
     }
     return;
   }
@@ -663,9 +712,11 @@ async function main() {
         status('info', 'No installed skills or agent packs match the catalog.');
         return;
       }
-      if (!installItems(menu, { replaceExisting: true, runSetup })) process.exitCode = 1;
+      if (!await installItems(menu, { replaceExisting: true, runSetup })) process.exitCode = 1;
     } else {
-      if (!installItems(resolveUpdateNames(rest), { replaceExisting: true, runSetup })) process.exitCode = 1;
+      if (!await installItems(resolveUpdateNames(rest), { replaceExisting: true, runSetup })) {
+        process.exitCode = 1;
+      }
     }
     return;
   }

package/lib/gutter.js

@@ -0,0 +1,89 @@
+/**
+ * @file Renders streamed child-process output inside the `@clack/prompts` log
+ * gutter.
+ *
+ * Setup scripts (npm installs, package builds) emit long, unindented output that
+ * otherwise interrupts the CLI's vertical bar flow. This module reframes that
+ * output as subordinate detail: every line is prefixed with the gutter bar,
+ * dimmed, wrapped so long paths cannot escape the gutter, and runs of blank
+ * lines collapse to a single bar.
+ */
+import pc from 'picocolors';
+
+/** Matches ANSI escape sequences, which would fight the dim styling. */
+const ANSI = /\u001B\[[0-9;?]*[ -\/]*[@-~]/g;
+
+/**
+ * Wraps a line to a width, preferring a space break and hard-wrapping otherwise.
+ *
+ * @param {string} text - Single line of text (no newlines).
+ * @param {number} width - Maximum characters per returned line.
+ * @returns {string[]} One or more lines, none longer than `width`.
+ */
+export function wrapLine(text, width) {
+  const lines = [];
+  let rest = text;
+  while (rest.length > width) {
+    const space = rest.lastIndexOf(' ', width);
+    const cut = space > width / 2 ? space : width;
+    lines.push(rest.slice(0, cut).trimEnd());
+    rest = rest.slice(cut).trimStart();
+  }
+  lines.push(rest);
+  return lines;
+}
+
+/**
+ * Creates a line-buffered writer that emits guttered output.
+ *
+ * @param {object} options
+ * @param {import('node:stream').Writable} options.stream - Destination stream.
+ * @param {string} options.bar - The gutter character (`'│'`, or `'|'` without unicode).
+ * @param {() => number} [options.columns] - Current terminal width; read per line so a mid-run resize is respected.
+ * @returns {{write: (chunk: string, channel?: string) => void, end: () => void}} `write` takes arbitrary chunks tagged with an optional source channel (so a partial line from one stream never absorbs the next line of another); `end` flushes a trailing partial line.
+ */
+export function createGutterWriter({ stream, bar, columns = () => process.stdout.columns || 80 }) {
+  const gutter = pc.gray(bar);
+  let pending = '';
+  let blank = false;
+  let lastChannel = '';
+
+  const emit = raw => {
+    // Keep only the last carriage-return segment so redrawn progress lines
+    // (npm, tsc) land as one line rather than stacking up.
+    const carriage = raw.lastIndexOf('\r');
+    const line = (carriage === -1 ? raw : raw.slice(carriage + 1))
+      .replace(ANSI, '')
+      .replace(/\s+$/, '');
+
+    if (!line) {
+      if (!blank) stream.write(`${gutter}\n`);
+      blank = true;
+      return;
+    }
+    blank = false;
+
+    const width = Math.max(24, columns() - 6);
+    const [first, ...continued] = wrapLine(line, width);
+    stream.write(`${gutter}  ${pc.dim(first)}\n`);
+    for (const cont of continued) stream.write(`${gutter}    ${pc.dim(cont)}\n`);
+  };
+
+  return {
+    write(chunk, channel = '') {
+      if (channel !== lastChannel && pending) {
+        emit(pending);
+        pending = '';
+      }
+      lastChannel = channel;
+      pending += chunk;
+      const parts = pending.split('\n');
+      pending = parts.pop() ?? '';
+      for (const part of parts) emit(part);
+    },
+    end() {
+      if (pending) emit(pending);
+      pending = '';
+    },
+  };
+}

package/lib/installer.js

@@ -30,6 +30,21 @@ import {
 /** @type {ReportFn} */
 const noop = () => {};
 
+/**
+ * Runs a skill's setup command and resolves with its exit result. The CLI passes
+ * a presentation-aware runner that keeps child output inside its log gutter;
+ * the default simply inherits this process's stdio.
+ * @callback SetupRunner
+ * @param {{command: string, args: string[], cwd: string}} spec - Command to run and the directory to run it in.
+ * @returns {Promise<{status: (number|null), error?: Error}>} Exit status, or a spawn `error`.
+ */
+
+/** @type {SetupRunner} */
+const inheritStdioRunner = async ({ command, args, cwd }) => {
+  const result = spawnSync(command, args, { cwd, stdio: 'inherit', shell: false });
+  return { status: result.status, error: result.error };
+};
+
 /**
  * Recognized setup commands, in priority order, relative to an installed skill.
  * @type {{file: string, command: string, args: string[]}[]}
@@ -83,16 +98,17 @@ export function skillHasSetup(ctx, name) {
  * @param {string} dest - Installed skill directory.
  * @param {string} projectRoot - Root of the project receiving the skill.
  * @param {ReportFn} report
- * @returns {boolean} Whether setup succeeded or no setup existed.
+ * @param {SetupRunner} runner - Executes the setup command.
+ * @returns {Promise<boolean>} Whether setup succeeded or no setup existed.
  */
-function runSkillSetup(name, target, dest, projectRoot, report) {
+async function runSkillSetup(name, target, dest, projectRoot, report, runner) {
   const setup = findSkillSetup(dest);
   if (setup) {
     report('step', `setup: ${name} running ${setup.command} ${setup.args.join(' ')} in ${target.root}/skills/${name}/`);
-    const result = spawnSync(setup.command, setup.args, {
+    const result = await runner({
+      command: setup.command,
+      args: setup.args,
       cwd: dest,
-      stdio: 'inherit',
-      shell: false,
     });
     if (result.error) {
       report('error', `setup: ${name} failed in ${target.root}/skills/${name}/: ${result.error.message}`);
@@ -144,10 +160,16 @@ function registerBundledAgents(ctx, target, srcDir, report) {
  * @param {object} [options]
  * @param {boolean} [options.replaceExisting=false] - Overwrite an existing install (used by `update`).
  * @param {boolean} [options.runSetup=false] - Run recognized setup scripts after each target copy.
+ * @param {SetupRunner} [options.runner] - Executes setup commands; defaults to inheriting stdio.
  * @param {ReportFn} [options.report] - Progress sink.
- * @returns {boolean} `false` if the skill is not in the catalog or setup fails, otherwise `true`.
+ * @returns {Promise<boolean>} `false` if the skill is not in the catalog or setup fails, otherwise `true`.
  */
-export function installSkill(ctx, name, { replaceExisting = false, runSetup = false, report = noop } = {}) {
+export async function installSkill(ctx, name, {
+  replaceExisting = false,
+  runSetup = false,
+  runner = inheritStdioRunner,
+  report = noop,
+} = {}) {
   let ok = true;
   const src = path.join(ctx.skillsDir, name);
   if (!fs.existsSync(src)) {
@@ -164,7 +186,7 @@ export function installSkill(ctx, name, { replaceExisting = false, runSetup = fa
     copyDir(src, dest);
     report('success', `skill: ${name} ${replaceExisting ? 'updated' : 'installed'} → ${target.root}/skills/${name}/`);
     registerBundledAgents(ctx, target, src, report);
-    if (runSetup && !runSkillSetup(name, target, dest, ctx.targetRoot, report)) ok = false;
+    if (runSetup && !(await runSkillSetup(name, target, dest, ctx.targetRoot, report, runner))) ok = false;
   }
   return ok;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

package/skills/shopify-lint/SKILL.md

@@ -40,7 +40,7 @@ python3 .agents/skills/shopify-lint/scripts/shopify_lint.py --path .
 
 The script identifies files changed since the current branch's merge-base, adds staged, unstaged, and untracked files, then runs three linters over that set and merges their results into one report:
 
-- **Theme Check** — `shopify theme check --output json`. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory. `DisallowedScriptOrStyleTag` reports inline executable `<script>` and all `<style>` tags in modified Liquid files while allowing external-source and JSON-data scripts. `HardcodedText` reports rendered hard-coded copy, except content inside Liquid `stylesheet`, `javascript`, and `schema` tags. The generated `.theme-check.yml` also pins the upstream `StaticStylesheetAndJavascriptTags` to `error`, so Liquid written inside a `{% stylesheet %}` or `{% javascript %}` block always fails the lint.
+- **Theme Check** — `shopify theme check --output json`. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory. `DisallowedScriptOrStyleTag` reports inline executable `<script>` and all `<style>` tags in modified Liquid files while allowing external-source and JSON-data scripts. `HardcodedText` reports rendered hard-coded copy, except content inside Liquid `stylesheet`, `javascript`, and `schema` tags, and except text beginning with `--`, which is a CSS custom property name rather than copy. The generated `.theme-check.yml` also pins the upstream `StaticStylesheetAndJavascriptTags` to `error`, so Liquid written inside a `{% stylesheet %}` or `{% javascript %}` block always fails the lint.
 - **JavaScript** — ESLint's recommended rules plus the bundled `eslint-plugin-theory`, over modified `.js` and `.mjs` files *and* the JavaScript inside `{% javascript %}` blocks of modified `.liquid` files.
 - **CSS** — `stylelint-config-standard` through the bundled `stylelint-config-theory`, over modified `.css` files *and* the CSS inside `{% stylesheet %}` blocks of modified `.liquid` files.
 
@@ -48,7 +48,7 @@ Standalone JavaScript and CSS are linted only when the **filename** contains `td
 
 The filter does **not** apply to Liquid: `{% javascript %}` and `{% stylesheet %}` blocks are linted in every modified `.liquid` file regardless of its name, because that code is Theory's either way. A `{% stylesheet 'scss' %}` block is skipped, because its body is Sass rather than CSS, as is any block commented out with `{% comment %}` or `{% raw %}`.
 
-Offenses in a Liquid block are reported at their real line and column in the `.liquid` file. Check codes say where they came from: `PascalCase` is Theme Check, `theory/…` is a Theory JavaScript rule, `eslint/…` is an upstream ESLint rule, `stylelint/…` is an upstream Stylelint rule.
+Offenses in a Liquid block are reported at their real line and column in the `.liquid` file. Positions are one-indexed in both the JSON and the text report, matching the `file:line:column` convention editors and compilers use — Theme Check's LSP-style zero-indexed rows and columns are rebased on the way in, and ESLint's and Stylelint's pass through as reported. Check codes say where they came from: `PascalCase` is Theme Check, `theory/…` is a Theory JavaScript rule, `eslint/…` is an upstream ESLint rule, `stylelint/…` is an upstream Stylelint rule.
 
 `theory/guarded-custom-element-define` and `theory/no-unapproved-imports` are errors, as are genuine ESLint correctness failures; the convention rules (`theory/disconnected-callback-cleanup`, `theory/no-class-selectors`, `theory/centralize-selectors`, `theory/require-jsdoc`) are warnings. `theory/require-jsdoc` requires named classes and functions to have JSDoc comments, including typed `@param` and `@returns` tags. The severity distinction only affects `--fail-level`: the Stop hooks run at `--fail-level warning`, so warnings block handoff too. See `eslint-plugin-theory/README.md` for every rule and its blind spots.
 

package/skills/shopify-lint/eslint-plugin-theory/package-lock.json

@@ -1297,9 +1297,9 @@
       "license": "MIT"
     },
     "node_modules/brace-expansion": {
-      "version": "1.1.17",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.17.tgz",
-      "integrity": "sha512-w+aeW/mkgM4PyRMOJCgi3fOrTm5Q8QY1OSfn2TO2iuDj3ezIHqejmuxbjfPrqUkgqRew1iqkyAn0tr0ZwHD9+w==",
+      "version": "1.1.18",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
+      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0",

package/skills/shopify-lint/eslint-plugin-theory/src/liquid/mask.test.ts

@@ -199,6 +199,42 @@ describe('maskLiquid', () => {
     expect(maskLiquid(source)).toBeNull();
   });
 
+  it('skips a block inside a doc tag', () => {
+    // An `@example` shows the block a snippet expects its caller to provide; it
+    // is documentation, not code the storefront runs.
+    const source = [
+      '{% doc %}',
+      '  @example',
+      '  {% javascript %}',
+      '  run();',
+      '  {% endjavascript %}',
+      '{% enddoc %}',
+      '',
+    ].join('\n');
+    expect(maskLiquid(source)).toBeNull();
+  });
+
+  it('still lints a live block alongside a documented one', () => {
+    const masked =
+      maskLiquid(
+        [
+          '{% doc %}',
+          '  @example',
+          '  {% javascript %}',
+          '  example();',
+          '  {% endjavascript %}',
+          '{% enddoc %}',
+          '{% javascript %}',
+          'live();',
+          '{% endjavascript %}',
+          '',
+        ].join('\n'),
+      ) ?? '';
+
+    expect(masked).toContain('live();');
+    expect(masked).not.toContain('example();');
+  });
+
   it('still lints a live block alongside a commented-out one', () => {
     const masked =
       maskLiquid(

package/skills/shopify-lint/eslint-plugin-theory/src/liquid/mask.ts

@@ -19,8 +19,14 @@
 /** Matches a `{% javascript %}` … `{% endjavascript %}` pair, capturing the body. */
 const JAVASCRIPT_BLOCK = /(\{%-?\s*javascript\s*-?%\})([\s\S]*?)(\{%-?\s*endjavascript\s*-?%\})/g;
 
-/** Liquid tags whose bodies are not Liquid and must be masked wholesale. */
-const RAW_CONTENT_TAG = /\{%-?\s*(comment|raw)\s*-?%\}[\s\S]*?\{%-?\s*end\1\s*-?%\}/g;
+/**
+ * Liquid tags whose bodies are not Liquid and must be masked wholesale.
+ *
+ * `{% doc %}` is included because a documented snippet's `@example` routinely
+ * shows the very `{% javascript %}` block the snippet expects — sample code
+ * that is never executed and must not be linted.
+ */
+const RAW_CONTENT_TAG = /\{%-?\s*(comment|doc|raw)\s*-?%\}[\s\S]*?\{%-?\s*end\1\s*-?%\}/g;
 
 /** A Liquid output tag, e.g. `{{ section.settings.foo | json }}`. */
 const OUTPUT_TAG = /\{\{[\s\S]*?\}\}/g;
@@ -74,7 +80,7 @@ function contains(intervals: Interval[], offset: number): boolean {
   return intervals.some((interval) => offset >= interval.start && offset < interval.end);
 }
 
-/** Every `{% comment %}` / `{% raw %}` region in the source, in order. */
+/** Every raw-content region in the source, in order. */
 function rawContentRegions(source: string): Interval[] {
   return [...source.matchAll(RAW_CONTENT_TAG)].map((match) => ({
     start: match.index,
@@ -85,8 +91,8 @@ function rawContentRegions(source: string): Interval[] {
 /**
  * Mask the Liquid constructs inside one `{% javascript %}` body, in place.
  *
- * Order matters: `{% comment %}` and `{% raw %}` bodies are masked first so
- * that Liquid-looking text inside them is not substituted a second time.
+ * Order matters: raw-content bodies are masked first so that Liquid-looking
+ * text inside them is not substituted a second time.
  */
 function maskLiquidInBody(source: string, out: string[], start: number, end: number): void {
   const body = source.slice(start, end);
@@ -134,9 +140,10 @@ function maskLiquidInBody(source: string, out: string[], start: number, end: num
  *
  * Returns `null` when the file contains no complete `{% javascript %}` block
  * that is live code, which lets the processor skip the file entirely. A block
- * that sits inside a `{% comment %}` or `{% raw %}` region does not count:
- * commented-out blocks are common mid-migration, and linting one would report
- * offenses in code the storefront never runs.
+ * that sits inside a `{% comment %}`, `{% doc %}`, or `{% raw %}` region does
+ * not count: commented-out blocks are common mid-migration and documented ones
+ * are illustrations, so linting either would report offenses in code the
+ * storefront never runs.
  */
 export function maskLiquid(source: string): string | null {
   // Indexed per UTF-16 code unit, not per code point, so that offsets stay
@@ -151,7 +158,7 @@ export function maskLiquid(source: string): string | null {
 
   for (const match of source.matchAll(JAVASCRIPT_BLOCK)) {
     if (contains(rawRegions, match.index)) {
-      // A commented-out or raw-quoted block is not live JavaScript.
+      // A commented-out, documented, or raw-quoted block is not live JavaScript.
       continue;
     }
     found = true;

package/skills/shopify-lint/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +1 @@
-{"version":"4.1.10","results":[[":eslint-plugin-theory/src/rules/guarded-custom-element-define.test.ts",{"duration":0,"failed":true}]]}
+{"version":"4.1.10","results":[[":eslint-plugin-theory/src/rules/guarded-custom-element-define.test.ts",{"duration":0,"failed":true}],[":stylelint-config-theory/src/liquid/mask.test.ts",{"duration":21.486761,"failed":false}],[":theme-check-theory/src/checks/hardcoded-text.test.ts",{"duration":79.642067,"failed":false}],[":stylelint-config-theory/src/integration.test.ts",{"duration":322.234405,"failed":false}],[":theme-check-theory/src/checks/unguarded-nullable-setting.test.ts",{"duration":126.54217099999994,"failed":false}],[":eslint-plugin-theory/src/rules/disconnected-callback-cleanup.test.ts",{"duration":0,"failed":true}],[":eslint-plugin-theory/src/integration.test.ts",{"duration":207.055841,"failed":false}],[":eslint-plugin-theory/src/liquid/mask.test.ts",{"duration":31.769655,"failed":false}],[":stylelint-config-theory/src/config.test.ts",{"duration":13.856021999999996,"failed":false}],[":theme-check-theory/src/checks/unused-section-settings.test.ts",{"duration":63.80623400000002,"failed":false}],[":theme-check-theory/src/checks/unguarded-metaobject.test.ts",{"duration":34.325909000000024,"failed":false}],[":eslint-plugin-theory/src/index.test.ts",{"duration":6.773288999999977,"failed":false}],[":theme-check-theory/src/checks/disallowed-script-or-style-tag.test.ts",{"duration":32.848730000000046,"failed":false}],[":theme-check-theory/src/checks/unguarded-metafield.test.ts",{"duration":37.897699999999986,"failed":false}],[":eslint-plugin-theory/src/rules/no-class-selectors.test.ts",{"duration":0,"failed":true}],[":eslint-plugin-theory/src/rules/no-unapproved-imports.test.ts",{"duration":0,"failed":true}],[":eslint-plugin-theory/src/rules/require-jsdoc.test.ts",{"duration":87.66796799999997,"failed":false}],[":eslint-plugin-theory/src/rules/centralize-selectors.test.ts",{"duration":0,"failed":true}],[":stylelint-config-theory/src/build.test.ts",{"duration":903.9329710000001,"failed":false}],[":theme-check-theory/src/index.test.ts",{"duration":2.380390000000034,"failed":false}],[":eslint-plugin-theory/src/processors/liquid.test.ts",{"duration":6.720345000000009,"failed":false}],[":eslint-plugin-theory/src/build.test.ts",{"duration":965.007413,"failed":false}]]}

package/skills/shopify-lint/scripts/shopify_lint.py

@@ -41,9 +41,21 @@ STYLELINT_SEVERITIES = ("error", "warning")
 STYLELINT_PARSE_ERROR_RULE = "CssSyntaxError"
 
 # Theme Check reports LSP-style zero-indexed positions; ESLint and Stylelint are
-# both one-indexed.
+# both one-indexed. Positions are reported one-indexed throughout — the
+# `file:line:column` convention every editor and compiler uses — so Theme
+# Check's rows and columns are each shifted up by one and the other two runners'
+# pass through untouched.
 LINE_BASE_OFFSET = 1
 
+# Position fields carried on a Theme Check offense, rebased together so a single
+# offense never mixes indexing bases.
+THEME_CHECK_POSITION_KEYS = (
+    "start_row",
+    "start_column",
+    "end_row",
+    "end_column",
+)
+
 
 class ShopifyLintError(RuntimeError):
     """Raised when Git or Shopify CLI cannot produce filterable results."""
@@ -169,7 +181,26 @@ def run_theme_check(
 
     if not isinstance(reports, list):
         raise ShopifyLintError("Shopify Theme Check returned an unexpected JSON shape.")
-    return reports
+    return normalize_theme_check_reports(reports)
+
+
+def normalize_theme_check_reports(
+    reports: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Rebase Theme Check's zero-indexed positions onto the report's one-indexed ones."""
+    normalized = []
+    for report in reports:
+        offenses = []
+        for offense in report.get("offenses", []):
+            item = dict(offense)
+            for key in THEME_CHECK_POSITION_KEYS:
+                if key in item:
+                    item[key] = int(item[key]) + LINE_BASE_OFFSET
+            offenses.append(item)
+        entry = dict(report)
+        entry["offenses"] = offenses
+        normalized.append(entry)
+    return normalized
 
 
 def resolve_lint_target(
@@ -373,9 +404,9 @@ def normalize_stylelint_results(results: list[dict[str, Any]]) -> list[dict[str,
                     "check": stylelint_check_code(warning),
                     "severity": stylelint_severity(warning),
                     "message": str(warning.get("text", "")),
-                    "start_row": max(int(warning.get("line", 1)) - LINE_BASE_OFFSET, 0),
+                    "start_row": max(int(warning.get("line", 1)), LINE_BASE_OFFSET),
                     "start_column": max(
-                        int(warning.get("column", 1)) - LINE_BASE_OFFSET, 0
+                        int(warning.get("column", 1)), LINE_BASE_OFFSET
                     ),
                 }
             )
@@ -420,9 +451,9 @@ def normalize_eslint_results(results: list[dict[str, Any]]) -> list[dict[str, An
                     "check": eslint_check_code(message),
                     "severity": eslint_severity(message),
                     "message": str(message.get("message", "")),
-                    "start_row": max(int(message.get("line", 1)) - LINE_BASE_OFFSET, 0),
+                    "start_row": max(int(message.get("line", 1)), LINE_BASE_OFFSET),
                     "start_column": max(
-                        int(message.get("column", 1)) - LINE_BASE_OFFSET, 0
+                        int(message.get("column", 1)), LINE_BASE_OFFSET
                     ),
                 }
             )
@@ -510,8 +541,8 @@ def render_text(reports: list[dict[str, Any]], repo_root: Path) -> str:
             offense_count += 1
             severity = str(offense.get("severity", "unknown")).upper()
             check = offense.get("check", "UnknownCheck")
-            row = offense.get("start_row", 0)
-            column = offense.get("start_column", 0)
+            row = offense.get("start_row", LINE_BASE_OFFSET)
+            column = offense.get("start_column", LINE_BASE_OFFSET)
             message = offense.get("message", "")
             lines.append(f"  {severity} {check} {row}:{column} {message}".rstrip())
         lines.append("")

package/skills/shopify-lint/stylelint-config-theory/src/liquid/mask.test.ts

@@ -251,6 +251,45 @@ describe('maskLiquidStylesheet', () => {
     ).toBeNull();
   });
 
+  it('skips a block inside a doc tag', () => {
+    // An `@example` shows the block a snippet expects its caller to provide; it
+    // is documentation, not CSS the storefront renders.
+    expect(
+      maskLiquidStylesheet(
+        [
+          '{% doc %}',
+          '  @example',
+          '  {% stylesheet %}',
+          '  .a { color: red; }',
+          '  {% endstylesheet %}',
+          '{% enddoc %}',
+          '',
+        ].join('\n'),
+      ),
+    ).toBeNull();
+  });
+
+  it('still lints a live block alongside a documented one', () => {
+    const masked = maskLiquidStylesheet(
+      [
+        '{% doc %}',
+        '  @example',
+        '  {% stylesheet %}',
+        '  .old { color: red; }',
+        '  {% endstylesheet %}',
+        '{% enddoc %}',
+        '{% stylesheet %}',
+        '.new { color: blue; }',
+        '{% endstylesheet %}',
+        '',
+      ].join('\n'),
+    )!;
+    const lines = masked.split('\n');
+
+    expect(lines[3]!.trim()).toBe('');
+    expect(lines[7]).toBe('.new { color: blue; }');
+  });
+
   it('still lints a live block alongside a commented-out one', () => {
     const masked = maskLiquidStylesheet(
       [

package/skills/shopify-lint/stylelint-config-theory/src/liquid/mask.ts

@@ -27,8 +27,14 @@
 const STYLESHEET_BLOCK =
   /(\{%-?\s*stylesheet\b([^%]*?)-?%\})([\s\S]*?)(\{%-?\s*endstylesheet\s*-?%\})/g;
 
-/** Liquid tags whose bodies are not Liquid and must be masked wholesale. */
-const RAW_CONTENT_TAG = /\{%-?\s*(comment|raw)\s*-?%\}[\s\S]*?\{%-?\s*end\1\s*-?%\}/g;
+/**
+ * Liquid tags whose bodies are not Liquid and must be masked wholesale.
+ *
+ * `{% doc %}` is included because a documented snippet's `@example` routinely
+ * shows the very `{% stylesheet %}` block the snippet expects — sample code
+ * that is never rendered and must not be linted.
+ */
+const RAW_CONTENT_TAG = /\{%-?\s*(comment|doc|raw)\s*-?%\}[\s\S]*?\{%-?\s*end\1\s*-?%\}/g;
 
 /** A Liquid output tag, e.g. `{{ section.settings.accent | default: '#000' }}`. */
 const OUTPUT_TAG = /\{\{[\s\S]*?\}\}/g;
@@ -84,7 +90,7 @@ function contains(intervals: Interval[], offset: number): boolean {
   return intervals.some((interval) => offset >= interval.start && offset < interval.end);
 }
 
-/** Every `{% comment %}` / `{% raw %}` region in the source, in order. */
+/** Every raw-content region in the source, in order. */
 function rawContentRegions(source: string): Interval[] {
   return [...source.matchAll(RAW_CONTENT_TAG)].map((match) => ({
     start: match.index,
@@ -95,8 +101,8 @@ function rawContentRegions(source: string): Interval[] {
 /**
  * Mask the Liquid constructs inside one `{% stylesheet %}` body, in place.
  *
- * Order matters: `{% comment %}` and `{% raw %}` bodies are masked first so
- * that Liquid-looking text inside them is not substituted a second time.
+ * Order matters: raw-content bodies are masked first so that Liquid-looking
+ * text inside them is not substituted a second time.
  *
  * Shopify does not render Liquid inside a `{% stylesheet %}` tag, so any
  * interpolation found here is already broken theme code, and Theme Check's
@@ -156,8 +162,9 @@ function maskLiquidInBody(source: string, out: string[], start: number, end: num
  * when:
  *
  * - there is no complete `{% stylesheet %}` … `{% endstylesheet %}` pair;
- * - every such block sits inside a `{% comment %}` or `{% raw %}` region —
- *   commented-out blocks are common mid-migration;
+ * - every such block sits inside a `{% comment %}`, `{% doc %}`, or `{% raw %}`
+ *   region — commented-out blocks are common mid-migration, and a documented
+ *   block is an illustration rather than live CSS;
  * - every block carries an argument (`{% stylesheet 'scss' %}`), whose body is
  *   Sass rather than CSS and would only produce parse errors; or
  * - every block's body is blank once masked, which would otherwise be reported
@@ -178,7 +185,7 @@ export function maskLiquidStylesheet(source: string): string | null {
   for (const match of source.matchAll(STYLESHEET_BLOCK)) {
     const blockStart = match.index;
     if (contains(rawRegions, blockStart)) {
-      // A commented-out or raw-quoted block is not live CSS.
+      // A commented-out, documented, or raw-quoted block is not live CSS.
       continue;
     }
     if (match[2]!.trim() !== '') {

package/skills/shopify-lint/tests/test_shopify_lint.py

@@ -80,6 +80,35 @@ class ThemeCheckTests(unittest.TestCase):
             check=False,
         )
 
+    def test_rebases_theme_check_positions_onto_one_indexed_lines(self) -> None:
+        """Theme Check emits LSP-style zero-indexed positions; the report is one-indexed."""
+        reports = [
+            {
+                "path": "/repo/sections/td-hero.liquid",
+                "offenses": [
+                    {
+                        "check": "HardcodedText",
+                        "severity": "warning",
+                        "start_row": 0,
+                        "start_column": 4,
+                        "end_row": 2,
+                        "end_column": 9,
+                    }
+                ],
+            }
+        ]
+
+        [report] = shopify_lint.normalize_theme_check_reports(reports)
+        offense = report["offenses"][0]
+
+        self.assertEqual(offense["start_row"], 1)
+        self.assertEqual(offense["end_row"], 3)
+        self.assertEqual(offense["start_column"], 5)
+        self.assertEqual(offense["end_column"], 10)
+        # The input is not mutated in place.
+        self.assertEqual(reports[0]["offenses"][0]["start_row"], 0)
+        self.assertEqual(reports[0]["offenses"][0]["start_column"], 4)
+
     def test_filters_reports_to_changed_repo_relative_paths(self) -> None:
         root = Path("/repo")
         reports = [
@@ -360,7 +389,7 @@ class JsLintCommandTests(unittest.TestCase):
 
 
 class EslintNormalizationTests(unittest.TestCase):
-    def test_maps_severity_rule_and_zero_indexed_position(self) -> None:
+    def test_maps_severity_rule_and_position(self) -> None:
         results = [
             {
                 "filePath": "/repo/assets/td-app.js",
@@ -395,15 +424,15 @@ class EslintNormalizationTests(unittest.TestCase):
                             "check": "eslint/no-undef",
                             "severity": "error",
                             "message": "'x' is not defined.",
-                            "start_row": 3,
-                            "start_column": 2,
+                            "start_row": 4,
+                            "start_column": 3,
                         },
                         {
                             "check": "theory/no-class-selectors",
                             "severity": "warning",
                             "message": "Use a data-td-* hook.",
-                            "start_row": 8,
-                            "start_column": 0,
+                            "start_row": 9,
+                            "start_column": 1,
                         },
                     ],
                 }
@@ -684,7 +713,7 @@ class CssLintCommandTests(unittest.TestCase):
 
 
 class StylelintNormalizationTests(unittest.TestCase):
-    def test_namespaces_rules_and_zero_indexes_positions(self) -> None:
+    def test_namespaces_rules_and_maps_positions(self) -> None:
         results = [
             {
                 "path": "/theme/assets/component-td-card.css",
@@ -705,8 +734,8 @@ class StylelintNormalizationTests(unittest.TestCase):
 
         self.assertEqual(offense["check"], "stylelint/length-zero-no-unit")
         self.assertEqual(offense["severity"], "warning")
-        self.assertEqual(offense["start_row"], 3)
-        self.assertEqual(offense["start_column"], 2)
+        self.assertEqual(offense["start_row"], 4)
+        self.assertEqual(offense["start_column"], 3)
 
     def test_keeps_a_namespaced_plugin_rule_as_is(self) -> None:
         results = [
@@ -932,6 +961,32 @@ class MergeReportTests(unittest.TestCase):
     (SKILL_ROOT / "eslint-plugin-theory" / "dist").is_dir(),
     "run scripts/setup.sh to build eslint-plugin-theory",
 )
+class RenderTextTests(unittest.TestCase):
+    """The Stop hooks feed this text straight back to the agent."""
+
+    def test_prints_the_one_indexed_row_the_offense_carries(self) -> None:
+        reports = [
+            {
+                "path": "/repo/sections/td-hero.liquid",
+                "offenses": [
+                    {
+                        "check": "HardcodedText",
+                        "severity": "warning",
+                        "start_row": 12,
+                        "start_column": 4,
+                        "message": "Replace hard-coded text",
+                    }
+                ],
+            }
+        ]
+
+        rendered = shopify_lint.render_text(reports, Path("/repo"))
+
+        self.assertIn(
+            "  WARNING HardcodedText 12:4 Replace hard-coded text", rendered
+        )
+
+
 class EndToEndJsTests(unittest.TestCase):
     """Proves the Liquid line-mapping contract against the real runner."""
 
@@ -951,7 +1006,7 @@ class EndToEndJsTests(unittest.TestCase):
             "  {% endif %}",
             "{% endjavascript %}",
         ]
-        expected_row = lines.index("  const dupe = { a: 1, a: 2 };")
+        expected_row = lines.index("  const dupe = { a: 1, a: 2 };") + 1
 
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)
@@ -969,7 +1024,7 @@ class EndToEndJsTests(unittest.TestCase):
         ]
 
         self.assertEqual(len(dupe), 1)
-        # start_row is zero-indexed, matching Theme Check.
+        # start_row is one-indexed, matching the line numbers an editor shows.
         self.assertEqual(dupe[0]["start_row"], expected_row)
         self.assertEqual(dupe[0]["severity"], "error")
 
@@ -994,7 +1049,7 @@ class EndToEndCssTests(unittest.TestCase):
             "  .td-broken {}",
             "{% endstylesheet %}",
         ]
-        expected_row = lines.index("  .td-broken {}")
+        expected_row = lines.index("  .td-broken {}") + 1
 
         with tempfile.TemporaryDirectory() as directory:
             root = Path(directory)
@@ -1012,13 +1067,13 @@ class EndToEndCssTests(unittest.TestCase):
         ]
 
         self.assertEqual(len(empty), 1)
-        # start_row is zero-indexed, matching Theme Check.
+        # start_row is one-indexed, matching the line numbers an editor shows.
         self.assertEqual(empty[0]["start_row"], expected_row)
         self.assertEqual(empty[0]["severity"], "error")
         # The masked interpolation is graded like any other value now: Liquid
         # does not belong in a `{% stylesheet %}` block, and Theme Check reports
         # it separately through `StaticStylesheetAndJavascriptTags`.
-        interpolated_row = lines.index("    margin: {{ section.settings.gap }}px;")
+        interpolated_row = lines.index("    margin: {{ section.settings.gap }}px;") + 1
         self.assertEqual(
             [
                 offense["check"]

package/skills/shopify-lint/theme-check-theory/README.md

@@ -39,6 +39,13 @@ checked. It ignores technical attributes such as classes and IDs, Liquid logic
 strings, comments, punctuation-only fragments, and text made entirely of HTML
 character references.
 
+Text beginning with `--` is ignored as a CSS custom property name: Liquid
+routinely assembles a custom property declaration before handing it to a
+`style` attribute or a `{% style %}` block, neither of which this check reads.
+Only the fragment carrying the `--` prefix is exempt, so the tail of an
+interpolated declaration — the `px;` in
+`{% capture s %}--td-gap: {{ gap }}px;{% endcapture %}` — is still reported.
+
 Content inside `{% stylesheet %}`, `{% javascript %}`, and `{% schema %}` is
 ignored. A quoted translation key passed through `t` or `translate` is also
 accepted. Short alphabetic tokens and copyright years remain reportable because

package/skills/shopify-lint/theme-check-theory/package-lock.json

@@ -1071,16 +1071,16 @@
       }
     },
     "node_modules/brace-expansion": {
-      "version": "5.0.7",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.7.tgz",
-      "integrity": "sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==",
+      "version": "5.0.9",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
+      "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^4.0.2"
       },
       "engines": {
-        "node": "18 || 20 || >=22"
+        "node": "20 || >=22"
       }
     },
     "node_modules/cac": {

package/skills/shopify-lint/theme-check-theory/src/checks/hardcoded-text.test.ts

@@ -165,10 +165,38 @@ describe('HardcodedText', () => {
       'schema',
       '{% schema %}{"name":"Hard coded","settings":[]}{% endschema %}',
     ],
+    [
+      'doc',
+      '{% doc %}Hard coded documentation{% enddoc %}',
+    ],
   ])('ignores text inside the %s raw tag', async (_, source) => {
     expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
   });
 
+  it('ignores every part of a documentation block', async () => {
+    // The parser breaks a `{% doc %}` body into description, param, and example
+    // nodes, each carrying its own text — none of it rendered to the storefront.
+    const source = `{% doc %}
+      Renders a product card.
+
+      @param {product} product - The product to render
+      @param {string} [heading] - Optional heading text
+      @example
+      {% render 'card', product: product, heading: 'Featured' %}
+    {% enddoc %}`;
+
+    expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
+  });
+
+  it('still reports rendered text beside a documentation block', async () => {
+    const source = `{% doc %}
+      Renders a product card.
+    {% enddoc %}
+    <h2>Featured products</h2>`;
+
+    expect(await runLiquidCheck(HardcodedText, source)).toHaveLength(1);
+  });
+
   it('ignores comments, technical attributes, punctuation, and Liquid logic strings', async () => {
     const source = `
       <!-- Hard coded HTML comment -->
@@ -181,6 +209,38 @@ describe('HardcodedText', () => {
     expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
   });
 
+  it('accepts CSS custom properties built in Liquid', async () => {
+    const source = `
+      {% capture card_style %}--td-card-gap: 12px;{% endcapture %}
+      {{ '--td-card-columns' }}
+      {% echo "--td-card-radius: 4px;" %}
+      {% render 'card', style_key: '--td-card-accent' %}
+      <div style="{{ card_style }}">{{ section.settings.heading }}</div>
+    `;
+
+    expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
+  });
+
+  it('still reports the tail of an interpolated custom property', async () => {
+    // The parser splits the declaration around the output tag, and only the
+    // fragment that carries the `--` prefix is exempt. The trailing unit is a
+    // text node of its own with nothing marking it as CSS.
+    const source =
+      '{% capture style %}--td-gap: {{ section.settings.gap }}px;{% endcapture %}';
+
+    const offenses = await runLiquidCheck(HardcodedText, source);
+
+    expect(
+      offenses.map(({ start, end }) => source.slice(start.index, end.index)),
+    ).toEqual(['px;']);
+  });
+
+  it('still reports copy that only mentions a custom property later', async () => {
+    const source = '{% capture note %}Set --td-gap to widen the card{% endcapture %}';
+
+    expect(await runLiquidCheck(HardcodedText, source)).toHaveLength(1);
+  });
+
   it('still reports rendered text inside other raw tags', async () => {
     const source = '{% raw %}Hard coded raw output{% endraw %}';
 

package/skills/shopify-lint/theme-check-theory/src/checks/hardcoded-text.ts

@@ -21,6 +21,7 @@ import {
 
 const EXEMPT_RAW_TAGS = new Set([
   'comment',
+  'doc',
   'javascript',
   'schema',
   'stylesheet',
@@ -42,6 +43,12 @@ const BUTTON_INPUT_TYPES = new Set(['button', 'reset', 'submit']);
 const HTML_CHARACTER_REFERENCE =
   /&(?:#\d+|#x[\da-f]+|[a-z][\da-z]+);/giu;
 
+// A leading `--` is a CSS custom property name, never storefront copy. Liquid
+// routinely assembles custom property declarations before handing them to a
+// `style` attribute or a `{% style %}` block — places this check overlooks —
+// so the fragment that builds them is exempt too.
+const CSS_CUSTOM_PROPERTY = /^\s*--/u;
+
 type ValuedAttribute = Extract<AttributeNode, { value: unknown }>;
 
 function isValuedAttribute(node: LiquidHtmlNode): node is ValuedAttribute {
@@ -123,6 +130,8 @@ function isInlineSvgMarkup(ancestors: LiquidHtmlNode[]): boolean {
 }
 
 function hasMeaningfulText(value: string): boolean {
+  if (CSS_CUSTOM_PROPERTY.test(value)) return false;
+
   return /[\p{L}\p{N}]/u.test(
     value.replace(HTML_CHARACTER_REFERENCE, ''),
   );