@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.
- package/SKILL.md +84 -0
- package/format.mjs +570 -0
- 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(`[](${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 = `[](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
|
+
}
|