Add skills subcommand and fix npm metadata

New `impeccable skills` CLI with three subcommands: - `skills help`: fetches and displays all 20 commands from the API - `skills install`: delegates to `npx skills add pbakaus/impeccable` - `skills update`: tries `npx skills update` first; if skills aren't managed by the skills CLI, downloads the universal bundle from impeccable.style and overwrites provider folders directly, with git-based modification detection and confirmation prompt Also fixes npm metadata: homepage -> impeccable.style, license -> Apache-2.0 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-09-11 21:57:14 +03:00 · 2026-03-30 13:04:43 -07:00
parent 8d0e9de26d
commit da8a59e981
4 changed files with 302 additions and 5 deletions
@@ -5,7 +5,16 @@ Detect UI anti-patterns and design quality issues from the command line. Scans H
 ## Quick Start

 ```bash
-# Scan files or directories
+# Install skills into your AI harness (Claude, Cursor, Gemini, etc.)
+npx impeccable skills install
+
+# Update skills to the latest version
+npx impeccable skills update
+
+# List all available commands
+npx impeccable skills help
+
+# Scan files or directories for anti-patterns
 npx impeccable detect src/

 # Scan a live URL (requires Puppeteer)
@@ -0,0 +1,281 @@
+/**
+ * `impeccable skills` subcommand
+ *
+ * Usage:
+ *   impeccable skills help      Show all available skills and commands
+ *   impeccable skills install   Install skills via npx skills add
+ *   impeccable skills update    Update skills to latest version
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync, rmSync, createWriteStream } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { get } from 'node:https';
+import { tmpdir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const API_BASE = 'https://impeccable.style';
+
+// Provider folder names in project roots
+const PROVIDER_DIRS = ['.claude', '.cursor', '.gemini', '.codex', '.agents', '.kiro', '.opencode', '.pi', '.trae', '.trae-cn'];
+
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(r => rl.question(question, ans => { rl.close(); r(ans.trim().toLowerCase()); }));
+}
+
+// ─── skills help ──────────────────────────────────────────────────────────────
+
+async function showHelp() {
+  let commands;
+  try {
+    const res = await fetch(`${API_BASE}/api/commands`);
+    commands = await res.json();
+  } catch {
+    console.error('Could not fetch command list from impeccable.style. Check your network connection.');
+    process.exit(1);
+  }
+
+  const pad = (s, n) => s + ' '.repeat(Math.max(0, n - s.length));
+
+  console.log('\n  Impeccable Skills & Commands\n');
+  console.log('  Install:  npx impeccable skills install');
+  console.log('  Update:   npx impeccable skills update');
+  console.log('  Docs:     https://impeccable.style/cheatsheet\n');
+  console.log(`  ${pad('Command', 22)} Description`);
+  console.log(`  ${'-'.repeat(22)} ${'-'.repeat(52)}`);
+
+  for (const cmd of commands.sort((a, b) => a.id.localeCompare(b.id))) {
+    // Trim description to fit terminal
+    const desc = cmd.description.length > 72
+      ? cmd.description.substring(0, 69) + '...'
+      : cmd.description;
+    console.log(`  ${pad('/' + cmd.id, 22)} ${desc}`);
+  }
+  console.log(`\n  ${commands.length} commands available. Run /<command> in your AI harness.\n`);
+}
+
+// ─── skills install ───────────────────────────────────────────────────────────
+
+async function install() {
+  console.log('Installing impeccable skills via npx skills...\n');
+  try {
+    execSync('npx skills add pbakaus/impeccable', { stdio: 'inherit' });
+  } catch (e) {
+    process.exit(e.status ?? 1);
+  }
+}
+
+// ─── skills update ────────────────────────────────────────────────────────────
+
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, '.git'))) return dir;
+    dir = dirname(dir);
+  }
+  return process.cwd();
+}
+
+function findInstalledProviders(root) {
+  const found = [];
+  for (const d of PROVIDER_DIRS) {
+    const skillsDir = join(root, d, 'skills');
+    if (existsSync(skillsDir)) {
+      // Check if it has impeccable skills (look for any SKILL.md)
+      try {
+        const entries = readdirSync(skillsDir, { withFileTypes: true });
+        const hasSkills = entries.some(e =>
+          e.isDirectory() && existsSync(join(skillsDir, e.name, 'SKILL.md'))
+        );
+        if (hasSkills) found.push(d);
+      } catch {}
+    }
+  }
+  return found;
+}
+
+function getModifiedSkillFiles(root, providerDirs) {
+  // Use git to check if any skill files have local modifications
+  const modified = [];
+  try {
+    const status = execSync('git status --porcelain', { cwd: root, encoding: 'utf8' });
+    for (const line of status.split('\n')) {
+      if (!line.trim()) continue;
+      const file = line.substring(3);
+      for (const d of providerDirs) {
+        if (file.startsWith(`${d}/skills/`)) {
+          const flag = line.substring(0, 2).trim();
+          modified.push({ file, flag });
+        }
+      }
+    }
+  } catch {
+    // Not a git repo or git not available
+  }
+  return modified;
+}
+
+function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = createWriteStream(dest);
+    get(url, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        // Follow redirect
+        get(res.headers.location, (res2) => {
+          res2.pipe(file);
+          file.on('finish', () => { file.close(); resolve(); });
+        }).on('error', reject);
+        return;
+      }
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode}`));
+        return;
+      }
+      res.pipe(file);
+      file.on('finish', () => { file.close(); resolve(); });
+    }).on('error', reject);
+  });
+}
+
+async function update() {
+  // Try npx skills update first
+  console.log('Checking for skills manager...');
+  let noLockFile = true;
+  try {
+    const output = execSync('npx skills check', { encoding: 'utf8', timeout: 15000 });
+    noLockFile = output.includes('No skills tracked');
+  } catch {
+    // npx skills not available or errored
+  }
+
+  if (!noLockFile) {
+    // npx skills is managing our install -- delegate to it
+    console.log('Updating via npx skills...\n');
+    try {
+      execSync('npx skills update', { stdio: 'inherit' });
+    } catch (e) {
+      process.exit(e.status ?? 1);
+    }
+    process.exit(0);
+  }
+
+  // Fallback: manual update by downloading the universal bundle
+  console.log('Skills not managed by npx skills. Using direct download.\n');
+
+  const root = findProjectRoot();
+  const providers = findInstalledProviders(root);
+
+  if (providers.length === 0) {
+    console.log('No impeccable skill folders found in this project.');
+    console.log('Run `npx impeccable skills install` to install first.');
+    process.exit(1);
+  }
+
+  console.log(`Found impeccable skills in: ${providers.join(', ')}`);
+
+  // Check for local modifications
+  const modified = getModifiedSkillFiles(root, providers);
+  if (modified.length > 0) {
+    console.log(`\n  Warning: ${modified.length} skill file(s) have local changes:\n`);
+    for (const m of modified.slice(0, 10)) {
+      console.log(`    ${m.flag} ${m.file}`);
+    }
+    if (modified.length > 10) console.log(`    ... and ${modified.length - 10} more`);
+    console.log();
+    const ans = await ask('  Overwrite local changes? (y/N) ');
+    if (ans !== 'y' && ans !== 'yes') {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+  } else {
+    const ans = await ask(`Update skills in ${providers.length} provider folder(s)? (Y/n) `);
+    if (ans === 'n' || ans === 'no') {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+  }
+
+  // Download universal bundle
+  const tmpZip = join(tmpdir(), `impeccable-update-${Date.now()}.zip`);
+  console.log('\nDownloading latest skills...');
+  try {
+    await downloadFile(`${API_BASE}/api/download/bundle/universal`, tmpZip);
+  } catch (e) {
+    console.error(`Download failed: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Extract and copy to each provider folder
+  let unzip;
+  try {
+    // Use built-in decompress if available (Node 22+), otherwise shell unzip
+    const tmpDir = join(tmpdir(), `impeccable-update-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+    execSync(`unzip -qo "${tmpZip}" -d "${tmpDir}"`, { encoding: 'utf8' });
+
+    // The universal bundle has provider folders at the top level
+    let updated = 0;
+    for (const provider of providers) {
+      const srcDir = join(tmpDir, provider, 'skills');
+      const destDir = join(root, provider, 'skills');
+      if (!existsSync(srcDir)) continue;
+
+      // Copy each skill folder
+      const skills = readdirSync(srcDir, { withFileTypes: true });
+      for (const skill of skills) {
+        if (!skill.isDirectory()) continue;
+        const src = join(srcDir, skill.name);
+        const dest = join(destDir, skill.name);
+        // Remove old and copy new
+        if (existsSync(dest)) rmSync(dest, { recursive: true });
+        copyDirSync(src, dest);
+        updated++;
+      }
+    }
+
+    // Cleanup
+    rmSync(tmpDir, { recursive: true, force: true });
+    rmSync(tmpZip, { force: true });
+
+    console.log(`Updated ${updated} skills across ${providers.length} provider(s).`);
+    console.log('Done!\n');
+  } catch (e) {
+    console.error(`Extract failed: ${e.message}`);
+    rmSync(tmpZip, { force: true });
+    process.exit(1);
+  }
+}
+
+function copyDirSync(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const s = join(src, entry.name);
+    const d = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(s, d);
+    } else {
+      writeFileSync(d, readFileSync(s));
+    }
+  }
+}
+
+// ─── Router ───────────────────────────────────────────────────────────────────
+
+export async function run(args) {
+  const sub = args[0];
+
+  if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+    await showHelp();
+  } else if (sub === 'install') {
+    await install();
+  } else if (sub === 'update') {
+    await update();
+  } else {
+    console.error(`Unknown skills command: ${sub}`);
+    console.error(`Run 'impeccable skills --help' for available commands.`);
+    process.exit(1);
+  }
+}
@@ -5,7 +5,7 @@
 *
 * Usage:
 *   npx impeccable detect [file-or-dir-or-url...]
