skillpacks 0.1.0 → 0.1.2

package/src/cli/pack-normalization.mjs

@@ -7,11 +7,11 @@ const HIBERNATED_REACTIVATION_TEXT =
 const PACK_ALIAS_GROUPS = [
   {
     aliases: ['business', 'business_app', 'businessapp', 'product', 'saas', 'business-app'],
-    packs: ['business-discovery', 'customer-lifecycle', 'business-growth', 'business-ops']
+    packs: ['business-research', 'customer-lifecycle', 'business-growth', 'business-ops']
   },
   {
-    aliases: ['business-discovery', 'discovery', 'customer-discovery', 'customer_discovery'],
-    packs: ['business-discovery']
+    aliases: ['business-research', 'business-discovery', 'discovery', 'research'],
+    packs: ['business-research']
   },
   {
     aliases: [
@@ -320,6 +320,56 @@ function activePackNames(manifest) {
     .sort((a, b) => a.localeCompare(b));
 }
 
+function normalizePackTitle(title) {
+  return String(title || '').trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+function activePackTitleMap(manifest) {
+  const map = new Map();
+
+  for (const pack of manifest.packs || []) {
+    if (!pack.name || (pack.status !== undefined && pack.status !== 'active')) {
+      continue;
+    }
+
+    const title = normalizePackTitle(pack.title);
+    if (!title || map.has(title)) {
+      continue;
+    }
+    map.set(title, pack.name);
+  }
+
+  return map;
+}
+
+function packTitleToken(raw, activePackTitles) {
+  let token = String(raw).trim().replace(/,$/, '');
+  if (token.startsWith('pack:')) {
+    token = token.slice('pack:'.length);
+  }
+  if (!token || token === 'pack' || token === 'packs') {
+    return null;
+  }
+
+  const title = token.replace(/\s+/g, ' ').trim();
+  return activePackTitles.has(normalizePackTitle(title)) ? title : null;
+}
+
+function tokenizeInstallArgs(args, activePackTitles) {
+  const tokens = [];
+
+  for (const raw of args) {
+    const titleToken = packTitleToken(raw, activePackTitles);
+    if (titleToken) {
+      tokens.push(titleToken);
+      continue;
+    }
+    tokens.push(...tokenizePackArgs([raw]));
+  }
+
+  return tokens;
+}
+
 function availablePacksInline(manifest) {
   const names = activePackNames(manifest);
   if (names.length === 0) {
@@ -350,6 +400,33 @@ function skillPackMap(manifest) {
   return map;
 }
 
+function fuzzyMatchSkills(token, skillPacks) {
+  const suffix = [];
+  const prefix = [];
+  const substring = [];
+
+  for (const [skill, pack] of skillPacks) {
+    if (skill === token) continue;
+    if (skill.endsWith(`-${token}`)) {
+      suffix.push({ skill, pack });
+    } else if (skill.startsWith(`${token}-`)) {
+      prefix.push({ skill, pack });
+    } else if (skill.includes(token)) {
+      substring.push({ skill, pack });
+    }
+  }
+
+  if (suffix.length > 0) return suffix;
+  if (prefix.length > 0) return prefix;
+  if (substring.length > 0) return substring;
+  return [];
+}
+
+function fuzzyMatchError(token, matches) {
+  const lines = matches.map((m) => `  ${m.skill} (${m.pack})`).join('\n');
+  return new Error(`Ambiguous skill name '${token}'. Did you mean:\n${lines}`);
+}
+
 function enabledSkillPackMap(projectRoot) {
   const config = readProjectConfig(projectRoot);
   if (!config?.enabled_skills || typeof config.enabled_skills !== 'object') {
@@ -363,7 +440,7 @@ function allPacksExist(packs, activePacks) {
 }
 
 function unknownNameError(token, manifest) {
-  return new Error(`Unknown pack or skill '${token}'. Available packs: ${availablePacksInline(manifest)}`);
+  return new Error(`Unknown pack or skill '${token}'. Available packs: ${availablePacksInline(manifest)}\nRun 'npx skillpacks list' to see all available skills.`);
 }
 
 function hibernatedPackError(requested, pack) {
@@ -391,22 +468,27 @@ function hibernatedSkillError(skill, packs) {
 }
 
 function resolveInstallToken(token, context) {
-  const hibernatedPack = canonicalHibernatedPack(token);
-  if (hibernatedPack) {
-    throw hibernatedPackError(token, hibernatedPack);
+  if (context.skillPacks.has(token)) {
+    context.skills.push(token);
+    return;
   }
 
-  const normalizedPacks = normalizePack(token);
-  if (allPacksExist(normalizedPacks, context.activePacks)) {
-    context.packs.push(...normalizedPacks);
+  if (context.activePacks.has(token)) {
+    context.packs.push(token);
     return;
   }
 
-  if (context.skillPacks.has(token)) {
-    context.skills.push(token);
+  const titlePack = context.activePackTitles.get(normalizePackTitle(token));
+  if (titlePack) {
+    context.packs.push(titlePack);
     return;
   }
 
+  const hibernatedPack = canonicalHibernatedPack(token);
+  if (hibernatedPack) {
+    throw hibernatedPackError(token, hibernatedPack);
+  }
+
   const hibernatedSkillPacks = hibernatedPacksForSkill(token);
   if (hibernatedSkillPacks.length > 0) {
     throw hibernatedSkillError(token, hibernatedSkillPacks);
@@ -444,6 +526,16 @@ function resolveRemoveToken(token, context) {
     return;
   }
 
+  const fuzzyMatches = fuzzyMatchSkills(token, context.skillPacks);
+  if (fuzzyMatches.length === 1) {
+    console.error(`Resolved '${token}' → '${fuzzyMatches[0].skill}'`);
+    context.skills.push(fuzzyMatches[0].skill);
+    return;
+  }
+  if (fuzzyMatches.length > 1) {
+    throw fuzzyMatchError(token, fuzzyMatches);
+  }
+
   throw unknownNameError(token, context.manifest);
 }
 
@@ -458,6 +550,7 @@ export function resolvePackCommandArgs(command, args, options) {
   const context = {
     manifest: options.manifest,
     activePacks: new Set(activePackNames(options.manifest)),
+    activePackTitles: activePackTitleMap(options.manifest),
     skillPacks: skillPackMap(options.manifest),
     enabledSkillPacks: command === 'remove'
       ? enabledSkillPackMap(options.projectRoot || process.cwd())
@@ -466,7 +559,9 @@ export function resolvePackCommandArgs(command, args, options) {
     skills: []
   };
 
-  const tokens = tokenizePackArgs(args);
+  const tokens = command === 'install'
+    ? tokenizeInstallArgs(args, context.activePackTitles)
+    : tokenizePackArgs(args);
   for (const token of tokens) {
     if (command === 'install') {
       resolveInstallToken(token, context);

package/src/cli/run-pack-script.mjs

@@ -1,5 +1,5 @@
 import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
@@ -11,11 +11,13 @@ import {
 import { resolvePackCommandArgs } from './pack-normalization.mjs';
 import {
   doctorProject,
+  initProject,
   installResolved,
   pinSkill,
   pruneProject,
   refreshProject,
   removeResolved,
+  uninstallGlobal,
   unpinSkill
 } from './lifecycle.mjs';
 
@@ -24,8 +26,11 @@ const packageRoot = resolve(moduleDir, '..', '..');
 const checkoutRoot = resolve(packageRoot, '..', '..');
 const packageJsonPath = join(packageRoot, 'package.json');
 const packScriptPath = resolvePackagedPath('scripts/pack.sh');
-const initScriptPath = resolvePackagedPath('init.sh');
 const manifestPath = resolvePackagedPath('dist/skillpacks-manifest.json');
+const alignmentUpgradeScriptPath = resolvePackagedPath('scripts/upgrade-alignment-page.mjs');
+const alignmentAuditScriptPath = resolvePackagedPath('scripts/audit-alignment-pages.mjs');
+const alignmentInjectTtsScriptPath = resolvePackagedPath('scripts/inject-tts.mjs');
+const alignmentTtsAssetPath = resolvePackagedPath('scripts/alignment-tts-kokoro.js');
 
 function resolvePackagedPath(relativePath) {
   const packagedPath = join(packageRoot, relativePath);
@@ -111,6 +116,184 @@ function runCommand(command, args, options = {}) {
   });
 }
 
+function assertNoArgs(command, args) {
+  if (args.length > 0) {
+    throw new Error(`${command} does not accept arguments`);
+  }
+}
+
+function ensureAlignmentTtsAsset(projectRoot) {
+  if (!existsSync(alignmentTtsAssetPath)) {
+    throw new Error(
+      `alignment TTS asset not found at ${alignmentTtsAssetPath}. Reinstall skillpacks or use a source checkout that includes scripts/alignment-tts-kokoro.js.`
+    );
+  }
+
+  const target = join(projectRoot, 'scripts/alignment-tts-kokoro.js');
+  if (existsSync(target)) {
+    return;
+  }
+
+  mkdirSync(dirname(target), { recursive: true });
+  copyFileSync(alignmentTtsAssetPath, target);
+  console.log('Installed scripts/alignment-tts-kokoro.js for alignment page TTS.');
+}
+
+function alignmentHelp() {
+  console.log(`gskp alignment
+
+Usage:
+  gskp alignment bundles [--dry-run] [--check]
+  gskp alignment pages audit
+  gskp alignment pages inject-tts [--force] [--dry-run] [alignment/<page>.html]
+  gskp alignment verify
+
+Commands:
+  bundles                    Generate per-skill ALIGNMENT-PAGE.md bundles
+  bundles --dry-run          Preview generated bundle changes
+  bundles --check            Fail on generated-bundle drift without writing
+  pages audit                Audit active rendered alignment/*.html pages
+  pages inject-tts           Add the packaged Brief Me TTS script tag to pages
+  verify                     Run the focused alignment verification set when present`);
+}
+
+function validateArgs(command, args, options) {
+  const { allowedFlags = new Set(), maxPositionals = 0, positionalPattern = null } = options;
+  let positionals = 0;
+
+  for (const arg of args) {
+    if (arg.startsWith('-')) {
+      if (!allowedFlags.has(arg)) {
+        throw new Error(`${command}: unsupported flag '${arg}'`);
+      }
+      continue;
+    }
+
+    positionals += 1;
+    if (positionals > maxPositionals) {
+      throw new Error(`${command}: unexpected argument '${arg}'`);
+    }
+    if (positionalPattern && !positionalPattern.test(arg)) {
+      throw new Error(`${command}: expected an alignment HTML page path, got '${arg}'`);
+    }
+  }
+}
+
+export function resolveAlignmentCommand(args, options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const [scope, ...rest] = args;
+
+  if (!scope || scope === 'help' || scope === '--help' || scope === '-h') {
+    return { kind: 'help' };
+  }
+
+  if (scope === 'bundles') {
+    validateArgs('alignment bundles', rest, {
+      allowedFlags: new Set(['--dry-run', '--check'])
+    });
+    if (rest.includes('--dry-run') && rest.includes('--check')) {
+      throw new Error('alignment bundles accepts either --dry-run or --check, not both');
+    }
+    return {
+      kind: 'run',
+      command: process.execPath,
+      args: [alignmentUpgradeScriptPath, '--root', projectRoot, ...rest]
+    };
+  }
+
+  if (scope === 'pages') {
+    const [pagesCommand, ...pagesRest] = rest;
+    if (!pagesCommand || pagesCommand === 'help' || pagesCommand === '--help' || pagesCommand === '-h') {
+      return { kind: 'help' };
+    }
+
+    if (pagesCommand === 'audit') {
+      assertNoArgs('alignment pages audit', pagesRest);
+      return {
+        kind: 'run',
+        command: process.execPath,
+        args: [alignmentAuditScriptPath, '--root', projectRoot]
+      };
+    }
+
+    if (pagesCommand === 'inject-tts') {
+      validateArgs('alignment pages inject-tts', pagesRest, {
+        allowedFlags: new Set(['--force', '--dry-run']),
+        maxPositionals: 1,
+        positionalPattern: /^alignment\/[^/].*\.html$/
+      });
+      return {
+        kind: 'run',
+        command: process.execPath,
+        args: [alignmentInjectTtsScriptPath, '--root', projectRoot, ...pagesRest],
+        ensureTtsAsset: !pagesRest.includes('--dry-run')
+      };
+    }
+
+    throw new Error(`alignment pages: unknown command '${pagesCommand}'`);
+  }
+
+  if (scope === 'verify') {
+    assertNoArgs('alignment verify', rest);
+    return {
+      kind: 'verify',
+      projectRoot,
+      command: 'pnpm',
+      args: [
+        '--dir',
+        'tests',
+        'exec',
+        'vitest',
+        'run',
+        '--project',
+        'layer1',
+        'layer1/upgrade-alignment-page-bespoke.test.ts',
+        'layer1/audit-alignment-pages.test.ts',
+        'layer1/alignment-gates.test.ts',
+        'layer1/alignment-tts-kokoro.test.ts'
+      ]
+    };
+  }
+
+  throw new Error(`alignment: unknown command '${scope}'`);
+}
+
+function targetHasAlignmentVerifyTests(projectRoot) {
+  const required = [
+    'tests/package.json',
+    'tests/layer1/upgrade-alignment-page-bespoke.test.ts',
+    'tests/layer1/audit-alignment-pages.test.ts',
+    'tests/layer1/alignment-gates.test.ts',
+    'tests/layer1/alignment-tts-kokoro.test.ts'
+  ];
+  return required.every((relativePath) => existsSync(join(projectRoot, relativePath)));
+}
+
+function runAlignment(args) {
+  const resolved = resolveAlignmentCommand(args, { projectRoot: process.cwd() });
+  if (resolved.kind === 'help') {
+    alignmentHelp();
+    return 0;
+  }
+
+  if (resolved.kind === 'verify') {
+    if (!targetHasAlignmentVerifyTests(resolved.projectRoot)) {
+      console.error(
+        'alignment verify requires this repository\'s focused alignment Vitest files under tests/layer1. This target repo does not include them.'
+      );
+      return 1;
+    }
+    requireCommand('pnpm', 'Install pnpm or run the source-checkout Vitest command directly.');
+    return runCommand(resolved.command, resolved.args);
+  }
+
+  requireCommand('node', 'Install Node.js before running gskp alignment commands.');
+  if (resolved.ensureTtsAsset) {
+    ensureAlignmentTtsAsset(process.cwd());
+  }
+  return runCommand(resolved.command, resolved.args);
+}
+
 function printManifestJson(args) {
   if (args.length !== 1 || args[0] !== '--json') {
     throw new Error('list --json does not accept additional arguments');
@@ -162,10 +345,10 @@ function resolveDeckInstall(args) {
 }
 
 function usage() {
-  console.log(`skillpacks ${packageVersion()}
+  console.log(`gskp ${packageVersion()}
 
 Usage:
-  skillpacks <command> [args...]
+  gskp <command> [args...]
 
 Commands:
   list                         List available packs
@@ -175,16 +358,26 @@ Commands:
   recommend                    Recommend packs from repository signals
   install <name...>            Enable packs or individual skills
   install-deck <deck> [--full] Enable packs selected by deck metadata
+  init                         Install base skills into this project
+  uninstall-global             Remove legacy repo-managed base skills from ~/.claude and ~/.codex
   remove <name...>             Remove packs or individual skills
   refresh                      Recreate local skill roots from project config
   doctor                       Report skill-install drift
+  doctor --fix                 Clean generated skill-root drift
+  doctor --fix --agent-docs [--dry-run]
+                               Also migrate generated AGENTS.md/CLAUDE.md blocks
+  alignment bundles [--dry-run] [--check]
+                               Generate/check per-skill ALIGNMENT-PAGE.md bundles
+  alignment pages audit        Audit active rendered alignment/*.html pages
+  alignment pages inject-tts [--force] [alignment/<page>.html]
+                               Add the packaged Brief Me TTS script include
+  alignment verify             Run focused alignment tests when present
   prune [--dry-run]            Remove orphaned managed skill installs
   set-update-mode <mode>       Set skill update mode: warn, auto, or unset
   pin <skill> <version>        Pin a skill to an archived version
   unpin <skill>                Revert a pinned skill to latest
   set-mode <mode>              Set project agent mode
   which <skill>                Show which pack provides a skill
-  init-global [args...]        Install global core skills with packaged init.sh
 
 Project-local commands write to the current working directory.`);
 }
@@ -234,14 +427,14 @@ export async function runSkillpacksCli(args) {
     return setUpdateMode(rest[0]);
   }
 
-  if (command === 'init-global') {
-    requireCommand('bash', 'Install bash before running skillpacks.');
-    return runCommand('bash', [initScriptPath, ...rest]);
+  if (command === 'uninstall-global') {
+    assertNoArgs('uninstall-global', rest);
+    return uninstallGlobal();
   }
 
   if (command === 'install-deck') {
     const deckInstall = resolveDeckInstall(rest);
-    requireCommand('bash', 'Install bash before running skillpacks.');
+    requireCommand('bash', 'Install bash before running gskp.');
     requireCommand(
       'jq',
       'Install with: brew install jq (macOS) or apt install jq (Debian/Ubuntu).'
@@ -249,6 +442,20 @@ export async function runSkillpacksCli(args) {
     return runCommand('bash', [packScriptPath, 'install', ...deckInstall.packs]);
   }
 
+  if (command === 'alignment') {
+    return runAlignment(rest);
+  }
+
+  if (command === 'init') {
+    if (rest.length > 0) {
+      throw new Error('init does not accept arguments');
+    }
+    return initProject({
+      manifest: readManifest(),
+      projectRoot: process.cwd()
+    });
+  }
+
   if (!PACK_COMMANDS.has(command)) {
     usage();
     throw new Error(`unknown command '${command}'`);
@@ -288,7 +495,9 @@ export async function runSkillpacksCli(args) {
 
   if (command === 'doctor') {
     return doctorProject({
-      projectRoot: process.cwd()
+      manifest: readManifest(),
+      projectRoot: process.cwd(),
+      args: rest
     });
   }
 
@@ -317,7 +526,7 @@ export async function runSkillpacksCli(args) {
     });
   }
 
-  requireCommand('bash', 'Install bash before running skillpacks.');
+  requireCommand('bash', 'Install bash before running gskp.');
 
   return runCommand('bash', [packScriptPath, command, ...rest]);
 }

package/src/cli/update-check.mjs

@@ -0,0 +1,77 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+
+const CACHE_PATH = join(homedir(), '.skillpacks-update-check.json');
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_URL = 'https://registry.npmjs.org/skillpacks/latest';
+
+async function fetchLatestVersion() {
+  const res = await fetch(REGISTRY_URL, {
+    headers: { accept: 'application/json' },
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!res.ok) return null;
+  const data = await res.json();
+  return data.version || null;
+}
+
+async function readCache() {
+  try {
+    const raw = await readFile(CACHE_PATH, 'utf8');
+    const cache = JSON.parse(raw);
+    if (Date.now() - cache.checkedAt < CACHE_TTL_MS) {
+      return cache.latestVersion;
+    }
+  } catch {}
+  return null;
+}
+
+async function writeCache(latestVersion) {
+  try {
+    await writeFile(CACHE_PATH, JSON.stringify({ latestVersion, checkedAt: Date.now() }));
+  } catch {}
+}
+
+export function startUpdateCheck() {
+  return (async () => {
+    const cached = await readCache();
+    if (cached) return cached;
+    const latest = await fetchLatestVersion();
+    if (latest) await writeCache(latest);
+    return latest;
+  })().catch(() => null);
+}
+
+function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const na = pa[i] || 0;
+    const nb = pb[i] || 0;
+    if (na < nb) return -1;
+    if (na > nb) return 1;
+  }
+  return 0;
+}
+
+export async function printUpdateNotice(checkPromise, currentVersion) {
+  try {
+    const latest = await checkPromise;
+    if (!latest || !currentVersion) return;
+    if (compareVersions(currentVersion, latest) >= 0) return;
+
+    const msg = `  Update available: ${currentVersion} → ${latest}`;
+    const run = '  Run: npx skillpacks@latest';
+    const width = Math.max(msg.length, run.length) + 2;
+    const pad = (s) => s + ' '.repeat(width - s.length);
+    const border = '─'.repeat(width);
+
+    process.stderr.write(
+      `\n╭${border}╮\n` +
+      `│${pad(msg)}│\n` +
+      `│${pad(run)}│\n` +
+      `╰${border}╯\n`
+    );
+  } catch {}
+}