@ruebenfox/liquefaction 1.0.6 → 2.0.0

package/README.md

@@ -0,0 +1,113 @@
+# Liquid Library CLI Handbook
+
+A concise guide to using the Liquid Library CLI for installing and developing UI components.
+
+## Overview
+- **Public command**: `add` — install components from the library into your theme.
+- **Dev-only commands**: available when developing this library locally (if `dev/*` scripts are present). These scaffold components, manage assets, and run build audits.
+
+## Install Components (Public)
+- **Command**: `liq add <name>`
+- **What it does**: Copies the component files from the library `registry.json` into your theme, prefixing filenames with `lib-`.
+- **Example**:
+  ```powershell
+  liq add lib-button
+  ```
+
+## Develop Components (Dev-only)
+These commands are available when running the CLI inside the library repo with dev scripts present.
+
+### Generate
+- **Command**: `liq generate component <name> [-t javascript|liquid]`
+- **Prompts**:
+  - Component type (if `-t` not provided): `JavaScript` or `Liquid`
+  - Static assets: `JavaScript only`, `CSS only`, `Both`, or `None`
+- **What it does**:
+  - Scaffolds files from templates under `components/lib-<name>/`
+  - Creates `manifest.json` with initial hash/version
+  - Adds an entry to `registry.json`
+- **Example**:
+  ```powershell
+  liq generate component slider -t liquid
+  ```
+
+### Remove
+- **Command**: `liq remove component <name> [-y]`
+- **Flags**:
+  - `-y, --yes`: confirm removal without prompt
+- **What it does**: Removes the component scaffolds and updates the registry.
+- **Example**:
+  ```powershell
+  liq remove component slider -y
+  ```
+
+### Build (Audit)
+- **Command**: `liq build`
+- **What it does**:
+  - Computes the primary file hash for each component.
+  - Compares against `manifest.primary.hash`/`manifest.registry.hash`.
+  - Enforces versioning:
+    - If hash changed and `manifest.version` > `registry.version`: accepts the bump, writes new hashes, and updates the registry.
+    - If hash changed but versions are equal: requires you to bump `manifest.version`.
+    - If `manifest.version` is lower than the registry: fails.
+  - For Liquid components, on accepted bump: re-extracts `props`, `dependencies`, and `scope`.
+- **Example**:
+  ```powershell
+  liq build
+  ```
+
+### Manifest Utilities
+- **Compute Hash**: `liq manifest-hash [name] [-a]`
+  - `-a, --all`: process all components with a manifest
+  - Computes and writes `manifest.primary.hash` + `manifest.registry.hash`; syncs registry hash.
+- **Clean Manifests**: `liq manifest-clean [name] [--dry-run]`
+  - `--dry-run`: preview changes without writing
+  - Removes unused manifest keys (e.g., old audit metadata).
+
+### Asset Management
+- Group command: `liq asset`
+- **Add**: `liq asset add [name] -t css|js`
+  - Adds a CSS or JS asset file to a component and syncs manifest/registry `files`.
+- **Remove**: `liq asset remove [name] -t css|js`
+  - Removes a CSS or JS asset file and syncs manifest/registry `files`.
+
+## Metadata Extraction (Liquid)
+- **Descriptions**: Author descriptions inline in the first Liquid comment block:
+  - `@prop _title: Button label text`
+  - `@prop _price: Display price for the product`
+  - If a description is missing, it remains empty; downstream tooling can show a placeholder.
+- **Scope**: Annotate scope in the first comment block:
+  - `@scope= product, collection` or `- @scope= all`
+- **Required detection**:
+  - A prop is **required** when it has **no** `default` filter.
+  - If a `default` is present (e.g., `{{ _title | default: 'Hello' }}`), it is **not required** and the default becomes the `placeholder`.
+- **Dependencies**:
+  - Extracted from real `{% render 'lib-...' %}` tags **outside** comments.
+  - Guidance examples inside comments are ignored.
+
+## Files & Registry
+- **Manifests**: Per-component `components/lib-<name>/manifest.json` is dev-only; it tracks type, version, primary path, hashes, assets, props, dependencies, and scope.
+- **Registry**: Root `registry.json` is the canonical source for consumers (`liq add`). The build audit updates registry version, hash, and metadata on accepted changes.
+
+## Tips
+- Always bump `manifest.version` when changing the primary file to allow `liq build` to accept and sync changes.
+- Keep `@prop` descriptions short and clear; they are used for documentation and tooling.
+- Only real Liquid code contributes to prop/dependency extraction; comment examples are ignored.
+
+## Examples
+```powershell
+# Add to theme
+liq add lib-button
+
+# Generate a Liquid component with CSS & JS prompts
+liq generate component gallery -t liquid
+
+# Audit and sync after edits (remember to bump version)
+liq build
+
+# Compute hashes for all manifests
+liq manifest-hash -a
+
+# Add a CSS asset to a component
+liq asset add lib-gallery -t css
+```

