td-ai-tools 1.2.5 → 1.2.8

package/package.json

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

package/skills/README.md

@@ -16,7 +16,7 @@
 - `pull-request-statamic`: Generates GitHub pull request descriptions for Statamic and Laravel development by analyzing git diffs and…
 - `record-changes`: Update `docs/changes.md` by summarizing the current branch against the primary development branch.
 - `shopify-cli`: Shopify CLI workflows for theme development.
-- `shopify-lint`: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks while reporting and failing only on…
+- `shopify-lint`: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks, including warnings for hard-coded…
 - `stylesheet-migration`: Migrate Shopify Liquid `{% stylesheet %}` blocks into theme CSS assets using bundled Python scripts.
 - `td-js-vanilla-rules`: Theory Digital vanilla JavaScript standards for Shopify theme work.
 - `td-review`: Run parallel code review agents on a PR (including TD theme compliance) and produce a synthesized findings…

package/skills/shopify-lint/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: shopify-lint
-version: 1.1.0
-description: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks while reporting and failing only on offenses in files modified on the current Git branch. Use when Codex needs to lint a Shopify theme, validate branch-scoped Liquid or theme changes, enforce Theory theme rules, or avoid surfacing pre-existing Theme Check offenses from untouched files.
+version: 1.3.2
+description: Run Shopify CLI Theme Check with Theory Digital's bundled custom checks, including warnings for hard-coded storefront text and script or style tags in Liquid, while reporting and failing only on offenses in files modified on the current Git branch. Use when Codex needs to lint a Shopify theme, validate branch-scoped Liquid or theme changes, enforce Theory theme rules, or avoid surfacing pre-existing Theme Check offenses from untouched files.
 ---
 
 # Shopify Lint
@@ -17,7 +17,7 @@ bash .agents/skills/shopify-lint/scripts/setup.sh
 Installing with `td-ai-tools install --setup shopify-lint` runs this automatically. The script:
 
 1. Runs `npm install && npm run build` inside `theme-check-theory/`, producing `dist/index.js` — the CommonJS entry point the root `.theme-check.yml` requires.
-2. Writes a `.theme-check.yml` at the project root wiring in the bundled checks. If one already exists it is left untouched; ensure its `require:` list includes `./.agents/skills/shopify-lint/theme-check-theory`.
+2. Writes a `.theme-check.yml` at the project root wiring in the bundled checks. Setup replaces any existing file with the skill's current configuration so installs and updates cannot retain stale or incomplete settings.
 3. Through the installer's shared project-hook setup, installs matching Claude and Codex Stop hooks and merges their registrations into `.claude/settings.json` and `.codex/hooks.json` without replacing unrelated settings or hooks. Re-running setup updates the Shopify Lint hook in place instead of duplicating it.
 
 The Stop hooks run this skill's branch-scoped lint before handoff, return modified-file offenses to the agent, and allow handoff after three unsuccessful fix rounds. They require `jq`, `python3`, and Shopify CLI to be available when the hook runs. Directly running `scripts/setup.sh` performs the package build and Theme Check configuration; use `td-ai-tools install --setup` or `td-ai-tools update --setup` to apply the shared hook manifest as well.
