@wipcomputer/wip-readme-format 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/SKILL.md +84 -0
  2. package/format.mjs +570 -0
  3. package/package.json +15 -0
package/SKILL.md ADDED
@@ -0,0 +1,84 @@
1
+ ---
2
+ name: wip-readme-format
3
+ description: Reformat any repo's README to follow the WIP Computer standard.
4
+ license: MIT
5
+ interface: [cli, skill]
6
+ metadata:
7
+ display-name: "README Formatter"
8
+ version: "1.0.0"
9
+ homepage: "https://github.com/wipcomputer/wip-ai-devops-toolbox"
10
+ author: "Parker Todd Brooks"
11
+ category: repo-management
12
+ capabilities:
13
+ - readme-generation
14
+ - readme-validation
15
+ - section-staging
16
+ requires:
17
+ bins: [node]
18
+ openclaw:
19
+ requires:
20
+ bins: [node]
21
+ install:
22
+ - id: node
23
+ kind: node
24
+ package: "@wipcomputer/wip-readme-format"
25
+ bins: [wip-readme-format]
26
+ label: "Install via npm"
27
+ emoji: "📝"
28
+ compatibility: Requires node. Node.js 18+.
29
+ ---
30
+
31
+ # README Formatter
32
+
33
+ Reformats a repo's README to follow the WIP Computer standard. Agent-first, human-readable.
34
+
35
+ ## Commands
36
+
37
+ ```
38
+ wip-readme-format /path/to/repo # rewrite README.md
39
+ wip-readme-format /path/to/repo --dry-run # preview without writing
40
+ wip-readme-format /path/to/repo --check # validate, exit 0/1
41
+ ```
42
+
43
+ ## What happens
44
+
45
+ 1. Detects all interfaces (CLI, Module, MCP, OC Plugin, Skill, CC Hook)
46
+ 2. Reads package.json for name, description, repo URL
47
+ 3. Reads SKILL.md for features
48
+ 4. Generates the README following the standard:
49
+ - WIP Computer header + interface badges
50
+ - Title + tagline
51
+ - "Teach Your AI" onboarding block
52
+ - Features list
53
+ - Interface coverage table (toolbox repos only)
54
+ - More Info links
55
+ - License block
56
+ 5. Moves technical content to TECHNICAL.md (never deleted)
57
+
58
+ ## The standard
59
+
60
+ ```
61
+ [badges]
62
+ # Tool Name
63
+ Tagline.
64
+
65
+ ## Teach Your AI to [verb]
66
+ [onboarding prompt block]
67
+
68
+ ## Features
69
+ [feature list]
70
+
71
+ ## Interface Coverage (toolbox only)
72
+ [auto-generated table]
73
+
74
+ ## More Info
75
+ - Technical Documentation ... link
76
+ - Universal Interface Spec ... link
77
+
78
+ ## License
79
+ [standard block]
80
+ ```
81
+
82
+ ## Interfaces
83
+
84
+ CLI, Skill
package/format.mjs ADDED
@@ -0,0 +1,570 @@
1
+ #!/usr/bin/env node
2
+ // wip-readme-format: reformat a repo's README to follow the WIP Computer standard.
3
+ //
4
+ // Usage:
5
+ // wip-readme-format /path/to/repo # generate README-init-*.md section files
6
+ // wip-readme-format /path/to/repo --deploy # assemble sections into README.md + TECHNICAL.md
7
+ // wip-readme-format /path/to/repo --dry-run # preview without writing
8
+ // wip-readme-format /path/to/repo --check # validate existing README, exit 0/1
9
+ //
10
+ // Generated files:
11
+ // README-init-badges.md Org header + interface badges
12
+ // README-init-title.md Title + tagline
13
+ // README-init-teach.md "Teach Your AI" onboarding block
14
+ // README-init-features.md Features list
15
+ // README-init-coverage.md Interface coverage table (toolbox only)
16
+ // README-init-more-info.md Links to docs
17
+ // README-init-license.md License block
18
+ // README-init-technical.md Technical content extracted from old README
19
+ //
20
+ // Workflow (same pattern as release notes):
21
+ // 1. wip-readme-format /path/to/repo ... generates section files
22
+ // 2. Edit any section you want (e.g. README-init-license.md)
23
+ // 3. wip-readme-format /path/to/repo --deploy ... assembles + moves into place
24
+
25
+ import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, readdirSync } from 'node:fs';
26
+ import { join, resolve, basename, dirname } from 'node:path';
27
+ import { fileURLToPath } from 'node:url';
28
+ import { detectInterfaces, detectToolbox } from '../wip-universal-installer/detect.mjs';
29
+
30
+ const __dirname = dirname(fileURLToPath(import.meta.url));
31
+ const args = process.argv.slice(2);
32
+ const DRY_RUN = args.includes('--dry-run');
33
+ const CHECK = args.includes('--check');
34
+ const DEPLOY = args.includes('--deploy');
35
+ const target = args.find(a => !a.startsWith('--'));
36
+
37
+ function log(msg) { console.log(` ${msg}`); }
38
+ function ok(msg) { console.log(` \u2713 ${msg}`); }
39
+ function fail(msg) { console.error(` \u2717 ${msg}`); }
40
+ function warn(msg) { console.log(` ! ${msg}`); }
41
+
42
+ function readJSON(path) {
43
+ try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
44
+ }
45
+
46
+ function readFile(path) {
47
+ try { return readFileSync(path, 'utf8'); } catch { return null; }
48
+ }
49
+
50
+ // Section order for assembly. "coverage" is optional (toolbox only).
51
+ // "technical" is separate (becomes TECHNICAL.md, not part of README).
52
+ const SECTION_ORDER = ['badges', 'title', 'teach', 'features', 'coverage', 'more-info', 'license'];
53
+
54
+ function initPath(repoPath, section) {
55
+ return join(repoPath, `README-init-${section}.md`);
56
+ }
57
+
58
+ // ── Badge generation ──
59
+
60
+ const BADGE_MAP = {
61
+ cli: { label: 'CLI', file: null },
62
+ module: { label: 'Module', file: null },
63
+ mcp: { label: 'MCP Server', file: 'mcp-server.mjs' },
64
+ openclaw: { label: 'OpenClaw Plugin', file: 'openclaw.plugin.json' },
65
+ skill: { label: 'Skill', file: 'SKILL.md' },
66
+ claudeCodeHook: { label: 'Claude Code Hook', file: 'guard.mjs' },
67
+ };
68
+
69
+ function generateBadges(interfaces, repoUrl) {
70
+ const badges = [];
71
+ for (const [key, info] of Object.entries(interfaces)) {
72
+ const meta = BADGE_MAP[key];
73
+ if (!meta) continue;
74
+ const label = meta.label.replace(/ /g, '_');
75
+ const badge = `https://img.shields.io/badge/interface-${label}-black`;
76
+ const link = meta.file && repoUrl
77
+ ? `${repoUrl}/blob/main/${meta.file}`
78
+ : repoUrl || '#';
79
+ badges.push(`[![${meta.label}](${badge})](${link})`);
80
+ }
81
+ return badges.join(' ');
82
+ }
83
+
84
+ // ── Teach Your AI block ──
85
+
86
+ function generateTeachBlock(toolName, repoUrl, skillPath) {
87
+ const skillUrl = repoUrl
88
+ ? `${repoUrl}/blob/main/${skillPath || 'SKILL.md'}`
89
+ : 'SKILL.md';
90
+ const installCmd = repoUrl
91
+ ? `wip-install ${repoUrl.replace('https://github.com/', '')} --dry-run`
92
+ : `wip-install /path/to/repo --dry-run`;
93
+
94
+ return `## Teach Your AI to Use ${toolName}
95
+
96
+ Open your AI and say:
97
+
98
+ \`\`\`
99
+ Read the SKILL.md at ${skillUrl.replace('https://', '')}.
100
+
101
+ Then explain to me:
102
+ 1. What are these tools?
103
+ 2. What do they do?
104
+ 3. What would they change about how we work together?
105
+
106
+ Then ask me:
107
+ - Do you have more questions?
108
+ - Do you want to install them?
109
+
110
+ If I say yes, run: ${installCmd}
111
+
112
+ Show me exactly what will change on my system. When I'm ready, I'll tell you
113
+ to install for real.
114
+ \`\`\`
115
+
116
+ Your agent will read the repo, explain everything, and do a dry-run install first so you can see exactly what changes before anything is written to your system.`;
117
+ }
118
+
119
+ // ── Interface coverage table (toolbox mode) ──
120
+
121
+ function extractSkillName(toolPath) {
122
+ const skillContent = readFile(join(toolPath, 'SKILL.md'));
123
+ if (!skillContent) return null;
124
+ const match = skillContent.match(/^---\s*\n[\s\S]*?^name:\s*(.+)/m);
125
+ return match ? match[1].trim() : null;
126
+ }
127
+
128
+ function generateInterfaceTable(repoPath, subTools) {
129
+ const rows = [];
130
+ let num = 0;
131
+ for (const tool of subTools) {
132
+ num++;
133
+ const { interfaces, pkg: toolPkg } = detectInterfaces(tool.path);
134
+ const skillName = extractSkillName(tool.path);
135
+ const name = skillName || (() => {
136
+ const rawName = toolPkg?.name?.replace(/^@\w+\//, '').replace(/^wip-/, '') || tool.name;
137
+ return rawName.split('-').map(w => {
138
+ const lower = w.toLowerCase();
139
+ if (['ai', 'api', 'cli', 'mcp', 'os', 'devops'].includes(lower)) return lower === 'devops' ? 'DevOps' : lower.toUpperCase();
140
+ return w.charAt(0).toUpperCase() + w.slice(1);
141
+ }).join(' ');
142
+ })();
143
+ const cli = interfaces.cli ? 'Y' : '';
144
+ const mod = interfaces.module ? 'Y' : '';
145
+ const mcp = interfaces.mcp ? 'Y' : '';
146
+ const oc = interfaces.openclaw ? 'Y' : '';
147
+ const skill = interfaces.skill ? 'Y' : '';
148
+ const hook = interfaces.claudeCodeHook ? 'Y' : '';
149
+ rows.push(`| ${num} | ${name} | ${cli} | ${mod} | ${mcp} | ${oc} | ${skill} | ${hook} |`);
150
+ }
151
+
152
+ return `## Interface Coverage
153
+
154
+ | # | Tool | CLI | Module | MCP | OC Plugin | Skill | CC Hook |
155
+ |---|------|-----|--------|-----|-----------|-------|---------|
156
+ ${rows.join('\n')}`;
157
+ }
158
+
159
+ // ── Features extraction ──
160
+
161
+ function extractToolboxFeatures(subTools) {
162
+ const features = [];
163
+ for (const tool of subTools) {
164
+ const pkg = readJSON(join(tool.path, 'package.json'));
165
+ const name = pkg?.name?.replace(/^@\w+\//, '').replace(/^wip-/, '') || tool.name;
166
+ const displayName = name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
167
+ const desc = pkg?.description || '_No description_';
168
+ features.push({ name: displayName, description: desc });
169
+ }
170
+ return features;
171
+ }
172
+
173
+ // ── License block ──
174
+
175
+ function generateLicenseBlock(repoPath) {
176
+ const licenseGuard = readJSON(join(repoPath, '.license-guard.json'));
177
+ if (licenseGuard) {
178
+ return `## License
179
+
180
+ \`\`\`
181
+ MIT All CLI tools, MCP servers, skills, and hooks (use anywhere, no restrictions).
182
+ AGPLv3 Commercial redistribution, marketplace listings, or bundling into paid services.
183
+ \`\`\`
184
+
185
+ AGPLv3 for personal use is free. Commercial licenses available.`;
186
+ }
187
+
188
+ const license = readFile(join(repoPath, 'LICENSE'));
189
+ if (license) {
190
+ const pkg = readJSON(join(repoPath, 'package.json'));
191
+ return `## License
192
+
193
+ ${pkg?.license || 'See LICENSE file.'}`;
194
+ }
195
+
196
+ return `## License
197
+
198
+ _No license information found. Run \`wip-license-guard init\` to set up licensing._`;
199
+ }
200
+
201
+ // ── More Info section ──
202
+
203
+ function generateMoreInfo(repoPath, repoUrl) {
204
+ const links = [];
205
+
206
+ if (existsSync(join(repoPath, 'TECHNICAL.md')) || existsSync(initPath(repoPath, 'technical'))) {
207
+ const techLink = repoUrl ? `${repoUrl}/blob/main/TECHNICAL.md` : 'TECHNICAL.md';
208
+ links.push(`- [Technical Documentation](${repoUrl ? techLink : 'TECHNICAL.md'}) ... Source code locations, build steps, development setup, architecture details`);
209
+ }
210
+
211
+ links.push(`- [Universal Interface Spec](https://github.com/wipcomputer/wip-ai-devops-toolbox/blob/main/tools/wip-universal-installer/SPEC.md) ... The six interfaces every agent-native tool can ship`);
212
+
213
+ if (existsSync(join(repoPath, 'DEV-GUIDE-GENERAL-PUBLIC.md'))) {
214
+ links.push(`- [Dev Guide](DEV-GUIDE-GENERAL-PUBLIC.md) ... Best practices for AI-assisted development`);
215
+ }
216
+
217
+ return `## More Info
218
+
219
+ ${links.join('\n')}`;
220
+ }
221
+
222
+ // ── Existing README content extraction ──
223
+
224
+ function extractExistingContent(readmePath) {
225
+ const content = readFile(readmePath);
226
+ if (!content) return {};
227
+
228
+ const sections = {};
229
+ let currentSection = '_preamble';
230
+ let currentContent = [];
231
+
232
+ for (const line of content.split('\n')) {
233
+ const headingMatch = line.match(/^##\s+(.+)/);
234
+ if (headingMatch) {
235
+ sections[currentSection] = currentContent.join('\n').trim();
236
+ currentSection = headingMatch[1].trim().toLowerCase();
237
+ currentContent = [];
238
+ } else {
239
+ currentContent.push(line);
240
+ }
241
+ }
242
+ sections[currentSection] = currentContent.join('\n').trim();
243
+
244
+ return sections;
245
+ }
246
+
247
+ // ── Technical content detection ──
248
+
249
+ function isTechnicalContent(section) {
250
+ const techKeywords = [
251
+ 'architecture', 'api', 'endpoint', 'build', 'development setup',
252
+ 'configuration', 'schema', 'database', 'migration', 'deployment',
253
+ 'docker', 'environment variable', 'debugging',
254
+ ];
255
+ const lower = section.toLowerCase();
256
+ return techKeywords.some(k => lower.includes(k));
257
+ }
258
+
259
+ // ── Main ──
260
+
261
+ if (!target || target === '--help' || target === '-h') {
262
+ console.log('');
263
+ console.log(' wip-readme-format ... reformat a README to follow the WIP Computer standard');
264
+ console.log('');
265
+ console.log(' Usage:');
266
+ console.log(' wip-readme-format /path/to/repo generate README-init-*.md section files');
267
+ console.log(' wip-readme-format /path/to/repo --deploy assemble sections, back up old, move into place');
268
+ console.log(' wip-readme-format /path/to/repo --dry-run preview without writing');
269
+ console.log(' wip-readme-format /path/to/repo --check validate existing README');
270
+ console.log('');
271
+ console.log(' Workflow:');
272
+ console.log(' 1. wip-readme-format /path/to/repo ... generates section files');
273
+ console.log(' 2. Edit any section (e.g. README-init-license.md)');
274
+ console.log(' 3. wip-readme-format /path/to/repo --deploy ... assembles into README.md');
275
+ console.log('');
276
+ console.log(' Section files (in assembly order):');
277
+ console.log(' README-init-badges.md Org header + interface badges');
278
+ console.log(' README-init-title.md Title + tagline');
279
+ console.log(' README-init-teach.md "Teach Your AI" onboarding block');
280
+ console.log(' README-init-features.md Features list');
281
+ console.log(' README-init-coverage.md Interface coverage table (toolbox only)');
282
+ console.log(' README-init-more-info.md Links to docs');
283
+ console.log(' README-init-license.md License block + built-by line');
284
+ console.log(' README-init-technical.md Technical content (becomes TECHNICAL.md)');
285
+ console.log('');
286
+ process.exit(0);
287
+ }
288
+
289
+ const repoPath = resolve(target);
290
+ if (!existsSync(repoPath)) {
291
+ fail(`Path not found: ${repoPath}`);
292
+ process.exit(1);
293
+ }
294
+
295
+ const pkg = readJSON(join(repoPath, 'package.json'));
296
+ const { interfaces } = detectInterfaces(repoPath);
297
+ const subTools = detectToolbox(repoPath);
298
+ const isToolbox = subTools.length > 0;
299
+
300
+ // Determine repo URL from package.json
301
+ let repoUrl = null;
302
+ if (pkg?.repository?.url) {
303
+ repoUrl = pkg.repository.url
304
+ .replace('git+', '')
305
+ .replace('.git', '');
306
+ }
307
+
308
+ // Tool name: human-readable
309
+ const toolName = pkg?.name?.replace(/^@\w+\//, '').replace(/^wip-/, '') || basename(repoPath);
310
+ const ACRONYMS = ['ai', 'api', 'cli', 'mcp', 'os', 'pr', 'ui', 'url', 'devops'];
311
+ const displayName = toolName
312
+ .split('-')
313
+ .map(w => {
314
+ const lower = w.toLowerCase();
315
+ if (ACRONYMS.includes(lower)) return lower === 'devops' ? 'DevOps' : lower.toUpperCase();
316
+ return w.charAt(0).toUpperCase() + w.slice(1);
317
+ })
318
+ .join(' ');
319
+
320
+ const tagline = pkg?.description || '_What it solves in human words. Not what it is technically._';
321
+
322
+ const readmePath = join(repoPath, 'README.md');
323
+ const technicalPath = join(repoPath, 'TECHNICAL.md');
324
+ const existing = extractExistingContent(readmePath);
325
+
326
+ // ── Deploy mode ──
327
+
328
+ if (DEPLOY) {
329
+ console.log('');
330
+ console.log(' wip-readme-format --deploy');
331
+ console.log(` Target: ${repoPath}`);
332
+ console.log(` ${'─'.repeat(40)}`);
333
+
334
+ // Check that at least the badges section exists
335
+ if (!existsSync(initPath(repoPath, 'badges'))) {
336
+ fail('No README-init-*.md files found. Run wip-readme-format first to generate them.');
337
+ process.exit(1);
338
+ }
339
+
340
+ const date = new Date().toISOString().slice(0, 10);
341
+ const aiTrash = join(repoPath, 'ai', '_trash');
342
+
343
+ // Back up existing README.md
344
+ const oldReadme = readFile(readmePath);
345
+ if (oldReadme) {
346
+ if (!existsSync(aiTrash)) mkdirSync(aiTrash, { recursive: true });
347
+ writeFileSync(join(aiTrash, `README--before-format--${date}.md`), oldReadme);
348
+ ok('Backed up README.md to ai/_trash/');
349
+ }
350
+
351
+ // Back up existing TECHNICAL.md
352
+ const oldTech = readFile(technicalPath);
353
+ if (oldTech) {
354
+ if (!existsSync(aiTrash)) mkdirSync(aiTrash, { recursive: true });
355
+ writeFileSync(join(aiTrash, `TECHNICAL--before-format--${date}.md`), oldTech);
356
+ ok('Backed up TECHNICAL.md to ai/_trash/');
357
+ }
358
+
359
+ // Assemble README from sections in order
360
+ const readmeParts = [];
361
+ for (const section of SECTION_ORDER) {
362
+ const sectionPath = initPath(repoPath, section);
363
+ const content = readFile(sectionPath);
364
+ if (content) {
365
+ readmeParts.push(content.trimEnd());
366
+ unlinkSync(sectionPath);
367
+ ok(` ${section} -> README.md`);
368
+ }
369
+ }
370
+
371
+ if (readmeParts.length === 0) {
372
+ fail('No section files found to assemble.');
373
+ process.exit(1);
374
+ }
375
+
376
+ writeFileSync(readmePath, readmeParts.join('\n\n') + '\n');
377
+ ok('Assembled README.md');
378
+
379
+ // Move technical -> TECHNICAL.md
380
+ const techPath = initPath(repoPath, 'technical');
381
+ if (existsSync(techPath)) {
382
+ const techContent = readFileSync(techPath, 'utf8');
383
+ writeFileSync(technicalPath, techContent);
384
+ unlinkSync(techPath);
385
+ ok('README-init-technical.md -> TECHNICAL.md');
386
+ }
387
+
388
+ console.log(` ${'─'.repeat(40)}`);
389
+ ok('Deployed. Old files in ai/_trash/.\n');
390
+ process.exit(0);
391
+ }
392
+
393
+ // ── Check mode ──
394
+
395
+ if (CHECK) {
396
+ console.log('');
397
+ console.log(' wip-readme-format --check');
398
+ console.log(` Target: ${repoPath}`);
399
+ console.log(` ${'─'.repeat(40)}`);
400
+
401
+ const content = readFile(readmePath);
402
+ if (!content) {
403
+ fail('No README.md found');
404
+ process.exit(1);
405
+ }
406
+
407
+ let passed = true;
408
+ const required = ['teach your ai', 'features', 'more info', 'license'];
409
+ const sectionNames = Object.keys(existing).filter(k => k !== '_preamble');
410
+
411
+ for (const section of required) {
412
+ const found = sectionNames.some(s => s.includes(section));
413
+ if (found) {
414
+ ok(`Has "${section}" section`);
415
+ } else {
416
+ fail(`Missing "${section}" section`);
417
+ passed = false;
418
+ }
419
+ }
420
+
421
+ if (content.includes('img.shields.io/badge/interface')) {
422
+ ok('Has interface badges');
423
+ } else {
424
+ fail('Missing interface badges');
425
+ passed = false;
426
+ }
427
+
428
+ if (isToolbox) {
429
+ if (content.includes('Interface Coverage') || content.includes('interface coverage')) {
430
+ ok('Has interface coverage table');
431
+ } else {
432
+ fail('Missing interface coverage table (toolbox repo)');
433
+ passed = false;
434
+ }
435
+ }
436
+
437
+ // Check for stale staging files
438
+ const stale = SECTION_ORDER.concat(['technical']).filter(s => existsSync(initPath(repoPath, s)));
439
+ if (stale.length > 0) {
440
+ warn(`${stale.length} README-init-*.md file(s) found. Run --deploy to assemble.`);
441
+ }
442
+
443
+ console.log(` ${'─'.repeat(40)}`);
444
+ if (passed) {
445
+ ok('README follows the standard');
446
+ process.exit(0);
447
+ } else {
448
+ fail('README does not follow the standard');
449
+ process.exit(1);
450
+ }
451
+ }
452
+
453
+ // ── Generate mode (default) ──
454
+
455
+ console.log('');
456
+ console.log(` wip-readme-format${DRY_RUN ? ' (dry run)' : ''}`);
457
+ console.log(` Target: ${repoPath}`);
458
+ console.log(` ${'─'.repeat(40)}`);
459
+ log(`Package: ${pkg?.name || 'unknown'}`);
460
+ log(`Interfaces: ${Object.keys(interfaces).join(', ') || 'none'}`);
461
+ if (isToolbox) log(`Toolbox: ${subTools.length} sub-tools`);
462
+ console.log('');
463
+
464
+ // ── Build each section ──
465
+
466
+ const sections = {};
467
+
468
+ // 1. Badges
469
+ let allInterfaces = { ...interfaces };
470
+ if (isToolbox) {
471
+ for (const tool of subTools) {
472
+ const { interfaces: subIfaces } = detectInterfaces(tool.path);
473
+ for (const key of Object.keys(subIfaces)) {
474
+ if (!allInterfaces[key]) allInterfaces[key] = subIfaces[key];
475
+ }
476
+ }
477
+ }
478
+ const badges = generateBadges(allInterfaces, repoUrl);
479
+ const specBadge = `[![Universal Interface Spec](https://img.shields.io/badge/Universal_Interface_Spec-black?style=flat&color=black)](https://github.com/wipcomputer/wip-ai-devops-toolbox/blob/main/tools/wip-universal-installer/SPEC.md)`;
480
+ const badgeLines = ['###### WIP Computer', ''];
481
+ if (badges) badgeLines.push(badges + ' ' + specBadge);
482
+ else badgeLines.push(specBadge);
483
+ sections.badges = badgeLines.join('\n');
484
+
485
+ // 2. Title + tagline
486
+ sections.title = `# ${displayName}\n\n${tagline}`;
487
+
488
+ // 3. Teach Your AI
489
+ const skillPath = interfaces.skill ? 'SKILL.md' : null;
490
+ if (skillPath || isToolbox) {
491
+ sections.teach = generateTeachBlock(displayName, repoUrl, skillPath);
492
+ }
493
+
494
+ // 4. Features
495
+ const featureKeys = Object.keys(existing).filter(k =>
496
+ k.includes('features') || k.includes('feature')
497
+ );
498
+ const existingFeatures = featureKeys.length > 0 ? existing[featureKeys[0]] : null;
499
+
500
+ if (existingFeatures) {
501
+ sections.features = `## Features\n\n${existingFeatures}`;
502
+ } else if (isToolbox) {
503
+ const toolFeatures = extractToolboxFeatures(subTools);
504
+ const lines = ['## Features', ''];
505
+ for (const f of toolFeatures) {
506
+ lines.push(`**${f.name}**`);
507
+ lines.push(`- ${f.description}`, '');
508
+ }
509
+ sections.features = lines.join('\n').trimEnd();
510
+ } else {
511
+ sections.features = `## Features\n\n_Describe what this tool does for the user. Human-readable. Name, description, stability tag._`;
512
+ }
513
+
514
+ // 5. Interface Coverage (toolbox only)
515
+ if (isToolbox) {
516
+ sections.coverage = generateInterfaceTable(repoPath, subTools);
517
+ }
518
+
519
+ // 6. More Info
520
+ sections['more-info'] = generateMoreInfo(repoPath, repoUrl);
521
+
522
+ // 7. License + built-by
523
+ sections.license = generateLicenseBlock(repoPath) +
524
+ '\n\nBuilt by Parker Todd Brooks, Lēsa (OpenClaw, Claude Opus 4.6), Claude Code (Claude Opus 4.6).';
525
+
526
+ // 8. Technical (separate file, becomes TECHNICAL.md)
527
+ const techSections = [];
528
+ for (const [name, content] of Object.entries(existing)) {
529
+ if (name === '_preamble') continue;
530
+ if (isTechnicalContent(content)) {
531
+ techSections.push(`## ${name.charAt(0).toUpperCase() + name.slice(1)}\n\n${content}`);
532
+ }
533
+ }
534
+ if (techSections.length > 0) {
535
+ const existingTech = readFile(technicalPath) || `# ${displayName} ... Technical Documentation\n\n`;
536
+ sections.technical = existingTech.trimEnd() + '\n\n' + techSections.join('\n\n');
537
+ }
538
+
539
+ // ── Output ──
540
+
541
+ if (DRY_RUN) {
542
+ for (const section of SECTION_ORDER) {
543
+ if (!sections[section]) continue;
544
+ console.log(` ── README-init-${section}.md ──\n`);
545
+ console.log(sections[section]);
546
+ console.log('');
547
+ }
548
+ if (sections.technical) {
549
+ console.log(` ── README-init-technical.md ──\n`);
550
+ console.log(` (${techSections.length} section(s) extracted from old README)`);
551
+ }
552
+ console.log(`\n ${'─'.repeat(40)}`);
553
+ console.log(' Dry run complete. No files written.\n');
554
+ } else {
555
+ let count = 0;
556
+ for (const section of SECTION_ORDER) {
557
+ if (!sections[section]) continue;
558
+ writeFileSync(initPath(repoPath, section), sections[section] + '\n');
559
+ ok(`README-init-${section}.md`);
560
+ count++;
561
+ }
562
+ if (sections.technical) {
563
+ writeFileSync(initPath(repoPath, 'technical'), sections.technical + '\n');
564
+ ok('README-init-technical.md');
565
+ count++;
566
+ }
567
+
568
+ console.log(` ${'─'.repeat(40)}`);
569
+ ok(`${count} section files written. Edit any, then run with --deploy.\n`);
570
+ }
package/package.json ADDED
@@ -0,0 +1,15 @@
1
+ {
2
+ "name": "@wipcomputer/wip-readme-format",
3
+ "version": "1.0.0",
4
+ "description": "Reformat any repo's README to follow the WIP Computer standard. Agent-first, human-readable.",
5
+ "type": "module",
6
+ "bin": {
7
+ "wip-readme-format": "./format.mjs"
8
+ },
9
+ "license": "MIT AND AGPL-3.0-or-later",
10
+ "repository": {
11
+ "type": "git",
12
+ "url": "git+https://github.com/wipcomputer/wip-ai-devops-toolbox.git",
13
+ "directory": "tools/wip-readme-format"
14
+ }
15
+ }