package/bin/cli.js

@@ -1,6 +1,45 @@
 #!/usr/bin/env node
-const { program } = require('commander'); 
+const { program, Command } = require('commander'); 
 const addAction = require('../src/commands/add');
+let generateComponentAction = null;
+let removeComponentAction = null;
+let buildAction = null;
+let manifestHashAction = null;
+let manifestCleanAction = null;
+let assetAddAction = null;
+let assetRemoveAction = null;
+let serveAction = null;
+
+try {
+  serveAction = require('../dev/serve');
+} catch (_) {};
+
+try {
+  generateComponentAction = require('../dev/generate');
+} catch (_) {};
+
+try {
+  removeComponentAction = require('../dev/remove');
+} catch (_) {};
+
+try {
+  buildAction = require('../dev/build');
+} catch (_) {};
+
+try {
+  manifestHashAction = require('../dev/manifest-hash');
+} catch (_) {};
+
+try {
+  manifestCleanAction = require('../dev/manifest-clean');
+} catch (_) {};
+
+try {
+  assetAddAction = require('../dev/asset-add');
+} catch(_) {};
+try {
+  assetRemoveAction = require('../dev/asset-remove');
+} catch(_) {};
 
 program
   .version('1.0.0')
@@ -11,4 +50,76 @@ program
   .description('Install a component from the library')
   .action(addAction);
 
+if(assetAddAction || assetRemoveAction) {
+  const assetCmd = new Command('asset');
+  assetCmd.description("Manage asset files on components");
+  if (assetAddAction) {
+    assetCmd
+      .command('add [name]')
+      .description('Add asset files (CSS/JS) to an existing component')
+      .option('-t, --type <type>', 'Asset type (css|js)')
+      .action((name, options) => assetAddAction(name, options));
+  }
+  if (assetRemoveAction) {
+    assetCmd
+      .command('remove [name]')
+      .description('Remove asset files (CSS/JS) from an existing component')
+      .option('-t, --type <type>', 'Asset type (css|js)')
+      .action((name, options) => assetRemoveAction(name, options));
+  }
+  program.addCommand(assetCmd);
+};
+
+if(generateComponentAction) {
+  const generateCmd = new Command('generate');
+  generateCmd.description('Generate scaffolds');
+  generateCmd
+    .command('component <name>')
+    .description('Generate a new component')
+    .option('-t, --type <type>', 'Component type (javascript|liquid)')
+    .action((name, options) => generateComponentAction(name, options));
+  program.addCommand(generateCmd);
+};
+
+if(removeComponentAction) {
+  const removeCmd = new Command('remove');
+  removeCmd.description('Remove scaffolds');
+  removeCmd
+    .command('component <name>')
+    .description('Remove an existing component')
+    .option('-y, --yes', 'Confirm removal without prompt')
+    .action((name, options) => removeComponentAction(name, options));
+  program.addCommand(removeCmd);
+};
+
+if(buildAction) {
+  program
+    .command('build')
+    .description('Audit components and sync registry hashes')
+    .action(() => buildAction());
+};
+
+if(manifestHashAction) {
+  program
+    .command('manifest-hash [name]')
+    .description('Compute and write manifest + registry hash for a component')
+    .option('-a, --all', 'Process all components with a manifest')
+    .action((name, options) => manifestHashAction(name, options));
+};
+
+if(manifestCleanAction) {
+  program
+    .command('manifest-clean [name]')
+    .description('Remove unused keys from component manifest(s)')
+    .option('--dry-run', 'Preview changes without writing')
+    .action((name, options) => manifestCleanAction(name, options));
+};
+
+if(serveAction) {
+  program
+    .command('serve [components] [context]')
+    .description('Start the local dev server for component preview')
+    .action((components, context) => serveAction(components, context));
+};
+  
 program.parse(process.argv);