@@ -32,7 +32,7 @@ Run the bundled Python script from the Shopify theme root:
 python3 .agents/skills/shopify-lint/scripts/shopify_lint.py --path .
 ```
 
-The script runs `shopify theme check --output json`, identifies files changed since the current branch's merge-base, adds staged, unstaged, and untracked files, and emits only reports whose paths are in that set. The root `.theme-check.yml` directly requires the bundled `theme-check-theory` package from this skill directory.
+The script runs `shopify theme check --output json`, identifies files changed since the current branch's merge-base, adds staged, unstaged, and untracked files, and emits only reports whose paths are in that set. 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.
 
 ## Workflow
 

package/skills/shopify-lint/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Shopify Lint"
-  short_description: "Lint modified theme files with Theory checks"
+  short_description: "Lint modified Shopify theme files"
   default_prompt: "Use $shopify-lint to run Theme Check for files modified on my current branch."

package/skills/shopify-lint/scripts/setup.sh

@@ -21,7 +21,7 @@ cd "$PKG_DIR"
 npm install
 npm run build
 
-# 2. Generate the project-root .theme-check.yml.
+# 2. Write the project-root .theme-check.yml.
 #
 # The installed layout is <project>/<.agents|.claude>/skills/shopify-lint, so
 # the project root is three levels above the skill directory. Guard against
@@ -37,12 +37,6 @@ fi
 PROJECT_ROOT="$(dirname "$TARGET_DIR")"
 THEME_CHECK_FILE="$PROJECT_ROOT/.theme-check.yml"
 
-if [[ -f "$THEME_CHECK_FILE" ]]; then
-  echo "shopify-lint setup: $THEME_CHECK_FILE already exists; leaving it unchanged."
-  echo "  Ensure its 'require:' list includes ./.agents/skills/shopify-lint/theme-check-theory"
-  exit 0
-fi
-
 cat > "$THEME_CHECK_FILE" <<'YAML'
 extends:
   - theme-check:recommended
@@ -50,13 +44,29 @@ extends:
 require:
   - ./.agents/skills/shopify-lint/theme-check-theory
 
+DisallowedScriptOrStyleTag:
+  enabled: true
+  severity: warning
+
+HardcodedText:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
+  enabled: false
+  severity: warning
+
+UnguardedNullableSetting:
+  enabled: true
+  severity: warning
+
+UnguardedMetafield:
   enabled: true
   severity: warning
 
-UnguardedTextSetting:
+UnguardedMetaobject:
   enabled: true
   severity: warning
 YAML
 
-echo "shopify-lint setup: wrote $THEME_CHECK_FILE"
+echo "shopify-lint setup: wrote $THEME_CHECK_FILE (replacing any existing configuration)"

package/skills/shopify-lint/theme-check-theory/.theme-check.example.yml

@@ -4,11 +4,26 @@ extends:
 require:
   - ./node_modules/theme-check-theory
 
+DisallowedScriptOrStyleTag:
+  enabled: true
+  severity: warning
+
+HardcodedText:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
+  enabled: false
+  severity: warning
+
+UnguardedNullableSetting:
   enabled: true
   severity: warning
 
-UnguardedTextSetting:
+UnguardedMetafield:
   enabled: true
   severity: warning
 
+UnguardedMetaobject:
+  enabled: true
+  severity: warning

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

@@ -11,8 +11,37 @@ integrated into Shopify CLI. It is not compatible with the archived Ruby
 
 | Code | Severity | What it catches |
 | --- | --- | --- |
+| `DisallowedScriptOrStyleTag` | warning | An inline executable `<script>` or any `<style>` tag in a Liquid file. |
+| `HardcodedText` | warning | Rendered hard-coded storefront copy that should use a dynamic content source. |
 | `UnusedSectionSettings` | warning | A setting declared in `{% schema %}` that is never referenced in the file. |
-| `UnguardedTextSetting` | warning | A text-like setting output with `{{ }}` and no presence guard (`{% if %}`/`{% unless %}`) or `\| default`. |
+| `UnguardedNullableSetting` | warning | A potentially blank setting output with `{{ }}` and no presence guard (`{% if %}`/`{% unless %}`) or `\| default`. |
+| `UnguardedMetafield` | warning | A metafield output with no presence guard or `\| default`. |
+| `UnguardedMetaobject` | warning | A metaobject entry output with no presence guard or `\| default`. |
+
+### DisallowedScriptOrStyleTag
+
+HTML `<script>` and `<style>` tags keep JavaScript and CSS embedded in Liquid
+files. Move their contents to theme assets or the appropriate Shopify Liquid
+tags instead. Scripts with a non-empty `src` attribute and scripts declared as
+JSON data, including `application/json` and `application/ld+json`, are allowed.
+HTML comments and similarly named elements such as `<script-template>` are
+ignored.
+
+### HardcodedText
+
+Rendered storefront copy should come from a section setting, translation key,
+metafield, or metaobject. The check reports text nodes, direct quoted output
+with `{{ }}` or `{% echo %}`, quoted `default` filter fallbacks, hard-coded
+`alt`, `title`, `placeholder`, and ARIA text attributes, and labels in the
+`value` attribute of button-like inputs. It ignores technical attributes such
+as classes and IDs, Liquid logic strings, comments, punctuation-only fragments,
+and text made entirely of HTML character references.
+
+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
+the check cannot reliably distinguish user-facing copy from currency codes,
+units, or other intentional literals.
 
 ### UnusedSectionSettings
 
@@ -25,31 +54,62 @@ If a file uses dynamic access such as `section.settings[key]`, or passes an
 entire settings object elsewhere, the check cannot prove which setting is
 unused. It therefore stays silent for the whole file to avoid false positives.
 
-### UnguardedTextSetting
+This check is disabled by default. Enable it explicitly when a theme's section
+settings are expected to be fully traceable within each file:
 
-Text-like settings render as an empty string when a merchant leaves them blank,
-so outputting them unguarded is a recurring bug source. A setting is considered
-handled if, anywhere in the file, it is either tested in an `if`, `unless`,
-`elsif`, or `case` conditional, or output with a `default` filter.
+```yaml
+UnusedSectionSettings:
+  enabled: true
+  severity: warning
+```
+
+### UnguardedNullableSetting
 
-Version 1 is deliberately coarse and per-file. It favors near-zero false
-positives over catching a setting guarded in one branch and output raw in
-another.
+Many settings can return an empty, `blank`, or `nil` value when a merchant
+leaves them unset or their selected resource is no longer available. Outputting
+them unguarded is a recurring bug source. Each output is evaluated independently.
+It is considered guarded when its active `if`, `unless`, `elsif`, or `case`
+branch tests that setting, or when that output uses a `default` filter. A guard
+or default on one invocation does not suppress offenses for unguarded
+invocations elsewhere in the file.
 
-The setting types considered text-like are configurable with
-`textualSettingTypes`. The defaults are `text`, `textarea`, `richtext`,
-`inline_richtext`, `html`, `liquid`, and `url`.
+The setting types checked are configurable with the `nullableSettingTypes`
+option. The defaults are `number`, `text`, `textarea`, `article`,
+`article_list`, `blog`, `collection`, `collection_list`, `image_picker`,
+`link_list`, `metaobject`, `metaobject_list`, `page`, `product`,
+`product_list`, `richtext`, `inline_richtext`, `html`, `liquid`, `url`,
+`video`, and `video_url`. Color-related settings are excluded because an unset
+color can resolve to a non-null fallback such as `transparent`.
 
 ```yaml
