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