@sociallane/elements 1.0.13 → 1.0.14

package/.github/workflows/npm-npx-gates.yml

@@ -0,0 +1,58 @@
+name: SocialLane npm/npx Gates
+
+on:
+  pull_request:
+    paths:
+      - 'sociallane-elements/**'
+  push:
+    branches:
+      - main
+    paths:
+      - 'sociallane-elements/**'
+  workflow_dispatch:
+
+jobs:
+  cli-smoke:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sociallane-elements
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: CLI smoke tests
+        run: node scripts/test-cli-smoke.js
+
+      - name: List command sanity check
+        run: node scripts/install.js list --json
+
+      - name: Doctor command sanity check
+        run: node scripts/install.js doctor --json --target .
+
+  release-gate:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    needs: cli-smoke
+    defaults:
+      run:
+        working-directory: sociallane-elements
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Sync canonical widget manifest
+        run: node scripts/generate-widget-manifest.js
+
+      - name: Release gate (strict)
+        run: node scripts/release-gate.js --strict

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sociallane/elements",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "Elementor widgets and elements with Tailwind CSS for SocialLane. WordPress plugin.",
   "type": "module",
   "private": false,
@@ -30,8 +30,13 @@
     "postinstall": "node scripts/postinstall.js",
     "setup": "bash scripts/setup.sh",
     "sync-widgets": "node scripts/sync-widgets.js",
+    "manifest:widgets": "node scripts/generate-widget-manifest.js",
+    "generate:widget-table": "node scripts/generate-widget-table.js",
     "build:widget-packages": "node scripts/build-widget-packages.js",
     "publish:widgets": "node scripts/build-widget-packages.js && node scripts/publish-widget-packages.js",
+    "test:cli-smoke": "node scripts/test-cli-smoke.js",
+    "release:check": "node scripts/release-gate.js --strict",
+    "release:check:local": "node scripts/release-gate.js --strict --skip-registry",
     "reinstall": "rm -rf node_modules && npm install",
     "format": "prettier --write .",
     "format:check": "prettier --check ."

package/packages/widget-manifest.json