-UnguardedTextSetting:
+UnguardedNullableSetting:
   enabled: true
   severity: warning
-  textualSettingTypes:
+  nullableSettingTypes:
     - text
     - textarea
     - image_picker
 ```
 
+### UnguardedMetafield and UnguardedMetaobject
+
+[Metafields](https://shopify.dev/docs/api/liquid/objects/metafield) are
+identified from the static `resource.metafields.namespace.key` access path,
+and [metaobjects](https://shopify.dev/docs/api/liquid/objects/metaobject) from
+`metaobjects.type.handle`. Outputting the object itself or any descendant, such
+as a metafield's `value` or a metaobject's field, requires a guard on the same
+object or a `default` filter on that output.
+
+Both dot and static square-bracket notation are supported. Dynamic namespace,
+key, type, and handle lookups are ignored because the selected object cannot be
+identified statically. The singular `metaobject` drop available inside a
+metaobject template is also ignored because the template is already rendering
+that entry.
+
+All three nullability checks share the same branch and `default`-filter
+analysis. A guard applies only inside its active `if`, `unless`, `elsif`, or
+`case` branch and only to the matching setting, metafield, or metaobject.
+
 ## Usage in a project
 
 Install the module as a development dependency:
@@ -67,11 +127,27 @@ extends:
 require:
   - ./node_modules/theme-check-theory
 
+DisallowedScriptOrStyleTag:
+  enabled: true
+  severity: warning
+
+HardcodedText:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
+  enabled: false
+  severity: warning
+
+UnguardedNullableSetting:
   enabled: true
   severity: warning
 
-UnguardedTextSetting:
+UnguardedMetafield:
+  enabled: true
+  severity: warning
+
+UnguardedMetaobject:
   enabled: true
   severity: warning
 ```
@@ -118,6 +194,7 @@ real Theme Check parser and traversal rather than a mocked AST.
 4. Add it to `configs/recommended.yml`.
 
 Shared schema parsing and setting-reference helpers live in `src/utils/ast.ts`.
-Their node shapes are verified against `@shopify/liquid-html-parser` 2.9.x;
-run the tests when upgrading that dependency.
-
+Null-guard analysis and nullable-object check construction live in
+`src/utils/null-guard.ts` and `src/utils/nullable-output-check.ts`. Their node
+shapes are verified against `@shopify/liquid-html-parser` 2.9.x; run the tests
+when upgrading that dependency.

