1#!/usr/bin/env node
2/**
3 * Pin/unpin sub-commands as standalone skill shortcuts.
4 *
5 * Usage:
6 *   node <scripts_path>/pin.mjs pin <command>
7 *   node <scripts_path>/pin.mjs unpin <command>
8 *
9 * `pin audit` creates a lightweight /audit skill that redirects to /impeccable audit.
10 * `unpin audit` removes that shortcut.
11 *
12 * The script discovers harness directories (.claude/skills, .cursor/skills, etc.)
13 * in the project root and creates/removes the pin in all of them.
14 */
15 
16import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from 'node:fs';
17import { join, resolve, dirname } from 'node:path';
18import { fileURLToPath } from 'node:url';
19 
20const __dirname = dirname(fileURLToPath(import.meta.url));
21 
22// All known harness directories
23const HARNESS_DIRS = [
24  '.claude', '.cursor', '.gemini', '.codex', '.agents',
25  '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
26];
27 
28// Valid sub-command names
29const VALID_COMMANDS = [
30  'craft', 'teach', 'extract', 'document', 'shape',
31  'critique', 'audit',
32  'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
33  'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',
34  'clarify', 'adapt', 'optimize',
35];
36 
37// Marker to identify pinned skills (so unpin doesn't delete user skills)
38const PIN_MARKER = '<!-- impeccable-pinned-skill -->';
39 
40/**
41 * Walk up from startDir to find a project root.
42 */
43function findProjectRoot(startDir = process.cwd()) {
44  let dir = resolve(startDir);
45  while (dir !== '/') {
46    if (
47      existsSync(join(dir, 'package.json')) ||
48      existsSync(join(dir, '.git')) ||
49      existsSync(join(dir, 'skills-lock.json'))
50    ) {
51      return dir;
52    }
53    const parent = resolve(dir, '..');
54    if (parent === dir) break;
55    dir = parent;
56  }
57  return resolve(startDir);
58}
59 
60/**
61 * Find harness skill directories that have an impeccable skill installed.
62 */
63function findHarnessDirs(projectRoot) {
64  const dirs = [];
65  for (const harness of HARNESS_DIRS) {
66    const skillsDir = join(projectRoot, harness, 'skills');
67    // Only pin in harness dirs that already have impeccable installed
68    const impeccableDir = join(skillsDir, 'impeccable');
69    if (existsSync(impeccableDir) || existsSync(join(skillsDir, 'i-impeccable'))) {
70      dirs.push(skillsDir);
71    }
72  }
73  return dirs;
74}
75 
76/**
77 * Load command metadata (descriptions for pinned skills).
78 */
79function loadCommandMetadata() {
80  const metadataPath = join(__dirname, 'command-metadata.json');
81  if (existsSync(metadataPath)) {
82    return JSON.parse(readFileSync(metadataPath, 'utf-8'));
83  }
84  return {};
85}
86 
87/**
88 * Generate a pinned skill's SKILL.md content.
89 */
90function generatePinnedSkill(command, metadata) {
91  const desc = metadata[command]?.description || `Shortcut for /impeccable ${command}.`;
92  const hint = metadata[command]?.argumentHint || '[target]';
93 
94  return `---
95name: ${command}
96description: "${desc}"
97argument-hint: "${hint}"
98user-invocable: true
99---
100 
101${PIN_MARKER}
102 
103This is a pinned shortcut for \`{{command_prefix}}impeccable ${command}\`.
104 
105Invoke {{command_prefix}}impeccable ${command}, passing along any arguments provided here, and follow its instructions.
106`;
107}
108 
109/**
110 * Pin a command: create shortcut skill in all harness dirs.
111 */
112function pin(command, projectRoot) {
113  const metadata = loadCommandMetadata();
114  const harnessDirs = findHarnessDirs(projectRoot);
115 
116  if (harnessDirs.length === 0) {
117    console.log('No harness directories with impeccable installed found.');
118    return false;
119  }
120 
121  const content = generatePinnedSkill(command, metadata);
122  let created = 0;
123 
124  for (const skillsDir of harnessDirs) {
125    // Check if skill already exists (and isn't a pin)
126    const skillDir = join(skillsDir, command);
127    if (existsSync(skillDir)) {
128      const existingMd = join(skillDir, 'SKILL.md');
129      if (existsSync(existingMd)) {
130        const existing = readFileSync(existingMd, 'utf-8');
131        if (!existing.includes(PIN_MARKER)) {
132          console.log(`  SKIP: ${skillDir} (non-pinned skill already exists)`);
133          continue;
134        }
135      }
136    }
137 
138    mkdirSync(skillDir, { recursive: true });
139    writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8');
140    console.log(`  + ${skillDir}`);
141    created++;
142  }
143 
144  if (created > 0) {
145    console.log(`\nPinned '${command}' as a standalone shortcut in ${created} location(s).`);
146    console.log(`You can now use /${command} directly.`);
147  }
148 
149  return created > 0;
150}
151 
152/**
153 * Unpin a command: remove shortcut skill from all harness dirs.
154 */
155function unpin(command, projectRoot) {
156  const harnessDirs = findHarnessDirs(projectRoot);
157  let removed = 0;
158 
159  for (const skillsDir of harnessDirs) {
160    const skillDir = join(skillsDir, command);
161    if (!existsSync(skillDir)) continue;
162 
163    const skillMd = join(skillDir, 'SKILL.md');
164    if (!existsSync(skillMd)) continue;
165 
166    // Safety: only remove if it's a pinned skill
167    const content = readFileSync(skillMd, 'utf-8');
168    if (!content.includes(PIN_MARKER)) {
169      console.log(`  SKIP: ${skillDir} (not a pinned skill)`);
170      continue;
171    }
172 
173    rmSync(skillDir, { recursive: true, force: true });
174    console.log(`  - ${skillDir}`);
175    removed++;
176  }
177 
178  if (removed > 0) {
179    console.log(`\nUnpinned '${command}' from ${removed} location(s).`);
180    console.log(`Use /impeccable ${command} to access it.`);
181  } else {
182    console.log(`No pinned '${command}' shortcut found.`);
183  }
184 
185  return removed > 0;
186}
187 
188// --- CLI ---
189const [,, action, command] = process.argv;
190 
191if (!action || !command) {
192  console.log('Usage: node pin.mjs <pin|unpin> <command>');
193  console.log(`\nAvailable commands: ${VALID_COMMANDS.join(', ')}`);
194  process.exit(1);
195}
196 
197if (action !== 'pin' && action !== 'unpin') {
198  console.error(`Unknown action: ${action}. Use 'pin' or 'unpin'.`);
199  process.exit(1);
200}
201 
202if (!VALID_COMMANDS.includes(command)) {
203  console.error(`Unknown command: ${command}`);
204  console.error(`Available commands: ${VALID_COMMANDS.join(', ')}`);
205  process.exit(1);
206}
207 
208const root = findProjectRoot();
209 
210if (action === 'pin') {
211  pin(command, root);
212} else {
213  unpin(command, root);
214}
215