package/components/lib-button/lib-button.css

@@ -0,0 +1 @@
+/* lib-button.css */

package/components/lib-button/lib-button.js

@@ -0,0 +1,2 @@
+// lib-button.js
+// TODO: add boilerplate for Liquid component behavior

package/components/lib-button/lib-button.liquid

@@ -0,0 +1,14 @@
+{% comment %} 
+ lib-button.liquid
+
+ Props can be drawn from anythign with the _ prefix:
+{% endcomment %}
+
+<button 
+  id="{{ _button_id }}"  
+  class="{{ _button_class }}" 
+  type="{{ _button_type }}">
+  <span>
+    {{ _button_text }}
+  </span>
+</button>

package/components/lib-button/manifest.json

@@ -0,0 +1,45 @@
+{
+  "name": "lib-button",
+  "type": "snippet-component",
+  "version": "0.0.5",
+  "description": "liquid component scaffold",
+  "primary": {
+    "path": "lib-button.liquid",
+    "hash": "20d21a698c954f5d613f96bcda12a9e8"
+  },
+  "files": [
+    {
+      "src": "components/lib-button.css",
+      "destDir": "assets"
+    },
+    {
+      "src": "components/lib-button.liquid",
+      "destDir": "snippets"
+    }
+  ],
+  "assets": {
+    "css": [
+      "lib-button.css"
+    ],
+    "js": [
+      "lib-button.js"
+    ]
+  },
+  "props": [
+    {
+      "name": "_button_text",
+      "type": "string",
+      "required": false,
+      "description": ""
+    }
+  ],
+  "dependencies": [],
+  "registry": {
+    "createdAt": "2026-01-19T22:51:34.014Z",
+    "hash": "20d21a698c954f5d613f96bcda12a9e8"
+  },
+  "build": {
+    "lastAuditAt": "2026-01-25T17:59:55.937Z"
+  },
+  "scope": []
+}

package/components/lib-clicker/lib-clicker.css

@@ -0,0 +1,11 @@
+/* lib-clicker.css */
+.lib-clicker {
+  --lib-clicker-gap: 0.5rem;
+  display: block;
+}
+
+.lib-clicker__content {
+  margin-block: var(--lib-clicker-gap);
+}
+
+.lib-clicker__content--empty { opacity: 0.6; }

package/components/lib-clicker/lib-clicker.js

@@ -0,0 +1,8 @@
+// lib-lib-clicker.js (optional behavior for Liquid components)
+(() => {
+  const selector = '.lib-clicker[data-lib="clicker"]';
+  document.querySelectorAll(selector).forEach((el) => {
+    // Hook point for interactive behavior
+    // Example: el.addEventListener('click', () => {});
+  });
+})();

package/components/lib-clicker/lib-clicker.liquid

@@ -0,0 +1,30 @@
+{%- comment -%}
+Component: lib-clicker
+Type: snippet-component
+
+Props (snake_case with leading underscore). Use a default filter to mark required:
+- _clicker_content: string (required)
+- _aria_label: string (optional)
+- _clicker_id: string (optional)
+
+Description
+- @description: Dummy add to cart button.
+
+Scope (theme contexts):
+- @scope= product, collection
+
+Docs (inline prop descriptions):
+- @prop _content: Product title to display
+- @prop _classes: Additional classes to add to the component wrapper
+- @prop _button_id: Optional ID for the button
+{%- endcomment -%}
+
+{% assign _classes = _classes | default: 'bg-red-600 p-3 rounded' %}
+{% assign _button_id = _button_id %}
+{% assign _content = _content | default: product.title %}
+
+<button {% if _button_id %} id="{{ _button_id }}" {% endif %} class="{{ _classes }}">
+  <span id="test-one" class="lib-clicker">
+    {{ _content }}
+  </span> 
+</button>

package/components/lib-clicker/manifest.json