package/skills/shopify-lint/theme-check-theory/configs/recommended.yml

@@ -1,8 +1,23 @@
+DisallowedScriptOrStyleTag:
+  enabled: true
+  severity: warning
+
+HardcodedText:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
+  enabled: false
+  severity: warning
+
+UnguardedNullableSetting:
   enabled: true
   severity: warning
 
-UnguardedTextSetting:
+UnguardedMetafield:
   enabled: true
   severity: warning
 
+UnguardedMetaobject:
+  enabled: true
+  severity: warning

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

@@ -1,12 +1,12 @@
 {
   "name": "theme-check-theory",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "theme-check-theory",
-      "version": "0.1.0",
+      "version": "0.2.1",
       "license": "UNLICENSED",
       "dependencies": {
         "@shopify/liquid-html-parser": "2.9.2",

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

@@ -1,6 +1,6 @@
 {
   "name": "theme-check-theory",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Theory Digital's custom Shopify Theme Check rules",
   "type": "commonjs",
   "main": "dist/index.js",

package/skills/shopify-lint/theme-check-theory/src/checks/disallowed-script-or-style-tag.test.ts

@@ -0,0 +1,87 @@
+import {
+  runLiquidCheck,
+} from '@shopify/theme-check-common/dist/test/test-helper';
+import { describe, expect, it } from 'vitest';
+
+import { DisallowedScriptOrStyleTag } from './disallowed-script-or-style-tag';
+
+describe('DisallowedScriptOrStyleTag', () => {
+  it('reports script and style tags', async () => {
+    const source = `
+      <script>window.example = true;</script>
+      <style>.example { color: red; }</style>
+    `;
+
+    const offenses = await runLiquidCheck(DisallowedScriptOrStyleTag, source);
+
+    expect(offenses).toHaveLength(2);
+    expect(offenses.map(({ message }) => message)).toEqual([
+      'Do not include <script> tags in Liquid files',
+      'Do not include <style> tags in Liquid files',
+    ]);
+    expect(
+      offenses.every(({ check }) => check === 'DisallowedScriptOrStyleTag'),
+    ).toBe(true);
+  });
+
+  it('reports case variants and self-closing tags', async () => {
+    const source = `
+      <SCRIPT type="module">window.example = true;</SCRIPT>
+      <STYLE />
+    `;
+
+    const offenses = await runLiquidCheck(DisallowedScriptOrStyleTag, source);
+
+    expect(offenses).toHaveLength(2);
+    expect(offenses.map(({ message }) => message)).toEqual([
+      'Do not include <script> tags in Liquid files',
+      'Do not include <style> tags in Liquid files',
+    ]);
+  });
+
+  it('ignores scripts with an external source', async () => {
+    const source = `
+      <script src="{{ 'theme.js' | asset_url }}" defer></script>
+      <SCRIPT SRC="https://cdn.example.com/widget.js"></SCRIPT>
+    `;
+
+    expect(
+      await runLiquidCheck(DisallowedScriptOrStyleTag, source),
+    ).toEqual([]);
+  });
+
+  it('ignores scripts containing JSON data', async () => {
+    const source = `
+      <script type="application/ld+json">{"@type":"Organization"}</script>
+      <script type="application/json">{"enabled":true}</script>
+    `;
+
+    expect(
+      await runLiquidCheck(DisallowedScriptOrStyleTag, source),
+    ).toEqual([]);
+  });
+
+  it('reports executable scripts with an empty src', async () => {
+    const source = `
+      <script src="">window.example = true;</script>
+      <script type="text/javascript">window.example = true;</script>
+    `;
+
+    expect(
+      await runLiquidCheck(DisallowedScriptOrStyleTag, source),
+    ).toHaveLength(2);
+  });
+
+  it('ignores tags in comments and similarly named elements', async () => {
+    const source = `
+      <!-- <script></script> -->
+      {% comment %}<style></style>{% endcomment %}
+      <script-template></script-template>
+      <div style="color: red"></div>
+    `;
+
+    expect(
+      await runLiquidCheck(DisallowedScriptOrStyleTag, source),
+    ).toEqual([]);
+  });
+});

package/skills/shopify-lint/theme-check-theory/src/checks/disallowed-script-or-style-tag.ts

@@ -0,0 +1,161 @@
+import {
+  AttributeNode,
+  HtmlElement,
+  HtmlRawNode,
+  HtmlSelfClosingElement,
+  NodeTypes,
+} from '@shopify/liquid-html-parser';
+import {
+  LiquidCheckDefinition,
+  Severity,
+  SourceCodeType,
+} from '@shopify/theme-check-common';
+
+const DISALLOWED_TAGS = new Set(['script', 'style']);
+
+type NamedHtmlNode = HtmlElement | HtmlSelfClosingElement;
+type ScriptNode = HtmlRawNode | NamedHtmlNode;
+type ValuedAttribute = Extract<AttributeNode, { value: unknown }>;
+
+function isValuedAttribute(
+  attribute: AttributeNode,
+): attribute is ValuedAttribute {
+  return (
+    attribute.type === NodeTypes.AttrDoubleQuoted ||
+    attribute.type === NodeTypes.AttrSingleQuoted ||
+    attribute.type === NodeTypes.AttrUnquoted
+  );
+}
+
+function staticAttributeName(attribute: ValuedAttribute): string | null {
+  if (
+    attribute.name.length !== 1 ||
+    attribute.name[0].type !== NodeTypes.TextNode
+  ) {
+    return null;
+  }
+
+  return attribute.name[0].value.toLowerCase();
+}
+
+function staticAttributeValue(
+  node: ScriptNode,
+  attributeName: string,
+): string | null {
+  const attribute = node.attributes.find(
+    (candidate) =>
+      isValuedAttribute(candidate) &&
+      staticAttributeName(candidate) === attributeName,
+  );
+  if (
+    !attribute ||
+    !isValuedAttribute(attribute) ||
+    !attribute.value.every(({ type }) => type === NodeTypes.TextNode)
+  ) {
+    return null;
+  }
+
+  return attribute.value
+    .map((part) => ('value' in part ? part.value : ''))
+    .join('')
+    .trim()
+    .toLowerCase();
+}
+
+function hasExternalSource(node: ScriptNode): boolean {
+  return node.attributes.some(
+    (attribute) =>
+      isValuedAttribute(attribute) &&
+      staticAttributeName(attribute) === 'src' &&
+      attribute.value.length > 0,
+  );
+}
+
+function containsJsonData(node: ScriptNode): boolean {
+  const type = staticAttributeValue(node, 'type');
+  if (!type) return false;
+
+  const mimeType = type.split(';', 1)[0].trim();
+  return (
+    mimeType.endsWith('/json') ||
+    mimeType.endsWith('+json') ||
+    mimeType === 'importmap' ||
+    mimeType === 'speculationrules'
+  );
+}
+
+function isAllowedScript(node: ScriptNode): boolean {
+  return hasExternalSource(node) || containsJsonData(node);
+}
+
+function staticTagName(node: NamedHtmlNode): string | null {
+  if (
+    node.name.length !== 1 ||
+    node.name[0].type !== NodeTypes.TextNode
+  ) {
+    return null;
+  }
+
+  return node.name[0].value.toLowerCase();
+}
+
+export const DisallowedScriptOrStyleTag: LiquidCheckDefinition = {
+  meta: {
+    code: 'DisallowedScriptOrStyleTag',
+    name: 'Prevent script and style tags in Liquid',
+    docs: {
+      description:
+        'Reports inline executable script and style tags in Liquid files.',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+  },
+  create(context) {
+    function report(tagName: string, startIndex: number, endIndex: number) {
+      if (!DISALLOWED_TAGS.has(tagName)) return;
+
+      context.report({
+        message: `Do not include <${tagName}> tags in Liquid files`,
+        startIndex,
+        endIndex,
+      });
+    }
+
+    function checkNamedNode(node: NamedHtmlNode) {
+      const tagName = staticTagName(node);
+      if (!tagName) return;
+      if (tagName === 'script' && isAllowedScript(node)) return;
+
+      report(
+        tagName,
+        node.blockStartPosition.start,
+        node.blockStartPosition.end,
+      );
+    }
+
+    return {
+      async HtmlRawNode(node) {
+        if (
+          node.name.toLowerCase() === 'script' &&
+          isAllowedScript(node)
+        ) {
+          return;
+        }
+
+        report(
+          node.name.toLowerCase(),
+          node.blockStartPosition.start,
+          node.blockStartPosition.end,
+        );
+      },
+      async HtmlElement(node) {
+        checkNamedNode(node);
+      },
+      async HtmlSelfClosingElement(node) {
+        checkNamedNode(node);
+      },
+    };
+  },
+};