@@ -0,0 +1,291 @@
+{
+  "schema_version": 1,
+  "generated_at": "2026-02-10T09:16:15.290Z",
+  "source": "packages/widgets",
+  "widgets": [
+    {
+      "slug": "bento-grid",
+      "package": "@sociallane/widget-bento-grid"
+    },
+    {
+      "slug": "bento-grid-4",
+      "package": "@sociallane/widget-bento-grid-4"
+    },
+    {
+      "slug": "bento-grid-5",
+      "package": "@sociallane/widget-bento-grid-5"
+    },
+    {
+      "slug": "bento-grid-6",
+      "package": "@sociallane/widget-bento-grid-6"
+    },
+    {
+      "slug": "bento-portfolio",
+      "package": "@sociallane/widget-bento-portfolio"
+    },
+    {
+      "slug": "bento-portfolio-4",
+      "package": "@sociallane/widget-bento-portfolio-4"
+    },
+    {
+      "slug": "bento-portfolio-5",
+      "package": "@sociallane/widget-bento-portfolio-5"
+    },
+    {
+      "slug": "bento-portfolio-6",
+      "package": "@sociallane/widget-bento-portfolio-6"
+    },
+    {
+      "slug": "blog-grid",
+      "package": "@sociallane/widget-blog-grid"
+    },
+    {
+      "slug": "card-hover-reveal",
+      "package": "@sociallane/widget-card-hover-reveal"
+    },
+    {
+      "slug": "client-logos",
+      "package": "@sociallane/widget-client-logos"
+    },
+    {
+      "slug": "content-block",
+      "package": "@sociallane/widget-content-block"
+    },
+    {
+      "slug": "cta-banner",
+      "package": "@sociallane/widget-cta-banner"
+    },
+    {
+      "slug": "cta-notify",
+      "package": "@sociallane/widget-cta-notify"
+    },
+    {
+      "slug": "cta-split",
+      "package": "@sociallane/widget-cta-split"
+    },
+    {
+      "slug": "faq-centered",
+      "package": "@sociallane/widget-faq-centered"
+    },
+    {
+      "slug": "faq-split",
+      "package": "@sociallane/widget-faq-split"
+    },
+    {
+      "slug": "faq-stacked",
+      "package": "@sociallane/widget-faq-stacked"
+    },
+    {
+      "slug": "feature-grid",
+      "package": "@sociallane/widget-feature-grid"
+    },
+    {
+      "slug": "feature-grid-centered",
+      "package": "@sociallane/widget-feature-grid-centered"
+    },
+    {
+      "slug": "feature-list",
+      "package": "@sociallane/widget-feature-list"
+    },
+    {
+      "slug": "feature-list-cta",
+      "package": "@sociallane/widget-feature-list-cta"
+    },
+    {
+      "slug": "footer",
+      "package": "@sociallane/widget-footer"
+    },
+    {
+      "slug": "footer-brand",
+      "package": "@sociallane/widget-footer-brand"
+    },
+    {
+      "slug": "footer-links-contact",
+      "package": "@sociallane/widget-footer-links-contact"
+    },
+    {
+      "slug": "form-contact",
+      "package": "@sociallane/widget-form-contact"
+    },
+    {
+      "slug": "grid-case-studies",
+      "package": "@sociallane/widget-grid-case-studies"
+    },
+    {
+      "slug": "grid-components",
+      "package": "@sociallane/widget-grid-components"
+    },
+    {
+      "slug": "grid-team",
+      "package": "@sociallane/widget-grid-team"
+    },
+    {
+      "slug": "hero-announcement",
+      "package": "@sociallane/widget-hero-announcement"
+    },
+    {
+      "slug": "hero-centered-image",
+      "package": "@sociallane/widget-hero-centered-image"
+    },
+    {
+      "slug": "hero-collage",
+      "package": "@sociallane/widget-hero-collage"
+    },
+    {
+      "slug": "hero-overlay",
+      "package": "@sociallane/widget-hero-overlay"
+    },
+    {
+      "slug": "hero-overlay-single",
+      "package": "@sociallane/widget-hero-overlay-single"
+    },
+    {
+      "slug": "hero-overlay-slider",
+      "package": "@sociallane/widget-hero-overlay-slider"
+    },
+    {
+      "slug": "hero-saas-centered",
+      "package": "@sociallane/widget-hero-saas-centered"
+    },
+    {
+      "slug": "hero-saas-split",
+      "package": "@sociallane/widget-hero-saas-split"
+    },
+    {
+      "slug": "hero-saas-stacked",
+      "package": "@sociallane/widget-hero-saas-stacked"
+    },
+    {
+      "slug": "hero-split",
+      "package": "@sociallane/widget-hero-split"
+    },
+    {
+      "slug": "hero-stacked-image",
+      "package": "@sociallane/widget-hero-stacked-image"
+    },
+    {
+      "slug": "intro-pattern",
+      "package": "@sociallane/widget-intro-pattern"
+    },
+    {
+      "slug": "intro-text",
+      "package": "@sociallane/widget-intro-text"
+    },
+    {
+      "slug": "logo-grid-centered",
+      "package": "@sociallane/widget-logo-grid-centered"
+    },
+    {
+      "slug": "logo-grid-row",
+      "package": "@sociallane/widget-logo-grid-row"
+    },
+    {
+      "slug": "logo-grid-split",
+      "package": "@sociallane/widget-logo-grid-split"
+    },
+    {
+      "slug": "nav-centered",
+      "package": "@sociallane/widget-nav-centered"
+    },
+    {
+      "slug": "nav-compact",
+      "package": "@sociallane/widget-nav-compact"
+    },
+    {
+      "slug": "nav-default",
+      "package": "@sociallane/widget-nav-default"
+    },
+    {
+      "slug": "nav-floating",
+      "package": "@sociallane/widget-nav-floating"
+    },
+    {
+      "slug": "nav-minimal",
+      "package": "@sociallane/widget-nav-minimal"
+    },
+    {
+      "slug": "newsletter",
+      "package": "@sociallane/widget-newsletter"
+    },
+    {
+      "slug": "newsletter-card",
+      "package": "@sociallane/widget-newsletter-card"
+    },
+    {
+      "slug": "newsletter-section",
+      "package": "@sociallane/widget-newsletter-section"
+    },
+    {
+      "slug": "outreach-dashboard",
+      "package": "@sociallane/widget-outreach-dashboard"
+    },
+    {
+      "slug": "page-hero-center",
+      "package": "@sociallane/widget-page-hero-center"
+    },
+    {
+      "slug": "page-hero-left",
+      "package": "@sociallane/widget-page-hero-left"
+    },
+    {
+      "slug": "pipeline-dashboard",
+      "package": "@sociallane/widget-pipeline-dashboard"
+    },
+    {
+      "slug": "posts-grid",
+      "package": "@sociallane/widget-posts-grid"
+    },
+    {
+      "slug": "posts-grid-overlay",
+      "package": "@sociallane/widget-posts-grid-overlay"
+    },
+    {
+      "slug": "pricing-table",
+      "package": "@sociallane/widget-pricing-table"
+    },
+    {
+      "slug": "sales-dashboard",
+      "package": "@sociallane/widget-sales-dashboard"
+    },
+    {
+      "slug": "section-stats",
+      "package": "@sociallane/widget-section-stats"
+    },
+    {
+      "slug": "services",
+      "package": "@sociallane/widget-services"
+    },
+    {
+      "slug": "simple-page-hero",
+      "package": "@sociallane/widget-simple-page-hero"
+    },
+    {
+      "slug": "social-proof",
+      "package": "@sociallane/widget-social-proof"
+    },
+    {
+      "slug": "social-proof-trust",
+      "package": "@sociallane/widget-social-proof-trust"
+    },
+    {
+      "slug": "testimonial-quote",
+      "package": "@sociallane/widget-testimonial-quote"
+    },
+    {
+      "slug": "testimonials-bento",
+      "package": "@sociallane/widget-testimonials-bento"
+    },
+    {
+      "slug": "testimonials-grid",
+      "package": "@sociallane/widget-testimonials-grid"
+    },
+    {
+      "slug": "testimonials-masonry",
+      "package": "@sociallane/widget-testimonials-masonry"
+    },
+    {
+      "slug": "widget-filter",
+      "package": "@sociallane/widget-widget-filter"
+    }
+  ]
+}

package/scripts/build-widget-packages.js

@@ -5,27 +5,15 @@
  * Run from plugin root: npm run build:widget-packages
  */
 
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { getWidgetSourceDir, syncWidgetManifest } from './lib/widgets-manifest.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pluginRoot = path.resolve(__dirname, '..');
-const widgetsDir = path.join(pluginRoot, 'packages', 'widgets');
 const npmWidgetsDir = path.join(pluginRoot, 'packages', 'npm-widgets');