@@ -0,0 +1,69 @@
+{
+  "name": "lib-clicker",
+  "type": "snippet-component",
+  "version": "0.1.0",
+  "description": "Dummy add to cart button.",
+  "primary": {
+    "path": "lib-clicker.liquid",
+    "hash": "99b32b4f5482111e958ff7be9dde9446"
+  },
+  "files": [
+    {
+      "src": "components/lib-clicker/lib-clicker.css",
+      "destDir": "assets",
+      "hash": "1400e68714456397b1b08bfd62997c23"
+    },
+    {
+      "src": "components/lib-clicker/lib-clicker.liquid",
+      "destDir": "snippets",
+      "hash": "99b32b4f5482111e958ff7be9dde9446"
+    },
+    {
+      "src": "components/lib-clicker/lib-clicker.js",
+      "destDir": "assets",
+      "hash": "4c226a2521a6bdccc1020348c7d320a7"
+    }
+  ],
+  "assets": {
+    "css": [
+      "lib-clicker.css"
+    ],
+    "js": [
+      "lib-clicker.js"
+    ]
+  },
+  "props": [
+    {
+      "name": "_content",
+      "type": "string",
+      "required": true,
+      "description": "Product title to display",
+      "placeholder": "product.title"
+    },
+    {
+      "name": "_classes",
+      "type": "string",
+      "required": true,
+      "description": "Additional classes to add to the component wrapper",
+      "placeholder": "'bg-red-600 p-3 rounded'"
+    },
+    {
+      "name": "_button_id",
+      "type": "string",
+      "required": false,
+      "description": "Optional ID for the button"
+    }
+  ],
+  "dependencies": [],
+  "scope": [
+    "product",
+    "collection"
+  ],
+  "registry": {
+    "createdAt": "2026-01-31T00:26:37.644Z",
+    "hash": "99b32b4f5482111e958ff7be9dde9446"
+  },
+  "build": {
+    "lastAuditAt": "2026-01-31T00:27:20.182Z"
+  }
+}

package/components/lib-footer/lib-footer.css

@@ -0,0 +1 @@
+/* lib-footer.css */

package/components/lib-footer/lib-footer.js

@@ -0,0 +1,2 @@
+// lib-footer.js
+// TODO: add boilerplate for Liquid component behavior

package/components/lib-footer/lib-footer.liquid

@@ -0,0 +1 @@
+{% comment %} lib-footer.liquid {% endcomment %}

package/components/lib-footer/manifest.json

@@ -0,0 +1,37 @@
+{
+  "name": "lib-footer",
+  "type": "snippet-component",
+  "version": "0.0.1",
+  "description": "liquid component scaffold",
+  "primary": {
+    "path": "lib-footer.liquid",
+    "hash": "6ec74860565455844b1f3c46a28f4bad"
+  },
+  "files": [
+    {
+      "src": "components/lib-footer.css",
+      "destDir": "assets"
+    },
+    {
+      "src": "components/lib-footer.liquid",
+      "destDir": "snippets"
+    }
+  ],
+  "assets": {
+    "css": [
+      "lib-footer.css"
+    ],
+    "js": [
+      "lib-footer.js"
+    ]
+  },
+  "props": [],
+  "dependencies": [],
+  "registry": {
+    "createdAt": "2026-01-19T23:15:09.156Z",
+    "hash": "6ec74860565455844b1f3c46a28f4bad"
+  },
+  "build": {
+    "lastAuditAt": ""
+  }
+}

package/components/lib-foxiness/lib-foxiness.css

@@ -0,0 +1 @@
+/* lib-foxiness.css */

package/components/lib-foxiness/lib-foxiness.js

@@ -0,0 +1,60 @@
+/**
+ * @scope: global
+ * @docs: This is to test data extraction for WP's.
+ * @dependencies: [lib-helpers, lib-widgets]
+ */
+
+// lib-lib-foxiness.js (Light DOM)
+export class LibFoxiness extends HTMLElement {
+  static get is() { return 'lib-foxiness'; }
+  
+  // These are the "Props" your Registry/In-situ docs will scrape
+  static get props() { 
+    return {
+      'aria-label': 'string',
+      'theme': 'primary | secondary',
+      'disabled': 'boolean'
+    };
+  };
+
+  static get observedAttributes() { 
+    return Object.keys(LibFoxiness.props); 
+  };
+
+  connectedCallback() {
+
+    if(this._initialized) return;
+    this._initialized = true;
+    this.classList.add('lib-foxiness');
+
+    // Initial attribute check
+    if(!this.hasAttribute('aria-label')) {
+      this.setAttribute('aria-label', 'Lib LibFoxiness');
+    };
+
+    // "Lego" Root Construction
+    let root = this.querySelector('.lib-foxiness__root');
+    if(!root) {
+      root = document.createElement('div');
+      root.className = 'lib-foxiness__root';
+      root.setAttribute('role', 'region');
+      const slot = document.createElement('slot');
+      root.appendChild(slot);
+      this.appendChild(root);
+    };
+
+  };
+
+  attributeChangedCallback(name, _oldVal, newVal) {
+    const root = this.querySelector('.lib-foxiness__root');
+    if(root && name === 'aria-label') {
+      root.setAttribute('aria-label', newVal || '');
+    };
+  };
+
+};
+
+// Safe Registry Handshake
+if(!customElements.get(LibFoxiness.is)) {
+  customElements.define(LibFoxiness.is, LibFoxiness);
+};

