@shrkcrft/cli 0.1.0-alpha.1 → 0.1.0-alpha.10
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/README.md +1 -1
- package/dist/commands/api-diff.command.d.ts +11 -0
- package/dist/commands/api-diff.command.d.ts.map +1 -0
- package/dist/commands/api-diff.command.js +116 -0
- package/dist/commands/arch.command.d.ts +9 -0
- package/dist/commands/arch.command.d.ts.map +1 -0
- package/dist/commands/arch.command.js +186 -0
- package/dist/commands/boundaries.command.d.ts.map +1 -1
- package/dist/commands/boundaries.command.js +0 -12
- package/dist/commands/check.command.d.ts.map +1 -1
- package/dist/commands/check.command.js +20 -30
- package/dist/commands/code-intel.command.d.ts +18 -0
- package/dist/commands/code-intel.command.d.ts.map +1 -0
- package/dist/commands/code-intel.command.js +146 -0
- package/dist/commands/command-catalog.d.ts +7 -3
- package/dist/commands/command-catalog.d.ts.map +1 -1
- package/dist/commands/command-catalog.js +201 -47
- package/dist/commands/commands.command.d.ts.map +1 -1
- package/dist/commands/commands.command.js +4 -4
- package/dist/commands/completion.command.d.ts +10 -0
- package/dist/commands/completion.command.d.ts.map +1 -0
- package/dist/commands/completion.command.js +121 -0
- package/dist/commands/constructs.command.d.ts.map +1 -1
- package/dist/commands/constructs.command.js +5 -22
- package/dist/commands/context.command.d.ts.map +1 -1
- package/dist/commands/context.command.js +89 -0
- package/dist/commands/diff-check.command.d.ts +30 -0
- package/dist/commands/diff-check.command.d.ts.map +1 -0
- package/dist/commands/diff-check.command.js +210 -0
- package/dist/commands/doctor.command.d.ts.map +1 -1
- package/dist/commands/doctor.command.js +42 -9
- package/dist/commands/export.command.d.ts.map +1 -1
- package/dist/commands/export.command.js +76 -3
- package/dist/commands/framework.command.d.ts +12 -0
- package/dist/commands/framework.command.d.ts.map +1 -0
- package/dist/commands/framework.command.js +180 -0
- package/dist/commands/gate.command.d.ts +15 -0
- package/dist/commands/gate.command.d.ts.map +1 -0
- package/dist/commands/gate.command.js +296 -0
- package/dist/commands/graph-code-subverbs.d.ts +11 -0
- package/dist/commands/graph-code-subverbs.d.ts.map +1 -0
- package/dist/commands/graph-code-subverbs.js +818 -0
- package/dist/commands/graph.command.d.ts.map +1 -1
- package/dist/commands/graph.command.js +22 -0
- package/dist/commands/help.command.d.ts +4 -3
- package/dist/commands/help.command.d.ts.map +1 -1
- package/dist/commands/help.command.js +77 -21
- package/dist/commands/helper.command.js +1 -1
- package/dist/commands/impact.command.d.ts.map +1 -1
- package/dist/commands/impact.command.js +170 -1
- package/dist/commands/import.command.d.ts.map +1 -1
- package/dist/commands/import.command.js +121 -5
- package/dist/commands/init.command.d.ts.map +1 -1
- package/dist/commands/init.command.js +184 -16
- package/dist/commands/mcp.command.d.ts.map +1 -1
- package/dist/commands/mcp.command.js +2 -131
- package/dist/commands/migrate.command.d.ts +13 -0
- package/dist/commands/migrate.command.d.ts.map +1 -0
- package/dist/commands/migrate.command.js +152 -0
- package/dist/commands/onboard.command.d.ts.map +1 -1
- package/dist/commands/onboard.command.js +3 -15
- package/dist/commands/packs-new.d.ts +1 -1
- package/dist/commands/packs-new.d.ts.map +1 -1
- package/dist/commands/packs-new.js +5 -36
- package/dist/commands/packs.command.d.ts.map +1 -1
- package/dist/commands/packs.command.js +3 -17
- package/dist/commands/plan-context.command.d.ts +11 -0
- package/dist/commands/plan-context.command.d.ts.map +1 -0
- package/dist/commands/plan-context.command.js +77 -0
- package/dist/commands/profiles.command.js +4 -4
- package/dist/commands/release.command.js +13 -13
- package/dist/commands/review.command.d.ts.map +1 -1
- package/dist/commands/review.command.js +2 -28
- package/dist/commands/rule-graph-subverbs.d.ts +3 -0
- package/dist/commands/rule-graph-subverbs.d.ts.map +1 -0
- package/dist/commands/rule-graph-subverbs.js +132 -0
- package/dist/commands/search-structural.command.d.ts +18 -0
- package/dist/commands/search-structural.command.d.ts.map +1 -0
- package/dist/commands/search-structural.command.js +376 -0
- package/dist/commands/search.command.js +1 -1
- package/dist/commands/task-context.command.js +0 -16
- package/dist/commands/task.command.d.ts.map +1 -1
- package/dist/commands/task.command.js +8 -2
- package/dist/dashboard/code-intelligence-data.d.ts +33 -0
- package/dist/dashboard/code-intelligence-data.d.ts.map +1 -0
- package/dist/dashboard/code-intelligence-data.js +307 -0
- package/dist/dashboard/dashboard-api-server.d.ts.map +1 -1
- package/dist/dashboard/dashboard-api-server.js +137 -1
- package/dist/export/claude-commands-export.d.ts +60 -0
- package/dist/export/claude-commands-export.d.ts.map +1 -0
- package/dist/export/claude-commands-export.js +276 -0
- package/dist/export/export-formats.d.ts +1 -1
- package/dist/export/export-formats.d.ts.map +1 -1
- package/dist/export/export-formats.js +139 -12
- package/dist/init/init-templates.d.ts.map +1 -1
- package/dist/init/init-templates.js +133 -113
- package/dist/init/paths-advisory.d.ts +20 -0
- package/dist/init/paths-advisory.d.ts.map +1 -0
- package/dist/init/paths-advisory.js +88 -0
- package/dist/main.d.ts +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +137 -46
- package/dist/output/failure-hints.d.ts +1 -9
- package/dist/output/failure-hints.d.ts.map +1 -1
- package/dist/output/failure-hints.js +2 -8
- package/dist/output/watch-loop.d.ts +9 -1
- package/dist/output/watch-loop.d.ts.map +1 -1
- package/dist/output/watch-loop.js +13 -3
- package/dist/schemas/json-schemas.d.ts +36 -36
- package/dist/schemas/json-schemas.js +36 -36
- package/dist/surface/about.d.ts.map +1 -1
- package/dist/surface/about.js +37 -15
- package/dist/surface/no-args-landing.d.ts.map +1 -1
- package/dist/surface/no-args-landing.js +9 -13
- package/dist/surface/surface-config-writer.d.ts.map +1 -1
- package/dist/surface/surface-config-writer.js +23 -11
- package/package.json +36 -25
- package/dist/commands/plugin.command.d.ts +0 -11
- package/dist/commands/plugin.command.d.ts.map +0 -1
- package/dist/commands/plugin.command.js +0 -394
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `.claude/commands/` generator — emits per-project slash commands
|
|
3
|
+
* for Claude Code. Companion to `claude-skill` export, but with a
|
|
4
|
+
* different inversion semantics:
|
|
5
|
+
*
|
|
6
|
+
* - **claude-skill** loads rules into Claude's prompt automatically
|
|
7
|
+
* based on description match. Passive — Claude reads the rules.
|
|
8
|
+
* - **claude-commands** registers slash commands the USER invokes
|
|
9
|
+
* (`/new-service`, `/check-changes`). Active — the command IS the
|
|
10
|
+
* recipe; Claude follows it step-by-step.
|
|
11
|
+
*
|
|
12
|
+
* Generated commands fall into two buckets:
|
|
13
|
+
*
|
|
14
|
+
* **Static commands** (always present, project-agnostic recipes):
|
|
15
|
+
* - `/follow-shrk` — short reminder of the apply-gate flow.
|
|
16
|
+
* - `/check-changes` — runs `shrk check boundaries --changed-only`
|
|
17
|
+
* scoped to the current diff and reports back.
|
|
18
|
+
* - `/shrk-brief` — runs `shrk brief` and uses the output for the
|
|
19
|
+
* current task.
|
|
20
|
+
* - `/explain-file <path>` — per-file rules / paths / boundary
|
|
21
|
+
* lookup (pairs with `shrk advise <path>` from Phase 3).
|
|
22
|
+
*
|
|
23
|
+
* **Per-template commands** (one per id in `sharkcraft/templates.ts`):
|
|
24
|
+
* - `/new-<template-id>` — Claude runs `shrk gen <template-id>
|
|
25
|
+
* <name> --dry-run --save-plan ...`, reviews the plan, and
|
|
26
|
+
* applies via `shrk apply ... --verify-signature --validate`.
|
|
27
|
+
*
|
|
28
|
+
* Generated files are self-contained markdown — no `@shrkcrft/*`
|
|
29
|
+
* imports, no shell expansions. Each one is a complete "recipe in a
|
|
30
|
+
* file" that Claude Code reads when the user types the slash command.
|
|
31
|
+
*/
|
|
32
|
+
// ─── Static commands (always emitted) ────────────────────────────────────────
|
|
33
|
+
const STATIC_FOLLOW_SHRK = `---
|
|
34
|
+
description: Reminder of the shrk apply-gate flow for this project. Use when generating or modifying code so the change passes the same boundary / validation gates the project CI uses.
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
# Follow the shrk apply-gate flow
|
|
38
|
+
|
|
39
|
+
This repo uses [SharkCraft](https://github.com/shrkcrft/sharkcraft) as the
|
|
40
|
+
gate for AI-written code. Skip the gate and CI will fail with the same
|
|
41
|
+
errors anyway — save the round-trip.
|
|
42
|
+
|
|
43
|
+
## The loop
|
|
44
|
+
|
|
45
|
+
1. **Get focused context first.**
|
|
46
|
+
- Run: \`shrk task "<one-sentence task>"\` for a task packet (relevant rules + templates + verification commands).
|
|
47
|
+
- Or: \`shrk brief\` for the single-page project brief.
|
|
48
|
+
|
|
49
|
+
2. **Scaffold via a template (not freehand).**
|
|
50
|
+
- List options: \`shrk templates list\`.
|
|
51
|
+
- Dry-run + save plan: \`shrk gen <template-id> <name> --dry-run --save-plan /tmp/plan.json\`.
|
|
52
|
+
|
|
53
|
+
3. **Apply the plan through the CLI.**
|
|
54
|
+
- \`shrk apply /tmp/plan.json --verify-signature --validate\`.
|
|
55
|
+
- Never write files directly through MCP — MCP is read-only in this repo.
|
|
56
|
+
|
|
57
|
+
4. **Verify before declaring done.**
|
|
58
|
+
- \`shrk check boundaries --changed-only\` — fails if the diff broke any layer rule.
|
|
59
|
+
- \`shrk check imports\` — fails on lazy requires / cross-package deep imports.
|
|
60
|
+
- Project verification commands (from \`shrk task\`'s \`actionHints.verificationCommands\`).
|
|
61
|
+
|
|
62
|
+
## When this loop doesn't apply
|
|
63
|
+
|
|
64
|
+
- Tiny changes that don't touch source files (docs, comments).
|
|
65
|
+
- Read-only investigations.
|
|
66
|
+
- Anything where shrk would clearly be in the way.
|
|
67
|
+
|
|
68
|
+
In all other cases: **follow the loop**. The gates are short; the rework if you skip them is long.
|
|
69
|
+
`;
|
|
70
|
+
const STATIC_CHECK_CHANGES = `---
|
|
71
|
+
description: Run shrk's boundary + import-hygiene checks on the current git diff. Use after making any file change to confirm the change didn't violate the project's architecture rules before declaring the task done.
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
# Check the current diff for boundary violations
|
|
75
|
+
|
|
76
|
+
Run the diff-scoped boundary check:
|
|
77
|
+
|
|
78
|
+
\`\`\`bash
|
|
79
|
+
shrk check boundaries --changed-only
|
|
80
|
+
\`\`\`
|
|
81
|
+
|
|
82
|
+
Run the import-hygiene check on the changed files:
|
|
83
|
+
|
|
84
|
+
\`\`\`bash
|
|
85
|
+
shrk check imports
|
|
86
|
+
\`\`\`
|
|
87
|
+
|
|
88
|
+
## Interpreting the output
|
|
89
|
+
|
|
90
|
+
- **Exit 0, "0 violations":** safe to declare done.
|
|
91
|
+
- **Exit non-zero with violations listed:** fix each violation before continuing. Each violation has a \`suggestedFix\` line — apply it.
|
|
92
|
+
- **A violation on a file you didn't change:** that's a pre-existing violation in the repo. Ignore it; the \`--changed-only\` filter only fails on violations your diff introduced.
|
|
93
|
+
|
|
94
|
+
If the violations look like false positives, consult \`sharkcraft/boundaries.ts\` (the rule definitions) — don't disable them ad-hoc.
|
|
95
|
+
`;
|
|
96
|
+
const STATIC_SHRK_BRIEF = `---
|
|
97
|
+
description: Pull shrk's single-page project brief — focused rules, paths, verification commands. Use when starting work in this codebase so you have the project's actual conventions in context before writing any code.
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
# Pull the shrk brief for this project
|
|
101
|
+
|
|
102
|
+
Run the project brief:
|
|
103
|
+
|
|
104
|
+
\`\`\`bash
|
|
105
|
+
shrk brief
|
|
106
|
+
\`\`\`
|
|
107
|
+
|
|
108
|
+
This returns a compact markdown brief covering:
|
|
109
|
+
- Project overview (name, frameworks, package manager).
|
|
110
|
+
- Top rules that apply to code generation in this repo.
|
|
111
|
+
- Path conventions (where different file types belong).
|
|
112
|
+
- Action hints (commands, MCP tools, verification commands).
|
|
113
|
+
- Forbidden actions (what NOT to do).
|
|
114
|
+
|
|
115
|
+
For a per-task version (only the rules + paths + templates relevant to one task):
|
|
116
|
+
|
|
117
|
+
\`\`\`bash
|
|
118
|
+
shrk task "<one-sentence task description>"
|
|
119
|
+
\`\`\`
|
|
120
|
+
|
|
121
|
+
Both are read-only — no files are touched. Use the output to shape your plan before making any changes.
|
|
122
|
+
`;
|
|
123
|
+
const STATIC_EXPLAIN_FILE = `---
|
|
124
|
+
description: Look up the rules, path conventions, and boundary rules that apply to a specific file in this codebase. Use before editing an unfamiliar file so you follow the project's per-area conventions instead of generic patterns.
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
# Explain what applies to a file in this codebase
|
|
128
|
+
|
|
129
|
+
For a given file path (e.g. \`apps/users/src/profile.service.ts\`):
|
|
130
|
+
|
|
131
|
+
\`\`\`bash
|
|
132
|
+
shrk why <file-path>
|
|
133
|
+
\`\`\`
|
|
134
|
+
|
|
135
|
+
Returns:
|
|
136
|
+
- Which package / layer the file belongs to.
|
|
137
|
+
- Which path conventions apply (e.g. "services live in \`apps/<x>/src/services/\`").
|
|
138
|
+
- Which rules are scoped to this file's path.
|
|
139
|
+
- Which boundary rules constrain this file's imports.
|
|
140
|
+
- Cross-references to related knowledge entries.
|
|
141
|
+
|
|
142
|
+
Use this *before* editing. The output is the project's actual conventions for that area, not your guess based on the file's content.
|
|
143
|
+
`;
|
|
144
|
+
// ─── Per-template command generator ──────────────────────────────────────────
|
|
145
|
+
/**
|
|
146
|
+
* Slugify a template id into a slash-command name. Template ids
|
|
147
|
+
* conventionally look like `typescript.service`; the slash command is
|
|
148
|
+
* `new-typescript-service` (or `new-service` if the segment after the
|
|
149
|
+
* dot is unique and shorter).
|
|
150
|
+
*/
|
|
151
|
+
function templateSlash(templateId) {
|
|
152
|
+
// Use the LAST dot-separated segment as the primary name —
|
|
153
|
+
// `typescript.service` → `new-service`. Falls back to the full id
|
|
154
|
+
// when there's no dot or the segment is too generic (single char).
|
|
155
|
+
const parts = templateId.split('.');
|
|
156
|
+
const tail = parts[parts.length - 1] ?? templateId;
|
|
157
|
+
const safeName = tail.length >= 3 ? tail : templateId.replace(/\./g, '-');
|
|
158
|
+
return `new-${safeName}`
|
|
159
|
+
.toLowerCase()
|
|
160
|
+
.replace(/[^a-z0-9-]+/g, '-')
|
|
161
|
+
.replace(/-+/g, '-')
|
|
162
|
+
.replace(/^-+|-+$/g, '');
|
|
163
|
+
}
|
|
164
|
+
function templateCommandBody(template) {
|
|
165
|
+
const displayName = template.name ?? template.id;
|
|
166
|
+
const description = template.description
|
|
167
|
+
? template.description.replace(/\s+/g, ' ').trim()
|
|
168
|
+
: `Scaffold a new ${displayName} using the project's actual template (\`${template.id}\`). Follows the shrk plan → apply → validate flow.`;
|
|
169
|
+
return `---
|
|
170
|
+
description: ${JSON.stringify(description)}
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
# /${templateSlash(template.id)} — scaffold ${displayName}
|
|
174
|
+
|
|
175
|
+
This command scaffolds a new ${displayName} using the project's actual template
|
|
176
|
+
defined in \`sharkcraft/templates.ts\`. The template encodes this repo's
|
|
177
|
+
conventions for path, naming, and structure — the result will match how
|
|
178
|
+
the rest of the codebase is organized, not generic patterns.
|
|
179
|
+
|
|
180
|
+
## The flow
|
|
181
|
+
|
|
182
|
+
When the user invokes \`/${templateSlash(template.id)} <name>\`:
|
|
183
|
+
|
|
184
|
+
1. **Generate a plan (no writes yet):**
|
|
185
|
+
\`\`\`bash
|
|
186
|
+
shrk gen ${template.id} <name> --dry-run --save-plan /tmp/${templateSlash(template.id)}.plan.json
|
|
187
|
+
\`\`\`
|
|
188
|
+
|
|
189
|
+
2. **Read the plan back** from \`/tmp/${templateSlash(template.id)}.plan.json\` and show the user which files will be created.
|
|
190
|
+
|
|
191
|
+
3. **Confirm.** Wait for the user to approve. If they want changes, adjust the plan or re-run \`shrk gen\` with different flags.
|
|
192
|
+
|
|
193
|
+
4. **Apply through the validated CLI path:**
|
|
194
|
+
\`\`\`bash
|
|
195
|
+
shrk apply /tmp/${templateSlash(template.id)}.plan.json --verify-signature --validate
|
|
196
|
+
\`\`\`
|
|
197
|
+
|
|
198
|
+
5. **Verify** the diff didn't break any boundary rules:
|
|
199
|
+
\`\`\`bash
|
|
200
|
+
shrk check boundaries --changed-only
|
|
201
|
+
\`\`\`
|
|
202
|
+
|
|
203
|
+
## If the template doesn't fit
|
|
204
|
+
|
|
205
|
+
If the user's request doesn't match the \`${template.id}\` template
|
|
206
|
+
shape, fall back to:
|
|
207
|
+
|
|
208
|
+
- \`shrk templates list\` — see all available templates.
|
|
209
|
+
- \`shrk gen <other-template> <name> --dry-run\` — try a different template.
|
|
210
|
+
- Hand-author only as last resort, and run \`/check-changes\` after.
|
|
211
|
+
|
|
212
|
+
The whole point of using the template is consistency with the rest of
|
|
213
|
+
this codebase. Skipping it means the new code will look different from
|
|
214
|
+
what's already there.
|
|
215
|
+
`;
|
|
216
|
+
}
|
|
217
|
+
/**
|
|
218
|
+
* Build the full set of `.claude/commands/*.md` files for a project.
|
|
219
|
+
*
|
|
220
|
+
* Pure — caller writes the bytes. Same shape as the `synthesize-*`
|
|
221
|
+
* functions in this codebase: input inspection → output file list.
|
|
222
|
+
*/
|
|
223
|
+
export function buildClaudeCommands(inspection, options = {}) {
|
|
224
|
+
const files = [];
|
|
225
|
+
files.push({
|
|
226
|
+
path: '.claude/commands/follow-shrk.md',
|
|
227
|
+
slash: 'follow-shrk',
|
|
228
|
+
source: 'static',
|
|
229
|
+
content: STATIC_FOLLOW_SHRK,
|
|
230
|
+
});
|
|
231
|
+
files.push({
|
|
232
|
+
path: '.claude/commands/check-changes.md',
|
|
233
|
+
slash: 'check-changes',
|
|
234
|
+
source: 'static',
|
|
235
|
+
content: STATIC_CHECK_CHANGES,
|
|
236
|
+
});
|
|
237
|
+
files.push({
|
|
238
|
+
path: '.claude/commands/shrk-brief.md',
|
|
239
|
+
slash: 'shrk-brief',
|
|
240
|
+
source: 'static',
|
|
241
|
+
content: STATIC_SHRK_BRIEF,
|
|
242
|
+
});
|
|
243
|
+
files.push({
|
|
244
|
+
path: '.claude/commands/explain-file.md',
|
|
245
|
+
slash: 'explain-file',
|
|
246
|
+
source: 'static',
|
|
247
|
+
content: STATIC_EXPLAIN_FILE,
|
|
248
|
+
});
|
|
249
|
+
// Per-template commands — bounded so a pack with 50 templates
|
|
250
|
+
// doesn't dump 50 slash commands into the user's palette. Sorted
|
|
251
|
+
// by id for deterministic emit order.
|
|
252
|
+
const cap = options.maxTemplateCommands ?? 20;
|
|
253
|
+
const templates = [...inspection.templates].sort((a, b) => a.id.localeCompare(b.id));
|
|
254
|
+
const seenSlash = new Set(files.map((f) => f.slash));
|
|
255
|
+
for (const t of templates) {
|
|
256
|
+
if (files.filter((f) => f.source === 'template').length >= cap)
|
|
257
|
+
break;
|
|
258
|
+
let slash = templateSlash(t.id);
|
|
259
|
+
if (seenSlash.has(slash)) {
|
|
260
|
+
// Two templates with the same tail (e.g. `ts.service` and
|
|
261
|
+
// `py.service` both → `new-service`) — fall back to the full id
|
|
262
|
+
// to disambiguate the second one.
|
|
263
|
+
slash = `new-${t.id.replace(/\./g, '-').toLowerCase()}`;
|
|
264
|
+
if (seenSlash.has(slash))
|
|
265
|
+
continue;
|
|
266
|
+
}
|
|
267
|
+
seenSlash.add(slash);
|
|
268
|
+
files.push({
|
|
269
|
+
path: `.claude/commands/${slash}.md`,
|
|
270
|
+
slash,
|
|
271
|
+
source: 'template',
|
|
272
|
+
content: templateCommandBody(t),
|
|
273
|
+
});
|
|
274
|
+
}
|
|
275
|
+
return { files };
|
|
276
|
+
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ISharkcraftInspection } from '@shrkcrft/inspector';
|
|
2
|
-
export type ExportFormat = 'agents-md' | 'claude-md' | 'cursor-rules' | 'copilot-instructions';
|
|
2
|
+
export type ExportFormat = 'agents-md' | 'claude-md' | 'claude-skill' | 'cursor-rules' | 'copilot-instructions';
|
|
3
3
|
export interface ExportOptions {
|
|
4
4
|
format: ExportFormat;
|
|
5
5
|
/** Optional task to scope the export. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"export-formats.d.ts","sourceRoot":"","sources":["../../src/export/export-formats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAIjE,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,WAAW,GACX,cAAc,GACd,sBAAsB,CAAC;AAE3B,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;
|
|
1
|
+
{"version":3,"file":"export-formats.d.ts","sourceRoot":"","sources":["../../src/export/export-formats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAIjE,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,WAAW,GACX,cAAc,GACd,cAAc,GACd,sBAAsB,CAAC;AAE3B,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAqPD,wBAAgB,YAAY,CAC1B,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,aAAa,GACrB,YAAY,CAmCd;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAQnE;AAED,eAAO,MAAM,kBAAkB,EAAE,SAAS,YAAY,EAMpD,CAAC"}
|
|
@@ -1,11 +1,28 @@
|
|
|
1
1
|
import { aggregateActionHints, KnowledgeType } from '@shrkcrft/knowledge';
|
|
2
2
|
import { priorityWeight } from '@shrkcrft/knowledge';
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
3
|
+
function projectSlug(name) {
|
|
4
|
+
if (!name)
|
|
5
|
+
return 'project';
|
|
6
|
+
return (name
|
|
7
|
+
.toLowerCase()
|
|
8
|
+
.replace(/[^a-z0-9]+/g, '-')
|
|
9
|
+
.replace(/^-+|-+$/g, '')
|
|
10
|
+
.slice(0, 48) || 'project');
|
|
11
|
+
}
|
|
12
|
+
function defaultOutputFor(format, inspection) {
|
|
13
|
+
switch (format) {
|
|
14
|
+
case 'agents-md':
|
|
15
|
+
return 'AGENTS.md';
|
|
16
|
+
case 'claude-md':
|
|
17
|
+
return 'CLAUDE.md';
|
|
18
|
+
case 'claude-skill':
|
|
19
|
+
return `.claude/skills/${projectSlug(inspection.config?.projectName)}/SKILL.md`;
|
|
20
|
+
case 'cursor-rules':
|
|
21
|
+
return '.cursor/rules/sharkcraft.mdc';
|
|
22
|
+
case 'copilot-instructions':
|
|
23
|
+
return '.github/copilot-instructions.md';
|
|
24
|
+
}
|
|
25
|
+
}
|
|
9
26
|
function selectTopByPriority(entries, limit) {
|
|
10
27
|
return [...entries]
|
|
11
28
|
.sort((a, b) => priorityWeight(b.priority) - priorityWeight(a.priority))
|
|
@@ -100,23 +117,131 @@ function renderBody(inspection, options) {
|
|
|
100
117
|
}
|
|
101
118
|
return sections.join('\n\n');
|
|
102
119
|
}
|
|
120
|
+
/**
|
|
121
|
+
* Filter rules / paths to the high-signal subset for an inlined skill.
|
|
122
|
+
*
|
|
123
|
+
* Every rule the skill carries pays in Claude's context every time the
|
|
124
|
+
* skill is loaded. Low-priority items dilute the signal of the
|
|
125
|
+
* load-bearing ones (`Critical` safety + `High` architecture). We keep
|
|
126
|
+
* only Critical + High by default, falling back to "all" only if the
|
|
127
|
+
* filtered list is empty (e.g. a repo with no high-priority entries
|
|
128
|
+
* yet shouldn't ship an empty skill).
|
|
129
|
+
*/
|
|
130
|
+
function filterHighSignal(entries) {
|
|
131
|
+
const filtered = entries.filter((e) => {
|
|
132
|
+
const p = String(e.priority).toLowerCase();
|
|
133
|
+
return p === 'critical' || p === 'high';
|
|
134
|
+
});
|
|
135
|
+
return filtered.length > 0 ? filtered : [...entries];
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* Render the body in tight, decision-driving form for the Claude Code
|
|
139
|
+
* Skill format. Skills get loaded into Claude's prompt when the skill's
|
|
140
|
+
* `description` matches the current task, so the body must be short and
|
|
141
|
+
* directly actionable — no preamble, no metadata about generation, no
|
|
142
|
+
* pipelines (Claude can run `shrk task` for those when needed).
|
|
143
|
+
*
|
|
144
|
+
* Sections:
|
|
145
|
+
* 1. Where files belong (path conventions, top N) — most-leveraged signal.
|
|
146
|
+
* 2. Rules to follow (Critical + High only) — pads context otherwise.
|
|
147
|
+
* 3. Do / Don't — forbidden actions and verification commands.
|
|
148
|
+
* 4. How to write code in this repo — the gen → review → apply loop
|
|
149
|
+
* verbatim, since Claude needs to know shrk is the write path.
|
|
150
|
+
*/
|
|
151
|
+
function renderSkillBody(inspection, options) {
|
|
152
|
+
const { rules: allRules, paths: allPaths } = gatherRulesAndPaths(inspection, {
|
|
153
|
+
...options,
|
|
154
|
+
// Pull more upfront, then filter down to high-signal — keeps the
|
|
155
|
+
// softcap-at-15 default but the inlined skill stays terse.
|
|
156
|
+
maxRules: options.maxRules ?? 24,
|
|
157
|
+
maxPaths: options.maxPaths ?? 18,
|
|
158
|
+
});
|
|
159
|
+
// Skills are inlined into the prompt — every entry costs Claude
|
|
160
|
+
// context. Only ship the items the user said are load-bearing.
|
|
161
|
+
const rules = filterHighSignal(allRules).slice(0, options.maxRules ?? 12);
|
|
162
|
+
const paths = filterHighSignal(allPaths).slice(0, options.maxPaths ?? 10);
|
|
163
|
+
const sections = [];
|
|
164
|
+
if (inspection.config?.description) {
|
|
165
|
+
sections.push(`## About this codebase\n\n${inspection.config.description}`);
|
|
166
|
+
}
|
|
167
|
+
const pathsBody = renderPathsSection(paths);
|
|
168
|
+
if (pathsBody) {
|
|
169
|
+
sections.push(`## Where files belong\n\nWhen creating or moving a file, place it according to these conventions:\n\n${pathsBody}`);
|
|
170
|
+
}
|
|
171
|
+
const rulesBody = renderRulesSection(rules);
|
|
172
|
+
if (rulesBody) {
|
|
173
|
+
sections.push(`## Rules this codebase follows\n\nApply these whenever you generate, modify, or review code:\n\n${rulesBody}`);
|
|
174
|
+
}
|
|
175
|
+
const agg = aggregateActionHints(inspection.knowledgeEntries);
|
|
176
|
+
const doDont = [];
|
|
177
|
+
if (agg.forbiddenActions.length) {
|
|
178
|
+
doDont.push('**Do not:**');
|
|
179
|
+
for (const f of agg.forbiddenActions.slice(0, 8))
|
|
180
|
+
doDont.push(`- ${f}`);
|
|
181
|
+
doDont.push('');
|
|
182
|
+
}
|
|
183
|
+
if (agg.verificationCommands.length) {
|
|
184
|
+
doDont.push('**Verify changes with:**');
|
|
185
|
+
for (const c of agg.verificationCommands.slice(0, 6))
|
|
186
|
+
doDont.push(`- \`${c}\``);
|
|
187
|
+
}
|
|
188
|
+
if (doDont.length) {
|
|
189
|
+
sections.push(`## Do / Don't\n\n${doDont.join('\n').trim()}`);
|
|
190
|
+
}
|
|
191
|
+
sections.push(`## How to write code in this repo\n\n` +
|
|
192
|
+
`This repository uses [SharkCraft](https://github.com/shrkcrft/sharkcraft) to gate writes — the CLI is the only write path, and writes go through a plan → review → apply loop.\n\n` +
|
|
193
|
+
`1. **Get a task packet** before non-trivial work: \`shrk task "<one-sentence task>"\` returns the focused rules, paths, templates, and verification commands for that task.\n` +
|
|
194
|
+
`2. **Scaffold via templates** instead of writing files freehand: \`shrk gen <template-id> <name> --dry-run --save-plan plan.json\` produces a signed plan.\n` +
|
|
195
|
+
`3. **Apply the plan** through the CLI: \`shrk apply plan.json --verify-signature\` — never write through MCP.\n` +
|
|
196
|
+
`4. **Check the result**: \`shrk check boundaries\` + the verification commands listed above.\n\n` +
|
|
197
|
+
`For ad-hoc questions about the codebase, query the MCP server (\`shrk mcp serve\`) or run \`shrk context --task "<query>"\` for token-budgeted context.`);
|
|
198
|
+
return sections.join('\n\n');
|
|
199
|
+
}
|
|
200
|
+
/**
|
|
201
|
+
* Build the YAML frontmatter for a Claude Code Skill. The `description`
|
|
202
|
+
* field is what Claude uses to decide whether to load this skill — keep
|
|
203
|
+
* it specific (project name + what's covered) so it doesn't trigger on
|
|
204
|
+
* unrelated tasks.
|
|
205
|
+
*/
|
|
206
|
+
function renderSkillFrontmatter(inspection) {
|
|
207
|
+
const slug = projectSlug(inspection.config?.projectName);
|
|
208
|
+
const projectName = inspection.config?.projectName ?? slug;
|
|
209
|
+
const description = `Codebase rules, path conventions, and review gates for ${projectName}. ` +
|
|
210
|
+
`Use this skill whenever generating, modifying, or reviewing code in this repository — ` +
|
|
211
|
+
`it tells you the per-file path conventions, the architecture boundaries, the verification commands, ` +
|
|
212
|
+
`and the safe write path (CLI plan → review → apply).`;
|
|
213
|
+
return `---\nname: ${slug}\ndescription: ${JSON.stringify(description)}\n---`;
|
|
214
|
+
}
|
|
103
215
|
export function renderExport(inspection, options) {
|
|
104
|
-
const
|
|
105
|
-
const suggestedPath = DEFAULT_OUTPUT_PATH[options.format];
|
|
216
|
+
const suggestedPath = defaultOutputFor(options.format, inspection);
|
|
106
217
|
let content = '';
|
|
107
218
|
switch (options.format) {
|
|
108
|
-
case 'agents-md':
|
|
219
|
+
case 'agents-md': {
|
|
220
|
+
const body = renderBody(inspection, options);
|
|
109
221
|
content = `# Agents Guide\n\n${PREAMBLE}\n\n${body}\n`;
|
|
110
222
|
break;
|
|
111
|
-
|
|
223
|
+
}
|
|
224
|
+
case 'claude-md': {
|
|
225
|
+
const body = renderBody(inspection, options);
|
|
112
226
|
content = `# CLAUDE.md\n\n${PREAMBLE}\n\nThis file is read by Claude Code (claude.ai/code) at session start. Treat it as a compatibility view of the project's SharkCraft knowledge — use the MCP server (\`shrk mcp serve\`) for the live, queryable source of truth.\n\n${body}\n`;
|
|
113
227
|
break;
|
|
228
|
+
}
|
|
229
|
+
case 'claude-skill': {
|
|
230
|
+
// Claude Code Skill: YAML frontmatter declares when to load this,
|
|
231
|
+
// body is tight decision-driving content. No preamble, no boilerplate
|
|
232
|
+
// — every token in here costs Claude context when loaded.
|
|
233
|
+
const frontmatter = renderSkillFrontmatter(inspection);
|
|
234
|
+
const projectName = inspection.config?.projectName ?? 'this codebase';
|
|
235
|
+
const body = renderSkillBody(inspection, options);
|
|
236
|
+
content = `${frontmatter}\n\n# ${projectName} — codebase guide\n\n${body}\n`;
|
|
237
|
+
break;
|
|
238
|
+
}
|
|
114
239
|
case 'cursor-rules':
|
|
115
240
|
// Cursor MDC frontmatter: leave alwaysApply off so the user can tune.
|
|
116
|
-
content = `---\ndescription: SharkCraft project rules (auto-generated)\nalwaysApply: false\n---\n\n${PREAMBLE}\n\n${
|
|
241
|
+
content = `---\ndescription: SharkCraft project rules (auto-generated)\nalwaysApply: false\n---\n\n${PREAMBLE}\n\n${renderBody(inspection, options)}\n`;
|
|
117
242
|
break;
|
|
118
243
|
case 'copilot-instructions':
|
|
119
|
-
content = `# Copilot instructions\n\n${PREAMBLE}\n\n${
|
|
244
|
+
content = `# Copilot instructions\n\n${PREAMBLE}\n\n${renderBody(inspection, options)}\n`;
|
|
120
245
|
break;
|
|
121
246
|
}
|
|
122
247
|
return { format: options.format, suggestedPath, content };
|
|
@@ -124,12 +249,14 @@ export function renderExport(inspection, options) {
|
|
|
124
249
|
export function isExportFormat(value) {
|
|
125
250
|
return (value === 'agents-md' ||
|
|
126
251
|
value === 'claude-md' ||
|
|
252
|
+
value === 'claude-skill' ||
|
|
127
253
|
value === 'cursor-rules' ||
|
|
128
254
|
value === 'copilot-instructions');
|
|
129
255
|
}
|
|
130
256
|
export const ALL_EXPORT_FORMATS = Object.freeze([
|
|
131
257
|
'agents-md',
|
|
132
258
|
'claude-md',
|
|
259
|
+
'claude-skill',
|
|
133
260
|
'cursor-rules',
|
|
134
261
|
'copilot-instructions',
|
|
135
262
|
]);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init-templates.d.ts","sourceRoot":"","sources":["../../src/init/init-templates.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;
|
|
1
|
+
{"version":3,"file":"init-templates.d.ts","sourceRoot":"","sources":["../../src/init/init-templates.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAUD,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EA2W1C,CAAC"}
|