-
-function getWidgetSlugs() {
-  if (!existsSync(widgetsDir)) return [];
-  const entries = readdirSync(widgetsDir, { withFileTypes: true });
-  const slugs = [];
-  for (const ent of entries) {
-    if (!ent.isDirectory()) continue;
-    const slug = ent.name;
-    const phpFile = path.join(widgetsDir, slug, `${slug}.php`);
-    if (existsSync(phpFile)) slugs.push(slug);
-  }
-  return slugs.sort((a, b) => a.localeCompare(b));
-}
+const widgetsDir = getWidgetSourceDir(pluginRoot);
 
 function getRootVersion() {
   const pkgPath = path.join(pluginRoot, 'package.json');
@@ -79,7 +67,8 @@ This installs the SocialLane Elements plugin if needed, then adds this widget an
 }
 
 function main() {
-  const slugs = getWidgetSlugs();
+  const manifest = syncWidgetManifest(pluginRoot);
+  const slugs = manifest.widgets.map((widget) => widget.slug);
   const version = getRootVersion();
   if (!existsSync(npmWidgetsDir)) mkdirSync(npmWidgetsDir, { recursive: true });
   for (const slug of slugs) {

package/scripts/generate-widget-manifest.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Generate packages/widget-manifest.json from widget sources on disk.
+ * Run from plugin root: npm run manifest:widgets
+ */
+
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { syncWidgetManifest, getWidgetManifestPath } from './lib/widgets-manifest.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = path.resolve(__dirname, '..');
+
+const manifest = syncWidgetManifest(pluginRoot);
+const manifestPath = getWidgetManifestPath(pluginRoot);
+
+console.log(
+  `Widget manifest updated: ${manifest.widgets.length} widgets (${manifest.source}) -> ${manifestPath}`
+);

package/scripts/generate-widget-table.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Generate a markdown table from the canonical widget manifest.
+ * Prints to stdout by default, or write to --out <path>.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { loadWidgetManifest } from './lib/widgets-manifest.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = path.resolve(__dirname, '..');
+
+function parseOutPath(args) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== '--out') continue;
+    const value = args[i + 1];
+    if (!value || value.startsWith('-')) {
+      console.error('Missing value for --out');
+      process.exit(1);
+    }
+    return value;
+  }
+  return '';
+}
+
+function buildMarkdownTable(manifest) {
+  const lines = [];
+  lines.push('| Widget | Package | Command |');
+  lines.push('|--------|---------|---------|');
+
+  for (const widget of manifest.widgets) {
+    lines.push(
+      `| ${widget.slug} | \`${widget.package}\` | \`npm install ${widget.package}\` |`
+    );
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const out = parseOutPath(args);
+  const manifest = loadWidgetManifest(pluginRoot);
+  const table = buildMarkdownTable(manifest);
+
+  if (!out) {
+    process.stdout.write(table);
+    return;
+  }
+
+  const outPath = path.resolve(process.cwd(), out);
+  const outDir = path.dirname(outPath);
+  if (!existsSync(outDir)) {
+    mkdirSync(outDir, { recursive: true });
+  }
+
+  writeFileSync(outPath, table, 'utf8');
+  console.log(`Widget table generated: ${outPath}`);
+}
+
+main();

package/scripts/install.js

@@ -5,6 +5,8 @@
  * Install (base):  npx @sociallane/elements --base [path]
  * Install (full):  npx @sociallane/elements [path]
  * Add widgets:     npx @sociallane/elements add <slug> [slug...]
+ * List widgets:    npx @sociallane/elements list [--json]
+ * Doctor checks:   npx @sociallane/elements doctor [--target <path>] [--json]
  *
  * Install: copies package to wp-content/plugins/sociallane-elements (or path), runs npm install.
  * Base install: installs core/deps and keeps widgets.json empty (no widgets loaded by default).
@@ -15,6 +17,7 @@ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync
 import { spawnSync } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { getWidgetSourceDir, loadWidgetManifest } from './lib/widgets-manifest.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, '..');
@@ -35,6 +38,8 @@ function printHelp() {
   console.log('Usage:');
   console.log('  npx @sociallane/elements [--base|--minimal] [target]');
   console.log('  npx @sociallane/elements add [--only] [--target <path>] <slug> [slug...]');
+  console.log('  npx @sociallane/elements list [--json]');
+  console.log('  npx @sociallane/elements doctor [--target <path>] [--json]');
   console.log('  npx @sociallane/elements --help');
   console.log('  npx @sociallane/elements --version');
   console.log('');
@@ -42,6 +47,7 @@ function printHelp() {
   console.log('  --base, --minimal   Install core/deps only, keep widgets.json empty');
   console.log('  --only              With add: replace widgets.json with exactly provided slugs');
   console.log('  --target <path>     With add: explicit plugin directory target');
+  console.log('  --json              With list/doctor: output machine-readable JSON');
   console.log('  --help              Show this help text');
   console.log('  --version           Show CLI version');
   console.log('');
@@ -49,6 +55,8 @@ function printHelp() {
   console.log('  npx @sociallane/elements --base');
   console.log('  npx @sociallane/elements add faq-stacked hero-split');
   console.log('  npx @sociallane/elements add --only --target wp-content/plugins/sociallane-elements content-block');
+  console.log('  npx @sociallane/elements list');
+  console.log('  npx @sociallane/elements doctor --target wp-content/plugins/sociallane-elements');
 }
 
 function resolvePluginDir(targetPath = '') {
@@ -79,23 +87,7 @@ function resolvePluginDir(targetPath = '') {
 }
 
 function getWidgetsSourceDir() {
-  const candidates = [
-    path.join(packageRoot, 'packages', 'widgets'),
-    path.join(packageRoot, 'widgets'),
-  ];
-
-  for (const dir of candidates) {
-    if (!existsSync(dir)) {
-      continue;
-    }
-    const available = readdirSync(dir, { withFileTypes: true })
-      .filter((d) => d.isDirectory() && existsSync(path.join(dir, d.name, `${d.name}.php`)))
-      .map((d) => d.name);
-    if (available.length > 0) {
-      return dir;
-    }
-  }
-  return candidates[0];
+  return getWidgetSourceDir(packageRoot);
 }
 
 function updateWidgetsJson(pluginDir, slugsToAdd, replaceAll = false) {
@@ -196,6 +188,144 @@ function addWidgets(slugs, options = {}) {
   console.log('Done. Widgets added:', slugs.join(', '));
 }
 
+function listWidgets(options = {}) {
+  const asJson = options.asJson === true;
+  const manifest = loadWidgetManifest(packageRoot);
+  const slugs = manifest.widgets.map((widget) => widget.slug);
+
+  if (asJson) {
+    console.log(
+      JSON.stringify(
+        {
+          count: slugs.length,
+          source: manifest.source || null,
+          widgets: slugs,
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  if (slugs.length === 0) {
+    console.log('No widgets found.');
+    return;
+  }
+
+  console.log(slugs.join('\n'));
+  console.log('');
+  console.log(`Total: ${slugs.length}`);
+}
+
+function checkCommandVersion(command, args = ['--version']) {
+  const result = spawnSync(command, args, {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    shell: true,
+  });
+  return {
+    ok: result.status === 0,
+    output: (result.stdout || result.stderr || '').trim(),
+  };
+}
+
+function runDoctor(options = {}) {
+  const asJson = options.asJson === true;
+  const targetPath = options.targetPath || '';
+  const targetPlugin = resolvePluginDir(targetPath);
+  const checks = [];
+
+  const nodeVersion = process.version || '';
+  checks.push({
+    name: 'Node.js',
+    ok: nodeVersion !== '',
+    detail: nodeVersion || 'not detected',
+  });
+
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const npm = checkCommandVersion(npmCmd);
+  checks.push({
+    name: 'npm',
+    ok: npm.ok,
+    detail: npm.ok ? npm.output : `not available (${npm.output || 'command failed'})`,
+  });
+
+  const pluginExists = existsSync(targetPlugin);
+  checks.push({
+    name: 'Plugin directory',
+    ok: pluginExists,
+    detail: targetPlugin,
+  });
+
+  const bootstrapPath = path.join(targetPlugin, 'sociallane-elements.php');
+  checks.push({
+    name: 'Plugin bootstrap',
+    ok: existsSync(bootstrapPath),
+    detail: bootstrapPath,
+  });
+
+  const corePath = path.join(targetPlugin, 'packages', 'core');
+  checks.push({
+    name: 'Core package',
+    ok: existsSync(corePath),
+    detail: corePath,
+  });
+
+  const widgetsPath = path.join(targetPlugin, 'packages', 'widgets');
+  const legacyWidgetsPath = path.join(targetPlugin, 'widgets');
+  checks.push({
+    name: 'Widgets source',
+    ok: existsSync(widgetsPath) || existsSync(legacyWidgetsPath),
+    detail: existsSync(widgetsPath) ? widgetsPath : legacyWidgetsPath,
+  });
+
+  const widgetsJsonPath = path.join(targetPlugin, 'widgets.json');
+  let widgetsJsonValid = false;
+  let widgetsCount = 0;
+  if (existsSync(widgetsJsonPath)) {
+    try {
+      const raw = readFileSync(widgetsJsonPath, 'utf8');
+      const parsed = JSON.parse(raw);
+      widgetsJsonValid = Array.isArray(parsed?.widgets);
+      if (widgetsJsonValid) {
+        widgetsCount = parsed.widgets.length;
+      }
+    } catch {
+      widgetsJsonValid = false;
+    }
+  }
+  checks.push({
+    name: 'widgets.json',
+    ok: existsSync(widgetsJsonPath) && widgetsJsonValid,
+    detail: existsSync(widgetsJsonPath)
+      ? `${widgetsJsonPath} (${widgetsCount} widgets)`
+      : `${widgetsJsonPath} (missing)`,
+  });
+
+  const summary = {
+    target: targetPlugin,
+    ok: checks.every((check) => check.ok),
+    checks,
+  };
+
+  if (asJson) {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log('SocialLane Elements doctor');
+    console.log(`Target: ${summary.target}`);
+    console.log('');
+    for (const check of checks) {
+      const status = check.ok ? 'OK' : 'FAIL';
+      console.log(`[${status}] ${check.name}: ${check.detail}`);
+    }
+  }
+
+  if (!summary.ok) {
+    process.exit(1);
+  }
+}
+
 function prepareBaseMode(pluginDir) {
   const widgetsDest = path.join(pluginDir, 'packages', 'widgets');
   if (!existsSync(widgetsDest)) {
@@ -334,6 +464,53 @@ function main() {
     return;
   }
 
+  if (args[0] === 'list') {
+    const listArgs = args.slice(1).filter(Boolean);
+    const knownListFlags = new Set(['--json']);
+    for (const arg of listArgs) {
+      if (!arg.startsWith('-')) {
+        console.error('Usage: npx @sociallane/elements list [--json]');
+        process.exit(1);
+      }
+      if (!knownListFlags.has(arg)) {
+        console.error('Unknown option for list:', arg);
+        process.exit(1);
+      }
+    }
+    listWidgets({ asJson: listArgs.includes('--json') });
+    return;
+  }
+
+  if (args[0] === 'doctor') {
+    const doctorArgs = args.slice(1).filter(Boolean);
+    const knownDoctorFlags = new Set(['--target', '--json']);
+    let targetPath = '';
+    for (let i = 0; i < doctorArgs.length; i++) {
+      const arg = doctorArgs[i];
+      if (arg === '--target') {
+        const next = doctorArgs[i + 1];
+        if (!next || next.startsWith('-')) {
+          console.error('Missing value for --target');
+          process.exit(1);
+        }
+        targetPath = next;
+        i++;
+        continue;
+      }
+      if (arg.startsWith('-')) {
+        if (!knownDoctorFlags.has(arg)) {
+          console.error('Unknown option for doctor:', arg);
+          process.exit(1);
+        }
+        continue;
+      }
+      console.error('Usage: npx @sociallane/elements doctor [--target <path>] [--json]');
+      process.exit(1);
+    }
+    runDoctor({ targetPath, asJson: doctorArgs.includes('--json') });
+    return;
+  }
+
   if (args[0] === 'add') {
     const addArgs = args.slice(1).filter(Boolean);
     const knownAddFlags = new Set(['--only', '--target']);

package/scripts/lib/widgets-manifest.js

@@ -0,0 +1,163 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import path from 'path';
+
+export const WIDGET_MANIFEST_RELATIVE_PATH = 'packages/widget-manifest.json';
+
+function normalizeSlug(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function uniqueSortedSlugs(slugs) {
+  return [...new Set(slugs.map(normalizeSlug).filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+
+function normalizeSourcePath(pluginRoot, sourceDir) {
+  const relative = path.relative(pluginRoot, sourceDir).split(path.sep).join('/');
+  return relative === '' ? '.' : relative;
+}
+
+function normalizeManifestWidget(entry) {
+  if (typeof entry === 'string') {
+    const slug = normalizeSlug(entry);
+    if (!slug) return null;
+    return { slug, package: `@sociallane/widget-${slug}` };
+  }
+
+  if (!entry || typeof entry !== 'object') {
+    return null;
+  }
+
+  const slug = normalizeSlug(entry.slug);
+  if (!slug) {
+    return null;
+  }
+
+  const pkg =
+    typeof entry.package === 'string' && entry.package.trim() !== ''
+      ? entry.package.trim()
+      : `@sociallane/widget-${slug}`;
+
+  return { slug, package: pkg };
+}
+
+export function getWidgetSourceDir(pluginRoot) {
+  const candidates = [path.join(pluginRoot, 'packages', 'widgets'), path.join(pluginRoot, 'widgets')];
+
+  for (const dir of candidates) {
+    if (!existsSync(dir)) {
+      continue;
+    }
+
+    const hasWidgets = readdirSync(dir, { withFileTypes: true }).some((entry) => {
+      if (!entry.isDirectory()) return false;
+      return existsSync(path.join(dir, entry.name, `${entry.name}.php`));
+    });
+
+    if (hasWidgets) {
+      return dir;
+    }
+  }
+
+  for (const dir of candidates) {
+    if (existsSync(dir)) {
+      return dir;
+    }
+  }
+
+  return candidates[0];
+}
+
+export function getWidgetSlugsFromSource(pluginRoot) {
+  const sourceDir = getWidgetSourceDir(pluginRoot);
+  if (!existsSync(sourceDir)) {
+    return [];
+  }
+
+  const slugs = readdirSync(sourceDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(path.join(sourceDir, entry.name, `${entry.name}.php`)))
+    .map((entry) => entry.name);
+
+  return uniqueSortedSlugs(slugs);
+}
+
+export function buildWidgetManifest(pluginRoot) {
+  const sourceDir = getWidgetSourceDir(pluginRoot);
+  const slugs = getWidgetSlugsFromSource(pluginRoot);
+
+  return {
+    schema_version: 1,
+    generated_at: new Date().toISOString(),
+    source: normalizeSourcePath(pluginRoot, sourceDir),
+    widgets: slugs.map((slug) => ({
+      slug,
+      package: `@sociallane/widget-${slug}`,
+    })),
+  };
+}
+
+export function getWidgetManifestPath(pluginRoot) {
+  return path.join(pluginRoot, WIDGET_MANIFEST_RELATIVE_PATH);
+}
+
+export function readWidgetManifest(pluginRoot) {
+  const manifestPath = getWidgetManifestPath(pluginRoot);
+  if (!existsSync(manifestPath)) {
+    return null;
+  }
+
+  try {
+    const raw = readFileSync(manifestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+
+    const widgets = Array.isArray(parsed.widgets) ? parsed.widgets.map(normalizeManifestWidget).filter(Boolean) : [];
+    const uniqueSlugs = uniqueSortedSlugs(widgets.map((widget) => widget.slug));
+    const widgetsBySlug = new Map(widgets.map((widget) => [widget.slug, widget.package]));
+
+    return {
+      schema_version: typeof parsed.schema_version === 'number' ? parsed.schema_version : 1,
+      generated_at: typeof parsed.generated_at === 'string' ? parsed.generated_at : null,
+      source: typeof parsed.source === 'string' ? parsed.source : null,
+      widgets: uniqueSlugs.map((slug) => ({
+        slug,
+        package: widgetsBySlug.get(slug) || `@sociallane/widget-${slug}`,
+      })),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeWidgetManifest(pluginRoot, manifest) {
+  const manifestPath = getWidgetManifestPath(pluginRoot);
+  const manifestDir = path.dirname(manifestPath);
+  if (!existsSync(manifestDir)) {
+    mkdirSync(manifestDir, { recursive: true });
+  }
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+  return manifestPath;
+}
+
+export function syncWidgetManifest(pluginRoot) {
+  const manifest = buildWidgetManifest(pluginRoot);
+  writeWidgetManifest(pluginRoot, manifest);
+  return manifest;
+}
+
+export function loadWidgetManifest(pluginRoot, options = {}) {
+  const preferSource = options.preferSource === true;
+  if (!preferSource) {
+    const fromDisk = readWidgetManifest(pluginRoot);
+    if (fromDisk) {
+      return fromDisk;
+    }
+  }
+  return buildWidgetManifest(pluginRoot);
+}
+
+export function getWidgetSlugsFromManifest(pluginRoot, options = {}) {
+  const manifest = loadWidgetManifest(pluginRoot, options);
+  return manifest.widgets.map((widget) => widget.slug);
+}

package/scripts/publish-widget-packages.js

@@ -9,6 +9,7 @@ import { readdirSync, existsSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
+import { readWidgetManifest } from './lib/widgets-manifest.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pluginRoot = path.resolve(__dirname, '..');
@@ -19,10 +20,27 @@ if (!existsSync(npmWidgetsDir)) {
   process.exit(1);
 }
 
-const dirs = readdirSync(npmWidgetsDir, { withFileTypes: true })
+const manifest = readWidgetManifest(pluginRoot);
+if (!manifest || !Array.isArray(manifest.widgets) || manifest.widgets.length === 0) {
+  console.error('Widget manifest not found or empty. Run npm run sync-widgets first.');
+  process.exit(1);
+}
+
+const manifestSlugs = manifest.widgets.map((widget) => widget.slug).sort((a, b) => a.localeCompare(b));
+const availableDirs = readdirSync(npmWidgetsDir, { withFileTypes: true })
   .filter((d) => d.isDirectory())
-  .map((d) => d.name)
-  .sort((a, b) => a.localeCompare(b));
+  .map((d) => d.name);
+const dirs = manifestSlugs.filter((slug) => availableDirs.includes(slug));
+
+const missingBuiltPackages = manifestSlugs.filter((slug) => !availableDirs.includes(slug));
+if (missingBuiltPackages.length > 0) {
+  console.error(
+    'Missing built widget packages in packages/npm-widgets/:',
+    missingBuiltPackages.slice(0, 20).join(', ') + (missingBuiltPackages.length > 20 ? '...' : '')
+  );
+  console.error('Run npm run build:widget-packages first.');
+  process.exit(1);
+}
 
 if (dirs.length === 0) {
   console.error('No widget packages in packages/npm-widgets/');

package/scripts/release-gate.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * Release gate checks:
+ * - canonical widget manifest exists and matches widget folders
+ * - CLI sample slugs in install.js exist in manifest
+ * - npm registry versions match root package version (strict mode)
+ *
+ * Usage:
+ *   node scripts/release-gate.js --strict
+ *   node scripts/release-gate.js --strict --skip-registry
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+import { getWidgetSlugsFromSource, readWidgetManifest, syncWidgetManifest } from './lib/widgets-manifest.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = path.resolve(__dirname, '..');
+const args = process.argv.slice(2);
+const strict = args.includes('--strict');
+const skipRegistry = args.includes('--skip-registry');
+
+function runNpmViewVersion(pkgName) {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const result = spawnSync(
+    npmCmd,
+    ['view', pkgName, 'version', '--registry=https://registry.npmjs.org', '--loglevel=error'],
+    {
+      cwd: pluginRoot,
+      encoding: 'utf8',
+      shell: true,
+    }
+  );
+
+  if (result.status !== 0) {
+    const stderr = (result.stderr || '')
+      .split('\n')
+      .map((line) => line.trim())
+      .find((line) => line !== '');
+    return { ok: false, version: null, error: stderr || 'npm view failed' };
+  }
+
+  const version = (result.stdout || '').trim().split('\n').pop().trim();
+  if (!version) {
+    return { ok: false, version: null, error: 'empty version response' };
+  }
+
+  return { ok: true, version, error: null };
+}
+
+function getRootVersion() {
+  const packageJsonPath = path.join(pluginRoot, 'package.json');
+  const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+  return typeof pkg.version === 'string' ? pkg.version : '';
+}
+
+function checkCliExampleSlugs(manifestSlugs, issues) {
+  const installScriptPath = path.join(pluginRoot, 'scripts', 'install.js');
+  if (!existsSync(installScriptPath)) {
+    issues.push('scripts/install.js not found for CLI example validation.');
+    return;
+  }
+
+  const content = readFileSync(installScriptPath, 'utf8');
+  const expectedSampleSlugs = ['faq-stacked', 'hero-split', 'content-block'];
+
+  for (const slug of expectedSampleSlugs) {
+    if (!manifestSlugs.includes(slug)) {
+      issues.push(`CLI sample slug "${slug}" is not present in canonical widget manifest.`);
+    }
+  }
+
+  if (!content.includes('npx @sociallane/elements add')) {
+    issues.push('CLI help examples do not include add command examples.');
+  }
+}
+
+function checkDocumentationExamples(manifestSlugs, manifestPackages, issues) {
+  const docsFiles = [
+    path.join(pluginRoot, 'docs', 'install-new-instance.md'),
+    path.join(pluginRoot, 'docs', 'package-installation.md'),
+    path.join(pluginRoot, 'docs', 'npm-widget-cheatsheet.md'),
+  ];
+
+  for (const docsFile of docsFiles) {
+    if (!existsSync(docsFile)) {
+      continue;
+    }
+
+    const content = readFileSync(docsFile, 'utf8');
+
+    // Validate widget package references in docs.
+    const packageMatches = content.match(/@sociallane\/widget-[a-z0-9-]+/g) || [];
+    for (const pkg of packageMatches) {
+      if (!manifestPackages.has(pkg)) {
+        issues.push(`Docs reference unknown widget package "${pkg}" (${path.basename(docsFile)}).`);
+      }
+    }
+
+    // Validate npx add slug examples in docs.
+    const addCommandMatches =
+      content.match(/npx\s+@sociallane\/elements\s+add(?:\s+--[a-z-]+(?:\s+[^\s`]+)?)*\s+[a-z0-9-][^\n`]*/g) || [];
+    for (const cmd of addCommandMatches) {
+      const parts = cmd.split(/\s+/).slice(3); // strip: npx @sociallane/elements add
+      const slugs = parts.filter((part, idx) => {
+        if (!part || part.startsWith('--')) return false;
+        // Skip values for --target
+        const prev = parts[idx - 1];
+        if (prev === '--target') return false;
+        return /^[a-z0-9-]+$/.test(part);
+      });
+
+      for (const slug of slugs) {
+        if (/^slug\d*$/i.test(slug)) {
+          continue; // placeholder tokens in docs examples
+        }
+        if (!manifestSlugs.has(slug)) {
+          issues.push(`Docs add command references unknown slug "${slug}" (${path.basename(docsFile)}).`);
+        }
+      }
+    }
+  }
+}
+
+function main() {
+  const issues = [];
+
+  // Keep manifest current as part of the gate.
+  syncWidgetManifest(pluginRoot);
+  const manifest = readWidgetManifest(pluginRoot);
+  if (!manifest || !Array.isArray(manifest.widgets) || manifest.widgets.length === 0) {
+    issues.push('Widget manifest is missing or empty. Run npm run manifest:widgets.');
+  }
+
+  const manifestSlugs = manifest ? manifest.widgets.map((widget) => widget.slug) : [];
+  const manifestSlugSet = new Set(manifestSlugs);
+  const manifestPackageSet = new Set((manifest?.widgets ?? []).map((widget) => widget.package));
+  const sourceSlugs = getWidgetSlugsFromSource(pluginRoot);
+
+  if (manifestSlugs.length !== sourceSlugs.length) {
+    issues.push(
+      `Manifest/source widget count mismatch (manifest=${manifestSlugs.length}, source=${sourceSlugs.length}).`
+    );
+  }
+
+  const missingInManifest = sourceSlugs.filter((slug) => !manifestSlugs.includes(slug));
+  if (missingInManifest.length > 0) {
+    issues.push(`Widget slugs missing in manifest: ${missingInManifest.slice(0, 20).join(', ')}`);
+  }
+
+  const missingInSource = manifestSlugs.filter((slug) => !sourceSlugs.includes(slug));
+  if (missingInSource.length > 0) {
+    issues.push(`Manifest contains missing widget folders: ${missingInSource.slice(0, 20).join(', ')}`);
+  }
+
+  checkCliExampleSlugs(manifestSlugs, issues);
+  checkDocumentationExamples(manifestSlugSet, manifestPackageSet, issues);
+
+  const rootVersion = getRootVersion();
+  if (!rootVersion) {
+    issues.push('Could not determine root package version from package.json.');
+  }
+
+  if (strict && !skipRegistry) {
+    console.log(`Checking npm registry versions against @sociallane/elements@${rootVersion}...`);
+
+    const rootPkg = '@sociallane/elements';
+    const rootVersionCheck = runNpmViewVersion(rootPkg);
+    if (!rootVersionCheck.ok) {
+      issues.push(`${rootPkg}: ${rootVersionCheck.error}`);
+    } else if (rootVersionCheck.version !== rootVersion) {
+      issues.push(`${rootPkg} version mismatch (registry=${rootVersionCheck.version}, local=${rootVersion}).`);
+    }
+
+    for (const widget of manifest?.widgets ?? []) {
+      const view = runNpmViewVersion(widget.package);
+      if (!view.ok) {
+        issues.push(`${widget.package}: ${view.error}`);
+        continue;
+      }
+      if (view.version !== rootVersion) {
+        issues.push(`${widget.package} version mismatch (registry=${view.version}, expected=${rootVersion}).`);
+      }
+    }
+  }
+
+  if (issues.length > 0) {
+    console.error('Release gate failed:');
+    for (const issue of issues) {
+      console.error(`- ${issue}`);
+    }
+    process.exit(1);
+  }
+
+  console.log(`Release gate passed (${manifestSlugs.length} widgets validated).`);
+}
+
+main();

package/scripts/sync-widgets.js

@@ -10,28 +10,15 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { getWidgetSlugsFromSource, syncWidgetManifest } from './lib/widgets-manifest.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const PLUGIN_ROOT = path.resolve(__dirname, '..');
-const WIDGETS_DIR = path.join(PLUGIN_ROOT, 'packages', 'widgets');
 const WIDGETS_JSON = path.join(PLUGIN_ROOT, 'widgets.json');
 
 function getSlugsOnDisk() {
-	if (!fs.existsSync(WIDGETS_DIR)) {
-		return [];
-	}
-	const entries = fs.readdirSync(WIDGETS_DIR, { withFileTypes: true });
-	const slugs = [];
-	for (const ent of entries) {
-		if (!ent.isDirectory()) continue;
-		const slug = ent.name;
-		const phpFile = path.join(WIDGETS_DIR, slug, `${slug}.php`);
-		if (fs.existsSync(phpFile)) {
-			slugs.push(slug);
-		}
-	}
-	return slugs.sort((a, b) => a.localeCompare(b));
+	return getWidgetSlugsFromSource(PLUGIN_ROOT);
 }
 
 function getExistingSlugs() {
@@ -64,6 +51,11 @@ function main() {
 	if (added > 0 || removed > 0) {
 		console.log(`widgets.json updated: ${added} added, ${removed} removed. Total: ${widgets.length}`);
 	}
+
+	const manifest = syncWidgetManifest(PLUGIN_ROOT);
+	if (added > 0 || removed > 0) {
+		console.log(`widget manifest synced: ${manifest.widgets.length} widgets.`);
+	}
 }
 
 main();

package/scripts/test-cli-smoke.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * CLI smoke tests for scripts/install.js.
+ * Uses a fake npm binary so tests run quickly and offline.
+ */
+
+import assert from 'assert/strict';
+import { chmodSync, existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = path.resolve(__dirname, '..');
+const cliPath = path.join(pluginRoot, 'scripts', 'install.js');
+
+function fail(message, extra = '') {
+  const details = extra ? `\n${extra}` : '';
+  throw new Error(`${message}${details}`);
+}
+
+function runCli(args, options = {}) {
+  const result = spawnSync(process.execPath, [cliPath, ...args], {
+    cwd: options.cwd || pluginRoot,
+    env: options.env || process.env,
+    encoding: 'utf8',
+  });
+  return result;
+}
+
+function createFakeNpmBin(rootDir) {
+  const binDir = path.join(rootDir, 'fake-bin');
+  mkdirSync(binDir, { recursive: true });
+
+  const npmPath = path.join(binDir, 'npm');
+  writeFileSync(
+    npmPath,
+    [
+      '#!/usr/bin/env sh',
+      'echo "fake npm $@" >> "$FAKE_NPM_LOG"',
+      'exit 0',
+      '',
+    ].join('\n'),
+    'utf8'
+  );
+  chmodSync(npmPath, 0o755);
+
+  return binDir;
+}
+
+function main() {
+  const tempRoot = mkdtempSync(path.join(os.tmpdir(), 'sociallane-cli-smoke-'));
+
+  try {
+    const fakeLog = path.join(tempRoot, 'fake-npm.log');
+    const fakeBin = createFakeNpmBin(tempRoot);
+    const env = {
+      ...process.env,
+      PATH: `${fakeBin}${path.delimiter}${process.env.PATH || ''}`,
+      FAKE_NPM_LOG: fakeLog,
+      SOCIALLANE_SKIP_SYNC_WIDGETS: '1',
+    };
+
+    // 1) help exits successfully
+    const help = runCli(['--help'], { env });
+    assert.equal(help.status, 0, `--help failed: ${help.stderr}`);
+    assert.match(help.stdout, /SocialLane Elements CLI/, '--help output missing CLI header');
+
+    // 2) unknown flag fails
+    const bad = runCli(['--not-a-real-flag'], { env });
+    assert.notEqual(bad.status, 0, 'Unknown flag should fail');
+
+    // 3) base install creates plugin with empty widgets.json and no imported widgets
+    const wpRoot = path.join(tempRoot, 'site');
+    const pluginDir = path.join(wpRoot, 'wp-content', 'plugins', 'sociallane-elements');
+    const base = runCli(['--base', pluginDir], { cwd: tempRoot, env });
+    assert.equal(base.status, 0, `--base failed:\n${base.stdout}\n${base.stderr}`);
+
+    const widgetsJsonPath = path.join(pluginDir, 'widgets.json');
+    assert.equal(existsSync(path.join(pluginDir, 'sociallane-elements.php')), true, 'Plugin bootstrap missing');
+    assert.equal(existsSync(widgetsJsonPath), true, 'widgets.json missing after base install');
+
+    const widgetsJson = JSON.parse(readFileSync(widgetsJsonPath, 'utf8'));
+    assert.deepEqual(widgetsJson.widgets, [], 'Base install should keep widgets.json empty');
+
+    const widgetsPackagesDir = path.join(pluginDir, 'packages', 'widgets');
+    assert.equal(existsSync(widgetsPackagesDir), true, 'packages/widgets should exist after base install');
+    const widgetsAfterBase = readdirSync(widgetsPackagesDir, { withFileTypes: true }).filter((entry) =>
+      entry.isDirectory()
+    );
+    assert.equal(widgetsAfterBase.length, 0, 'Base install should not import widget component folders');
+
+    // 4) add with explicit --target from one directory above plugins
+    const fromWpContent = path.join(wpRoot, 'wp-content');
+    const addTarget = runCli(['add', '--target', pluginDir, 'faq-stacked', 'hero-split'], {
+      cwd: fromWpContent,
+      env,
+    });
+    assert.equal(addTarget.status, 0, `add --target failed:\n${addTarget.stdout}\n${addTarget.stderr}`);
+
+    const widgetsJsonAfterAdd = JSON.parse(readFileSync(widgetsJsonPath, 'utf8'));
+    assert.deepEqual(
+      widgetsJsonAfterAdd.widgets,
+      ['faq-stacked', 'hero-split'],
+      'add --target should set selected slugs'
+    );
+
+    assert.equal(
+      existsSync(path.join(pluginDir, 'packages', 'widgets', 'faq-stacked', 'faq-stacked.php')),
+      true,
+      'faq-stacked folder missing after add'
+    );
+    assert.equal(
+      existsSync(path.join(pluginDir, 'packages', 'widgets', 'hero-split', 'hero-split.php')),
+      true,
+      'hero-split folder missing after add'
+    );
+
+    // 5) add without --target from wp-content should auto-resolve plugin dir
+    const addAuto = runCli(['add', 'content-block'], { cwd: fromWpContent, env });
+    assert.equal(addAuto.status, 0, `add (auto target) failed:\n${addAuto.stdout}\n${addAuto.stderr}`);
+
+    const widgetsJsonAfterAuto = JSON.parse(readFileSync(widgetsJsonPath, 'utf8'));
+    assert.deepEqual(
+      widgetsJsonAfterAuto.widgets,
+      ['faq-stacked', 'hero-split', 'content-block'],
+      'auto target add should append slug'
+    );
+
+    if (!existsSync(fakeLog)) {
+      fail('Fake npm was never invoked');
+    }
+
+    console.log('CLI smoke tests passed.');
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+main();