td-ai-tools 1.3.2 → 1.3.3

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.3",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

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/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/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 -->

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',