sliderpro-agentic-skills-etch 0.1.2 → 0.2.1

package/bin/cli.js

@@ -1,14 +1,33 @@
 #!/usr/bin/env node
 
-import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+// Installs the Slider Pro AI Connector skills into a project.
+//
+// The skills live in the docs repo and change more often than this package is
+// published, so the current files are fetched at install time and the bundled
+// copy is only a fallback for when the network is unavailable. Fetching is
+// all-or-nothing: a partial fetch would mix a new skills file with stale
+// component docs, which is worse than either source on its own.
+
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  applyRewrites,
+  DEFAULT_REF,
+  looksLikeMarkdown,
+  OUT_COMPONENTS_DIR,
+  OUT_SKILLS_DIR,
+  rawUrl,
+  REPO,
+  REPO_MANIFEST,
+} from "../lib/skills-source.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
-const sourceRoot = join(packageRoot, "skills-package");
+const bundleRoot = join(packageRoot, "skills-package");
 
-const DIRS = ["slider-skills", "components"];
+const DIRS = [OUT_SKILLS_DIR, OUT_COMPONENTS_DIR];
+const TIMEOUT_MS = 10000;
 
 function printHelp() {
   console.log(`
@@ -18,27 +37,37 @@ Usage:
   npx sliderpro-agentic-skills-etch [directory] [options]
 
 Options:
-  --force, -f    Overwrite existing slider-skills/ or components/
-  --help, -h     Show this help message
+  --force, -f     Overwrite existing slider-skills/ or components/
+  --offline       Skip the network and install the copy bundled with this package
+  --ref <ref>     Install from a branch or tag (default: ${DEFAULT_REF})
+  --help, -h      Show this help message
+
+By default the current skills are fetched from ${REPO} so they are never
+older than this package. Without a network the bundled copy is used instead.
 
 Examples:
   npx sliderpro-agentic-skills-etch
   npx sliderpro-agentic-skills-etch ./my-site-project
-  npx sliderpro-agentic-skills-etch --force
+  npx sliderpro-agentic-skills-etch --offline --force
 `);
 }
 
 function parseArgs(argv) {
-  const options = { force: false, help: false, target: process.cwd() };
-
-  for (const arg of argv) {
-    if (arg === "--help" || arg === "-h") {
-      options.help = true;
-    } else if (arg === "--force" || arg === "-f") {
-      options.force = true;
-    } else if (!arg.startsWith("-")) {
-      options.target = resolve(arg);
-    } else {
+  const options = { force: false, help: false, offline: false, ref: DEFAULT_REF, target: process.cwd() };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") options.help = true;
+    else if (arg === "--force" || arg === "-f") options.force = true;
+    else if (arg === "--offline") options.offline = true;
+    else if (arg === "--ref") {
+      options.ref = argv[++i];
+      if (!options.ref) {
+        console.error("--ref needs a branch or tag name");
+        process.exit(1);
+      }
+    } else if (!arg.startsWith("-")) options.target = resolve(arg);
+    else {
       console.error(`Unknown option: ${arg}`);
       printHelp();
       process.exit(1);
@@ -48,60 +77,141 @@ function parseArgs(argv) {
   return options;
 }
 
-function listConflicts(target) {
-  return DIRS.filter((dir) => existsSync(join(target, dir))).map((dir) => `${dir}/`);
+async function get(url) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: controller.signal, headers: { "user-agent": "sliderpro-agentic-skills-etch" } });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.text();
+  } finally {
+    clearTimeout(timer);
+  }
 }
 
-function copyPackageFiles(target, force) {
-  mkdirSync(target, { recursive: true });
+function bundledManifest() {
+  return JSON.parse(readFileSync(join(bundleRoot, "manifest.json"), "utf8"));
+}
 
-  for (const dir of DIRS) {
-    const source = join(sourceRoot, dir);
-    const dest = join(target, dir);
+/** Returns { files: [{out, content}] } or null if anything at all went wrong. */
+async function fetchLive(ref) {
+  let manifest;
+  try {
+    manifest = JSON.parse(await get(rawUrl(ref, REPO_MANIFEST)));
+  } catch {
+    // The manifest may predate this feature on an older ref; the bundled list
+    // is still a reasonable guess at what to fetch.
+    try {
+      manifest = bundledManifest();
+    } catch {
+      return null;
+    }
+  }
+
+  const entries = [...(manifest.skills || []), ...(manifest.components || [])];
+  if (entries.length === 0) return null;
 
-    if (existsSync(dest) && !force) {
-      continue;
+  const files = [];
+  for (const entry of entries) {
+    let text;
+    try {
+      text = await get(rawUrl(ref, entry.repo));
+    } catch {
+      return null;
     }
+    if (!looksLikeMarkdown(text)) return null;
+    files.push({ out: entry.out, content: applyRewrites(text) });
+  }
+  return files;
+}
+
+function writeFiles(target, files) {
+  for (const file of files) {
+    const dest = join(target, file.out);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, file.content);
+  }
+}
+
+function copyBundle(target) {
+  for (const dir of DIRS) {
+    const source = join(bundleRoot, dir);
+    if (existsSync(source)) cpSync(source, join(target, dir), { recursive: true });
+  }
+}
+
+// When each skills file is meant to be read. The split exists so that only the
+// entry file is read up front, so saying so here is part of the install.
+const SKILL_ROLES = {
+  "slider-pro-skills.md": "read this first, every session",
+  "slider-pro-skills-build.md": "read only when building from scratch",
+  "slider-pro-skills-reference.md": "lookup only, never read whole",
+};
 
-    cpSync(source, dest, { recursive: true });
+function installedSkills(target) {
+  try {
+    return readdirSync(join(target, OUT_SKILLS_DIR))
+      .filter((f) => f.endsWith(".md"))
+      .sort();
+  } catch {
+    return [];
   }
 }
 
-function countComponents() {
+function countComponents(target) {
   try {
-    return readdirSync(join(sourceRoot, "components")).filter((f) => f.endsWith(".md")).length;
+    return readdirSync(join(target, OUT_COMPONENTS_DIR)).filter((f) => f.endsWith(".md")).length;
   } catch {
     return 0;
   }
 }
 
-function main() {
-  const { force, help, target } = parseArgs(process.argv.slice(2));
+async function main() {
+  const { force, help, offline, ref, target } = parseArgs(process.argv.slice(2));
 
   if (help) {
     printHelp();
     return;
   }
 
-  const conflicts = listConflicts(target);
-
+  const conflicts = DIRS.filter((dir) => existsSync(join(target, dir))).map((dir) => `${dir}/`);
   if (conflicts.length > 0 && !force) {
     console.error("Installation blocked, the following already exist:");
-    for (const conflict of conflicts) {
-      console.error(`  ${conflict}`);
-    }
+    for (const conflict of conflicts) console.error(`  ${conflict}`);
     console.error("\nRe-run with --force to overwrite.");
     process.exit(1);
   }
 
-  copyPackageFiles(target, force);
+  mkdirSync(target, { recursive: true });
+
+  let source;
+  if (offline) {
+    copyBundle(target);
+    source = "the copy bundled with this package (--offline)";
+  } else {
+    const files = await fetchLive(ref);
+    if (files) {
+      writeFiles(target, files);
+      source = `${REPO} (${ref})`;
+    } else {
+      copyBundle(target);
+      source = "the copy bundled with this package (network unavailable)";
+    }
+  }
 
   console.log(`Installed Slider Pro AI Connector skills to ${target}`);
-  console.log(`  slider-skills/slider-pro-skills.md`);
-  console.log(`  slider-skills/slider-pro-skills-reference.md`);
-  console.log(`  components/ (${countComponents()} component prop docs)`);
-  console.log("\nPoint your AI coding agent at slider-skills/slider-pro-skills.md to load it.");
+  console.log(`  source: ${source}`);
+  for (const name of installedSkills(target)) {
+    const role = SKILL_ROLES[name];
+    console.log(`  ${OUT_SKILLS_DIR}/${name}${role ? ` (${role})` : ""}`);
+  }
+  console.log(`  ${OUT_COMPONENTS_DIR}/ (${countComponents(target)} component prop docs)`);
+  console.log(`\nPoint your AI coding agent at ${OUT_SKILLS_DIR}/slider-pro-skills.md to load it.`);
+  console.log("It reads the other two only when a task needs them.");
   console.log('Then tell the agent: "npx @digital-gravy/etch-connector serve"');
 }
 
-main();
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/lib/skills-source.js

@@ -0,0 +1,65 @@
+// Single source of truth for where the skills come from and how their links are
+// rewritten for an installed project. Both scripts/build.js (which bundles a
+// copy at publish time) and bin/cli.js (which prefers a live copy at install
+// time) import this, so the two paths cannot drift in how they rewrite links.
+
+export const REPO = "udoro/SliderPro-Etch-Docs";
+export const DEFAULT_REF = "master";
+export const DOCS_URL = "https://design-with-cracka.gitbook.io/etchsliderpro";
+
+// Where things live in the docs repo.
+export const REPO_SKILLS_DIR = "ai-connector/slider-skills";
+export const REPO_COMPONENTS_DIR = "components";
+export const REPO_MANIFEST = "ai-connector/skills-manifest.json";
+
+// Where they land in a user's project.
+export const OUT_SKILLS_DIR = "slider-skills";
+export const OUT_COMPONENTS_DIR = "components";
+
+// The docs repo nests slider-skills/ two levels below the root
+// (ai-connector/slider-skills/), so it links components/ as ../../components/.
+// Installed, slider-skills/ sits directly under the project root, so that
+// becomes ../components/.
+//
+// The sibling doc pages the skills link to do not ship in the package at all,
+// so point those at the public site rather than leave a link resolving to
+// nothing.
+export const PATH_REWRITE = [
+  [/\.\.\/\.\.\/components\//g, "../components/"],
+  [/\.\.\/\.\.\/card-stack-templates\.md/g, `${DOCS_URL}/card-stack-templates`],
+  [/\.\.\/\.\.\/premade-templates\.md/g, `${DOCS_URL}/premade-templates`],
+  [/\.\.\/\.\.\/javascript-api\.md/g, `${DOCS_URL}/javascript-api`],
+  [/\.\.\/\.\.\/styling-and-responsive\.md/g, `${DOCS_URL}/styling-and-responsive`],
+  [/\.\.\/\.\.\/admin-settings\.md/g, `${DOCS_URL}/admin-settings`],
+  [/\.\.\/\.\.\/troubleshooting\.md/g, `${DOCS_URL}/troubleshooting`],
+];
+
+export function applyRewrites(content) {
+  let out = content;
+  for (const [pattern, replacement] of PATH_REWRITE) out = out.replace(pattern, replacement);
+  return out;
+}
+
+/**
+ * Only a markdown LINK TARGET pointing outside the package is a defect: it would
+ * 404 for every installed user. A bare ../../ path in prose is not, because the
+ * skills files deliberately reference optional local files and always say what
+ * to do when they are absent.
+ */
+export function findStaleLinks(content) {
+  return [...content.matchAll(/\]\((\.\.\/\.\.\/[^)]+)\)/g)].map((m) => m[1]);
+}
+
+export function rawUrl(ref, repoPath) {
+  return `https://raw.githubusercontent.com/${REPO}/${ref}/${repoPath}`;
+}
+
+/**
+ * A fetched file only counts if it is non-empty markdown. A proxy or an error
+ * page returning 200 with HTML would otherwise be written out as a skills file.
+ */
+export function looksLikeMarkdown(text) {
+  if (!text || text.trim().length < 200) return false;
+  const head = text.slice(0, 400).toLowerCase();
+  return !head.includes("<!doctype html") && !head.includes("<html");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sliderpro-agentic-skills-etch",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Installs the Slider Pro for Etch AI Connector skills files and component docs into any project",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bin",
+    "lib",
     "skills-package"
   ],
   "scripts": {

package/skills-package/components/dwc-slider-pagination.md

@@ -58,3 +58,41 @@ Set **Custom Pagination Mode** to `Template` and design the *first* item as your
 
 - **Numbers** count up starting from whatever number you type, so `1` produces `1, 2, 3, ...` while `2003` produces `2003, 2004, 2005, ...`. Leading zeros are preserved as the number grows (`007` → `007, 008, ..., 010, 011, ...`).
 - **Letters and roman numerals** (`a`, `A`, `i`, `I`) always start at the beginning of their sequence (a/b/c…, i/ii/iii…). Only numbers support a custom starting point.
+
+## Styling the active item
+
+Slider Pro adds the class `is-active` to whichever pagination item matches the slide on screen. Use
+it to style the current one:
+
+```css
+.my-dot           { background: #e5e7eb; }
+.my-dot.is-active { background: #45bf55; }
+```
+
+The class moves on its own as the slider changes, so you do not need any JavaScript. It works the
+same in `Default` and `Template` mode.
+
+***
+
+## If your own layout does not apply
+
+The pagination lays itself out as a flex row or column, using the **Direction** and **Gap**
+settings above, and it is only as tall as its items.
+
+If you write your own layout on it, for example a grid, and nothing seems to happen, this is why:
+your rule and the plugin's rule are equally specific, so the plugin's wins. Put the plugin's class
+in front of yours to make your rule stronger:
+
+```css
+/* has no effect on its own */
+.my-pagination { display: grid; }
+
+/* wins */
+.dwc-slider-pagination-wrapper.my-pagination {
+  display: grid;
+  block-size: 100%;
+  gap: 0;
+}
+```
+
+Remember to reset `gap` if you set your own spacing, because the flex gap still applies.

package/skills-package/manifest.json

@@ -0,0 +1,47 @@
+{
+  "generated": "2026-08-29",
+  "skills": [
+    {
+      "repo": "ai-connector/slider-skills/slider-pro-skills-build.md",
+      "out": "slider-skills/slider-pro-skills-build.md"
+    },
+    {
+      "repo": "ai-connector/slider-skills/slider-pro-skills-reference.md",
+      "out": "slider-skills/slider-pro-skills-reference.md"
+    },
+    {
+      "repo": "ai-connector/slider-skills/slider-pro-skills.md",
+      "out": "slider-skills/slider-pro-skills.md"
+    }
+  ],
+  "components": [
+    {
+      "repo": "components/dwc-slide.md",
+      "out": "components/dwc-slide.md"
+    },
+    {
+      "repo": "components/dwc-slider-nav-button.md",
+      "out": "components/dwc-slider-nav-button.md"
+    },
+    {
+      "repo": "components/dwc-slider-pagination.md",
+      "out": "components/dwc-slider-pagination.md"
+    },
+    {
+      "repo": "components/dwc-slider-play-pause.md",
+      "out": "components/dwc-slider-play-pause.md"
+    },
+    {
+      "repo": "components/dwc-slider-progress.md",
+      "out": "components/dwc-slider-progress.md"
+    },
+    {
+      "repo": "components/dwc-slider-wrapper.md",
+      "out": "components/dwc-slider-wrapper.md"
+    },
+    {
+      "repo": "components/dwc-slider.md",
+      "out": "components/dwc-slider.md"
+    }
+  ]
+}