- *   npx impeccable detect --fast --json src/
+ *   npx impeccable skills help|install|update
 *   npx impeccable --help
 */

@@ -22,12 +22,15 @@ if (!command || command === '--help' || command === '-h') {

 Commands:
  detect [file-or-dir-or-url...]   Scan for UI anti-patterns and design quality issues
+  skills help                      List all available skills and commands
+  skills install                   Install impeccable skills into your project
+  skills update                    Update skills to the latest version

 Options:
  --help       Show this help message
  --version    Show version number

-Run 'impeccable detect --help' for detection-specific options.`);
+Run 'impeccable <command> --help' for command-specific options.`);
  process.exit(0);
 }

@@ -38,10 +41,12 @@ if (command === '--version' || command === '-v') {
 }

 if (command === 'detect') {
-  // Remove 'detect' from argv so the detection script sees the right args
  process.argv = [process.argv[0], process.argv[1], ...args.slice(1)];
  const { detectCli } = await import('../source/skills/critique/scripts/detect-antipatterns.mjs');
  await detectCli();
+} else if (command === 'skills') {
+  const { run } = await import('./commands/skills.mjs');
+  await run(args.slice(1));
 } else {
  console.error(`Unknown command: ${command}`);
  console.error(`Run 'impeccable --help' for available commands.`);
@@ -9,6 +9,7 @@
    "bin/",
    "source/skills/critique/scripts/detect-antipatterns.mjs",
    "source/skills/critique/scripts/detect-antipatterns-browser.js",
+    "lib/download-providers.js",
    "LICENSE"
  ],
  "dependencies": {
@@ -29,7 +30,8 @@
    "html",
    "cli"
  ],
-  "license": "SEE LICENSE FILE",
+  "license": "Apache-2.0",
+  "homepage": "https://impeccable.style",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/pbakaus/impeccable.git"