package/components/lib-foxiness/manifest.json

@@ -0,0 +1,59 @@
+{
+  "name": "lib-foxiness",
+  "type": "web-component",
+  "version": "0.1.1",
+  "description": "This is to test data extraction for WP's.",
+  "primary": {
+    "path": "lib-foxiness.js",
+    "hash": "ccc89652ee3cf755b831d0242e0830b6"
+  },
+  "files": [
+    {
+      "src": "components/lib-foxiness/lib-foxiness.js",
+      "destDir": "assets"
+    },
+    {
+      "src": "components/lib-foxiness/lib-foxiness.css",
+      "destDir": "assets"
+    }
+  ],
+  "assets": {
+    "css": [
+      "lib-foxiness.css"
+    ]
+  },
+  "props": [
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "description": ""
+    },
+    {
+      "name": "theme",
+      "type": "primary | secondary",
+      "required": false,
+      "description": ""
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "description": ""
+    }
+  ],
+  "dependencies": [
+    "lib-helpers",
+    "lib-widgets"
+  ],
+  "scope": [
+    "global"
+  ],
+  "registry": {
+    "createdAt": "2026-01-29T23:08:38.154Z",
+    "hash": "ccc89652ee3cf755b831d0242e0830b6"
+  },
+  "build": {
+    "lastAuditAt": "2026-01-30T23:12:46.892Z"
+  }
+}

package/components/lib-foxy/lib-foxy.css

@@ -0,0 +1,11 @@
+/* lib-foxy.css */
+.lib-foxy {
+  --lib-foxy-gap: 0.5rem;
+  display: block;
+}
+
+.lib-foxy__content {
+  margin-block: var(--lib-foxy-gap);
+}
+
+.lib-foxy__content--empty { opacity: 0.6; }

package/components/lib-foxy/lib-foxy.js

@@ -0,0 +1,8 @@
+// lib-lib-foxy.js (optional behavior for Liquid components)
+(() => {
+  const selector = '.lib-foxy[data-lib="foxy"]';
+  document.querySelectorAll(selector).forEach((el) => {
+    // Hook point for interactive behavior
+    // Example: el.addEventListener('click', () => {});
+  });
+})();

package/components/lib-foxy/lib-foxy.liquid

@@ -0,0 +1,45 @@
+{%- comment -%}
+Component: lib-foxy
+Type: snippet-component
+
+Props (snake_case with leading underscore):
+- _foxy_content: string (required)
+- _aria_label: string (optional)
+- _foxy_id: string (optional)
+
+Dependencies (rendered children):
+- {% render 'lib-child', _child_content: '...' %}
+
+Scope (theme contexts):
+- @scope= all
+
+Docs (inline prop descriptions):
+- @prop _empty: Describe the main content when empty.
+- @prop _test: Test for required flagging.
+
+{%- endcomment -%}
+
+{% assign _empty = 'Empty' | default: 'Empty' %}
+{% assign _test = 'Test for require flag' %}
+{% assign _agile = 'Test for require flag' | default: 'Test for require flag' %}
+{% assign test = 'Test for ommision in build' %}
+
+<div class="lib-foxy" data-lib="foxy" role="region">
+  {% render 'lib-button',
+    _button_class: "bg-red-600 text-white px-6 py-3 rounded-lg font-medium hover:bg-indigo-700 transition-colors shadow-lg",
+    _button_id: "button-id-1",
+    _button_text: "Click Me Bitch"
+  %}
+  {%- if _foxy_content -%}
+    <div class="lib-foxy__content">
+      {{ _foxy_content }}
+    </div>
+  {%- else -%}
+    <div class="lib-foxy__content lib-foxy__content--empty" aria-hidden="true">
+      {{ _empty }}
+    </div>
+  {%- endif -%}
+  {% render 'lib-footer',
+    _footer_text: 'This is the footer text'
+  %}
+</div>