heraspec 0.1.18 → 0.1.19
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 +3 -2
- package/bin/heraspec.js +2346 -1356
- package/bin/heraspec.js.map +4 -4
- package/dist/commands/ide.d.ts +12 -0
- package/dist/core/agents-composer.d.ts +51 -0
- package/dist/core/config.d.ts +4 -0
- package/dist/core/ide-adapter.d.ts +92 -0
- package/dist/core/init.d.ts +9 -40
- package/dist/core/templates/index.d.ts +32 -2
- package/dist/index.d.ts +4 -0
- package/dist/index.js +1952 -1069
- package/package.json +2 -2
package/dist/index.js
CHANGED
|
@@ -134,6 +134,8 @@ var init_config = __esm({
|
|
|
134
134
|
HERASPEC_MARKERS = {
|
|
135
135
|
PROJECT_MD: "project.md",
|
|
136
136
|
AGENTS_MD: "AGENTS.heraspec.md",
|
|
137
|
+
AGENTS_CUSTOM_MD: "AGENTS.custom.md",
|
|
138
|
+
STATE_JSON: ".heraspec-state.json",
|
|
137
139
|
CONFIG_YAML: "config.yaml",
|
|
138
140
|
PROPOSAL_MD: "proposal.md",
|
|
139
141
|
TASKS_MD: "tasks.md",
|
|
@@ -266,6 +268,422 @@ var init_file_system = __esm({
|
|
|
266
268
|
}
|
|
267
269
|
});
|
|
268
270
|
|
|
271
|
+
// src/core/templates/index.ts
|
|
272
|
+
var TemplateManager;
|
|
273
|
+
var init_templates = __esm({
|
|
274
|
+
"src/core/templates/index.ts"() {
|
|
275
|
+
"use strict";
|
|
276
|
+
TemplateManager = class {
|
|
277
|
+
static getProjectTemplate() {
|
|
278
|
+
return `# HeraSpec Project
|
|
279
|
+
|
|
280
|
+
## Slash Commands (Agent Triggers)
|
|
281
|
+
|
|
282
|
+
When the user types messages starting with a slash (/), you MUST intercept them as action triggers rather than conversational queries. Please execute the corresponding terminal commands immediately:
|
|
283
|
+
|
|
284
|
+
- /heraspec [args] : Run the heraspec CLI tool with the provided arguments (e.g. /heraspec validate my-change)
|
|
285
|
+
- /sync : Run heraspec sync <current-change>
|
|
286
|
+
- /archive : Run heraspec archive <current-change> --yes
|
|
287
|
+
- /skill [name] : Run heraspec skill add [name]
|
|
288
|
+
- /hotfix [title] : Run heraspec hotfix [title]
|
|
289
|
+
|
|
290
|
+
*If the user types a slash command, do not explain what you are going to do, just run the terminal command and report the output.*
|
|
291
|
+
|
|
292
|
+
## Overview
|
|
293
|
+
Describe your project here.
|
|
294
|
+
|
|
295
|
+
## Project Types
|
|
296
|
+
- List your project type(s) here (e.g., node-service, generic-webapp, backend-api, frontend-app, multi-stack, wordpress-plugin, wordpress-theme, perfex-module, laravel-package, content-channel)
|
|
297
|
+
|
|
298
|
+
## Tech Stack
|
|
299
|
+
- List primary languages, frameworks, runtime, and key libraries
|
|
300
|
+
|
|
301
|
+
## Architecture
|
|
302
|
+
Describe the high-level architecture: entry points, module structure, data flow.
|
|
303
|
+
|
|
304
|
+
## Key Dependencies
|
|
305
|
+
List critical dependencies and their purposes (e.g., better-sqlite3 for memory, commander for CLI).
|
|
306
|
+
|
|
307
|
+
## Conventions
|
|
308
|
+
Define coding standards, architectural patterns, and conventions to follow.
|
|
309
|
+
`;
|
|
310
|
+
}
|
|
311
|
+
static getCustomAgentsTemplate(projectName) {
|
|
312
|
+
const titleSuffix = projectName ? ` (${projectName})` : "";
|
|
313
|
+
return `# Project-Specific Agent Rules - HeraSpec Custom Layer${titleSuffix}
|
|
314
|
+
|
|
315
|
+
> **100% Project-Owned File**: HeraSpec CLI upgrades to \`AGENTS.heraspec.md\` will NEVER modify or overwrite this file.
|
|
316
|
+
> Add project-specific architecture invariants, CI/test gates, localization rules, security checks, and deployment bans below.
|
|
317
|
+
|
|
318
|
+
## Project-Specific Invariants & Quality Gates
|
|
319
|
+
|
|
320
|
+
- Add project-specific architecture constraints, test commands, and verification gates here.
|
|
321
|
+
`;
|
|
322
|
+
}
|
|
323
|
+
static resolveActiveDomains(ctx) {
|
|
324
|
+
if (ctx?.includeAllStacks) {
|
|
325
|
+
return { includeWordpress: true, includePerfex: true, includeContentChannel: true };
|
|
326
|
+
}
|
|
327
|
+
const types = new Set((ctx?.projectTypes || []).map((t) => t.toLowerCase()));
|
|
328
|
+
const skillKeys = (ctx?.installedSkills || []).map(
|
|
329
|
+
(s) => `${s.projectType || ""}/${s.name}`.toLowerCase()
|
|
330
|
+
);
|
|
331
|
+
const includeWordpress = Array.from(types).some((t) => t.startsWith("wordpress")) || skillKeys.some((k) => k.includes("wordpress") || k.includes("ux-element") || k.includes("plugin-check") || k.includes("plugin-directory"));
|
|
332
|
+
const includePerfex = types.has("perfex-module") || skillKeys.some((k) => k.includes("perfex-module") || k.includes("module-codebase") || k.includes("code-quality-guidelines"));
|
|
333
|
+
const includeContentChannel = types.has("content-channel") || skillKeys.some((k) => k.includes("content-channel") || k.includes("content-strategy") || k.includes("content-scripting"));
|
|
334
|
+
return { includeWordpress, includePerfex, includeContentChannel };
|
|
335
|
+
}
|
|
336
|
+
static buildIdeDiscoverySection(ctx) {
|
|
337
|
+
const customFile = ctx?.customFileName || "AGENTS.custom.md";
|
|
338
|
+
const projectLabel = ctx?.projectName || "Current Project";
|
|
339
|
+
const typesLabel = ctx?.projectTypes && ctx.projectTypes.length > 0 ? ctx.projectTypes.join(", ") : "unspecified (configure in heraspec/config.yaml)";
|
|
340
|
+
const ideFiles = ctx?.detectedIdeFiles || [];
|
|
341
|
+
const skillRoots = ctx?.detectedSkillRoots || [];
|
|
342
|
+
const installedSkills = ctx?.installedSkills || [];
|
|
343
|
+
const ideFilesLines = ideFiles.length > 0 ? ideFiles.map((f) => ` - [${f.relativePath}](${f.relativePath}) (${f.label}, ${f.scope})`).join("\n") : " - None auto-detected yet (check `.` and `..` for `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`).";
|
|
344
|
+
const skillRootsLines = skillRoots.length > 0 ? skillRoots.map((r) => ` - \`${r.relativePath}\` (${r.profile}, ${r.scope})`).join("\n") : " - Use canonical `heraspec/skills/*/skill.md`.";
|
|
345
|
+
const skillsSummaryLines = installedSkills.length > 0 ? installedSkills.map((s) => {
|
|
346
|
+
const label = s.projectType ? `${s.projectType}/${s.name}` : s.name;
|
|
347
|
+
const desc = s.description ? `: ${s.description}` : "";
|
|
348
|
+
return ` - \`${label}\` ([${s.relativePath}](${s.relativePath}))${desc}`;
|
|
349
|
+
}).join("\n") : " - No skills installed yet (`heraspec skill list` / `heraspec skill add <name>`).";
|
|
350
|
+
return `## Rule Precedence & IDE Workspace Discovery (Auto-Combined)
|
|
351
|
+
|
|
352
|
+
Before planning or editing code, agents MUST load and combine workspace rules in this exact order of precedence:
|
|
353
|
+
|
|
354
|
+
1. **Universal Safety Rules (This file - Immutable)**: Never relax \`NO AUTO-COMMIT\`, \`NO AUTO-PUBLISH\`, or dangerous command approval gates.
|
|
355
|
+
2. **Project Custom Engineering Rules ([${customFile}](${customFile}))**: Always read \`${customFile}\` in the same directory as \`AGENTS.heraspec.md\` (if present) for project-specific architecture invariants, test gates, security policies, and deployment restrictions.
|
|
356
|
+
3. **IDE-Native Workspace Rules (Auto-Discovery across \`.\` and \`..\`)**: Detect and apply active IDE rule files:
|
|
357
|
+
- Antigravity / Gemini: \`GEMINI.md\` or \`../GEMINI.md\`, skills in \`.agents/skills/*/SKILL.md\`
|
|
358
|
+
- Claude Code: \`CLAUDE.md\` or \`.claude/CLAUDE.md\`, skills in \`.claude/skills/*/SKILL.md\`
|
|
359
|
+
- Codex / Universal Agents: \`AGENTS.md\`
|
|
360
|
+
- Cursor / Windsurf / Copilot: \`.cursorrules\`, \`.cursor/rules/heraspec.mdc\`, \`.windsurfrules\`, \`.github/copilot-instructions.md\`
|
|
361
|
+
4. **Domain Specs & Canonical Skills**: Read \`heraspec/project.md\`, \`heraspec/config.yaml\`, \`heraspec/specs/\`, \`heraspec/changes/\`, and English \`skill.md\` files inside \`heraspec/skills/\` (strictly ignore \`*.vi.md\`, \`project.back*.md\`, and \`AGENTS.heraspec.backup-*.md\`).
|
|
362
|
+
|
|
363
|
+
### Auto-Detected Workspace Context
|
|
364
|
+
|
|
365
|
+
- **Project**: ${projectLabel} (\`projectType\`: ${typesLabel})
|
|
366
|
+
- **Project Custom Layer**: [${customFile}](${customFile})${ctx?.hasCustomFile === false ? " (create if needed for project rules)" : ""}
|
|
367
|
+
- **Detected IDE Rule Files**:
|
|
368
|
+
${ideFilesLines}
|
|
369
|
+
- **Detected IDE Skill Roots**:
|
|
370
|
+
${skillRootsLines}
|
|
371
|
+
- **Installed HeraSpec Skills**:
|
|
372
|
+
${skillsSummaryLines}`;
|
|
373
|
+
}
|
|
374
|
+
static getAgentsTemplate(ctx) {
|
|
375
|
+
const { includeWordpress, includePerfex, includeContentChannel } = this.resolveActiveDomains(ctx);
|
|
376
|
+
const customFile = ctx?.customFileName || "AGENTS.custom.md";
|
|
377
|
+
const wordpressWorkflowBlock = includeWordpress ? `
|
|
378
|
+
**Special case - Flatsome UX Element skill:**
|
|
379
|
+
- Task: \`(projectType: wordpress, skill: ux-element)\`
|
|
380
|
+
- Agent reads: \`heraspec/skills/wordpress/ux-element/skill.md\`
|
|
381
|
+
- Agent MUST follow the **Wrapping Rule**: Use \`<span>\` with \`id="{{:: shortcode.$id }}"\`
|
|
382
|
+
- Agent uses templates from \`heraspec/skills/wordpress/ux-element/templates/\` (Controller, Shortcode, HTML Template, SVG Thumbnail)
|
|
383
|
+
- Agent ensures real-time preview support in AngularJS template.
|
|
384
|
+
- **Variable Translation**: Variables with underscores in PHP (e.g., \`bg_color\`) MUST be accessed via camelCase in AngularJS (e.g., \`shortcode.options.bgColor\`).
|
|
385
|
+
|
|
386
|
+
**Special case - Plugin Check skill:**
|
|
387
|
+
- Task: \`(projectType: wordpress-plugin, skill: plugin-check)\`
|
|
388
|
+
- Install: \`heraspec skill add plugin-check --project-type wordpress-plugin\`
|
|
389
|
+
- Agent reads: \`heraspec/skills/wordpress-plugin/plugin-check/skill.md\`
|
|
390
|
+
- Agent runs WordPress Plugin Check (PCP) tool and fixes coding standard issues iteratively until all pass.
|
|
391
|
+
|
|
392
|
+
**Special case - Plugin Directory skill:**
|
|
393
|
+
- Task: \`(projectType: wordpress-plugin, skill: plugin-directory)\`
|
|
394
|
+
- Install: \`heraspec skill add plugin-directory --project-type wordpress-plugin\`
|
|
395
|
+
- Agent reads: \`heraspec/skills/wordpress-plugin/plugin-directory/skill.md\`
|
|
396
|
+
- Agent MUST review plugin against **18 WordPress.org Directory Guidelines** and present a full compliance report waiting for user confirmation before making changes.
|
|
397
|
+
` : "";
|
|
398
|
+
const perfexWorkflowBlock = includePerfex ? `
|
|
399
|
+
**Special case - Perfex Module Engineering skills:**
|
|
400
|
+
- Tasks: \`(projectType: perfex-module, skill: module-codebase)\` or \`(projectType: perfex-module, skill: code-quality-guidelines)\` or \`(skill: perfex-module)\`
|
|
401
|
+
- Install: \`heraspec skill add perfex-module\` or \`heraspec skill add module-codebase --project-type perfex-module\`
|
|
402
|
+
- Agent reads: \`heraspec/skills/perfex-module/skill.md\`, \`heraspec/skills/perfex-module/module-codebase/skill.md\`, and \`heraspec/skills/perfex-module/code-quality-guidelines/skill.md\`
|
|
403
|
+
- Agent MUST adhere to **10 Enterprise Code Quality & Clean Code Standards** (zero inline script/style, zero scanner triggers, \`editor.dom.loadCSS()\`, IIFE scoped admin JS, \`session_write_close()\` in read AJAX endpoints, clean release packaging, \`BASEPATH\` guard + CI Query Builder, DOM XSS prevention, 100% \`_l('key')\` parity, zero Unicode emojis).
|
|
404
|
+
` : "";
|
|
405
|
+
const contentChannelWorkflowBlock = includeContentChannel ? `
|
|
406
|
+
**Special case - Content & Channel Development skills (projectType: content-channel):**
|
|
407
|
+
- Tasks: \`(projectType: content-channel, skill: content-strategy)\`, \`(skill: content-scaffolding)\`, \`(skill: content-scripting)\`, \`(skill: content-voice-adapter)\`, \`(skill: content-prompts)\`, \`(skill: content-compliance)\`, \`(skill: content-vault-sync)\`, or \`(skill: content-channel)\`
|
|
408
|
+
- Install: \`heraspec skill add content-channel\` or \`heraspec skill add <skill-name> --project-type content-channel\`
|
|
409
|
+
- Agent reads corresponding skill instructions in \`heraspec/skills/<skill-name>/skill.md\` or \`heraspec/skills/content-channel/<skill-name>/skill.md\` and enforces MTxStudio 2-level hierarchy, strict TTS pacing rules, newline preservation for verses, Decree 15/2020/ND-CP 3-position disclaimers, and safe vault export via \`Facebook/export_vault_json.py\`.
|
|
410
|
+
` : "";
|
|
411
|
+
const skillsSection = this.getSkillsSection(ctx);
|
|
412
|
+
const discoverySection = this.buildIdeDiscoverySection(ctx);
|
|
413
|
+
return `# HeraSpec - AI Agent Instructions
|
|
414
|
+
|
|
415
|
+
This document defines the CLI-managed workflow for AI agents working with HeraSpec.
|
|
416
|
+
Project-specific rules, quality gates, and overrides live in [${customFile}](${customFile}) and are never overwritten by HeraSpec CLI upgrades.
|
|
417
|
+
|
|
418
|
+
## Universal Safety Rules
|
|
419
|
+
|
|
420
|
+
- **NO AUTO-COMMIT**: Agent MUST NOT perform \`git commit\` or \`git push\` autonomously. This task is reserved for the User unless explicitly ordered.
|
|
421
|
+
- **NO AUTO-PUBLISH**: Agent MUST NOT perform \`npm publish\` or trigger automated releases/deployments autonomously.
|
|
422
|
+
- **SKILL PREREQUISITE**: If a task maps to a skill (e.g., "Generate documentation"), you **MUST** verify the skill folder exists in \`heraspec/skills/\`. If missing:
|
|
423
|
+
- **Preferred**: Proactively install it via \`heraspec skill add <name>\` (e.g., \`heraspec skill add documents\`) if you have terminal access.
|
|
424
|
+
- **Fallback**: If you cannot install it, **STOP** and ask the user to add it. **DO NOT** attempt manual generation without the skill.
|
|
425
|
+
- **IGNORE VIETNAMESE SKILL FILES**: When reading and executing skill workflows, you **MUST ONLY** look at the English version of the skill instructions (e.g., \`skill.md\`). You **MUST completely ignore** all Vietnamese versions (e.g., \`skill.vi.md\` or files ending with \`*.vi.md\`). These Vietnamese files are for reference/development purposes by the user only.
|
|
426
|
+
- **USER CONFIRMATION**: For destructive actions or public releases, always request explicit User approval first.
|
|
427
|
+
|
|
428
|
+
### Restricted Commands (REQUIRE USER CONFIRMATION)
|
|
429
|
+
|
|
430
|
+
The following commands are classified by risk level. You **MUST NOT** execute them without explicit user confirmation/approval in the chat, especially if they are outside the source workspace or involve deletion.
|
|
431
|
+
|
|
432
|
+
#### GROUP 1 - EXTREMELY DANGEROUS (DATA DESTRUCTION, HARD / IMPOSSIBLE TO RECOVER)
|
|
433
|
+
- \`rm -rf\` : Recursive delete + no prompt, can wipe entire system
|
|
434
|
+
- \`rm -r\` : Delete directory and all contents
|
|
435
|
+
- \`rm\` : Delete file directly, bypassing trash
|
|
436
|
+
- \`unlink\` : Delete file at filesystem level, cannot undo
|
|
437
|
+
- \`shred\` : Overwrite data multiple times to make it unrecoverable
|
|
438
|
+
- \`wipe\` : Permanently wipe data on disk
|
|
439
|
+
- \`dd\` : Write/copy raw blocks, easily destroy disk or partition
|
|
440
|
+
- \`mkfs\`, \`mkfs.ext4\`, \`mkfs.xfs\` : Create new filesystem, wiping old data
|
|
441
|
+
- \`format\`, \`Format-Volume\` : Format drive/volume
|
|
442
|
+
|
|
443
|
+
#### GROUP 2 - HIGH DANGER (DELETE DIRECTORY / MULTIPLE FILES)
|
|
444
|
+
- \`rmdir\` : Delete directory
|
|
445
|
+
- \`rd\`, \`rmdir /s\` : Windows delete directory
|
|
446
|
+
- \`Remove-Item -Recurse\`, \`Remove-Item\` : PowerShell delete
|
|
447
|
+
- \`del /s\`, \`erase /s\` : CMD batch delete
|
|
448
|
+
|
|
449
|
+
#### GROUP 3 - MEDIUM DANGER (DELETE FILE / OVERWRITE)
|
|
450
|
+
- \`del\`, \`erase\` : Delete file
|
|
451
|
+
- \`Clear-Content\` : Clear file content
|
|
452
|
+
- \`cp --remove-destination\` : Overwrite destination by deleting first
|
|
453
|
+
|
|
454
|
+
#### GROUP 4 - INDIRECT DANGER (DATA LOSS)
|
|
455
|
+
- \`mv\` : Move / overwrite file, old data lost
|
|
456
|
+
- \`rsync --delete\` : Delete file at destination if not in source
|
|
457
|
+
- \`install\` : Overwrite system files
|
|
458
|
+
|
|
459
|
+
#### GROUP 5 - DISK / PARTITION MANAGEMENT
|
|
460
|
+
- \`fdisk\`, \`cfdisk\`, \`parted\`, \`diskpart\` : Partition management
|
|
461
|
+
- \`mount\`, \`umount\` : Filesystem mounting
|
|
462
|
+
|
|
463
|
+
#### GROUP 6 - LESS DANGEROUS (POTENTIAL CONSEQUENCES)
|
|
464
|
+
- \`truncate\` : Cut off file content
|
|
465
|
+
- \`chown\`, \`chmod\` : Change ownership/permissions
|
|
466
|
+
- \`attrib\` : Change attributes
|
|
467
|
+
|
|
468
|
+
${discoverySection}
|
|
469
|
+
|
|
470
|
+
## Core Workflow
|
|
471
|
+
|
|
472
|
+
### Step 1 - Create a Change
|
|
473
|
+
|
|
474
|
+
**When creating changes, ALWAYS read \`heraspec/project.md\` and \`${customFile}\` first to understand:**
|
|
475
|
+
- Project types being used
|
|
476
|
+
- Tech stack, conventions, and project-specific invariants
|
|
477
|
+
- Existing architecture patterns
|
|
478
|
+
- Coding and quality standards
|
|
479
|
+
|
|
480
|
+
> **IGNORE backup files**: Files like \`project.back1.md\`, \`project.back2.md\`, \`AGENTS.heraspec.backup-*.md\`, etc. are automatic backups created during \`heraspec init\` updates. NEVER read or reference them unless explicitly asked by the user. Only \`project.md\`, \`AGENTS.heraspec.md\`, and \`${customFile}\` are active sources of truth.
|
|
481
|
+
|
|
482
|
+
**Then scaffold:**
|
|
483
|
+
- \`heraspec/changes/<slug>/\` - Create \`proposal.md\`, \`tasks.md\`, \`design.md\` (optional)
|
|
484
|
+
- \`heraspec/specs/<slug>/\` - Create delta specs here (NOT inside changes folder)
|
|
485
|
+
|
|
486
|
+
**If user asks to create changes based on project.md:**
|
|
487
|
+
1. Read \`heraspec/project.md\` thoroughly
|
|
488
|
+
2. Identify all features/capabilities mentioned
|
|
489
|
+
3. Create separate changes for each major feature
|
|
490
|
+
4. Ensure each change follows \`project.md\` and \`${customFile}\` conventions
|
|
491
|
+
5. Use correct project types and skills from \`project.md\` / \`config.yaml\`
|
|
492
|
+
|
|
493
|
+
### Step 2 - Refine Specs
|
|
494
|
+
- Update delta specs in \`heraspec/specs/<slug>/\`
|
|
495
|
+
- Never modify source-of-truth specs directly before approval and archive
|
|
496
|
+
- Validate changes cleanly with \`heraspec validate <slug> --strict\`
|
|
497
|
+
|
|
498
|
+
### Step 3 - Approval
|
|
499
|
+
- Wait for user confirmation (for example: "Specs approved.") before starting implementation of major changes
|
|
500
|
+
|
|
501
|
+
### Step 4 - Implementation
|
|
502
|
+
|
|
503
|
+
**CRITICAL: When implementing tasks, ALWAYS use the Skills system and project custom rules:**
|
|
504
|
+
|
|
505
|
+
1. **Read task line** to identify skill:
|
|
506
|
+
\`\`\`markdown
|
|
507
|
+
## 1. Module - Feature (projectType: backend-api, skill: ui-ux)
|
|
508
|
+
- [ ] 1.1 Implement feature
|
|
509
|
+
\`\`\`
|
|
510
|
+
|
|
511
|
+
2. **Find skill folder**:
|
|
512
|
+
- Project-specific: \`heraspec/skills/<project-type>/<skill-name>/\`
|
|
513
|
+
- Cross-cutting: \`heraspec/skills/<skill-name>/\`
|
|
514
|
+
|
|
515
|
+
3. **Read \`skill.md\`**:
|
|
516
|
+
- Understand purpose, steps, inputs, outputs
|
|
517
|
+
- Follow tone, rules, and limitations
|
|
518
|
+
- Check available templates and scripts
|
|
519
|
+
- **Ignore Vietnamese Skill Files**: Only read the English \`skill.md\` instructions. Completely ignore any \`*.vi.md\` translation files.
|
|
520
|
+
|
|
521
|
+
4. **Use skill resources**:
|
|
522
|
+
- Run scripts from \`scripts/\` folder if needed
|
|
523
|
+
- Use templates from \`templates/\` folder
|
|
524
|
+
- Reference examples from \`examples/\` folder
|
|
525
|
+
|
|
526
|
+
5. **Implement following \`skill.md\` and \`${customFile}\` guidance**:
|
|
527
|
+
- Follow step-by-step process and naming conventions
|
|
528
|
+
- Verify all quality/sync gates defined in \`${customFile}\` and active IDE rules
|
|
529
|
+
${wordpressWorkflowBlock}${perfexWorkflowBlock}${contentChannelWorkflowBlock}
|
|
530
|
+
- Follow \`tasks.md\`
|
|
531
|
+
- Mark tasks completed: \`- [x]\`
|
|
532
|
+
|
|
533
|
+
### Step 5 - Archive
|
|
534
|
+
- Run: \`heraspec archive <slug> --yes\`
|
|
535
|
+
- This merges delta specs into source specs
|
|
536
|
+
- Moves change folder to archives
|
|
537
|
+
|
|
538
|
+
#### Handling Parallel Merge Conflicts
|
|
539
|
+
If \`heraspec archive\` throws a **Parallel Merge Conflict** error:
|
|
540
|
+
1. It means someone else modified the base requirement in the source spec while you were working.
|
|
541
|
+
2. **DO NOT PANIC** and **DO NOT OVERWRITE** manually.
|
|
542
|
+
3. Run: \`heraspec sync <slug>\`
|
|
543
|
+
4. The system will automatically update your fingerprint to match the new source spec and warn you.
|
|
544
|
+
5. Review your delta spec again. Make sure your \`MODIFIED/REMOVED\` requirements still make sense given the new source.
|
|
545
|
+
6. Once verified, run \`heraspec archive <slug> --yes\` again.
|
|
546
|
+
|
|
547
|
+
## Spec Format
|
|
548
|
+
|
|
549
|
+
Specs must include:
|
|
550
|
+
- \`## Meta\` section with project type, domain, stack
|
|
551
|
+
- \`## Purpose\`
|
|
552
|
+
- \`## Requirements\` with scenarios
|
|
553
|
+
|
|
554
|
+
## Delta Spec Format
|
|
555
|
+
|
|
556
|
+
Delta specs use:
|
|
557
|
+
- \`## ADDED Requirements\`
|
|
558
|
+
- \`## MODIFIED Requirements\`
|
|
559
|
+
- \`## REMOVED Requirements\`
|
|
560
|
+
|
|
561
|
+
## Tasks Format
|
|
562
|
+
|
|
563
|
+
Tasks grouped by project type and skill:
|
|
564
|
+
\`\`\`
|
|
565
|
+
## 1. Feature Group - Capability (projectType: <type>, skill: <skill-name>)
|
|
566
|
+
- [ ] Task description
|
|
567
|
+
\`\`\`
|
|
568
|
+
|
|
569
|
+
${skillsSection}
|
|
570
|
+
|
|
571
|
+
## Proactive Memory-Aware Development
|
|
572
|
+
|
|
573
|
+
If \`heraspec/skills/project-memory/\` exists, the agent MUST proactively use memory to maintain project context. DO NOT wait for the user to prompt you to use memory.
|
|
574
|
+
|
|
575
|
+
### CRITICAL RULES FOR AUTOMATIC MEMORY USAGE
|
|
576
|
+
1. **Always Check Context First**: At the beginning of a complex task or when encountering an unfamiliar codebase area, you MUST autonomously run \`heraspec memory context\` or \`heraspec memory search "keywords"\` BEFORE writing any code.
|
|
577
|
+
2. **Auto-Log via Archive**: You DO NOT need to run \`heraspec memory log\` manually. Every time you successfully implement a feature and run \`heraspec archive <change-name>\`, the system will automatically read your proposal and log the memory observation under the hood. Just use \`heraspec archive\` as normal!
|
|
578
|
+
3. **Session Summary**: (Optional) When wrapping up a large session, you can run \`heraspec memory summarize --request "..." --completed "..."\` to compress knowledge, though \`archive\` already auto-logs completed features.
|
|
579
|
+
|
|
580
|
+
### When to SKIP Memory
|
|
581
|
+
- Simple bug fixes, typo corrections, formatting changes
|
|
582
|
+
- Trivial tasks that take < 5 minutes
|
|
583
|
+
- When doing what the agent's built-in context already covers
|
|
584
|
+
|
|
585
|
+
### Smart Code Exploration
|
|
586
|
+
If \`heraspec/skills/smart-explore/\` exists, prefer token-efficient exploration:
|
|
587
|
+
- \`heraspec explore outline <file>\` -> View structure (~1K tokens vs ~12K full file)
|
|
588
|
+
- \`heraspec explore search "<query>" <path>\` -> Find symbols across codebase
|
|
589
|
+
- \`heraspec explore unfold <file> <symbol>\` -> Read just one function
|
|
590
|
+
`;
|
|
591
|
+
}
|
|
592
|
+
static getSkillsSection(ctx) {
|
|
593
|
+
const { includeWordpress, includePerfex, includeContentChannel } = this.resolveActiveDomains(ctx);
|
|
594
|
+
const hasUiUx = (ctx?.installedSkills || []).some((s) => s.name === "ui-ux") || ctx?.includeAllStacks;
|
|
595
|
+
const hasDocuments = (ctx?.installedSkills || []).some((s) => s.name === "documents") || ctx?.includeAllStacks;
|
|
596
|
+
const primaryType = ctx?.projectTypes && ctx.projectTypes[0] || "backend-api";
|
|
597
|
+
const customSkillsBlock = (ctx?.installedSkills || []).map((s) => {
|
|
598
|
+
const key = s.projectType ? `${s.projectType}/${s.name}` : s.name;
|
|
599
|
+
return `- **${key}**: Read \`${s.relativePath}\`${s.description ? ` - ${s.description}` : ""}`;
|
|
600
|
+
}).join("\n");
|
|
601
|
+
const uiUxSnippet = hasUiUx ? `
|
|
602
|
+
**Special case - UI/UX skill:**
|
|
603
|
+
- Task: \`(skill: ui-ux)\`
|
|
604
|
+
- Agent reads: \`heraspec/skills/ui-ux/skill.md\`
|
|
605
|
+
- Agent MUST use search scripts before implementing:
|
|
606
|
+
\`\`\`bash
|
|
607
|
+
python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain>
|
|
608
|
+
python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --stack <stack>
|
|
609
|
+
\`\`\`
|
|
610
|
+
` : "";
|
|
611
|
+
const docsSnippet = hasDocuments ? `
|
|
612
|
+
**Example prompt for Documents skill:**
|
|
613
|
+
> "Generate documentation with skill documents for [project-name]. Include:
|
|
614
|
+
> - Concise overview (documentations/documentation.txt)
|
|
615
|
+
> - Technical Markdown (documentations/documentation.md)
|
|
616
|
+
> - Interactive HTML (documentations/documentation.html)
|
|
617
|
+
> - Premium Documentation Landing Page (documentations/documentation-landing-page.html)
|
|
618
|
+
> - CRITICAL: Save all files in the /documentations directory (create it if missing)."
|
|
619
|
+
` : "";
|
|
620
|
+
const wpSnippet = includeWordpress ? `
|
|
621
|
+
**WordPress Skills:**
|
|
622
|
+
- Flatsome UX Element: \`heraspec/skills/wordpress/ux-element/skill.md\`
|
|
623
|
+
- WordPress Plugin Check / Directory: \`heraspec/skills/wordpress-plugin/plugin-check/skill.md\`, \`heraspec/skills/wordpress-plugin/plugin-directory/skill.md\`
|
|
624
|
+
` : "";
|
|
625
|
+
const perfexSnippet = includePerfex ? `
|
|
626
|
+
**Perfex Module Engineering Skills:**
|
|
627
|
+
- Tasks: \`(projectType: perfex-module, skill: module-codebase)\` or \`(projectType: perfex-module, skill: code-quality-guidelines)\`
|
|
628
|
+
- Agent reads: \`heraspec/skills/perfex-module/skill.md\`, \`module-codebase/skill.md\`, and \`code-quality-guidelines/skill.md\`
|
|
629
|
+
` : "";
|
|
630
|
+
const contentSnippet = includeContentChannel ? `
|
|
631
|
+
**Content & Channel Development Skills (content-channel):**
|
|
632
|
+
- Available skills: \`content-strategy\`, \`content-scaffolding\`, \`content-scripting\`, \`content-voice-adapter\`, \`content-prompts\`, \`content-compliance\`, \`content-vault-sync\`
|
|
633
|
+
- Agent reads \`heraspec/skills/content-channel/<skill-name>/skill.md\` (or \`heraspec/skills/<skill-name>/skill.md\`) and enforces strict TTS acoustics, verse newline preservation, legal disclaimers, and safe vault export.
|
|
634
|
+
` : "";
|
|
635
|
+
const activeListBlock = customSkillsBlock ? `
|
|
636
|
+
### Active Project Skills
|
|
637
|
+
|
|
638
|
+
${customSkillsBlock}
|
|
639
|
+
` : "";
|
|
640
|
+
return `## Skills System
|
|
641
|
+
|
|
642
|
+
**CRITICAL: Mandatory Prerequisite Check**
|
|
643
|
+
|
|
644
|
+
1. **Stop & Verify**: If you are asked to implement a task requiring a skill (e.g., "Generate documentation...", "Create UI/UX...", etc.), you MUST first check if the skill folder exists in \`heraspec/skills/\`.
|
|
645
|
+
2. **Missing Skill = AUTO-INSTALL OR STOP**: If the skill folder does NOT exist:
|
|
646
|
+
- **Option A (Preferred)**: If you can run commands, execute \`heraspec skill add <skill-name>\` immediately.
|
|
647
|
+
- **Option B (Fallback)**: If you cannot run commands, **STOP** and ask the user to run it.
|
|
648
|
+
- **DO NOT** create a task plan or attempt manual generation without the skill language.
|
|
649
|
+
3. **Execute After Install**: Only after the skill folder is created (or installed), read the \`skill.md\` and proceed with the task.
|
|
650
|
+
4. **Ignore Vietnamese Skill Files**: You MUST only read the English \`skill.md\` file inside the skill folder. Completely ignore all \`*.vi.md\` files (e.g., \`skill.vi.md\`), as they are strictly for reference purposes by human developers.
|
|
651
|
+
${activeListBlock}${uiUxSnippet}${docsSnippet}${wpSnippet}${perfexSnippet}${contentSnippet}
|
|
652
|
+
### Skill Discovery & Usage
|
|
653
|
+
|
|
654
|
+
- List all skills: Check \`heraspec/skills/\` directory or run \`heraspec skill list\`
|
|
655
|
+
- Project-specific skills: \`heraspec/skills/<project-type>/\`
|
|
656
|
+
- Cross-cutting skills: \`heraspec/skills/<skill-name>/\` (root level)
|
|
657
|
+
- IDE skill parity check: Run \`heraspec ide sync --check\` when mirroring skills to \`.agents/skills/\` or \`.claude/skills/\`
|
|
658
|
+
- **Consistency**: Follow the step-by-step process in the skill's \`skill.md\`.
|
|
659
|
+
|
|
660
|
+
### When Change Has Multiple Skills
|
|
661
|
+
|
|
662
|
+
**Important**: Each task group uses ONE skill. When working on a task group, agent MUST use that skill's \`skill.md\`.
|
|
663
|
+
|
|
664
|
+
Example with multiple skills in one change:
|
|
665
|
+
\`\`\`markdown
|
|
666
|
+
## 1. Domain Logic - Feature (projectType: ${primaryType}, skill: project-memory)
|
|
667
|
+
- [ ] Task 1.1 Design and implement core module
|
|
668
|
+
|
|
669
|
+
## 2. UI/UX - Interface (skill: ui-ux)
|
|
670
|
+
- [ ] Task 2.1 Apply layout and accessibility checks
|
|
671
|
+
\`\`\`
|
|
672
|
+
|
|
673
|
+
**Key rule**: Switch \`skill.md\` when switching task groups!
|
|
674
|
+
`;
|
|
675
|
+
}
|
|
676
|
+
static getConfigTemplate() {
|
|
677
|
+
return `projectType: generic-webapp
|
|
678
|
+
projectName: "HeraSpec Project"
|
|
679
|
+
description: "A new project using HeraSpec"
|
|
680
|
+
skills: []
|
|
681
|
+
`;
|
|
682
|
+
}
|
|
683
|
+
};
|
|
684
|
+
}
|
|
685
|
+
});
|
|
686
|
+
|
|
269
687
|
// src/core/templates/skills-template-map.ts
|
|
270
688
|
function getSkillTemplateInfo(skillName, projectType) {
|
|
271
689
|
if (projectType) {
|
|
@@ -2975,11 +3393,1069 @@ var init_skill_manager = __esm({
|
|
|
2975
3393
|
}
|
|
2976
3394
|
});
|
|
2977
3395
|
|
|
2978
|
-
// src/core/
|
|
2979
|
-
|
|
2980
|
-
|
|
2981
|
-
|
|
2982
|
-
|
|
3396
|
+
// src/core/ide-adapter.ts
|
|
3397
|
+
import path7 from "path";
|
|
3398
|
+
import { createHash } from "crypto";
|
|
3399
|
+
function normalizeLineEndings(content) {
|
|
3400
|
+
return content.replace(/\r\n/g, "\n");
|
|
3401
|
+
}
|
|
3402
|
+
function computeNormalizedSha256(content) {
|
|
3403
|
+
return createHash("sha256").update(normalizeLineEndings(content), "utf8").digest("hex");
|
|
3404
|
+
}
|
|
3405
|
+
function toPosixRelative(fromDir, targetPath) {
|
|
3406
|
+
const rel = path7.relative(fromDir, targetPath).replace(/\\/g, "/");
|
|
3407
|
+
return rel || ".";
|
|
3408
|
+
}
|
|
3409
|
+
function parseSkillFrontmatter(content) {
|
|
3410
|
+
const normalized = normalizeLineEndings(content);
|
|
3411
|
+
const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---/);
|
|
3412
|
+
if (fmMatch) {
|
|
3413
|
+
const yamlBlock = fmMatch[1];
|
|
3414
|
+
const nameMatch = yamlBlock.match(/^name:\s*(.+)$/m);
|
|
3415
|
+
const descMatch = yamlBlock.match(/^description:\s*(.+)$/m);
|
|
3416
|
+
const stripQuotes = (s) => s ? s.trim().replace(/^["']|["']$/g, "") : void 0;
|
|
3417
|
+
return {
|
|
3418
|
+
name: stripQuotes(nameMatch?.[1]),
|
|
3419
|
+
description: stripQuotes(descMatch?.[1])
|
|
3420
|
+
};
|
|
3421
|
+
}
|
|
3422
|
+
const lines = normalized.split("\n");
|
|
3423
|
+
for (const rawLine of lines) {
|
|
3424
|
+
const line = rawLine.trim();
|
|
3425
|
+
if (!line || line.startsWith("#") || line.startsWith(">")) continue;
|
|
3426
|
+
return { description: line.length > 160 ? `${line.slice(0, 157)}...` : line };
|
|
3427
|
+
}
|
|
3428
|
+
return {};
|
|
3429
|
+
}
|
|
3430
|
+
var HERASPEC_ADAPTER_START, HERASPEC_ADAPTER_END, IDE_PROFILES, IdeAdapterManager;
|
|
3431
|
+
var init_ide_adapter = __esm({
|
|
3432
|
+
"src/core/ide-adapter.ts"() {
|
|
3433
|
+
"use strict";
|
|
3434
|
+
init_file_system();
|
|
3435
|
+
init_config();
|
|
3436
|
+
init_skill_manager();
|
|
3437
|
+
HERASPEC_ADAPTER_START = "<!-- HERASPEC:ADAPTER_START -->";
|
|
3438
|
+
HERASPEC_ADAPTER_END = "<!-- HERASPEC:ADAPTER_END -->";
|
|
3439
|
+
IDE_PROFILES = [
|
|
3440
|
+
{
|
|
3441
|
+
name: "gemini",
|
|
3442
|
+
label: "Antigravity / Gemini",
|
|
3443
|
+
primaryRuleFile: "GEMINI.md",
|
|
3444
|
+
ruleCandidates: ["GEMINI.md"],
|
|
3445
|
+
skillRootDir: ".agents/skills"
|
|
3446
|
+
},
|
|
3447
|
+
{
|
|
3448
|
+
name: "claude",
|
|
3449
|
+
label: "Claude Code",
|
|
3450
|
+
primaryRuleFile: "CLAUDE.md",
|
|
3451
|
+
ruleCandidates: ["CLAUDE.md", ".claude/CLAUDE.md"],
|
|
3452
|
+
skillRootDir: ".claude/skills"
|
|
3453
|
+
},
|
|
3454
|
+
{
|
|
3455
|
+
name: "codex",
|
|
3456
|
+
label: "OpenAI Codex / Universal Agents",
|
|
3457
|
+
primaryRuleFile: "AGENTS.md",
|
|
3458
|
+
ruleCandidates: ["AGENTS.md"]
|
|
3459
|
+
},
|
|
3460
|
+
{
|
|
3461
|
+
name: "cursor",
|
|
3462
|
+
label: "Cursor",
|
|
3463
|
+
primaryRuleFile: ".cursorrules",
|
|
3464
|
+
ruleCandidates: [".cursorrules", ".cursor/rules/heraspec.mdc"]
|
|
3465
|
+
},
|
|
3466
|
+
{
|
|
3467
|
+
name: "windsurf",
|
|
3468
|
+
label: "Windsurf",
|
|
3469
|
+
primaryRuleFile: ".windsurfrules",
|
|
3470
|
+
ruleCandidates: [".windsurfrules"]
|
|
3471
|
+
},
|
|
3472
|
+
{
|
|
3473
|
+
name: "copilot",
|
|
3474
|
+
label: "GitHub Copilot",
|
|
3475
|
+
primaryRuleFile: ".github/copilot-instructions.md",
|
|
3476
|
+
ruleCandidates: [".github/copilot-instructions.md"]
|
|
3477
|
+
}
|
|
3478
|
+
];
|
|
3479
|
+
IdeAdapterManager = class {
|
|
3480
|
+
static async discoverWorkspace(projectPath, ideOption = "auto") {
|
|
3481
|
+
const resolvedProject = path7.resolve(projectPath);
|
|
3482
|
+
const parentCandidate = path7.dirname(resolvedProject);
|
|
3483
|
+
const hasDistinctParent = parentCandidate && parentCandidate !== resolvedProject && parentCandidate !== path7.parse(resolvedProject).root;
|
|
3484
|
+
const searchScopes = [
|
|
3485
|
+
{ scope: "project", dir: resolvedProject }
|
|
3486
|
+
];
|
|
3487
|
+
if (hasDistinctParent) {
|
|
3488
|
+
searchScopes.push({ scope: "parent", dir: parentCandidate });
|
|
3489
|
+
}
|
|
3490
|
+
const detectedFiles = [];
|
|
3491
|
+
const detectedSkillRoots = [];
|
|
3492
|
+
const existingTargets = [];
|
|
3493
|
+
const existingSkillRoots = [];
|
|
3494
|
+
const seenPaths = /* @__PURE__ */ new Set();
|
|
3495
|
+
for (const profile of IDE_PROFILES) {
|
|
3496
|
+
for (const { scope, dir } of searchScopes) {
|
|
3497
|
+
for (const candidate of profile.ruleCandidates) {
|
|
3498
|
+
const absPath = path7.join(dir, candidate);
|
|
3499
|
+
if (seenPaths.has(absPath)) continue;
|
|
3500
|
+
if (await FileSystemUtils.fileExists(absPath)) {
|
|
3501
|
+
seenPaths.add(absPath);
|
|
3502
|
+
const rel = toPosixRelative(resolvedProject, absPath);
|
|
3503
|
+
detectedFiles.push({
|
|
3504
|
+
profile: profile.name,
|
|
3505
|
+
label: profile.label,
|
|
3506
|
+
relativePath: rel,
|
|
3507
|
+
scope
|
|
3508
|
+
});
|
|
3509
|
+
existingTargets.push({
|
|
3510
|
+
profile: profile.name,
|
|
3511
|
+
label: profile.label,
|
|
3512
|
+
absolutePath: absPath,
|
|
3513
|
+
relativeFromProject: rel,
|
|
3514
|
+
scope,
|
|
3515
|
+
exists: true
|
|
3516
|
+
});
|
|
3517
|
+
}
|
|
3518
|
+
}
|
|
3519
|
+
if (profile.skillRootDir) {
|
|
3520
|
+
const skillRootAbs = path7.join(dir, profile.skillRootDir);
|
|
3521
|
+
if (!seenPaths.has(skillRootAbs) && await FileSystemUtils.fileExists(skillRootAbs)) {
|
|
3522
|
+
seenPaths.add(skillRootAbs);
|
|
3523
|
+
const relRoot = toPosixRelative(resolvedProject, skillRootAbs);
|
|
3524
|
+
detectedSkillRoots.push({
|
|
3525
|
+
profile: profile.name,
|
|
3526
|
+
relativePath: relRoot,
|
|
3527
|
+
scope
|
|
3528
|
+
});
|
|
3529
|
+
existingSkillRoots.push({
|
|
3530
|
+
profile: profile.name,
|
|
3531
|
+
absolutePath: skillRootAbs,
|
|
3532
|
+
relativeFromProject: relRoot,
|
|
3533
|
+
scope,
|
|
3534
|
+
exists: true
|
|
3535
|
+
});
|
|
3536
|
+
}
|
|
3537
|
+
}
|
|
3538
|
+
}
|
|
3539
|
+
}
|
|
3540
|
+
const targetRuleFiles = [];
|
|
3541
|
+
const targetSkillRoots = [];
|
|
3542
|
+
if (ideOption === "none") {
|
|
3543
|
+
return {
|
|
3544
|
+
projectPath: resolvedProject,
|
|
3545
|
+
parentPath: hasDistinctParent ? parentCandidate : null,
|
|
3546
|
+
ideOption,
|
|
3547
|
+
detectedFiles,
|
|
3548
|
+
detectedSkillRoots,
|
|
3549
|
+
targetRuleFiles,
|
|
3550
|
+
targetSkillRoots
|
|
3551
|
+
};
|
|
3552
|
+
}
|
|
3553
|
+
const selectedProfiles = ideOption === "all" ? IDE_PROFILES.map((p) => p.name) : ideOption === "auto" ? [] : [ideOption];
|
|
3554
|
+
if (ideOption === "auto") {
|
|
3555
|
+
targetRuleFiles.push(...existingTargets);
|
|
3556
|
+
targetSkillRoots.push(...existingSkillRoots);
|
|
3557
|
+
for (const profile of IDE_PROFILES) {
|
|
3558
|
+
if (!profile.skillRootDir) continue;
|
|
3559
|
+
const alreadyHasRoot = targetSkillRoots.some((r) => r.profile === profile.name);
|
|
3560
|
+
const hasProjectRule = existingTargets.some(
|
|
3561
|
+
(t) => t.profile === profile.name && t.scope === "project"
|
|
3562
|
+
);
|
|
3563
|
+
if (!alreadyHasRoot && hasProjectRule) {
|
|
3564
|
+
const absRoot = path7.join(resolvedProject, profile.skillRootDir);
|
|
3565
|
+
targetSkillRoots.push({
|
|
3566
|
+
profile: profile.name,
|
|
3567
|
+
absolutePath: absRoot,
|
|
3568
|
+
relativeFromProject: toPosixRelative(resolvedProject, absRoot),
|
|
3569
|
+
scope: "project",
|
|
3570
|
+
exists: false
|
|
3571
|
+
});
|
|
3572
|
+
}
|
|
3573
|
+
}
|
|
3574
|
+
} else {
|
|
3575
|
+
const addedRulePaths = /* @__PURE__ */ new Set();
|
|
3576
|
+
const addedSkillRoots = /* @__PURE__ */ new Set();
|
|
3577
|
+
for (const profileName of selectedProfiles) {
|
|
3578
|
+
const profile = IDE_PROFILES.find((p) => p.name === profileName);
|
|
3579
|
+
if (!profile) continue;
|
|
3580
|
+
const matchingExisting = existingTargets.filter((t) => t.profile === profileName);
|
|
3581
|
+
if (matchingExisting.length > 0) {
|
|
3582
|
+
for (const target of matchingExisting) {
|
|
3583
|
+
if (!addedRulePaths.has(target.absolutePath)) {
|
|
3584
|
+
addedRulePaths.add(target.absolutePath);
|
|
3585
|
+
targetRuleFiles.push(target);
|
|
3586
|
+
}
|
|
3587
|
+
}
|
|
3588
|
+
} else {
|
|
3589
|
+
const absNew = path7.join(resolvedProject, profile.primaryRuleFile);
|
|
3590
|
+
addedRulePaths.add(absNew);
|
|
3591
|
+
targetRuleFiles.push({
|
|
3592
|
+
profile: profile.name,
|
|
3593
|
+
label: profile.label,
|
|
3594
|
+
absolutePath: absNew,
|
|
3595
|
+
relativeFromProject: toPosixRelative(resolvedProject, absNew),
|
|
3596
|
+
scope: "project",
|
|
3597
|
+
exists: false
|
|
3598
|
+
});
|
|
3599
|
+
}
|
|
3600
|
+
if (profile.skillRootDir) {
|
|
3601
|
+
const matchingRoots = existingSkillRoots.filter((r) => r.profile === profileName);
|
|
3602
|
+
if (matchingRoots.length > 0) {
|
|
3603
|
+
for (const root of matchingRoots) {
|
|
3604
|
+
if (!addedSkillRoots.has(root.absolutePath)) {
|
|
3605
|
+
addedSkillRoots.add(root.absolutePath);
|
|
3606
|
+
targetSkillRoots.push(root);
|
|
3607
|
+
}
|
|
3608
|
+
}
|
|
3609
|
+
} else {
|
|
3610
|
+
const absRoot = path7.join(resolvedProject, profile.skillRootDir);
|
|
3611
|
+
addedSkillRoots.add(absRoot);
|
|
3612
|
+
targetSkillRoots.push({
|
|
3613
|
+
profile: profile.name,
|
|
3614
|
+
absolutePath: absRoot,
|
|
3615
|
+
relativeFromProject: toPosixRelative(resolvedProject, absRoot),
|
|
3616
|
+
scope: "project",
|
|
3617
|
+
exists: false
|
|
3618
|
+
});
|
|
3619
|
+
}
|
|
3620
|
+
}
|
|
3621
|
+
}
|
|
3622
|
+
}
|
|
3623
|
+
return {
|
|
3624
|
+
projectPath: resolvedProject,
|
|
3625
|
+
parentPath: hasDistinctParent ? parentCandidate : null,
|
|
3626
|
+
ideOption,
|
|
3627
|
+
detectedFiles,
|
|
3628
|
+
detectedSkillRoots,
|
|
3629
|
+
targetRuleFiles,
|
|
3630
|
+
targetSkillRoots
|
|
3631
|
+
};
|
|
3632
|
+
}
|
|
3633
|
+
static buildAdapterBlock(targetFilePath, projectPath, hasCustomFile) {
|
|
3634
|
+
const targetDir = path7.dirname(path7.resolve(targetFilePath));
|
|
3635
|
+
const resolvedProject = path7.resolve(projectPath);
|
|
3636
|
+
const relAgents = toPosixRelative(targetDir, path7.join(resolvedProject, HERASPEC_MARKERS.AGENTS_MD));
|
|
3637
|
+
const relCustom = toPosixRelative(
|
|
3638
|
+
targetDir,
|
|
3639
|
+
path7.join(resolvedProject, HERASPEC_MARKERS.AGENTS_CUSTOM_MD)
|
|
3640
|
+
);
|
|
3641
|
+
const relProjectMd = toPosixRelative(
|
|
3642
|
+
targetDir,
|
|
3643
|
+
path7.join(resolvedProject, HERASPEC_DIR_NAME, HERASPEC_MARKERS.PROJECT_MD)
|
|
3644
|
+
);
|
|
3645
|
+
const relSkillsDir = toPosixRelative(
|
|
3646
|
+
targetDir,
|
|
3647
|
+
path7.join(resolvedProject, HERASPEC_DIR_NAME, SKILLS_DIR_NAME)
|
|
3648
|
+
);
|
|
3649
|
+
const customPointer = hasCustomFile ? ` and [${relCustom}](${relCustom}) (project-specific rules and quality gates)` : ` (create \`${relCustom}\` for project-specific rules)`;
|
|
3650
|
+
return `${HERASPEC_ADAPTER_START}
|
|
3651
|
+
## HeraSpec Workflow Integration
|
|
3652
|
+
|
|
3653
|
+
> **Managed by HeraSpec CLI** - Do not duplicate CLI workflow rules here.
|
|
3654
|
+
> Follow [${relAgents}](${relAgents}) (CLI workflow, safety rules, specs lifecycle)${customPointer}, alongside [${relProjectMd}](${relProjectMd}) and English \`${relSkillsDir}/*/skill.md\` (ignore \`*.vi.md\`).
|
|
3655
|
+
${HERASPEC_ADAPTER_END}`;
|
|
3656
|
+
}
|
|
3657
|
+
static upsertAdapterBlock(existingContent, adapterBlock) {
|
|
3658
|
+
if (!existingContent || existingContent.trim().length === 0) {
|
|
3659
|
+
return `${adapterBlock}
|
|
3660
|
+
`;
|
|
3661
|
+
}
|
|
3662
|
+
const normalized = normalizeLineEndings(existingContent);
|
|
3663
|
+
const startIdx = normalized.indexOf(HERASPEC_ADAPTER_START);
|
|
3664
|
+
const endIdx = normalized.indexOf(HERASPEC_ADAPTER_END);
|
|
3665
|
+
if (startIdx !== -1 && endIdx !== -1 && endIdx >= startIdx) {
|
|
3666
|
+
const before = normalized.slice(0, startIdx).trimEnd();
|
|
3667
|
+
const after = normalized.slice(endIdx + HERASPEC_ADAPTER_END.length).trimStart();
|
|
3668
|
+
const parts = [];
|
|
3669
|
+
if (before) parts.push(before);
|
|
3670
|
+
parts.push(adapterBlock);
|
|
3671
|
+
if (after) parts.push(after);
|
|
3672
|
+
return parts.join("\n\n") + "\n";
|
|
3673
|
+
}
|
|
3674
|
+
return `${normalized.trimEnd()}
|
|
3675
|
+
|
|
3676
|
+
${adapterBlock}
|
|
3677
|
+
`;
|
|
3678
|
+
}
|
|
3679
|
+
static async collectCanonicalSkills(projectPath) {
|
|
3680
|
+
const resolvedProject = path7.resolve(projectPath);
|
|
3681
|
+
const skills = await SkillManager.listSkills(resolvedProject);
|
|
3682
|
+
const summaries = [];
|
|
3683
|
+
const byName = /* @__PURE__ */ new Map();
|
|
3684
|
+
for (const skill of skills) {
|
|
3685
|
+
const lowerSkillMd = path7.join(skill.path, "skill.md");
|
|
3686
|
+
const upperSkillMd = path7.join(skill.path, "SKILL.md");
|
|
3687
|
+
const sourceSkillFile = await FileSystemUtils.fileExists(lowerSkillMd) ? lowerSkillMd : await FileSystemUtils.fileExists(upperSkillMd) ? upperSkillMd : null;
|
|
3688
|
+
if (!sourceSkillFile) continue;
|
|
3689
|
+
const rawContent = await FileSystemUtils.readFile(sourceSkillFile);
|
|
3690
|
+
const { description } = parseSkillFrontmatter(rawContent);
|
|
3691
|
+
const relativeSkillFile = toPosixRelative(resolvedProject, sourceSkillFile);
|
|
3692
|
+
summaries.push({
|
|
3693
|
+
name: skill.skillName,
|
|
3694
|
+
projectType: skill.projectType,
|
|
3695
|
+
relativePath: relativeSkillFile,
|
|
3696
|
+
description
|
|
3697
|
+
});
|
|
3698
|
+
const existing = byName.get(skill.skillName);
|
|
3699
|
+
if (!existing || !skill.projectType && existing.projectType) {
|
|
3700
|
+
byName.set(skill.skillName, {
|
|
3701
|
+
name: skill.skillName,
|
|
3702
|
+
projectType: skill.projectType,
|
|
3703
|
+
sourceDir: skill.path,
|
|
3704
|
+
sourceSkillFile,
|
|
3705
|
+
relativeSkillFile,
|
|
3706
|
+
description,
|
|
3707
|
+
content: rawContent,
|
|
3708
|
+
sha256: computeNormalizedSha256(rawContent)
|
|
3709
|
+
});
|
|
3710
|
+
}
|
|
3711
|
+
}
|
|
3712
|
+
summaries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
|
|
3713
|
+
const canonical = Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
|
|
3714
|
+
return { canonical, summaries };
|
|
3715
|
+
}
|
|
3716
|
+
static async syncAdaptersAndSkills(options) {
|
|
3717
|
+
const {
|
|
3718
|
+
projectPath,
|
|
3719
|
+
ideOption = "auto",
|
|
3720
|
+
hasCustomFile,
|
|
3721
|
+
checkOnly = false,
|
|
3722
|
+
dryRun = false,
|
|
3723
|
+
force = false,
|
|
3724
|
+
preserveModifiedSkillTargets = false,
|
|
3725
|
+
recordedMirrors = {},
|
|
3726
|
+
skipAdapters = false,
|
|
3727
|
+
skillNames
|
|
3728
|
+
} = options;
|
|
3729
|
+
const discovery = await this.discoverWorkspace(projectPath, ideOption);
|
|
3730
|
+
const reports = [];
|
|
3731
|
+
const updatedMirrors = { ...recordedMirrors };
|
|
3732
|
+
let hasDrift = false;
|
|
3733
|
+
const shouldWrite = !checkOnly && !dryRun;
|
|
3734
|
+
if (!skipAdapters) {
|
|
3735
|
+
for (const target of discovery.targetRuleFiles) {
|
|
3736
|
+
const exists = await FileSystemUtils.fileExists(target.absolutePath);
|
|
3737
|
+
const existing = exists ? await FileSystemUtils.readFile(target.absolutePath) : null;
|
|
3738
|
+
const adapterBlock = this.buildAdapterBlock(
|
|
3739
|
+
target.absolutePath,
|
|
3740
|
+
discovery.projectPath,
|
|
3741
|
+
hasCustomFile
|
|
3742
|
+
);
|
|
3743
|
+
const nextContent = this.upsertAdapterBlock(existing, adapterBlock);
|
|
3744
|
+
if (existing !== null && normalizeLineEndings(existing) === normalizeLineEndings(nextContent)) {
|
|
3745
|
+
reports.push({
|
|
3746
|
+
kind: "adapter",
|
|
3747
|
+
targetPath: target.absolutePath,
|
|
3748
|
+
relativePath: target.relativeFromProject,
|
|
3749
|
+
status: "in-sync"
|
|
3750
|
+
});
|
|
3751
|
+
continue;
|
|
3752
|
+
}
|
|
3753
|
+
if (checkOnly) {
|
|
3754
|
+
hasDrift = true;
|
|
3755
|
+
reports.push({
|
|
3756
|
+
kind: "adapter",
|
|
3757
|
+
targetPath: target.absolutePath,
|
|
3758
|
+
relativePath: target.relativeFromProject,
|
|
3759
|
+
status: exists ? "drifted" : "missing",
|
|
3760
|
+
detail: exists ? "HeraSpec adapter block missing or out of date" : "IDE rule file missing"
|
|
3761
|
+
});
|
|
3762
|
+
continue;
|
|
3763
|
+
}
|
|
3764
|
+
if (shouldWrite) {
|
|
3765
|
+
await FileSystemUtils.createDirectory(path7.dirname(target.absolutePath));
|
|
3766
|
+
await FileSystemUtils.writeFile(target.absolutePath, nextContent);
|
|
3767
|
+
}
|
|
3768
|
+
reports.push({
|
|
3769
|
+
kind: "adapter",
|
|
3770
|
+
targetPath: target.absolutePath,
|
|
3771
|
+
relativePath: target.relativeFromProject,
|
|
3772
|
+
status: exists ? "updated" : "created"
|
|
3773
|
+
});
|
|
3774
|
+
}
|
|
3775
|
+
}
|
|
3776
|
+
if (discovery.targetSkillRoots.length > 0) {
|
|
3777
|
+
const { canonical } = await this.collectCanonicalSkills(discovery.projectPath);
|
|
3778
|
+
const allowedSkillSet = skillNames ? new Set(skillNames) : null;
|
|
3779
|
+
const skillsToMirror = allowedSkillSet ? canonical.filter((s) => allowedSkillSet.has(s.name)) : canonical;
|
|
3780
|
+
for (const root of discovery.targetSkillRoots) {
|
|
3781
|
+
for (const skill of skillsToMirror) {
|
|
3782
|
+
const destSkillDir = path7.join(root.absolutePath, skill.name);
|
|
3783
|
+
const destSkillMd = path7.join(destSkillDir, "SKILL.md");
|
|
3784
|
+
const mirrorKey = toPosixRelative(discovery.projectPath, destSkillMd);
|
|
3785
|
+
const destExists = await FileSystemUtils.fileExists(destSkillMd);
|
|
3786
|
+
const destContent = destExists ? await FileSystemUtils.readFile(destSkillMd) : null;
|
|
3787
|
+
const destHash = destContent !== null ? computeNormalizedSha256(destContent) : null;
|
|
3788
|
+
if (destHash === skill.sha256) {
|
|
3789
|
+
updatedMirrors[mirrorKey] = skill.sha256;
|
|
3790
|
+
reports.push({
|
|
3791
|
+
kind: "skill",
|
|
3792
|
+
targetPath: destSkillMd,
|
|
3793
|
+
relativePath: mirrorKey,
|
|
3794
|
+
status: "in-sync",
|
|
3795
|
+
sha256: skill.sha256
|
|
3796
|
+
});
|
|
3797
|
+
continue;
|
|
3798
|
+
}
|
|
3799
|
+
if (checkOnly) {
|
|
3800
|
+
hasDrift = true;
|
|
3801
|
+
reports.push({
|
|
3802
|
+
kind: "skill",
|
|
3803
|
+
targetPath: destSkillMd,
|
|
3804
|
+
relativePath: mirrorKey,
|
|
3805
|
+
status: destExists ? "drifted" : "missing",
|
|
3806
|
+
detail: destExists ? `SHA-256 differs from ${skill.relativeSkillFile}` : `Missing mirror of ${skill.relativeSkillFile}`,
|
|
3807
|
+
sha256: destHash || void 0
|
|
3808
|
+
});
|
|
3809
|
+
continue;
|
|
3810
|
+
}
|
|
3811
|
+
const recordedBaseline = recordedMirrors[mirrorKey];
|
|
3812
|
+
if (preserveModifiedSkillTargets && !force && destExists && destHash !== null && destHash !== recordedBaseline) {
|
|
3813
|
+
hasDrift = true;
|
|
3814
|
+
reports.push({
|
|
3815
|
+
kind: "skill",
|
|
3816
|
+
targetPath: destSkillMd,
|
|
3817
|
+
relativePath: mirrorKey,
|
|
3818
|
+
status: "preserved",
|
|
3819
|
+
detail: `IDE skill modified locally; preserved (run "heraspec ide sync" to overwrite from ${skill.relativeSkillFile})`,
|
|
3820
|
+
sha256: destHash
|
|
3821
|
+
});
|
|
3822
|
+
continue;
|
|
3823
|
+
}
|
|
3824
|
+
if (shouldWrite) {
|
|
3825
|
+
await FileSystemUtils.createDirectory(destSkillDir);
|
|
3826
|
+
await FileSystemUtils.writeFile(destSkillMd, normalizeLineEndings(skill.content));
|
|
3827
|
+
await this.copySkillResourceSubdirs(skill.sourceDir, destSkillDir);
|
|
3828
|
+
}
|
|
3829
|
+
updatedMirrors[mirrorKey] = skill.sha256;
|
|
3830
|
+
reports.push({
|
|
3831
|
+
kind: "skill",
|
|
3832
|
+
targetPath: destSkillMd,
|
|
3833
|
+
relativePath: mirrorKey,
|
|
3834
|
+
status: destExists ? "updated" : "created",
|
|
3835
|
+
sha256: skill.sha256
|
|
3836
|
+
});
|
|
3837
|
+
}
|
|
3838
|
+
}
|
|
3839
|
+
}
|
|
3840
|
+
return {
|
|
3841
|
+
discovery,
|
|
3842
|
+
reports,
|
|
3843
|
+
updatedMirrors,
|
|
3844
|
+
hasDrift
|
|
3845
|
+
};
|
|
3846
|
+
}
|
|
3847
|
+
static async copySkillResourceSubdirs(sourceSkillDir, destSkillDir) {
|
|
3848
|
+
const resourceFolders = ["scripts", "templates", "examples", "references", "resources"];
|
|
3849
|
+
for (const folder of resourceFolders) {
|
|
3850
|
+
const srcSub = path7.join(sourceSkillDir, folder);
|
|
3851
|
+
if (!await FileSystemUtils.fileExists(srcSub)) continue;
|
|
3852
|
+
const entries = await FileSystemUtils.readDirectory(srcSub);
|
|
3853
|
+
const validEntries = entries.filter((name) => !name.endsWith(".vi.md"));
|
|
3854
|
+
if (validEntries.length === 0) continue;
|
|
3855
|
+
const destSub = path7.join(destSkillDir, folder);
|
|
3856
|
+
await FileSystemUtils.createDirectory(destSub);
|
|
3857
|
+
for (const entry of validEntries) {
|
|
3858
|
+
const srcEntry = path7.join(srcSub, entry);
|
|
3859
|
+
const destEntry = path7.join(destSub, entry);
|
|
3860
|
+
const stat = await FileSystemUtils.stat(srcEntry);
|
|
3861
|
+
if (stat.isDirectory()) {
|
|
3862
|
+
await FileSystemUtils.copyDirectory(srcEntry, destEntry);
|
|
3863
|
+
} else {
|
|
3864
|
+
await FileSystemUtils.copyFile(srcEntry, destEntry);
|
|
3865
|
+
}
|
|
3866
|
+
}
|
|
3867
|
+
}
|
|
3868
|
+
}
|
|
3869
|
+
};
|
|
3870
|
+
}
|
|
3871
|
+
});
|
|
3872
|
+
|
|
3873
|
+
// src/core/agents-composer.ts
|
|
3874
|
+
import path8 from "path";
|
|
3875
|
+
function normalizeHeadingKey(heading) {
|
|
3876
|
+
return heading.replace(/^#{1,6}\s+/, "").replace(/^\d+\.\s*/, "").replace(/[\u2014\u2013]/g, "-").replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
|
|
3877
|
+
}
|
|
3878
|
+
function normalizeComparisonLine(line) {
|
|
3879
|
+
return line.replace(/[\u2014\u2013]/g, "-").replace(/\u2192/g, "->").replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
|
|
3880
|
+
}
|
|
3881
|
+
function buildBaselineLineSet() {
|
|
3882
|
+
const set = /* @__PURE__ */ new Set();
|
|
3883
|
+
const seedTexts = [
|
|
3884
|
+
TemplateManager.getAgentsTemplate({ includeAllStacks: true }),
|
|
3885
|
+
TemplateManager.getSkillsSection({ includeAllStacks: true }),
|
|
3886
|
+
...LEGACY_V01_EXTRA_BOILERPLATE
|
|
3887
|
+
];
|
|
3888
|
+
for (const text of seedTexts) {
|
|
3889
|
+
for (const raw of normalizeLineEndings(text).split("\n")) {
|
|
3890
|
+
const norm = normalizeComparisonLine(raw);
|
|
3891
|
+
if (norm) set.add(norm);
|
|
3892
|
+
}
|
|
3893
|
+
}
|
|
3894
|
+
return set;
|
|
3895
|
+
}
|
|
3896
|
+
function splitTopLevelSections(content) {
|
|
3897
|
+
const normalized = normalizeLineEndings(content);
|
|
3898
|
+
const allLines = normalized.split("\n");
|
|
3899
|
+
const preamble = [];
|
|
3900
|
+
const sections = [];
|
|
3901
|
+
let current = null;
|
|
3902
|
+
let inCodeBlock = false;
|
|
3903
|
+
for (const line of allLines) {
|
|
3904
|
+
const trimmed = line.trim();
|
|
3905
|
+
if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
|
|
3906
|
+
inCodeBlock = !inCodeBlock;
|
|
3907
|
+
}
|
|
3908
|
+
if (!inCodeBlock && /^##\s+/.test(line)) {
|
|
3909
|
+
if (current) sections.push(current);
|
|
3910
|
+
current = {
|
|
3911
|
+
heading: line.trim(),
|
|
3912
|
+
key: normalizeHeadingKey(line),
|
|
3913
|
+
lines: []
|
|
3914
|
+
};
|
|
3915
|
+
continue;
|
|
3916
|
+
}
|
|
3917
|
+
if (current) {
|
|
3918
|
+
current.lines.push(line);
|
|
3919
|
+
} else {
|
|
3920
|
+
preamble.push(line);
|
|
3921
|
+
}
|
|
3922
|
+
}
|
|
3923
|
+
if (current) sections.push(current);
|
|
3924
|
+
return { preamble, sections };
|
|
3925
|
+
}
|
|
3926
|
+
function isLegacyBoilerplateLine(rawLine, normalized) {
|
|
3927
|
+
if (!normalized) return true;
|
|
3928
|
+
if (/^[-*_]{3,}$/.test(normalized)) return true;
|
|
3929
|
+
if (normalized === "```" || normalized.startsWith("```") || normalized === "~~~") return true;
|
|
3930
|
+
if (LEGACY_BASELINE_SET.has(normalized)) return true;
|
|
3931
|
+
if (/^\d{1,2}\.\s+(gpl compatibility|developer responsibility|stable version availability|human readable code|no trialware|software as a service|user tracking consent|no external executable code|legal and ethical conduct|external links and credits|admin dashboard experience|no spam in public pages|wordpress default libraries|commit frequency|version number increment|complete plugin required|trademark and copyright|directory maintenance rights)$/i.test(normalized)) {
|
|
3932
|
+
return true;
|
|
3933
|
+
}
|
|
3934
|
+
if (/^\d{1,2}\.\s+(separation of concerns|static analysis neutrality|safe stylesheet loading|scoped admin js|concurrency & performance|clean release packaging|defensive php security|dom xss prevention|100% multilingual parity|zero emojis|golden naming rule|mtxstudio 2-level|strict tts acoustic|strict poetry|mandatory 3-position disclaimer|safe vault sync|channel voice adaptation)/.test(normalized)) {
|
|
3935
|
+
return true;
|
|
3936
|
+
}
|
|
3937
|
+
if (/^#{3,4}\s+/.test(rawLine.trim())) {
|
|
3938
|
+
const key = normalizeHeadingKey(rawLine);
|
|
3939
|
+
if (STANDARD_CLI_H3_H4_KEYS.has(key)) return true;
|
|
3940
|
+
}
|
|
3941
|
+
if (rawLine.trim().startsWith(">") && (normalized.includes("generate documentation with skill documents") || normalized.includes("s\u1EED d\u1EE5ng skill content-") || normalized.includes("tip: add the") || normalized.includes("heraspec skill add documents") || normalized.includes("t\xEAn k\xEAnh:") || normalized.includes("tr\u1EE5 c\u1ED9t:") || normalized.includes("y\xEAu c\u1EA7u:"))) {
|
|
3942
|
+
return true;
|
|
3943
|
+
}
|
|
3944
|
+
return false;
|
|
3945
|
+
}
|
|
3946
|
+
function extractCustomRulesFromLegacyAgents(existingContent) {
|
|
3947
|
+
const { preamble, sections } = splitTopLevelSections(existingContent);
|
|
3948
|
+
const customSections = [];
|
|
3949
|
+
const migratedAdditions = [];
|
|
3950
|
+
const customPreambleLines = preamble.filter((raw) => {
|
|
3951
|
+
const trimmed = raw.trim();
|
|
3952
|
+
if (!trimmed) return false;
|
|
3953
|
+
if (/^#\s+HeraSpec\b/i.test(trimmed)) return false;
|
|
3954
|
+
const norm = normalizeComparisonLine(raw);
|
|
3955
|
+
return !isLegacyBoilerplateLine(raw, norm);
|
|
3956
|
+
});
|
|
3957
|
+
if (customPreambleLines.length > 0) {
|
|
3958
|
+
migratedAdditions.push({
|
|
3959
|
+
heading: "Project Notes (Header)",
|
|
3960
|
+
lines: customPreambleLines
|
|
3961
|
+
});
|
|
3962
|
+
}
|
|
3963
|
+
for (const section of sections) {
|
|
3964
|
+
if (!STANDARD_CLI_H2_KEYS.has(section.key)) {
|
|
3965
|
+
const body = section.lines.join("\n").trim();
|
|
3966
|
+
if (body.length > 0) {
|
|
3967
|
+
customSections.push(`${section.heading}
|
|
3968
|
+
|
|
3969
|
+
${body}`);
|
|
3970
|
+
}
|
|
3971
|
+
continue;
|
|
3972
|
+
}
|
|
3973
|
+
const nonBaselineLines = [];
|
|
3974
|
+
for (const rawLine of section.lines) {
|
|
3975
|
+
const norm = normalizeComparisonLine(rawLine);
|
|
3976
|
+
if (!isLegacyBoilerplateLine(rawLine, norm)) {
|
|
3977
|
+
nonBaselineLines.push(rawLine.trimEnd());
|
|
3978
|
+
}
|
|
3979
|
+
}
|
|
3980
|
+
if (nonBaselineLines.length > 0) {
|
|
3981
|
+
const cleanHeading = section.heading.replace(/^##\s+/, "").trim();
|
|
3982
|
+
migratedAdditions.push({
|
|
3983
|
+
heading: `Migrated Customizations from "${cleanHeading}"`,
|
|
3984
|
+
lines: nonBaselineLines
|
|
3985
|
+
});
|
|
3986
|
+
}
|
|
3987
|
+
}
|
|
3988
|
+
return {
|
|
3989
|
+
customSections,
|
|
3990
|
+
migratedAdditions,
|
|
3991
|
+
hasCustomContent: customSections.length > 0 || migratedAdditions.length > 0
|
|
3992
|
+
};
|
|
3993
|
+
}
|
|
3994
|
+
function formatMigratedCustomContent(extraction, projectName) {
|
|
3995
|
+
const header = TemplateManager.getCustomAgentsTemplate(projectName).split("## Project-Specific Invariants & Quality Gates")[0].trimEnd();
|
|
3996
|
+
const parts = [header, "", HERASPEC_MIGRATION_MARKER, ""];
|
|
3997
|
+
for (const section of extraction.customSections) {
|
|
3998
|
+
parts.push(section.trim(), "");
|
|
3999
|
+
}
|
|
4000
|
+
for (const group of extraction.migratedAdditions) {
|
|
4001
|
+
parts.push(`## ${group.heading}`, "");
|
|
4002
|
+
parts.push(...group.lines, "");
|
|
4003
|
+
}
|
|
4004
|
+
return parts.join("\n").trimEnd() + "\n";
|
|
4005
|
+
}
|
|
4006
|
+
function appendMigratedCustomContent(existingCustom, extraction) {
|
|
4007
|
+
const newBlocks = [];
|
|
4008
|
+
const normalizedExisting = normalizeLineEndings(existingCustom);
|
|
4009
|
+
for (const section of extraction.customSections) {
|
|
4010
|
+
if (!normalizedExisting.includes(normalizeLineEndings(section).trim())) {
|
|
4011
|
+
newBlocks.push(section.trim());
|
|
4012
|
+
}
|
|
4013
|
+
}
|
|
4014
|
+
for (const group of extraction.migratedAdditions) {
|
|
4015
|
+
const missingLines = group.lines.filter(
|
|
4016
|
+
(line) => !normalizedExisting.includes(line.trim())
|
|
4017
|
+
);
|
|
4018
|
+
if (missingLines.length > 0) {
|
|
4019
|
+
newBlocks.push(`## ${group.heading}
|
|
4020
|
+
|
|
4021
|
+
${missingLines.join("\n")}`);
|
|
4022
|
+
}
|
|
4023
|
+
}
|
|
4024
|
+
if (newBlocks.length === 0) return null;
|
|
4025
|
+
const stamp = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
|
|
4026
|
+
return normalizedExisting.trimEnd() + `
|
|
4027
|
+
|
|
4028
|
+
${HERASPEC_MIGRATION_MARKER}
|
|
4029
|
+
<!-- Synced from legacy AGENTS.heraspec.md on ${stamp} -->
|
|
4030
|
+
|
|
4031
|
+
` + newBlocks.join("\n\n") + "\n";
|
|
4032
|
+
}
|
|
4033
|
+
function parseConfigYamlContent(yamlContent) {
|
|
4034
|
+
const normalized = normalizeLineEndings(yamlContent);
|
|
4035
|
+
const lines = normalized.split("\n");
|
|
4036
|
+
let projectName;
|
|
4037
|
+
const projectTypes = [];
|
|
4038
|
+
const skills = [];
|
|
4039
|
+
let currentArrayKey = null;
|
|
4040
|
+
const validProjectTypes = new Set(PROJECT_TYPES);
|
|
4041
|
+
for (const rawLine of lines) {
|
|
4042
|
+
const line = rawLine.trim();
|
|
4043
|
+
if (!line || line.startsWith("#")) continue;
|
|
4044
|
+
const listMatch = rawLine.match(/^\s*-\s+(.+)$/);
|
|
4045
|
+
if (listMatch && currentArrayKey) {
|
|
4046
|
+
const value = listMatch[1].trim().replace(/^["']|["']$/g, "");
|
|
4047
|
+
if (value) {
|
|
4048
|
+
if (currentArrayKey === "projectType") projectTypes.push(value);
|
|
4049
|
+
if (currentArrayKey === "skills") skills.push(value);
|
|
4050
|
+
}
|
|
4051
|
+
continue;
|
|
4052
|
+
}
|
|
4053
|
+
currentArrayKey = null;
|
|
4054
|
+
const nameMatch = line.match(/^projectName:\s*(.+)$/i);
|
|
4055
|
+
if (nameMatch) {
|
|
4056
|
+
projectName = nameMatch[1].trim().replace(/^["']|["']$/g, "");
|
|
4057
|
+
continue;
|
|
4058
|
+
}
|
|
4059
|
+
const typeMatch = line.match(/^projectTypes?:\s*(.*)$/i);
|
|
4060
|
+
if (typeMatch) {
|
|
4061
|
+
const rhs = typeMatch[1].trim();
|
|
4062
|
+
if (!rhs) {
|
|
4063
|
+
currentArrayKey = "projectType";
|
|
4064
|
+
} else if (rhs.startsWith("[") && rhs.endsWith("]")) {
|
|
4065
|
+
rhs.slice(1, -1).split(",").map((v) => v.trim().replace(/^["']|["']$/g, "")).filter(Boolean).forEach((v) => projectTypes.push(v));
|
|
4066
|
+
} else {
|
|
4067
|
+
const clean = rhs.replace(/^["']|["']$/g, "");
|
|
4068
|
+
if (clean) projectTypes.push(clean);
|
|
4069
|
+
}
|
|
4070
|
+
continue;
|
|
4071
|
+
}
|
|
4072
|
+
const skillsMatch = line.match(/^skills:\s*(.*)$/i);
|
|
4073
|
+
if (skillsMatch) {
|
|
4074
|
+
const rhs = skillsMatch[1].trim();
|
|
4075
|
+
if (!rhs) {
|
|
4076
|
+
currentArrayKey = "skills";
|
|
4077
|
+
} else if (rhs.startsWith("[") && rhs.endsWith("]")) {
|
|
4078
|
+
rhs.slice(1, -1).split(",").map((v) => v.trim().replace(/^["']|["']$/g, "")).filter(Boolean).forEach((v) => skills.push(v));
|
|
4079
|
+
} else {
|
|
4080
|
+
const clean = rhs.replace(/^["']|["']$/g, "");
|
|
4081
|
+
if (clean) skills.push(clean);
|
|
4082
|
+
}
|
|
4083
|
+
}
|
|
4084
|
+
}
|
|
4085
|
+
const dedupedTypes = Array.from(
|
|
4086
|
+
new Set(projectTypes.filter((t) => validProjectTypes.has(t) || t.length > 0))
|
|
4087
|
+
);
|
|
4088
|
+
return {
|
|
4089
|
+
projectName,
|
|
4090
|
+
projectTypes: dedupedTypes,
|
|
4091
|
+
skills: Array.from(new Set(skills))
|
|
4092
|
+
};
|
|
4093
|
+
}
|
|
4094
|
+
async function readProjectMetadata(heraspecPath) {
|
|
4095
|
+
const configPath = path8.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
|
|
4096
|
+
const projectMdPath = path8.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
|
|
4097
|
+
let metadata = { projectTypes: [], skills: [] };
|
|
4098
|
+
if (await FileSystemUtils.fileExists(configPath)) {
|
|
4099
|
+
const configContent = await FileSystemUtils.readFile(configPath);
|
|
4100
|
+
metadata = parseConfigYamlContent(configContent);
|
|
4101
|
+
}
|
|
4102
|
+
if (await FileSystemUtils.fileExists(projectMdPath)) {
|
|
4103
|
+
const projectContent = normalizeLineEndings(await FileSystemUtils.readFile(projectMdPath));
|
|
4104
|
+
if (!metadata.projectName) {
|
|
4105
|
+
const h1Match = projectContent.match(/^#\s+(?:HeraSpec Project:\s*)?(.+)$/m);
|
|
4106
|
+
if (h1Match) {
|
|
4107
|
+
const candidate = h1Match[1].trim();
|
|
4108
|
+
if (candidate && candidate.toLowerCase() !== "heraspec project") {
|
|
4109
|
+
metadata.projectName = candidate;
|
|
4110
|
+
}
|
|
4111
|
+
}
|
|
4112
|
+
}
|
|
4113
|
+
if (metadata.projectTypes.length === 0) {
|
|
4114
|
+
const typesSectionMatch = projectContent.match(/##\s+Project Types\s*\n([\s\S]*?)(?=\n##\s|$)/i);
|
|
4115
|
+
if (typesSectionMatch) {
|
|
4116
|
+
for (const rawLine of typesSectionMatch[1].split("\n")) {
|
|
4117
|
+
const itemMatch = rawLine.match(/^\s*-\s+`?([a-z0-9-]+)`?(?:\s*:|\s*$)/i);
|
|
4118
|
+
if (itemMatch && itemMatch[1] && itemMatch[1].toLowerCase() !== "list") {
|
|
4119
|
+
metadata.projectTypes.push(itemMatch[1].trim());
|
|
4120
|
+
}
|
|
4121
|
+
}
|
|
4122
|
+
metadata.projectTypes = Array.from(new Set(metadata.projectTypes));
|
|
4123
|
+
}
|
|
4124
|
+
}
|
|
4125
|
+
}
|
|
4126
|
+
return metadata;
|
|
4127
|
+
}
|
|
4128
|
+
async function readHeraspecState(heraspecPath) {
|
|
4129
|
+
const statePath = path8.join(heraspecPath, HERASPEC_MARKERS.STATE_JSON);
|
|
4130
|
+
if (!await FileSystemUtils.fileExists(statePath)) return null;
|
|
4131
|
+
try {
|
|
4132
|
+
const raw = await FileSystemUtils.readFile(statePath);
|
|
4133
|
+
return JSON.parse(raw);
|
|
4134
|
+
} catch {
|
|
4135
|
+
return null;
|
|
4136
|
+
}
|
|
4137
|
+
}
|
|
4138
|
+
async function writeHeraspecState(heraspecPath, state) {
|
|
4139
|
+
const statePath = path8.join(heraspecPath, HERASPEC_MARKERS.STATE_JSON);
|
|
4140
|
+
await FileSystemUtils.writeFile(statePath, JSON.stringify(state, null, 2) + "\n");
|
|
4141
|
+
}
|
|
4142
|
+
function formatBackupTimestamp(now = /* @__PURE__ */ new Date()) {
|
|
4143
|
+
const pad = (n) => String(n).padStart(2, "0");
|
|
4144
|
+
return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
|
|
4145
|
+
}
|
|
4146
|
+
async function resolveBackupFilePath(projectPath) {
|
|
4147
|
+
const stamp = formatBackupTimestamp();
|
|
4148
|
+
const baseName = `AGENTS.heraspec.backup-${stamp}.md`;
|
|
4149
|
+
let candidate = path8.join(projectPath, baseName);
|
|
4150
|
+
let suffix = 2;
|
|
4151
|
+
while (await FileSystemUtils.fileExists(candidate)) {
|
|
4152
|
+
candidate = path8.join(projectPath, `AGENTS.heraspec.backup-${stamp}-${suffix}.md`);
|
|
4153
|
+
suffix++;
|
|
4154
|
+
}
|
|
4155
|
+
return candidate;
|
|
4156
|
+
}
|
|
4157
|
+
async function buildAgentsComposePlan(options) {
|
|
4158
|
+
const { projectPath, heraspecPath, ideOption = "auto", force = false } = options;
|
|
4159
|
+
const agentsPath = path8.join(projectPath, HERASPEC_MARKERS.AGENTS_MD);
|
|
4160
|
+
const customAgentsPath = path8.join(projectPath, HERASPEC_MARKERS.AGENTS_CUSTOM_MD);
|
|
4161
|
+
const statePath = path8.join(heraspecPath, HERASPEC_MARKERS.STATE_JSON);
|
|
4162
|
+
const [metadata, discovery, skillsInfo, existingState, customExists, agentsExists] = await Promise.all([
|
|
4163
|
+
readProjectMetadata(heraspecPath),
|
|
4164
|
+
IdeAdapterManager.discoverWorkspace(projectPath, ideOption),
|
|
4165
|
+
IdeAdapterManager.collectCanonicalSkills(projectPath),
|
|
4166
|
+
readHeraspecState(heraspecPath),
|
|
4167
|
+
FileSystemUtils.fileExists(customAgentsPath),
|
|
4168
|
+
FileSystemUtils.fileExists(agentsPath)
|
|
4169
|
+
]);
|
|
4170
|
+
const legacyCodexAgentsPath = path8.join(projectPath, "AGENTS.md");
|
|
4171
|
+
const legacyAgentsExists = !agentsExists && await FileSystemUtils.fileExists(legacyCodexAgentsPath);
|
|
4172
|
+
let legacyAgentsContent = null;
|
|
4173
|
+
if (legacyAgentsExists) {
|
|
4174
|
+
const candidateContent = await FileSystemUtils.readFile(legacyCodexAgentsPath);
|
|
4175
|
+
if (/HeraSpec|heraspec\/project\.md|Universal Safety Rules/i.test(candidateContent)) {
|
|
4176
|
+
legacyAgentsContent = candidateContent;
|
|
4177
|
+
}
|
|
4178
|
+
}
|
|
4179
|
+
let extraction = {
|
|
4180
|
+
customSections: [],
|
|
4181
|
+
migratedAdditions: [],
|
|
4182
|
+
hasCustomContent: false
|
|
4183
|
+
};
|
|
4184
|
+
let backupPath = null;
|
|
4185
|
+
let agentsAction = "create";
|
|
4186
|
+
let customAction = customExists ? "preserve" : "create-starter";
|
|
4187
|
+
let nextCustomContent = customExists ? null : TemplateManager.getCustomAgentsTemplate(metadata.projectName);
|
|
4188
|
+
const sourceToInspectPath = agentsExists ? agentsPath : legacyAgentsContent ? legacyCodexAgentsPath : null;
|
|
4189
|
+
const existingAgentsContent = agentsExists ? await FileSystemUtils.readFile(agentsPath) : legacyAgentsContent;
|
|
4190
|
+
if (existingAgentsContent !== null) {
|
|
4191
|
+
const existingSha = computeNormalizedSha256(existingAgentsContent);
|
|
4192
|
+
const hasTrackedHash = Boolean(existingState?.agentsHeraspecSha256);
|
|
4193
|
+
const matchesTrackedHash = hasTrackedHash && existingState?.agentsHeraspecSha256 === existingSha;
|
|
4194
|
+
if (agentsExists && matchesTrackedHash && !force) {
|
|
4195
|
+
agentsAction = "upgrade-clean";
|
|
4196
|
+
} else {
|
|
4197
|
+
extraction = extractCustomRulesFromLegacyAgents(existingAgentsContent);
|
|
4198
|
+
if (sourceToInspectPath === agentsPath) {
|
|
4199
|
+
if (!hasTrackedHash || !matchesTrackedHash) {
|
|
4200
|
+
backupPath = await resolveBackupFilePath(projectPath);
|
|
4201
|
+
}
|
|
4202
|
+
}
|
|
4203
|
+
if (extraction.hasCustomContent) {
|
|
4204
|
+
agentsAction = "migrate-and-regenerate";
|
|
4205
|
+
if (!customExists) {
|
|
4206
|
+
customAction = "create-from-migration";
|
|
4207
|
+
nextCustomContent = formatMigratedCustomContent(extraction, metadata.projectName);
|
|
4208
|
+
} else {
|
|
4209
|
+
const currentCustom = await FileSystemUtils.readFile(customAgentsPath);
|
|
4210
|
+
const appended = appendMigratedCustomContent(currentCustom, extraction);
|
|
4211
|
+
if (appended !== null) {
|
|
4212
|
+
customAction = "append-migration";
|
|
4213
|
+
nextCustomContent = appended;
|
|
4214
|
+
} else {
|
|
4215
|
+
customAction = "preserve";
|
|
4216
|
+
nextCustomContent = null;
|
|
4217
|
+
}
|
|
4218
|
+
}
|
|
4219
|
+
} else {
|
|
4220
|
+
agentsAction = hasTrackedHash && !matchesTrackedHash ? "migrate-and-regenerate" : "upgrade-clean";
|
|
4221
|
+
}
|
|
4222
|
+
}
|
|
4223
|
+
}
|
|
4224
|
+
const willHaveCustomFile = customExists || nextCustomContent !== null;
|
|
4225
|
+
const context = {
|
|
4226
|
+
projectName: metadata.projectName,
|
|
4227
|
+
projectTypes: metadata.projectTypes,
|
|
4228
|
+
hasCustomFile: willHaveCustomFile,
|
|
4229
|
+
customFileName: HERASPEC_MARKERS.AGENTS_CUSTOM_MD,
|
|
4230
|
+
detectedIdeFiles: discovery.detectedFiles,
|
|
4231
|
+
detectedSkillRoots: discovery.detectedSkillRoots,
|
|
4232
|
+
installedSkills: skillsInfo.summaries
|
|
4233
|
+
};
|
|
4234
|
+
const renderedAgents = TemplateManager.getAgentsTemplate(context);
|
|
4235
|
+
const renderedSha256 = computeNormalizedSha256(renderedAgents);
|
|
4236
|
+
if (agentsExists && existingAgentsContent !== null && computeNormalizedSha256(existingAgentsContent) === renderedSha256 && !force) {
|
|
4237
|
+
agentsAction = "up-to-date";
|
|
4238
|
+
backupPath = null;
|
|
4239
|
+
}
|
|
4240
|
+
return {
|
|
4241
|
+
agentsPath,
|
|
4242
|
+
customAgentsPath,
|
|
4243
|
+
statePath,
|
|
4244
|
+
backupPath,
|
|
4245
|
+
agentsAction,
|
|
4246
|
+
customAction,
|
|
4247
|
+
extraction,
|
|
4248
|
+
renderedAgents,
|
|
4249
|
+
nextCustomContent,
|
|
4250
|
+
renderedSha256,
|
|
4251
|
+
context
|
|
4252
|
+
};
|
|
4253
|
+
}
|
|
4254
|
+
var HERASPEC_MIGRATION_MARKER, STANDARD_CLI_H2_KEYS, STANDARD_CLI_H3_H4_KEYS, LEGACY_V01_EXTRA_BOILERPLATE, LEGACY_BASELINE_SET;
|
|
4255
|
+
var init_agents_composer = __esm({
|
|
4256
|
+
"src/core/agents-composer.ts"() {
|
|
4257
|
+
"use strict";
|
|
4258
|
+
init_file_system();
|
|
4259
|
+
init_config();
|
|
4260
|
+
init_templates();
|
|
4261
|
+
init_ide_adapter();
|
|
4262
|
+
HERASPEC_MIGRATION_MARKER = "<!-- HERASPEC:MIGRATED_FROM_LEGACY -->";
|
|
4263
|
+
STANDARD_CLI_H2_KEYS = /* @__PURE__ */ new Set([
|
|
4264
|
+
"universal safety rules",
|
|
4265
|
+
"core workflow",
|
|
4266
|
+
"spec format",
|
|
4267
|
+
"delta spec format",
|
|
4268
|
+
"tasks format",
|
|
4269
|
+
"skills system",
|
|
4270
|
+
"proactive memory-aware development",
|
|
4271
|
+
"memory-aware development",
|
|
4272
|
+
"rule precedence & ide workspace discovery (auto-combined)",
|
|
4273
|
+
"ide & workspace rule discovery",
|
|
4274
|
+
"ide & workspace rule discovery (auto-combined)"
|
|
4275
|
+
]);
|
|
4276
|
+
STANDARD_CLI_H3_H4_KEYS = /* @__PURE__ */ new Set([
|
|
4277
|
+
"restricted commands (require user confirmation)",
|
|
4278
|
+
"group 1 - extremely dangerous (data destruction, hard / impossible to recover)",
|
|
4279
|
+
"group 2 - high danger (delete directory / multiple files)",
|
|
4280
|
+
"group 3 - medium danger (delete file / overwrite)",
|
|
4281
|
+
"group 4 - indirect danger (data loss)",
|
|
4282
|
+
"group 5 - disk / partition management",
|
|
4283
|
+
"group 6 - less dangerous (potential consequences)",
|
|
4284
|
+
"step 1 - create a change",
|
|
4285
|
+
"step 2 - refine specs",
|
|
4286
|
+
"step 3 - approval",
|
|
4287
|
+
"step 4 - implementation",
|
|
4288
|
+
"step 5 - archive",
|
|
4289
|
+
"handling parallel merge conflicts",
|
|
4290
|
+
"skill discovery & usage",
|
|
4291
|
+
"when change has multiple skills",
|
|
4292
|
+
"critical rules for automatic memory usage",
|
|
4293
|
+
"when to skip memory",
|
|
4294
|
+
"smart code exploration",
|
|
4295
|
+
"auto-detected workspace context",
|
|
4296
|
+
"active project skills",
|
|
4297
|
+
"skills system"
|
|
4298
|
+
]);
|
|
4299
|
+
LEGACY_V01_EXTRA_BOILERPLATE = [
|
|
4300
|
+
"This document defines the workflow for AI agents working with HeraSpec.",
|
|
4301
|
+
"**CRITICAL: When implementing tasks, ALWAYS use Skills system:**",
|
|
4302
|
+
"**Important**: Each task group uses ONE skill. When working on a task group, agent MUST use that skill's skill.md.",
|
|
4303
|
+
"**Key rule**: Switch skill.md when switching task groups!",
|
|
4304
|
+
"Example workflow:",
|
|
4305
|
+
"**Example workflow:**",
|
|
4306
|
+
"### Step 1 - Create a Change",
|
|
4307
|
+
"### Step 2 - Refine Specs",
|
|
4308
|
+
"### Step 3 - Approval",
|
|
4309
|
+
"### Step 4 - Implementation",
|
|
4310
|
+
"### Step 5 - Archive",
|
|
4311
|
+
"> **IGNORE backup files**: Files like project.back1.md, project.back2.md, etc. are automatic backups created during heraspec init updates. NEVER read or reference them unless explicitly asked by the user. Only project.md is the source of truth.",
|
|
4312
|
+
"**When creating changes, ALWAYS read heraspec/project.md first to understand:**",
|
|
4313
|
+
"- Project types being used",
|
|
4314
|
+
"- Tech stack and conventions",
|
|
4315
|
+
"- Existing architecture patterns",
|
|
4316
|
+
"- Coding standards",
|
|
4317
|
+
"**Then scaffold:**",
|
|
4318
|
+
"- heraspec/changes/<slug>/ - Create proposal.md, tasks.md, design.md (optional)",
|
|
4319
|
+
"- heraspec/specs/<slug>/ - Create delta specs here (NOT inside changes folder)",
|
|
4320
|
+
"**If user asks to create changes based on project.md:**",
|
|
4321
|
+
"1. Read heraspec/project.md thoroughly",
|
|
4322
|
+
"2. Identify all features/capabilities mentioned",
|
|
4323
|
+
"3. Create separate changes for each major feature",
|
|
4324
|
+
"4. Ensure each change follows project.md conventions",
|
|
4325
|
+
"5. Use correct project types and skills from project.md",
|
|
4326
|
+
"- Never modify source-of-truth specs directly",
|
|
4327
|
+
'- Wait for user: "Specs approved."',
|
|
4328
|
+
"1. Read task line to identify skill:",
|
|
4329
|
+
"## 1. Perfex module - Category Management (projectType: perfex-module, skill: module-codebase)",
|
|
4330
|
+
"- [ ] 1.1 Create module structure",
|
|
4331
|
+
"2. Find skill folder:",
|
|
4332
|
+
"3. Read skill.md:",
|
|
4333
|
+
"- Understand purpose, steps, inputs, outputs",
|
|
4334
|
+
"- Follow tone, rules, and limitations",
|
|
4335
|
+
"- Check available templates and scripts",
|
|
4336
|
+
"- Ignore Vietnamese Skill Files: Only read the English skill.md instructions. Completely ignore any *.vi.md translation files.",
|
|
4337
|
+
"4. Use skill resources:",
|
|
4338
|
+
"5. Implement following skill.md guidance:",
|
|
4339
|
+
"- Follow step-by-step process",
|
|
4340
|
+
"- Use correct naming conventions",
|
|
4341
|
+
"- Apply code style rules",
|
|
4342
|
+
"- Respect limitations",
|
|
4343
|
+
"- Task: (projectType: perfex-module, skill: module-codebase)",
|
|
4344
|
+
"- Agent reads: heraspec/skills/perfex-module/module-codebase/skill.md",
|
|
4345
|
+
"- Agent follows: Steps, uses templates, runs scripts",
|
|
4346
|
+
"- Agent implements: According to skill.md guidelines",
|
|
4347
|
+
"- Task: (skill: ui-ux)",
|
|
4348
|
+
"- Agent reads: heraspec/skills/ui-ux/skill.md",
|
|
4349
|
+
"- Agent MUST use search scripts before implementing:",
|
|
4350
|
+
"# Search for design intelligence",
|
|
4351
|
+
"- Agent synthesizes search results",
|
|
4352
|
+
"- Agent implements with proper colors, fonts, styles from search results",
|
|
4353
|
+
"- Agent verifies with pre-delivery checklist",
|
|
4354
|
+
"- Agent generates a **Compliance Report** with:",
|
|
4355
|
+
"- \u2705 Passed items",
|
|
4356
|
+
"- \u26A0\uFE0F Items needing review",
|
|
4357
|
+
"- \u274C Violations with file paths and line numbers",
|
|
4358
|
+
"- **CRITICAL**: Agent MUST present full report and **wait for user confirmation** before making changes",
|
|
4359
|
+
'- Reference guideline numbers (e.g., "Guideline 7: User Tracking Consent")',
|
|
4360
|
+
"- Task: (projectType: wordpress-plugin, skill: ux-element)",
|
|
4361
|
+
"- **Special case - WordPress Plugin:**",
|
|
4362
|
+
"- **Example prompt for Documents skill:**",
|
|
4363
|
+
"If you need to generate multi-format documentation, use this prompt:",
|
|
4364
|
+
"- **Dynamic Documentation Generation**:",
|
|
4365
|
+
"When generating documentation, do NOT simply fill a template. The Agent MUST:",
|
|
4366
|
+
"1. **Create** the /documentations directory if it does not exist.",
|
|
4367
|
+
"2. **Design** a custom layout and content structure suitable for the project type.",
|
|
4368
|
+
"3. **Synchronize** with the ui-ux skill for premium visual design (colors, typography, animations).",
|
|
4369
|
+
"4. **Scan All Specs**: If project-wide, read heraspec/project.md and all files in heraspec/specs/ to synthesize the content.",
|
|
4370
|
+
"- Task: (projectType: wordpress, skill: ux-element)",
|
|
4371
|
+
"- Task: (projectType: wordpress-plugin, skill: plugin-check)",
|
|
4372
|
+
"- Task: (projectType: wordpress-plugin, skill: plugin-directory)",
|
|
4373
|
+
"- Follow tasks.md",
|
|
4374
|
+
"- Mark tasks completed: - [x]",
|
|
4375
|
+
`> "Tip: Add the 'documents' skill for premium HTML & Landing Page support:`,
|
|
4376
|
+
'> heraspec skill add documents"',
|
|
4377
|
+
"- Project-specific: heraspec/skills/<project-type>/",
|
|
4378
|
+
"- Cross-cutting: heraspec/skills/<skill-name>/ (root level)",
|
|
4379
|
+
"- **Consistency**: Follow the step-by-step process in the skill's skill.md.",
|
|
4380
|
+
"## 1. WordPress module - Feature (skill: admin-settings-page)",
|
|
4381
|
+
"- [ ] Task 1.1 Create module structure",
|
|
4382
|
+
"- [ ] Task 1.2 Configure registration",
|
|
4383
|
+
"## 2. UI/UX - Admin Interface (skill: ui-ux)",
|
|
4384
|
+
"- [ ] Task 2.1 Design color palette",
|
|
4385
|
+
"- [ ] Task 2.2 Create component styles",
|
|
4386
|
+
"## 3. Documents - User Guide (skill: documents)",
|
|
4387
|
+
"- [ ] Task 3.1 Write technical docs",
|
|
4388
|
+
"## 1. WordPress plugin - admin settings page (projectType: wordpress-plugin, skill: admin-settings-page)",
|
|
4389
|
+
"- [ ] Task description",
|
|
4390
|
+
"- `truncate` : Cutt off file content",
|
|
4391
|
+
"truncate : Cutt off file content",
|
|
4392
|
+
"- heraspec explore outline <file> -> View structure (~1K tokens vs ~12K full file)",
|
|
4393
|
+
'- heraspec explore search "<query>" <path> -> Find symbols across codebase',
|
|
4394
|
+
"- heraspec explore unfold <file> <symbol> -> Read just one function",
|
|
4395
|
+
"Example with multiple skills in one change:",
|
|
4396
|
+
'python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain>',
|
|
4397
|
+
'python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --stack <stack>',
|
|
4398
|
+
"- Agent reads: heraspec/skills/wordpress-plugin/plugin-directory/skill.md",
|
|
4399
|
+
"- Agent MUST review plugin against **18 WordPress.org Directory Guidelines**:",
|
|
4400
|
+
"- Agent MUST adhere to **10 Enterprise Code Quality & Clean Code Standards**:",
|
|
4401
|
+
"- Use templates from heraspec/skills/perfex-module/module-codebase/templates/ (module-main.php, install.php, uninstall.php, controller-admin.php, controller-api.php, model-main.php, helper.php, deploy.ps1, webpack.config.js).",
|
|
4402
|
+
"- Tasks: (projectType: content-channel, skill: content-strategy), (skill: content-scaffolding), (skill: content-scripting), (skill: content-voice-adapter), (skill: content-prompts), (skill: content-compliance), (skill: content-vault-sync), or (skill: content-channel)",
|
|
4403
|
+
"- Install: heraspec skill add content-channel or heraspec skill add <skill-name> --project-type content-channel",
|
|
4404
|
+
"- Agent reads corresponding skill instructions in heraspec/skills/<skill-name>/skill.md or heraspec/skills/content-channel/<skill-name>/skill.md.",
|
|
4405
|
+
"- Agent MUST adhere to **7 Core Content Production Standards**:",
|
|
4406
|
+
"- Short sentences: 12 - 20 words max per sentence (never exceed 25 words or 120 chars).",
|
|
4407
|
+
"- Comma clauses: 8 - 12 words max.",
|
|
4408
|
+
"- Repetition Bug Prevention: Never place 2 reduplicative words (t\u1EEB l\xE1y) adjacently; always separate with a natural comma ,.",
|
|
4409
|
+
"- Clean text: Zero artificial bracket tags; rely entirely on natural punctuation (., ,, ..., !) and sentence rhythm for voice pacing.",
|
|
4410
|
+
"- **Example prompts for Content Channel Development (content-channel skills):**",
|
|
4411
|
+
"- Channel Strategy (content-strategy):",
|
|
4412
|
+
"- Channel Scaffolding (content-scaffolding):",
|
|
4413
|
+
"- Raw Text Transmutation (content-voice-adapter):",
|
|
4414
|
+
"- Scriptwriting from Scratch (content-scripting):",
|
|
4415
|
+
"- AI Visual & Suno BGM Prompts (content-prompts):",
|
|
4416
|
+
"- Legal Compliance & Disclaimer (content-compliance):",
|
|
4417
|
+
"- Vault Synchronization (content-vault-sync):",
|
|
4418
|
+
"- Agent reads: heraspec/skills/perfex-module/skill.md, heraspec/skills/perfex-module/module-codebase/skill.md, and heraspec/skills/perfex-module/code-quality-guidelines/skill.md",
|
|
4419
|
+
"- Install: heraspec skill add perfex-module or heraspec skill add module-codebase --project-type perfex-module or heraspec skill add code-quality-guidelines --project-type perfex-module",
|
|
4420
|
+
"- List all skills: Check heraspec/skills/ directory",
|
|
4421
|
+
"- Agent MUST run WordPress Plugin Check (PCP) tool",
|
|
4422
|
+
"- Agent fixes coding standard issues iteratively until all pass",
|
|
4423
|
+
"- If missing:",
|
|
4424
|
+
"- Preferred: Proactively install it via heraspec skill add <name> (e.g., heraspec skill add documents) if you have terminal access.",
|
|
4425
|
+
"- Fallback: If you cannot install it, STOP and ask the user to add it. DO NOT attempt manual generation without the skill.",
|
|
4426
|
+
"- Option A (Preferred): If you can run commands, execute heraspec skill add <skill-name> immediately.",
|
|
4427
|
+
"- Option B (Fallback): If you cannot run commands, STOP and ask the user to run it.",
|
|
4428
|
+
"- DO NOT create a task plan or attempt manual generation without the skill language.",
|
|
4429
|
+
'- CRITICAL: Save all files in the /documentations directory (create it if missing)."',
|
|
4430
|
+
"- Concise overview (documentations/documentation.txt)",
|
|
4431
|
+
"- Technical Markdown (documentations/documentation.md)",
|
|
4432
|
+
"- Interactive HTML (documentations/documentation.html)",
|
|
4433
|
+
"- Premium Documentation Landing Page (documentations/documentation-landing-page.html)",
|
|
4434
|
+
"- ## 1. WordPress module - Feature (skill: admin-settings-page)",
|
|
4435
|
+
"## 1. WordPress module - Feature (skill: admin-settings-page)",
|
|
4436
|
+
"- Agent runs WordPress Plugin Check (PCP) tool",
|
|
4437
|
+
"**Example prompts for Content Channel Development (content-channel skills):**",
|
|
4438
|
+
"**Dynamic Documentation Generation**:",
|
|
4439
|
+
"> - Ng\xE1ch: [V\xED d\u1EE5: Thi\u1EC1n \u0111\u1ECBnh & L\u1ED1i s\u1ED1ng t\u1ED1i gi\u1EA3n]",
|
|
4440
|
+
"> - Kh\xE1n gi\u1EA3 m\u1EE5c ti\xEAu: [V\xED d\u1EE5: 25 - 40 tu\u1ED5i, nh\xE2n vi\xEAn v\u0103n ph\xF2ng stress]",
|
|
4441
|
+
"> - Slogan: [V\xED d\u1EE5: Th\xE2n c\xF3 an, t\xE2m m\u1EDBi l\u1EA1c] | Icon Lucide: [Heart] | M\xE0u: [#10b981]",
|
|
4442
|
+
"> [D\xC1N \u0110O\u1EA0N V\u0102N B\u1EA2N TH\xD4 V\xC0O \u0110\xC2Y]",
|
|
4443
|
+
'> Y\xEAu c\u1EA7u qua 4 b\u01B0\u1EDBc: (1) L\u1ECDc l\u1EC7ch tone theo ma tr\u1EADn th\u1EC3 lo\u1EA1i (ch\u1EEFa l\xE0nh: l\u1ECDc m\xEA t\xEDn/\u0111\u1ED5 l\u1ED7i; truy\u1EC7n ma: l\u1ECDc m\xE1u me/vi ph\u1EA1m N\u0110 15 t\xEAn ng\u01B0\u1EDDi th\u1EADt/c\u1EE3t nh\u1EA3; d\u01B0\u1EE1ng sinh: l\u1ECDc ph\u1EA3n khoa h\u1ECDc/th\u1EA7n th\xE1nh h\xF3a; chi\xEAm nghi\u1EC7m: l\u1ECDc than th\u1EDF n\u1EA1n nh\xE2n), (2) T\xE1i c\u1EA5u tr\xFAc theo DNA tri\u1EBFt l\xFD v\xE0 \u0111\u1EA1i t\u1EEB nh\xE2n x\u01B0ng c\u1EE7a k\xEAnh, (3) T\u1ED1i \u01B0u \xE2m h\u1ECDc TTS 12-20 t\u1EEB/c\xE2u s\u1EA1ch th\u1EBB ngo\u1EB7c vu\xF4ng, (4) \u0110\xF3ng g\xF3i 6 ph\u1EA7n chu\u1EA9n MTxStudio k\xE8m Storyboard prompt, Caption v\xE0 Disclaimer ph\xE1p l\xFD ph\xF9 h\u1EE3p th\u1EC3 lo\u1EA1i."',
|
|
4444
|
+
'> - Y\xEAu c\u1EA7u \xE2m h\u1ECDc TTS: C\xE2u ng\u1EAFn 12-20 t\u1EEB, ng\u1EAFt nh\u1ECBp d\u1EA5u ph\u1EA9y r\xF5 r\xE0ng, kh\xF4ng \u0111i\u1EC7p \xE2m t\u1EEB l\xE1y, TUY\u1EC6T \u0110\u1ED0I KH\xD4NG ch\xE8n th\u1EBB ngo\u1EB7c vu\xF4ng ([l\u1EA5y h\u01A1i], [th\u1EDF d\xE0i]), b\u1EA3o to\xE0n th\u01A1 ca m\u1ED7i c\xE2u 1 d\xF2ng (\\n), xu\u1EA5t \u0111\u1EA7y \u0111\u1EE7 6 ph\u1EA7n k\xE8m Storyboard v\xE0 Caption Facebook."',
|
|
4445
|
+
`> - C\u1EA7n t\u1EA1o: Prompt Avatar 1:1, Cover 16:9, B\u1EA3ng 5 Prompts Storyboard b\xE0i vi\u1EBFt '[T\xEAn b\xE0i vi\u1EBFt]', v\xE0 Prompt Suno AI BGM kh\xF4ng l\u1EDDi."`,
|
|
4446
|
+
"> - Cung c\u1EA5p Disclaimer chu\u1EA9n ph\xE1p l\xFD (Ngh\u1ECB \u0111\u1ECBnh 15/2020/N\u0110-CP) \u0111\u1EB7t \u1EDF ch\xE2n Caption.",
|
|
4447
|
+
'> - Cung c\u1EA5p Prompt m\xE0n h\xECnh c\u1EA3nh b\xE1o Intro Warning Card (0:00 - 0:04, t\u1EF7 l\u1EC7 16:9)."',
|
|
4448
|
+
"- Use heraspec explore outline <file> -> View structure (~1K tokens vs ~12K full file)"
|
|
4449
|
+
];
|
|
4450
|
+
LEGACY_BASELINE_SET = buildBaselineLineSet();
|
|
4451
|
+
}
|
|
4452
|
+
});
|
|
4453
|
+
|
|
4454
|
+
// src/core/skills/index.ts
|
|
4455
|
+
var init_skills = __esm({
|
|
4456
|
+
"src/core/skills/index.ts"() {
|
|
4457
|
+
"use strict";
|
|
4458
|
+
init_skill_parser();
|
|
2983
4459
|
init_skill_manager();
|
|
2984
4460
|
}
|
|
2985
4461
|
});
|
|
@@ -2989,7 +4465,8 @@ var skill_exports = {};
|
|
|
2989
4465
|
__export(skill_exports, {
|
|
2990
4466
|
SkillCommand: () => SkillCommand
|
|
2991
4467
|
});
|
|
2992
|
-
import
|
|
4468
|
+
import path9 from "path";
|
|
4469
|
+
import chalk2 from "chalk";
|
|
2993
4470
|
import ora2 from "ora";
|
|
2994
4471
|
import { fileURLToPath } from "url";
|
|
2995
4472
|
import { dirname, join } from "path";
|
|
@@ -2998,7 +4475,7 @@ async function getCoreTemplatesDir() {
|
|
|
2998
4475
|
const possiblePaths = [];
|
|
2999
4476
|
try {
|
|
3000
4477
|
const packageJsonPath = require2.resolve("../package.json");
|
|
3001
|
-
const packageDir =
|
|
4478
|
+
const packageDir = path9.dirname(packageJsonPath);
|
|
3002
4479
|
possiblePaths.push(
|
|
3003
4480
|
join(packageDir, "src", "core", "templates", "skills"),
|
|
3004
4481
|
// Source (when linked, this is the actual source)
|
|
@@ -3009,7 +4486,7 @@ async function getCoreTemplatesDir() {
|
|
|
3009
4486
|
}
|
|
3010
4487
|
try {
|
|
3011
4488
|
const packageJsonPath = require2.resolve("heraspec/package.json");
|
|
3012
|
-
const packageDir =
|
|
4489
|
+
const packageDir = path9.dirname(packageJsonPath);
|
|
3013
4490
|
possiblePaths.push(
|
|
3014
4491
|
join(packageDir, "dist", "core", "templates", "skills"),
|
|
3015
4492
|
// Built
|
|
@@ -3041,6 +4518,8 @@ var init_skill = __esm({
|
|
|
3041
4518
|
init_skills();
|
|
3042
4519
|
init_config();
|
|
3043
4520
|
init_skills_template_map();
|
|
4521
|
+
init_ide_adapter();
|
|
4522
|
+
init_agents_composer();
|
|
3044
4523
|
require2 = createRequire(import.meta.url);
|
|
3045
4524
|
__filename = fileURLToPath(import.meta.url);
|
|
3046
4525
|
__dirname = dirname(__filename);
|
|
@@ -3182,7 +4661,7 @@ var init_skill = __esm({
|
|
|
3182
4661
|
});
|
|
3183
4662
|
console.log();
|
|
3184
4663
|
}
|
|
3185
|
-
const skillMdPath =
|
|
4664
|
+
const skillMdPath = path9.join(skillInfo.skillPath, "skill.md");
|
|
3186
4665
|
if (await FileSystemUtils.fileExists(skillMdPath)) {
|
|
3187
4666
|
console.log("\u2550".repeat(60));
|
|
3188
4667
|
console.log("\n## Full skill.md Content\n");
|
|
@@ -3194,7 +4673,7 @@ var init_skill = __esm({
|
|
|
3194
4673
|
async repair(projectPath = ".") {
|
|
3195
4674
|
const spinner = ora2("Repairing skills structure...").start();
|
|
3196
4675
|
try {
|
|
3197
|
-
const skillsDir =
|
|
4676
|
+
const skillsDir = path9.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
|
|
3198
4677
|
if (!await FileSystemUtils.fileExists(skillsDir)) {
|
|
3199
4678
|
spinner.fail('Skills directory does not exist. Run "heraspec init" first.');
|
|
3200
4679
|
process.exitCode = 1;
|
|
@@ -3205,7 +4684,7 @@ var init_skill = __esm({
|
|
|
3205
4684
|
let errors = 0;
|
|
3206
4685
|
for (const skill of skills) {
|
|
3207
4686
|
const skillPath = skill.path;
|
|
3208
|
-
const skillMdPath =
|
|
4687
|
+
const skillMdPath = path9.join(skillPath, "skill.md");
|
|
3209
4688
|
if (!await FileSystemUtils.fileExists(skillMdPath)) {
|
|
3210
4689
|
spinner.warn(`Missing skill.md in ${skillPath}`);
|
|
3211
4690
|
errors++;
|
|
@@ -3213,7 +4692,7 @@ var init_skill = __esm({
|
|
|
3213
4692
|
}
|
|
3214
4693
|
const standardDirs = ["templates", "scripts", "examples"];
|
|
3215
4694
|
for (const dir of standardDirs) {
|
|
3216
|
-
const dirPath =
|
|
4695
|
+
const dirPath = path9.join(skillPath, dir);
|
|
3217
4696
|
if (!await FileSystemUtils.fileExists(dirPath)) {
|
|
3218
4697
|
await FileSystemUtils.createDirectory(dirPath);
|
|
3219
4698
|
fixed++;
|
|
@@ -3263,10 +4742,10 @@ var init_skill = __esm({
|
|
|
3263
4742
|
process.exitCode = 1;
|
|
3264
4743
|
return;
|
|
3265
4744
|
}
|
|
3266
|
-
const skillsDir =
|
|
4745
|
+
const skillsDir = path9.join(projectPath, HERASPEC_DIR_NAME, SKILLS_DIR_NAME);
|
|
3267
4746
|
let destPath;
|
|
3268
4747
|
if (templateInfo.isCrossCutting) {
|
|
3269
|
-
destPath =
|
|
4748
|
+
destPath = path9.join(skillsDir, skillName);
|
|
3270
4749
|
} else {
|
|
3271
4750
|
if (!templateInfo.projectType) {
|
|
3272
4751
|
spinner.fail("Project type is required for this skill");
|
|
@@ -3280,8 +4759,8 @@ var init_skill = __esm({
|
|
|
3280
4759
|
effectiveSkillName = parts[1];
|
|
3281
4760
|
}
|
|
3282
4761
|
}
|
|
3283
|
-
destPath =
|
|
3284
|
-
const legacyPath =
|
|
4762
|
+
destPath = path9.join(skillsDir, templateInfo.projectType, effectiveSkillName);
|
|
4763
|
+
const legacyPath = path9.join(skillsDir, templateInfo.projectType, `${templateInfo.projectType}:${effectiveSkillName}`);
|
|
3285
4764
|
if (legacyPath !== destPath && await FileSystemUtils.fileExists(legacyPath)) {
|
|
3286
4765
|
spinner.info(`Cleaning up legacy prefixed skill folder: ${legacyPath}`);
|
|
3287
4766
|
try {
|
|
@@ -3302,39 +4781,65 @@ var init_skill = __esm({
|
|
|
3302
4781
|
process.exitCode = 1;
|
|
3303
4782
|
return;
|
|
3304
4783
|
}
|
|
3305
|
-
const templateFile =
|
|
4784
|
+
const templateFile = path9.join(coreTemplatesDir, templateInfo.templateFileName);
|
|
3306
4785
|
if (!await FileSystemUtils.fileExists(templateFile)) {
|
|
3307
4786
|
spinner.fail(`Template file not found: ${templateFile}`);
|
|
3308
4787
|
process.exitCode = 1;
|
|
3309
4788
|
return;
|
|
3310
4789
|
}
|
|
3311
|
-
await FileSystemUtils.copyFile(templateFile,
|
|
3312
|
-
const upperTemplateFile =
|
|
4790
|
+
await FileSystemUtils.copyFile(templateFile, path9.join(destPath, "skill.md"));
|
|
4791
|
+
const upperTemplateFile = path9.join(path9.dirname(templateFile), "SKILL.md");
|
|
3313
4792
|
if (await FileSystemUtils.fileExists(upperTemplateFile)) {
|
|
3314
|
-
await FileSystemUtils.copyFile(upperTemplateFile,
|
|
4793
|
+
await FileSystemUtils.copyFile(upperTemplateFile, path9.join(destPath, "SKILL.md"));
|
|
3315
4794
|
}
|
|
3316
4795
|
if (templateInfo.viFileName) {
|
|
3317
|
-
const viFile =
|
|
4796
|
+
const viFile = path9.join(coreTemplatesDir, templateInfo.viFileName);
|
|
3318
4797
|
if (await FileSystemUtils.fileExists(viFile)) {
|
|
3319
|
-
await FileSystemUtils.copyFile(viFile,
|
|
4798
|
+
await FileSystemUtils.copyFile(viFile, path9.join(destPath, "skill.vi.md"));
|
|
3320
4799
|
}
|
|
3321
4800
|
}
|
|
3322
4801
|
if (templateInfo.resourceDirs) {
|
|
3323
4802
|
for (const resourceDir of templateInfo.resourceDirs) {
|
|
3324
|
-
const srcResourceDir =
|
|
3325
|
-
const destResourceDir =
|
|
4803
|
+
const srcResourceDir = path9.join(coreTemplatesDir, resourceDir);
|
|
4804
|
+
const destResourceDir = path9.join(destPath, path9.basename(resourceDir));
|
|
3326
4805
|
if (await FileSystemUtils.fileExists(srcResourceDir)) {
|
|
3327
4806
|
await FileSystemUtils.copyDirectory(srcResourceDir, destResourceDir);
|
|
3328
4807
|
}
|
|
3329
4808
|
}
|
|
3330
4809
|
}
|
|
3331
|
-
await FileSystemUtils.createDirectory(
|
|
3332
|
-
await FileSystemUtils.createDirectory(
|
|
3333
|
-
await FileSystemUtils.createDirectory(
|
|
4810
|
+
await FileSystemUtils.createDirectory(path9.join(destPath, "templates"));
|
|
4811
|
+
await FileSystemUtils.createDirectory(path9.join(destPath, "scripts"));
|
|
4812
|
+
await FileSystemUtils.createDirectory(path9.join(destPath, "examples"));
|
|
4813
|
+
const heraspecDir = path9.join(path9.resolve(projectPath), HERASPEC_DIR_NAME);
|
|
4814
|
+
const existingState = await readHeraspecState(heraspecDir);
|
|
4815
|
+
const installedName = path9.basename(destPath);
|
|
4816
|
+
const ideSync = await IdeAdapterManager.syncAdaptersAndSkills({
|
|
4817
|
+
projectPath,
|
|
4818
|
+
ideOption: "auto",
|
|
4819
|
+
hasCustomFile: await FileSystemUtils.fileExists(
|
|
4820
|
+
path9.join(path9.resolve(projectPath), HERASPEC_MARKERS.AGENTS_CUSTOM_MD)
|
|
4821
|
+
),
|
|
4822
|
+
skipAdapters: true,
|
|
4823
|
+
skillNames: [installedName],
|
|
4824
|
+
force: true,
|
|
4825
|
+
recordedMirrors: existingState?.mirroredSkills
|
|
4826
|
+
});
|
|
4827
|
+
if (existingState) {
|
|
4828
|
+
await writeHeraspecState(heraspecDir, {
|
|
4829
|
+
...existingState,
|
|
4830
|
+
updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
|
|
4831
|
+
mirroredSkills: ideSync.updatedMirrors
|
|
4832
|
+
});
|
|
4833
|
+
}
|
|
3334
4834
|
const successMessage = isUpdate ? `Skill "${skillName}" updated successfully` : `Skill "${skillName}" added successfully`;
|
|
3335
4835
|
spinner.succeed(successMessage);
|
|
3336
4836
|
console.log(`
|
|
3337
4837
|
\u{1F4CD} Location: ${destPath}`);
|
|
4838
|
+
for (const report of ideSync.reports) {
|
|
4839
|
+
if (report.status === "created" || report.status === "updated") {
|
|
4840
|
+
console.log(chalk2.cyan(` \u2713 Mirrored to IDE skill root: ${report.relativePath}`));
|
|
4841
|
+
}
|
|
4842
|
+
}
|
|
3338
4843
|
if (isUpdate) {
|
|
3339
4844
|
console.log(`
|
|
3340
4845
|
\u2728 Skill has been updated with latest features and improvements.`);
|
|
@@ -3363,649 +4868,294 @@ var ProjectTypeSchema = z.enum([
|
|
|
3363
4868
|
"wordpress-plugin",
|
|
3364
4869
|
"wordpress-theme",
|
|
3365
4870
|
"perfex-module",
|
|
3366
|
-
"laravel-package",
|
|
3367
|
-
"node-service",
|
|
3368
|
-
"generic-webapp",
|
|
3369
|
-
"backend-api",
|
|
3370
|
-
"frontend-app",
|
|
3371
|
-
"multi-stack",
|
|
3372
|
-
"content-channel"
|
|
3373
|
-
]);
|
|
3374
|
-
var SpecMetaSchema = z.object({
|
|
3375
|
-
projectType: z.union([
|
|
3376
|
-
ProjectTypeSchema,
|
|
3377
|
-
z.array(ProjectTypeSchema)
|
|
3378
|
-
]).optional(),
|
|
3379
|
-
domain: z.string().optional(),
|
|
3380
|
-
stack: z.union([
|
|
3381
|
-
z.string(),
|
|
3382
|
-
z.array(z.string())
|
|
3383
|
-
]).optional()
|
|
3384
|
-
}).optional();
|
|
3385
|
-
var ScenarioSchema = z.object({
|
|
3386
|
-
name: z.string(),
|
|
3387
|
-
steps: z.array(z.string()).min(1)
|
|
3388
|
-
});
|
|
3389
|
-
var RequirementSchema = z.object({
|
|
3390
|
-
id: z.string().optional(),
|
|
3391
|
-
name: z.string(),
|
|
3392
|
-
description: z.string(),
|
|
3393
|
-
scenarios: z.array(ScenarioSchema).optional(),
|
|
3394
|
-
constraints: z.array(z.string()).optional()
|
|
3395
|
-
});
|
|
3396
|
-
|
|
3397
|
-
// src/core/schemas/spec.schema.ts
|
|
3398
|
-
import { z as z2 } from "zod";
|
|
3399
|
-
var SpecSchema = z2.object({
|
|
3400
|
-
name: z2.string().min(1),
|
|
3401
|
-
meta: SpecMetaSchema,
|
|
3402
|
-
overview: z2.string().min(1),
|
|
3403
|
-
requirements: z2.array(RequirementSchema).min(1),
|
|
3404
|
-
metadata: z2.object({
|
|
3405
|
-
version: z2.string().default("1.0.0"),
|
|
3406
|
-
format: z2.literal("heraspec"),
|
|
3407
|
-
sourcePath: z2.string().optional()
|
|
3408
|
-
}).optional()
|
|
3409
|
-
});
|
|
3410
|
-
|
|
3411
|
-
// src/core/schemas/change.schema.ts
|
|
3412
|
-
import { z as z3 } from "zod";
|
|
3413
|
-
var DeltaTypeSchema = z3.enum(["ADDED", "MODIFIED", "REMOVED"]);
|
|
3414
|
-
var DeltaRequirementSchema = z3.object({
|
|
3415
|
-
type: DeltaTypeSchema,
|
|
3416
|
-
requirement: z3.object({
|
|
3417
|
-
id: z3.string().optional(),
|
|
3418
|
-
name: z3.string(),
|
|
3419
|
-
description: z3.string(),
|
|
3420
|
-
scenarios: z3.array(z3.object({
|
|
3421
|
-
name: z3.string(),
|
|
3422
|
-
steps: z3.array(z3.string())
|
|
3423
|
-
})).optional(),
|
|
3424
|
-
constraints: z3.array(z3.string()).optional()
|
|
3425
|
-
})
|
|
3426
|
-
});
|
|
3427
|
-
var ChangeSchema = z3.object({
|
|
3428
|
-
name: z3.string(),
|
|
3429
|
-
proposal: z3.string().min(1),
|
|
3430
|
-
tasks: z3.array(z3.string()).optional(),
|
|
3431
|
-
design: z3.string().optional()
|
|
3432
|
-
});
|
|
3433
|
-
|
|
3434
|
-
// src/core/init.ts
|
|
3435
|
-
init_file_system();
|
|
3436
|
-
import ora3 from "ora";
|
|
3437
|
-
import chalk2 from "chalk";
|
|
3438
|
-
import path8 from "path";
|
|
3439
|
-
|
|
3440
|
-
// src/core/templates/index.ts
|
|
3441
|
-
var TemplateManager = class {
|
|
3442
|
-
static getProjectTemplate() {
|
|
3443
|
-
return `# HeraSpec Project
|
|
3444
|
-
|
|
3445
|
-
## \u26A1 Slash Commands (Agent Triggers)
|
|
3446
|
-
|
|
3447
|
-
When the user types messages starting with a slash (/), you MUST intercept them as action triggers rather than conversational queries. Please execute the corresponding terminal commands immediately:
|
|
3448
|
-
|
|
3449
|
-
- /heraspec [args] : Run the heraspec CLI tool with the provided arguments (e.g. /heraspec validate my-change)
|
|
3450
|
-
- /sync : Run heraspec sync <current-change>
|
|
3451
|
-
- /archive : Run heraspec archive <current-change> --yes
|
|
3452
|
-
- /skill [name] : Run heraspec skill add [name]
|
|
3453
|
-
- /hotfix [title] : Run heraspec hotfix [title]
|
|
3454
|
-
|
|
3455
|
-
*If the user types a slash command, do not explain what you are going to do, just run the terminal command and report the output.*
|
|
3456
|
-
|
|
3457
|
-
## Overview
|
|
3458
|
-
Describe your project here.
|
|
3459
|
-
|
|
3460
|
-
## Project Types
|
|
3461
|
-
- List your project type(s) here (e.g., content-channel, node-service, wordpress-plugin, wordpress-theme, perfex-module, laravel-package, generic-webapp, backend-api, frontend-app, multi-stack)
|
|
3462
|
-
|
|
3463
|
-
## Tech Stack
|
|
3464
|
-
- List primary languages, frameworks, runtime, and key libraries
|
|
3465
|
-
|
|
3466
|
-
## Architecture
|
|
3467
|
-
Describe the high-level architecture: entry points, module structure, data flow.
|
|
3468
|
-
|
|
3469
|
-
## Key Dependencies
|
|
3470
|
-
List critical dependencies and their purposes (e.g., better-sqlite3 for memory, commander for CLI).
|
|
3471
|
-
|
|
3472
|
-
## Conventions
|
|
3473
|
-
Define coding standards, architectural patterns, and conventions to follow.
|
|
3474
|
-
`;
|
|
3475
|
-
}
|
|
3476
|
-
static getAgentsTemplate() {
|
|
3477
|
-
return `# HeraSpec \u2014 AI Agent Instructions
|
|
3478
|
-
|
|
3479
|
-
This document defines the workflow for AI agents working with HeraSpec.
|
|
3480
|
-
|
|
3481
|
-
## Universal Safety Rules
|
|
3482
|
-
|
|
3483
|
-
- **NO AUTO-COMMIT**: Agent MUST NOT perform \`git commit\` or \`git push\` autonomously. This task is reserved for the User unless explicitly ordered.
|
|
3484
|
-
- **NO AUTO-PUBLISH**: Agent MUST NOT perform \`npm publish\` or trigger automated releases/deployments autonomously.
|
|
3485
|
-
- **SKILL PREREQUISITE**: If a task maps to a skill (e.g., "Generate documentation"), you **MUST** verify the skill folder exists in \`heraspec/skills/\`. If missing:
|
|
3486
|
-
- **Preferred**: Proactively install it via \`heraspec skill add <name>\` (e.g., \`heraspec skill add documents\`) if you have terminal access.
|
|
3487
|
-
- **Fallback**: If you cannot install it, **STOP** and ask the user to add it. **DO NOT** attempt manual generation without the skill.
|
|
3488
|
-
- **IGNORE VIETNAMESE SKILL FILES**: When reading and executing skill workflows, you **MUST ONLY** look at the English version of the skill instructions (e.g., \`skill.md\`). You **MUST completely ignore** all Vietnamese versions (e.g., \`skill.vi.md\` or files ending with \`*.vi.md\`). These Vietnamese files are for reference/development purposes by the user only.
|
|
3489
|
-
- **USER CONFIRMATION**: For destructive actions or public releases, always request explicit User approval first.
|
|
3490
|
-
|
|
3491
|
-
### Restricted Commands (REQUIRE USER CONFIRMATION)
|
|
3492
|
-
|
|
3493
|
-
The following commands are classified by risk level. You **MUST NOT** execute them without explicit user confirmation/approval in the chat, especially if they are outside the source workspace or involve deletion.
|
|
3494
|
-
|
|
3495
|
-
#### GROUP 1 \u2013 EXTREMELY DANGEROUS (DATA DESTRUCTION, HARD / IMPOSSIBLE TO RECOVER)
|
|
3496
|
-
- \`rm -rf\` : Recursive delete + no prompt, can wipe entire system
|
|
3497
|
-
- \`rm -r\` : Delete directory and all contents
|
|
3498
|
-
- \`rm\` : Delete file directly, bypassing trash
|
|
3499
|
-
- \`unlink\` : Delete file at filesystem level, cannot undo
|
|
3500
|
-
- \`shred\` : Overwrite data multiple times to make it unrecoverable
|
|
3501
|
-
- \`wipe\` : Permanently wipe data on disk
|
|
3502
|
-
- \`dd\` : Write/copy raw blocks, easily destroy disk or partition
|
|
3503
|
-
- \`mkfs\`, \`mkfs.ext4\`, \`mkfs.xfs\` : Create new filesystem, wiping old data
|
|
3504
|
-
- \`format\`, \`Format-Volume\` : Format drive/volume
|
|
3505
|
-
|
|
3506
|
-
#### GROUP 2 \u2013 HIGH DANGER (DELETE DIRECTORY / MULTIPLE FILES)
|
|
3507
|
-
- \`rmdir\` : Delete directory
|
|
3508
|
-
- \`rd\`, \`rmdir /s\` : Windows delete directory
|
|
3509
|
-
- \`Remove-Item -Recurse\`, \`Remove-Item\` : PowerShell delete
|
|
3510
|
-
- \`del /s\`, \`erase /s\` : CMD batch delete
|
|
3511
|
-
|
|
3512
|
-
#### GROUP 3 \u2013 MEDIUM DANGER (DELETE FILE / OVERWRITE)
|
|
3513
|
-
- \`del\`, \`erase\` : Delete file
|
|
3514
|
-
- \`Clear-Content\` : Clear file content
|
|
3515
|
-
- \`cp --remove-destination\` : Overwrite destination by deleting first
|
|
3516
|
-
|
|
3517
|
-
#### GROUP 4 \u2013 INDIRECT DANGER (DATA LOSS)
|
|
3518
|
-
- \`mv\` : Move / overwrite file, old data lost
|
|
3519
|
-
- \`rsync --delete\` : Delete file at destination if not in source
|
|
3520
|
-
- \`install\` : Overwrite system files
|
|
3521
|
-
|
|
3522
|
-
#### GROUP 5 \u2013 DISK / PARTITION MANAGEMENT
|
|
3523
|
-
- \`fdisk\`, \`cfdisk\`, \`parted\`, \`diskpart\` : Partition management
|
|
3524
|
-
- \`mount\`, \`umount\` : Filesystem mounting
|
|
3525
|
-
|
|
3526
|
-
#### GROUP 6 \u2013 LESS DANGEROUS (POTENTIAL CONSEQUENCES)
|
|
3527
|
-
- \`truncate\` : Cutt off file content
|
|
3528
|
-
- \`chown\`, \`chmod\` : Change ownership/permissions
|
|
3529
|
-
- \`attrib\` : Change attributes
|
|
3530
|
-
|
|
3531
|
-
## Core Workflow
|
|
3532
|
-
|
|
3533
|
-
### Step 1 \u2014 Create a Change
|
|
3534
|
-
|
|
3535
|
-
**When creating changes, ALWAYS read heraspec/project.md first to understand:**
|
|
3536
|
-
- Project types being used
|
|
3537
|
-
- Tech stack and conventions
|
|
3538
|
-
- Existing architecture patterns
|
|
3539
|
-
- Coding standards
|
|
3540
|
-
|
|
3541
|
-
> **IGNORE backup files**: Files like \`project.back1.md\`, \`project.back2.md\`, etc. are automatic backups created during \`heraspec init\` updates. NEVER read or reference them unless explicitly asked by the user. Only \`project.md\` is the source of truth.
|
|
3542
|
-
|
|
3543
|
-
**Then scaffold:**
|
|
3544
|
-
- \`heraspec/changes/<slug>/\` - Create proposal.md, tasks.md, design.md (optional)
|
|
3545
|
-
- \`heraspec/specs/<slug>/\` - Create delta specs here (NOT inside changes folder)
|
|
3546
|
-
|
|
3547
|
-
**If user asks to create changes based on project.md:**
|
|
3548
|
-
1. Read \`heraspec/project.md\` thoroughly
|
|
3549
|
-
2. Identify all features/capabilities mentioned
|
|
3550
|
-
3. Create separate changes for each major feature
|
|
3551
|
-
4. Ensure each change follows project.md conventions
|
|
3552
|
-
5. Use correct project types and skills from project.md
|
|
3553
|
-
|
|
3554
|
-
### Step 2 \u2014 Refine Specs
|
|
3555
|
-
- Update delta specs in \`heraspec/specs/<slug>/\`
|
|
3556
|
-
- Never modify source-of-truth specs directly
|
|
3557
|
-
|
|
3558
|
-
### Step 3 \u2014 Approval
|
|
3559
|
-
- Wait for user: "Specs approved."
|
|
3560
|
-
|
|
3561
|
-
### Step 4 \u2014 Implementation
|
|
3562
|
-
|
|
3563
|
-
**CRITICAL: When implementing tasks, ALWAYS use Skills system:**
|
|
3564
|
-
|
|
3565
|
-
1. **Read task line** to identify skill:
|
|
3566
|
-
\`\`\`markdown
|
|
3567
|
-
## 1. Perfex module \u2013 Category Management (projectType: perfex-module, skill: module-codebase)
|
|
3568
|
-
- [ ] 1.1 Create module structure
|
|
3569
|
-
\`\`\`
|
|
3570
|
-
|
|
3571
|
-
2. **Find skill folder**:
|
|
3572
|
-
- Project-specific: \`heraspec/skills/<project-type>/<skill-name>/\`
|
|
3573
|
-
- Cross-cutting: \`heraspec/skills/<skill-name>/\`
|
|
3574
|
-
|
|
3575
|
-
3. **Read skill.md**:
|
|
3576
|
-
- Understand purpose, steps, inputs, outputs
|
|
3577
|
-
- Follow tone, rules, and limitations
|
|
3578
|
-
- Check available templates and scripts
|
|
3579
|
-
- **Ignore Vietnamese Skill Files**: Only read the English \`skill.md\` instructions. Completely ignore any \`*.vi.md\` translation files.
|
|
3580
|
-
|
|
3581
|
-
4. **Use skill resources**:
|
|
3582
|
-
- Run scripts from \`scripts/\` folder if needed
|
|
3583
|
-
- Use templates from \`templates/\` folder
|
|
3584
|
-
- Reference examples from \`examples/\` folder
|
|
3585
|
-
|
|
3586
|
-
5. **Implement following skill.md guidance**:
|
|
3587
|
-
- Follow step-by-step process
|
|
3588
|
-
- Use correct naming conventions
|
|
3589
|
-
- Apply code style rules
|
|
3590
|
-
- Respect limitations
|
|
3591
|
-
|
|
3592
|
-
**Example workflow:**
|
|
3593
|
-
- Task: \`(projectType: perfex-module, skill: module-codebase)\`
|
|
3594
|
-
- Agent reads: \`heraspec/skills/perfex-module/module-codebase/skill.md\`
|
|
3595
|
-
- Agent follows: Steps, uses templates, runs scripts
|
|
3596
|
-
- Agent implements: According to skill.md guidelines
|
|
3597
|
-
|
|
3598
|
-
**Special case - UI/UX skill:**
|
|
3599
|
-
- Task: \`(skill: ui-ux)\`
|
|
3600
|
-
- Agent reads: \`heraspec/skills/ui-ux/skill.md\`
|
|
3601
|
-
- Agent MUST use search scripts before implementing:
|
|
3602
|
-
\`\`\`bash
|
|
3603
|
-
# Search for design intelligence
|
|
3604
|
-
python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --domain <domain>
|
|
3605
|
-
python3 heraspec/skills/ui-ux/scripts/search.py "<keyword>" --stack <stack>
|
|
3606
|
-
\`\`\`
|
|
3607
|
-
- Agent synthesizes search results
|
|
3608
|
-
- Agent implements with proper colors, fonts, styles from search results
|
|
3609
|
-
- Agent verifies with pre-delivery checklist
|
|
3610
|
-
|
|
3611
|
-
**Special case - Flatsome UX Element skill:**
|
|
3612
|
-
- Task: \`(projectType: wordpress, skill: ux-element)\`
|
|
3613
|
-
- Agent reads: \`heraspec/skills/wordpress/ux-element/skill.md\`
|
|
3614
|
-
- Agent MUST follow the **Wrapping Rule**: Use \`<span>\` with \`id="{{:: shortcode.$id }}"\`
|
|
3615
|
-
- Agent uses templates from \`heraspec/skills/wordpress/ux-element/templates/\` (Controller, Shortcode, HTML Template, SVG Thumbnail)
|
|
3616
|
-
- Agent ensures real-time preview support in AngularJS template.
|
|
3617
|
-
- **Variable Translation**: Variables with underscores in PHP (e.g., \`bg_color\`) MUST be accessed via camelCase in AngularJS (e.g., \`shortcode.options.bgColor\`).
|
|
3618
|
-
|
|
3619
|
-
**Special case - Plugin Check skill:**
|
|
3620
|
-
- Task: \`(projectType: wordpress-plugin, skill: plugin-check)\`
|
|
3621
|
-
- Install: \`heraspec skill add plugin-check --project-type wordpress-plugin\`
|
|
3622
|
-
- Agent reads: \`heraspec/skills/wordpress-plugin/plugin-check/skill.md\`
|
|
3623
|
-
- Agent runs WordPress Plugin Check (PCP) tool
|
|
3624
|
-
- Agent fixes coding standard issues iteratively until all pass
|
|
3625
|
-
|
|
3626
|
-
**Special case - Plugin Directory skill:**
|
|
3627
|
-
- Task: \`(projectType: wordpress-plugin, skill: plugin-directory)\`
|
|
3628
|
-
- Install: \`heraspec skill add plugin-directory --project-type wordpress-plugin\`
|
|
3629
|
-
- Agent reads: \`heraspec/skills/wordpress-plugin/plugin-directory/skill.md\`
|
|
3630
|
-
- Agent MUST review plugin against **18 WordPress.org Directory Guidelines**:
|
|
3631
|
-
1. GPL Compatibility
|
|
3632
|
-
2. Developer Responsibility
|
|
3633
|
-
3. Stable Version Availability
|
|
3634
|
-
4. Human Readable Code
|
|
3635
|
-
5. No Trialware
|
|
3636
|
-
6. Software as a Service
|
|
3637
|
-
7. User Tracking Consent
|
|
3638
|
-
8. No External Executable Code
|
|
3639
|
-
9. Legal and Ethical Conduct
|
|
3640
|
-
10. External Links and Credits
|
|
3641
|
-
11. Admin Dashboard Experience
|
|
3642
|
-
12. No Spam in Public Pages
|
|
3643
|
-
13. WordPress Default Libraries
|
|
3644
|
-
14. Commit Frequency
|
|
3645
|
-
15. Version Number Increment
|
|
3646
|
-
16. Complete Plugin Required
|
|
3647
|
-
17. Trademark and Copyright
|
|
3648
|
-
18. Directory Maintenance Rights
|
|
3649
|
-
- Agent generates a **Compliance Report** with:
|
|
3650
|
-
- \u2705 Passed items
|
|
3651
|
-
- \u26A0\uFE0F Items needing review
|
|
3652
|
-
- \u274C Violations with file paths and line numbers
|
|
3653
|
-
- **CRITICAL**: Agent MUST present full report and **wait for user confirmation** before making changes
|
|
3654
|
-
- Reference guideline numbers (e.g., "Guideline 7: User Tracking Consent")
|
|
3655
|
-
|
|
3656
|
-
**Special case - Perfex Module Engineering skills:**
|
|
3657
|
-
- Tasks: \`(projectType: perfex-module, skill: module-codebase)\` or \`(projectType: perfex-module, skill: code-quality-guidelines)\` or \`(skill: perfex-module)\`
|
|
3658
|
-
- Install: \`heraspec skill add perfex-module\` or \`heraspec skill add module-codebase --project-type perfex-module\` or \`heraspec skill add code-quality-guidelines --project-type perfex-module\`
|
|
3659
|
-
- Agent reads: \`heraspec/skills/perfex-module/skill.md\`, \`heraspec/skills/perfex-module/module-codebase/skill.md\`, and \`heraspec/skills/perfex-module/code-quality-guidelines/skill.md\`
|
|
3660
|
-
- Agent MUST adhere to **10 Enterprise Code Quality & Clean Code Standards**:
|
|
3661
|
-
1. **Separation of Concerns (Zero Inline Code)**: 0 inline <script> or <style> blocks in views and documentation HTML.
|
|
3662
|
-
2. **Static Analysis Neutrality**: 0 occurrences of high-risk scanner triggers (inject, seeder, bypass, eval, unserialize).
|
|
3663
|
-
3. **Safe Stylesheet Loading**: Use editor.dom.loadCSS() for TinyMCE/iframes; never inject raw CSS string arrays.
|
|
3664
|
-
4. **Scoped Admin JS**: Enclose scripts in window.addEventListener('load') + strict IIFE.
|
|
3665
|
-
5. **Concurrency & Performance**: Always call session_write_close() at the start of read/search AJAX endpoints.
|
|
3666
|
-
6. **Clean Release Packaging**: Exclude package.json, webpack.config.js, tests/, scratch/, .git in deploy.ps1.
|
|
3667
|
-
7. **Defensive PHP Security & Guards**: 100% PHP files start with defined('BASEPATH') or exit('No direct script access allowed');. Use CI Query Builder with auto-escaping.
|
|
3668
|
-
8. **DOM XSS Prevention (CWE-79)**: Use .textContent, .innerText, or strict HTML escaping helper; purify rich text.
|
|
3669
|
-
9. **100% Multilingual Parity**: 100% labels and messages use _l('key') with zero missing keys across languages.
|
|
3670
|
-
10. **Zero Emojis**: 0 Unicode emojis across custom code, comments, views, documentation, and UI.
|
|
3671
|
-
- Use templates from \`heraspec/skills/perfex-module/module-codebase/templates/\` (module-main.php, install.php, uninstall.php, controller-admin.php, controller-api.php, model-main.php, helper.php, deploy.ps1, webpack.config.js).
|
|
3672
|
-
|
|
3673
|
-
**Special case - Content & Channel Development skills (projectType: content-channel):**
|
|
3674
|
-
- Tasks: \`(projectType: content-channel, skill: content-strategy)\`, \`(skill: content-scaffolding)\`, \`(skill: content-scripting)\`, \`(skill: content-voice-adapter)\`, \`(skill: content-prompts)\`, \`(skill: content-compliance)\`, \`(skill: content-vault-sync)\`, or \`(skill: content-channel)\`
|
|
3675
|
-
- Install: \`heraspec skill add content-channel\` or \`heraspec skill add <skill-name> --project-type content-channel\`
|
|
3676
|
-
- Agent reads corresponding skill instructions in \`heraspec/skills/<skill-name>/skill.md\` or \`heraspec/skills/content-channel/<skill-name>/skill.md\`.
|
|
3677
|
-
- Agent MUST adhere to **7 Core Content Production Standards**:
|
|
3678
|
-
1. **Golden Naming Rule**: ZERO \`[K\xEAnh]\`, \`[Channel]\`, or \`K\xEAnh:\` prefixes in channel/folder names. 100% pure brand names only.
|
|
3679
|
-
2. **MTxStudio 2-Level Tree Hierarchy**: Every channel must map to standard categories: \`_plan\` (\`type: "docs"\`), \`_posts\` (\`type: "article"\`), \`_prompts\` (\`type: "prompts"\`), \`_music\` (\`type: "music"\`), and optional \`_affiliate\` (\`type: "docs"\`).
|
|
3680
|
-
3. **Strict TTS Acoustic Rules (Natural Flow)**:
|
|
3681
|
-
- Short sentences: 12 - 20 words max per sentence (never exceed 25 words or 120 chars).
|
|
3682
|
-
- Comma clauses: 8 - 12 words max.
|
|
3683
|
-
- Repetition Bug Prevention: Never place 2 reduplicative words (t\u1EEB l\xE1y) adjacently; always separate with a natural comma \`,\`.
|
|
3684
|
-
- Clean text: Zero artificial bracket tags; rely entirely on natural punctuation (\`.\`, \`,\`, \`...\`, \`!\`) and sentence rhythm for voice pacing.
|
|
3685
|
-
4. **Strict Poetry & Verse Formatting**: Never use \`join(' ')\` or combine verses into a single line. EVERY verse line MUST preserve its \`\\n\` newline.
|
|
3686
|
-
5. **Mandatory 3-Position Disclaimer (Decree 15/2020/ND-CP)**: For horror, health, psychological healing, and finance niches, disclaimers are mandatory at: (1) Intro Warning Card 0:00-0:04, (2) Caption Footer / Pinned Comment, (3) Spoken Narration.
|
|
3687
|
-
6. **Safe Vault Sync (Zero SQLite Tampering)**: NEVER write directly to \`mtxstudio.db\`. All channel exports must go through \`Facebook/export_vault_json.py\` to generate sanitized JSON bundles (\`mtxstudio_vault_import.json\`, \`all_channels_bundle.json\`) with UTF-8 encoding and zero en-dash/em-dash characters.
|
|
3688
|
-
7. **Channel Voice Adaptation (Transmutation)**: When repurposing raw texts, always use \`content-voice-adapter\` to de-bias off-brand elements and reframe the message through the designated channel's core philosophy and natural voice style.
|
|
3689
|
-
|
|
3690
|
-
- Follow tasks.md
|
|
3691
|
-
- Mark tasks completed: \`- [x]\`
|
|
3692
|
-
|
|
3693
|
-
### Step 5 \u2014 Archive
|
|
3694
|
-
- Run: \`heraspec archive <slug> --yes\`
|
|
3695
|
-
- This merges delta specs into source specs
|
|
3696
|
-
- Moves change folder to archives
|
|
3697
|
-
|
|
3698
|
-
#### Handling Parallel Merge Conflicts
|
|
3699
|
-
If \`heraspec archive\` throws a **Parallel Merge Conflict** error:
|
|
3700
|
-
1. It means someone else modified the base requirement in the source spec while you were working.
|
|
3701
|
-
2. **DO NOT PANIC** and **DO NOT OVERWRITE** manually.
|
|
3702
|
-
3. Run: \`heraspec sync <slug>\`
|
|
3703
|
-
4. The system will automatically update your fingerprint to match the new source spec and warn you.
|
|
3704
|
-
5. Review your delta spec again. Make sure your \`MODIFIED/REMOVED\` requirements still make sense given the new source.
|
|
3705
|
-
6. Once verified, run \`heraspec archive <slug> --yes\` again.
|
|
3706
|
-
|
|
3707
|
-
## Spec Format
|
|
3708
|
-
|
|
3709
|
-
Specs must include:
|
|
3710
|
-
- \`## Meta\` section with project type, domain, stack
|
|
3711
|
-
- \`## Purpose\`
|
|
3712
|
-
- \`## Requirements\` with scenarios
|
|
3713
|
-
|
|
3714
|
-
## Delta Spec Format
|
|
3715
|
-
|
|
3716
|
-
Delta specs use:
|
|
3717
|
-
- \`## ADDED Requirements\`
|
|
3718
|
-
- \`## MODIFIED Requirements\`
|
|
3719
|
-
- \`## REMOVED Requirements\`
|
|
3720
|
-
|
|
3721
|
-
## Tasks Format
|
|
3722
|
-
|
|
3723
|
-
Tasks grouped by project type and skill:
|
|
3724
|
-
\`\`\`
|
|
3725
|
-
## 1. WordPress plugin \u2013 admin settings page (projectType: wordpress-plugin, skill: admin-settings-page)
|
|
3726
|
-
- [ ] Task description
|
|
3727
|
-
\`\`\`
|
|
3728
|
-
|
|
3729
|
-
## Skills System
|
|
3730
|
-
|
|
3731
|
-
**CRITICAL: Mandatory Prerequisite Check**
|
|
3732
|
-
|
|
3733
|
-
1. **Stop & Verify**: If you are asked to implement a task requiring a skill (e.g., "Generate documentation...", "Create UI/UX...", etc.), you MUST first check if the skill folder exists in \`heraspec/skills/\`.
|
|
3734
|
-
2. **Missing Skill = AUTO-INSTALL OR STOP**: If the skill folder does NOT exist:
|
|
3735
|
-
- **Option A (Preferred)**: If you can run commands, execute \`heraspec skill add <skill-name>\` immediately.
|
|
3736
|
-
- **Option B (Fallback)**: If you cannot run commands, **STOP** and ask the user to run it.
|
|
3737
|
-
> "Tip: Add the 'documents' skill for premium HTML & Landing Page support:
|
|
3738
|
-
> heraspec skill add documents"
|
|
3739
|
-
- **DO NOT** create a task plan or attempt manual generation without the skill language.
|
|
3740
|
-
3. **Execute After Install**: Only after the skill folder is created (or installed), read the \`skill.md\` and proceed with the task.
|
|
3741
|
-
4. **Ignore Vietnamese Skill Files**: You MUST only read the English \`skill.md\` file inside the skill folder. Completely ignore all \`*.vi.md\` files (e.g., \`skill.vi.md\`), as they are strictly for reference purposes by human developers.
|
|
3742
|
-
|
|
3743
|
-
**Example prompt for Documents skill:**
|
|
3744
|
-
If you need to generate multi-format documentation, use this prompt:
|
|
3745
|
-
> "Generate documentation with skill documents for [project-name]. Include:
|
|
3746
|
-
> - Concise overview (documentations/documentation.txt)
|
|
3747
|
-
> - Technical Markdown (documentations/documentation.md)
|
|
3748
|
-
> - Interactive HTML (documentations/documentation.html)
|
|
3749
|
-
> - Premium Documentation Landing Page (documentations/documentation-landing-page.html)
|
|
3750
|
-
> - CRITICAL: Save all files in the /documentations directory (create it if missing)."
|
|
3751
|
-
|
|
3752
|
-
**Example prompts for Content Channel Development (content-channel skills):**
|
|
3753
|
-
- **Channel Strategy (\`content-strategy\`)**:
|
|
3754
|
-
> "S\u1EED d\u1EE5ng skill content-strategy \u0111\u1EC3 l\u1EADp B\u1EA3n K\u1EBF Ho\u1EA1ch 30 Ng\xE0y (plan.md) cho k\xEAnh m\u1EDBi:
|
|
3755
|
-
> - T\xEAn k\xEAnh: [T\xEAn thu\u1EA7n t\xFAy, v\xED d\u1EE5: G\xF3c An Tr\xFA]
|
|
3756
|
-
> - Ng\xE1ch: [V\xED d\u1EE5: Thi\u1EC1n \u0111\u1ECBnh & L\u1ED1i s\u1ED1ng t\u1ED1i gi\u1EA3n]
|
|
3757
|
-
> - Kh\xE1n gi\u1EA3 m\u1EE5c ti\xEAu: [V\xED d\u1EE5: 25 - 40 tu\u1ED5i, nh\xE2n vi\xEAn v\u0103n ph\xF2ng stress]
|
|
3758
|
-
> - Y\xEAu c\u1EA7u: X\xE2y d\u1EF1ng 5 tr\u1EE5 c\u1ED9t n\u1ED9i dung, l\u1ED9 tr\xECnh Cold Start 14 ng\xE0y (70% Reels / 30% In-stream), khung gi\u1EDD v\xE0ng v\xE0 b\u1EA3ng ph\xE2n b\u1ED5 30 b\xE0i vi\u1EBFt chi ti\u1EBFt."
|
|
3759
|
-
|
|
3760
|
-
- **Channel Scaffolding (\`content-scaffolding\`)**:
|
|
3761
|
-
> "S\u1EED d\u1EE5ng skill content-scaffolding \u0111\u1EC3 kh\u1EDFi t\u1EA1o c\u1EA5u tr\xFAc th\u01B0 m\u1EE5c k\xEAnh m\u1EDBi:
|
|
3762
|
-
> - T\xEAn k\xEAnh: [V\xED d\u1EE5: Th\xE2n An T\xE2m L\u1EA1c] | Folder: [Than-An-Tam-Lac]
|
|
3763
|
-
> - Slogan: [V\xED d\u1EE5: Th\xE2n c\xF3 an, t\xE2m m\u1EDBi l\u1EA1c] | Icon Lucide: [Heart] | M\xE0u: [#10b981]
|
|
3764
|
-
> - Y\xEAu c\u1EA7u: Tu\xE2n th\u1EE7 quy t\u1EAFc c\u1EA5m ti\u1EC1n t\u1ED1 [K\xEAnh], t\u1EA1o posts/README.md v\xE0 \u0111\u0103ng k\xFD v\xE0o CHANNELS_CONFIG trong export_vault_json.py."
|
|
3765
|
-
|
|
3766
|
-
- **Raw Text Transmutation (\`content-voice-adapter\`)**:
|
|
3767
|
-
> "S\u1EED d\u1EE5ng skill content-voice-adapter \u0111\u1EC3 chuy\u1EC3n th\u1EC3 \u0111o\u1EA1n v\u0103n b\u1EA3n th\xF4 d\u01B0\u1EDBi \u0111\xE2y th\xE0nh K\u1ECBch b\u1EA3n Video chu\u1EA9n cho k\xEAnh [T\xEAn K\xEAnh] (Th\u1EC3 lo\u1EA1i: [Ch\u1EEFa l\xE0nh / Truy\u1EC7n ma / D\u01B0\u1EE1ng sinh / Chi\xEAm nghi\u1EC7m...]):
|
|
3768
|
-
> [D\xC1N \u0110O\u1EA0N V\u0102N B\u1EA2N TH\xD4 V\xC0O \u0110\xC2Y]
|
|
3769
|
-
> Y\xEAu c\u1EA7u qua 4 b\u01B0\u1EDBc: (1) L\u1ECDc l\u1EC7ch tone theo ma tr\u1EADn th\u1EC3 lo\u1EA1i (ch\u1EEFa l\xE0nh: l\u1ECDc m\xEA t\xEDn/\u0111\u1ED5 l\u1ED7i; truy\u1EC7n ma: l\u1ECDc m\xE1u me/vi ph\u1EA1m N\u0110 15 t\xEAn ng\u01B0\u1EDDi th\u1EADt/c\u1EE3t nh\u1EA3; d\u01B0\u1EE1ng sinh: l\u1ECDc ph\u1EA3n khoa h\u1ECDc/th\u1EA7n th\xE1nh h\xF3a; chi\xEAm nghi\u1EC7m: l\u1ECDc than th\u1EDF n\u1EA1n nh\xE2n), (2) T\xE1i c\u1EA5u tr\xFAc theo DNA tri\u1EBFt l\xFD v\xE0 \u0111\u1EA1i t\u1EEB nh\xE2n x\u01B0ng c\u1EE7a k\xEAnh, (3) T\u1ED1i \u01B0u \xE2m h\u1ECDc TTS 12-20 t\u1EEB/c\xE2u s\u1EA1ch th\u1EBB ngo\u1EB7c vu\xF4ng, (4) \u0110\xF3ng g\xF3i 6 ph\u1EA7n chu\u1EA9n MTxStudio k\xE8m Storyboard prompt, Caption v\xE0 Disclaimer ph\xE1p l\xFD ph\xF9 h\u1EE3p th\u1EC3 lo\u1EA1i."
|
|
3770
|
-
|
|
3771
|
-
- **Scriptwriting from Scratch (\`content-scripting\`)**:
|
|
3772
|
-
> "S\u1EED d\u1EE5ng skill content-scripting \u0111\u1EC3 vi\u1EBFt K\u1ECBch b\u1EA3n T\u1EADp [S\u1ED1 t\u1EADp]: '[Ti\xEAu \u0111\u1EC1]' cho k\xEAnh [T\xEAn K\xEAnh]:
|
|
3773
|
-
> - Tr\u1EE5 c\u1ED9t: [T\xEAn tr\u1EE5 c\u1ED9t n\u1ED9i dung] | \u0110\u1ECBnh d\u1EA1ng: [Video In-stream 16:9 ho\u1EB7c Reels 9:16]
|
|
3774
|
-
> - Y\xEAu c\u1EA7u \xE2m h\u1ECDc TTS: C\xE2u ng\u1EAFn 12-20 t\u1EEB, ng\u1EAFt nh\u1ECBp d\u1EA5u ph\u1EA9y r\xF5 r\xE0ng, kh\xF4ng \u0111i\u1EC7p \xE2m t\u1EEB l\xE1y, TUY\u1EC6T \u0110\u1ED0I KH\xD4NG ch\xE8n th\u1EBB ngo\u1EB7c vu\xF4ng ([l\u1EA5y h\u01A1i], [th\u1EDF d\xE0i]), b\u1EA3o to\xE0n th\u01A1 ca m\u1ED7i c\xE2u 1 d\xF2ng (\\n), xu\u1EA5t \u0111\u1EA7y \u0111\u1EE7 6 ph\u1EA7n k\xE8m Storyboard v\xE0 Caption Facebook."
|
|
3775
|
-
|
|
3776
|
-
- **AI Visual & Suno BGM Prompts (\`content-prompts\`)**:
|
|
3777
|
-
> "S\u1EED d\u1EE5ng skill content-prompts \u0111\u1EC3 t\u1EA1o b\u1ED9 Prompt Visual v\xE0 \xC2m nh\u1EA1c cho k\xEAnh [T\xEAn K\xEAnh]:
|
|
3778
|
-
> - C\u1EA7n t\u1EA1o: Prompt Avatar 1:1, Cover 16:9, B\u1EA3ng 5 Prompts Storyboard b\xE0i vi\u1EBFt '[T\xEAn b\xE0i vi\u1EBFt]', v\xE0 Prompt Suno AI BGM kh\xF4ng l\u1EDDi."
|
|
3779
|
-
|
|
3780
|
-
- **Legal Compliance & Disclaimer (\`content-compliance\`)**:
|
|
3781
|
-
> "S\u1EED d\u1EE5ng skill content-compliance \u0111\u1EC3 ki\u1EC3m duy\u1EC7t k\u1ECBch b\u1EA3n v\xE0 sinh Disclaimer cho video thu\u1ED9c th\u1EC3 lo\u1EA1i [Truy\u1EC7n Ma / D\u01B0\u1EE1ng Sinh / T\xE2m L\xFD / T\xE0i Ch\xEDnh]:
|
|
3782
|
-
> - Cung c\u1EA5p Disclaimer chu\u1EA9n ph\xE1p l\xFD (Ngh\u1ECB \u0111\u1ECBnh 15/2020/N\u0110-CP) \u0111\u1EB7t \u1EDF ch\xE2n Caption.
|
|
3783
|
-
> - Cung c\u1EA5p Prompt m\xE0n h\xECnh c\u1EA3nh b\xE1o Intro Warning Card (0:00 - 0:04, t\u1EF7 l\u1EC7 16:9)."
|
|
3784
|
-
|
|
3785
|
-
- **Vault Synchronization (\`content-vault-sync\`)**:
|
|
3786
|
-
> "S\u1EED d\u1EE5ng skill content-vault-sync \u0111\u1EC3 \u0111\u1ED3ng b\u1ED9 d\u1EEF li\u1EC7u: Ki\u1EC3m tra t\xEDnh to\xE0n v\u1EB9n c\xE1c k\xEAnh trong Facebook/, ch\u1EA1y export_vault_json.py \u0111\u1EC3 t\xE1i xu\u1EA5t mtxstudio_vault_import.json v\xE0 all_channels_bundle.json, b\xE1o c\xE1o s\u1ED1 l\u01B0\u1EE3ng k\xEAnh, danh m\u1EE5c v\xE0 k\u1ECBch b\u1EA3n \u0111\xE3 \u0111\xF3ng g\xF3i th\xE0nh c\xF4ng."
|
|
3787
|
-
|
|
3788
|
-
**Dynamic Documentation Generation**:
|
|
3789
|
-
When generating documentation, do NOT simply fill a template. The Agent MUST:
|
|
3790
|
-
1. **Create** the \`/documentations\` directory if it does not exist.
|
|
3791
|
-
2. **Design** a custom layout and content structure suitable for the project type.
|
|
3792
|
-
3. **Synchronize** with the \`ui-ux\` skill for premium visual design (colors, typography, animations).
|
|
3793
|
-
4. **Scan All Specs**: If project-wide, read \`heraspec/project.md\` and all files in \`heraspec/specs/\` to synthesize the content.
|
|
3794
|
-
|
|
3795
|
-
### Skill Discovery & Usage
|
|
3796
|
-
|
|
3797
|
-
- List all skills: Check \`heraspec/skills/\` directory
|
|
3798
|
-
- Project-specific skills: \`heraspec/skills/<project-type>/\`
|
|
3799
|
-
- Cross-cutting skills: \`heraspec/skills/<skill-name>/\` (root level)
|
|
3800
|
-
- **Consistency**: Follow the step-by-step process in the skill's \`skill.md\`.
|
|
3801
|
-
|
|
3802
|
-
### When Change Has Multiple Skills
|
|
3803
|
-
|
|
3804
|
-
**Important**: Each task group uses ONE skill. When working on a task group, agent MUST use that skill's skill.md.
|
|
3805
|
-
|
|
3806
|
-
Example with multiple skills in one change:
|
|
3807
|
-
\`\`\`
|
|
3808
|
-
## 1. WordPress module \u2013 Feature (skill: admin-settings-page)
|
|
3809
|
-
- [ ] Task 1.1 Create module structure
|
|
3810
|
-
- [ ] Task 1.2 Configure registration
|
|
3811
|
-
|
|
3812
|
-
## 2. UI/UX \u2013 Admin Interface (skill: ui-ux)
|
|
3813
|
-
- [ ] Task 2.1 Design color palette
|
|
3814
|
-
- [ ] Task 2.2 Create component styles
|
|
3815
|
-
|
|
3816
|
-
## 3. Documents \u2013 User Guide (skill: documents)
|
|
3817
|
-
- [ ] Task 3.1 Write technical docs
|
|
3818
|
-
\`\`\`
|
|
3819
|
-
|
|
3820
|
-
**Key rule**: Switch skill.md when switching task groups!
|
|
3821
|
-
|
|
3822
|
-
## Proactive Memory-Aware Development
|
|
3823
|
-
|
|
3824
|
-
If \`heraspec/skills/project-memory/\` exists, the agent MUST proactively use memory to maintain project context. DO NOT wait for the user to prompt you to use memory.
|
|
3825
|
-
|
|
3826
|
-
### CRITICAL RULES FOR AUTOMATIC MEMORY USAGE
|
|
3827
|
-
1. **Always Check Context First**: At the beginning of a complex task or when encountering an unfamiliar codebase area, you MUST autonomously run \`heraspec memory context\` or \`heraspec memory search "keywords"\` BEFORE writing any code.
|
|
3828
|
-
2. **Auto-Log via Archive**: You DO NOT need to run \`heraspec memory log\` manually. Every time you successfully implement a feature and run \`heraspec archive <change-name>\`, the system will automatically read your proposal and log the memory observation under the hood. Just use \`heraspec archive\` as normal!
|
|
3829
|
-
3. **Session Summary**: (Optional) When wrapping up a large session, you can run \`heraspec memory summarize --request "..." --completed "..."\` to compress knowledge, though \`archive\` already auto-logs completed features.
|
|
3830
|
-
|
|
3831
|
-
### When to SKIP Memory
|
|
3832
|
-
- Simple bug fixes, typo corrections, formatting changes
|
|
3833
|
-
- Trivial tasks that take < 5 minutes
|
|
3834
|
-
- When doing what the agent's built-in context already covers
|
|
3835
|
-
|
|
3836
|
-
### Smart Code Exploration
|
|
3837
|
-
If \`heraspec/skills/smart-explore/\` exists, prefer token-efficient exploration:
|
|
3838
|
-
- \`heraspec explore outline <file>\` \u2192 View structure (~1K tokens vs ~12K full file)
|
|
3839
|
-
- \`heraspec explore search "<query>" <path>\` \u2192 Find symbols across codebase
|
|
3840
|
-
- \`heraspec explore unfold <file> <symbol>\` \u2192 Read just one function
|
|
3841
|
-
`;
|
|
3842
|
-
}
|
|
3843
|
-
static getSkillsSection() {
|
|
3844
|
-
return `## Skills System
|
|
3845
|
-
|
|
3846
|
-
**CRITICAL: Mandatory Prerequisite Check**
|
|
3847
|
-
|
|
3848
|
-
1. **Stop & Verify**: If you are asked to implement a task requiring a skill (e.g., "Generate documentation...", "Create UI/UX...", etc.), you MUST first check if the skill folder exists in \`heraspec/skills/\`.
|
|
3849
|
-
2. **Missing Skill = AUTO-INSTALL OR STOP**: If the skill folder does NOT exist:
|
|
3850
|
-
- **Option A (Preferred)**: If you can run commands, execute \`heraspec skill add <skill-name>\` immediately.
|
|
3851
|
-
- **Option B (Fallback)**: If you cannot run commands, **STOP** and ask the user to run it.
|
|
3852
|
-
> "Tip: Add the 'documents' skill for premium HTML & Landing Page support:
|
|
3853
|
-
> heraspec skill add documents"
|
|
3854
|
-
- **DO NOT** create a task plan or attempt manual generation without the skill language.
|
|
3855
|
-
3. **Execute After Install**: Only after the skill folder is created (or installed), read the \`skill.md\` and proceed with the task.
|
|
3856
|
-
4. **Ignore Vietnamese Skill Files**: You MUST only read the English \`skill.md\` file inside the skill folder. Completely ignore all \`*.vi.md\` files (e.g., \`skill.vi.md\`), as they are strictly for reference purposes by human developers.
|
|
3857
|
-
|
|
3858
|
-
**Example prompt for Documents skill:**
|
|
3859
|
-
If you need to generate multi-format documentation, use this prompt:
|
|
3860
|
-
> "Generate documentation with skill documents for [project-name]. Include:
|
|
3861
|
-
> - Concise overview (documentations/documentation.txt)
|
|
3862
|
-
> - Technical Markdown (documentations/documentation.md)
|
|
3863
|
-
> - Interactive HTML (documentations/documentation.html)
|
|
3864
|
-
> - Premium Documentation Landing Page (documentations/documentation-landing-page.html)
|
|
3865
|
-
> - CRITICAL: Save all files in the /documentations directory (create it if missing)."
|
|
3866
|
-
|
|
3867
|
-
**Dynamic Documentation Generation**:
|
|
3868
|
-
When generating documentation, do NOT simply fill a template. The Agent MUST:
|
|
3869
|
-
1. **Create** the \`/documentations\` directory if it does not exist.
|
|
3870
|
-
2. **Design** a custom layout and content structure suitable for the project type.
|
|
3871
|
-
3. **Synchronize** with the \`ui-ux\` skill for premium visual design (colors, typography, animations).
|
|
3872
|
-
4. **Scan All Specs**: If project-wide, read \`heraspec/project.md\` and all files in \`heraspec/specs/\` to synthesize the content.
|
|
3873
|
-
|
|
3874
|
-
### Skill Discovery & Usage
|
|
3875
|
-
|
|
3876
|
-
- List all skills: Check \`heraspec/skills/\` directory
|
|
3877
|
-
- Project-specific skills: \`heraspec/skills/<project-type>/\`
|
|
3878
|
-
- Cross-cutting skills: \`heraspec/skills/<skill-name>/\` (root level)
|
|
3879
|
-
- **Consistency**: Follow the step-by-step process in the skill's \`skill.md\`.
|
|
3880
|
-
|
|
3881
|
-
### When Change Has Multiple Skills
|
|
3882
|
-
|
|
3883
|
-
**Important**: Each task group uses ONE skill. When working on a task group, agent MUST use that skill's skill.md.
|
|
3884
|
-
|
|
3885
|
-
Example with multiple skills in one change:
|
|
3886
|
-
\`\`\`
|
|
3887
|
-
## 1. WordPress module \u2013 Feature (skill: admin-settings-page)
|
|
3888
|
-
- [ ] Task 1.1 Create module structure
|
|
3889
|
-
- [ ] Task 1.2 Configure registration
|
|
3890
|
-
|
|
3891
|
-
## 2. UI/UX \u2013 Admin Interface (skill: ui-ux)
|
|
3892
|
-
- [ ] Task 2.1 Design color palette
|
|
3893
|
-
- [ ] Task 2.2 Create component styles
|
|
4871
|
+
"laravel-package",
|
|
4872
|
+
"node-service",
|
|
4873
|
+
"generic-webapp",
|
|
4874
|
+
"backend-api",
|
|
4875
|
+
"frontend-app",
|
|
4876
|
+
"multi-stack",
|
|
4877
|
+
"content-channel"
|
|
4878
|
+
]);
|
|
4879
|
+
var SpecMetaSchema = z.object({
|
|
4880
|
+
projectType: z.union([
|
|
4881
|
+
ProjectTypeSchema,
|
|
4882
|
+
z.array(ProjectTypeSchema)
|
|
4883
|
+
]).optional(),
|
|
4884
|
+
domain: z.string().optional(),
|
|
4885
|
+
stack: z.union([
|
|
4886
|
+
z.string(),
|
|
4887
|
+
z.array(z.string())
|
|
4888
|
+
]).optional()
|
|
4889
|
+
}).optional();
|
|
4890
|
+
var ScenarioSchema = z.object({
|
|
4891
|
+
name: z.string(),
|
|
4892
|
+
steps: z.array(z.string()).min(1)
|
|
4893
|
+
});
|
|
4894
|
+
var RequirementSchema = z.object({
|
|
4895
|
+
id: z.string().optional(),
|
|
4896
|
+
name: z.string(),
|
|
4897
|
+
description: z.string(),
|
|
4898
|
+
scenarios: z.array(ScenarioSchema).optional(),
|
|
4899
|
+
constraints: z.array(z.string()).optional()
|
|
4900
|
+
});
|
|
3894
4901
|
|
|
3895
|
-
|
|
3896
|
-
|
|
3897
|
-
|
|
4902
|
+
// src/core/schemas/spec.schema.ts
|
|
4903
|
+
import { z as z2 } from "zod";
|
|
4904
|
+
var SpecSchema = z2.object({
|
|
4905
|
+
name: z2.string().min(1),
|
|
4906
|
+
meta: SpecMetaSchema,
|
|
4907
|
+
overview: z2.string().min(1),
|
|
4908
|
+
requirements: z2.array(RequirementSchema).min(1),
|
|
4909
|
+
metadata: z2.object({
|
|
4910
|
+
version: z2.string().default("1.0.0"),
|
|
4911
|
+
format: z2.literal("heraspec"),
|
|
4912
|
+
sourcePath: z2.string().optional()
|
|
4913
|
+
}).optional()
|
|
4914
|
+
});
|
|
3898
4915
|
|
|
3899
|
-
|
|
3900
|
-
|
|
3901
|
-
|
|
3902
|
-
|
|
3903
|
-
|
|
3904
|
-
|
|
3905
|
-
|
|
3906
|
-
|
|
3907
|
-
|
|
3908
|
-
|
|
3909
|
-
|
|
4916
|
+
// src/core/schemas/change.schema.ts
|
|
4917
|
+
import { z as z3 } from "zod";
|
|
4918
|
+
var DeltaTypeSchema = z3.enum(["ADDED", "MODIFIED", "REMOVED"]);
|
|
4919
|
+
var DeltaRequirementSchema = z3.object({
|
|
4920
|
+
type: DeltaTypeSchema,
|
|
4921
|
+
requirement: z3.object({
|
|
4922
|
+
id: z3.string().optional(),
|
|
4923
|
+
name: z3.string(),
|
|
4924
|
+
description: z3.string(),
|
|
4925
|
+
scenarios: z3.array(z3.object({
|
|
4926
|
+
name: z3.string(),
|
|
4927
|
+
steps: z3.array(z3.string())
|
|
4928
|
+
})).optional(),
|
|
4929
|
+
constraints: z3.array(z3.string()).optional()
|
|
4930
|
+
})
|
|
4931
|
+
});
|
|
4932
|
+
var ChangeSchema = z3.object({
|
|
4933
|
+
name: z3.string(),
|
|
4934
|
+
proposal: z3.string().min(1),
|
|
4935
|
+
tasks: z3.array(z3.string()).optional(),
|
|
4936
|
+
design: z3.string().optional()
|
|
4937
|
+
});
|
|
3910
4938
|
|
|
3911
4939
|
// src/core/init.ts
|
|
4940
|
+
init_file_system();
|
|
4941
|
+
init_templates();
|
|
3912
4942
|
init_config();
|
|
3913
4943
|
init_skills_template_map();
|
|
3914
4944
|
init_memory();
|
|
4945
|
+
init_ide_adapter();
|
|
4946
|
+
init_agents_composer();
|
|
4947
|
+
import ora3 from "ora";
|
|
4948
|
+
import chalk3 from "chalk";
|
|
4949
|
+
import path10 from "path";
|
|
3915
4950
|
import { fileURLToPath as fileURLToPath2 } from "url";
|
|
3916
4951
|
import { dirname as dirname2, join as join2 } from "path";
|
|
3917
4952
|
import { createRequire as createRequire2 } from "module";
|
|
3918
4953
|
var require3 = createRequire2(import.meta.url);
|
|
3919
4954
|
var __filename2 = fileURLToPath2(import.meta.url);
|
|
3920
4955
|
var __dirname2 = dirname2(__filename2);
|
|
4956
|
+
function getCliPackageVersion() {
|
|
4957
|
+
for (const rel of ["../package.json", "../../package.json"]) {
|
|
4958
|
+
try {
|
|
4959
|
+
const pkg = require3(rel);
|
|
4960
|
+
if (pkg?.version) return String(pkg.version);
|
|
4961
|
+
} catch {
|
|
4962
|
+
}
|
|
4963
|
+
}
|
|
4964
|
+
return "0.1.18";
|
|
4965
|
+
}
|
|
3921
4966
|
var InitCommand = class {
|
|
3922
|
-
async execute(targetPath = ".") {
|
|
3923
|
-
const resolvedPath =
|
|
3924
|
-
const heraspecPath =
|
|
4967
|
+
async execute(targetPath = ".", options = {}) {
|
|
4968
|
+
const resolvedPath = path10.resolve(targetPath);
|
|
4969
|
+
const heraspecPath = path10.join(resolvedPath, HERASPEC_DIR_NAME);
|
|
4970
|
+
const ideOption = options.ide || "auto";
|
|
3925
4971
|
const alreadyInitialized = await FileSystemUtils.fileExists(
|
|
3926
|
-
|
|
4972
|
+
path10.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD)
|
|
3927
4973
|
);
|
|
4974
|
+
if (options.dryRun) {
|
|
4975
|
+
await this.runDryRunPreview(resolvedPath, heraspecPath, alreadyInitialized, {
|
|
4976
|
+
...options,
|
|
4977
|
+
ide: ideOption
|
|
4978
|
+
});
|
|
4979
|
+
return;
|
|
4980
|
+
}
|
|
3928
4981
|
const spinner = ora3({
|
|
3929
4982
|
text: alreadyInitialized ? "Updating HeraSpec..." : "Initializing HeraSpec...",
|
|
3930
4983
|
color: "blue"
|
|
3931
4984
|
}).start();
|
|
3932
4985
|
try {
|
|
3933
4986
|
await FileSystemUtils.createDirectory(heraspecPath);
|
|
3934
|
-
await FileSystemUtils.createDirectory(
|
|
3935
|
-
await FileSystemUtils.createDirectory(
|
|
3936
|
-
await FileSystemUtils.createDirectory(
|
|
3937
|
-
await FileSystemUtils.createDirectory(
|
|
3938
|
-
await FileSystemUtils.createDirectory(
|
|
3939
|
-
const skillsReadmePath =
|
|
4987
|
+
await FileSystemUtils.createDirectory(path10.join(heraspecPath, SPECS_DIR_NAME));
|
|
4988
|
+
await FileSystemUtils.createDirectory(path10.join(heraspecPath, CHANGES_DIR_NAME));
|
|
4989
|
+
await FileSystemUtils.createDirectory(path10.join(heraspecPath, ARCHIVES_DIR_NAME));
|
|
4990
|
+
await FileSystemUtils.createDirectory(path10.join(heraspecPath, SKILLS_DIR_NAME));
|
|
4991
|
+
await FileSystemUtils.createDirectory(path10.join(heraspecPath, KNOWLEDGE_DIR_NAME));
|
|
4992
|
+
const skillsReadmePath = path10.join(heraspecPath, SKILLS_DIR_NAME, "README.md");
|
|
3940
4993
|
if (!await FileSystemUtils.fileExists(skillsReadmePath)) {
|
|
3941
4994
|
const skillsReadme = await this.getSkillsReadmeTemplate();
|
|
3942
4995
|
await FileSystemUtils.writeFile(skillsReadmePath, skillsReadme);
|
|
3943
4996
|
}
|
|
3944
|
-
const uiuxGuidePath =
|
|
4997
|
+
const uiuxGuidePath = path10.join(heraspecPath, SKILLS_DIR_NAME, "UI_UX_SKILL_QUICK_REFERENCE.md");
|
|
3945
4998
|
if (!await FileSystemUtils.fileExists(uiuxGuidePath)) {
|
|
3946
4999
|
const uiuxGuide = await this.getUIUXQuickReference();
|
|
3947
5000
|
await FileSystemUtils.writeFile(uiuxGuidePath, uiuxGuide);
|
|
3948
5001
|
}
|
|
3949
5002
|
await this.deployKnowledge(heraspecPath);
|
|
3950
5003
|
await this.createTemplateFiles(heraspecPath, alreadyInitialized);
|
|
3951
|
-
const legacyAgentsPath = path8.join(resolvedPath, "AGENTS.md");
|
|
3952
|
-
const newAgentsPath = path8.join(resolvedPath, HERASPEC_MARKERS.AGENTS_MD);
|
|
3953
|
-
if (await FileSystemUtils.fileExists(legacyAgentsPath) && !await FileSystemUtils.fileExists(newAgentsPath)) {
|
|
3954
|
-
await FileSystemUtils.moveFile(legacyAgentsPath, newAgentsPath);
|
|
3955
|
-
}
|
|
3956
|
-
await this.updateAgentsFile(newAgentsPath, alreadyInitialized);
|
|
3957
5004
|
if (alreadyInitialized) {
|
|
3958
5005
|
await this.updateInstalledSkills(heraspecPath);
|
|
3959
5006
|
}
|
|
3960
5007
|
await this.checkAndBootstrapMemory(heraspecPath, resolvedPath, spinner);
|
|
3961
5008
|
await this.checkAndBootstrapContentChannel(heraspecPath, resolvedPath, spinner);
|
|
3962
|
-
await
|
|
5009
|
+
const existingState = await readHeraspecState(heraspecPath);
|
|
5010
|
+
const composePlan = await buildAgentsComposePlan({
|
|
5011
|
+
projectPath: resolvedPath,
|
|
5012
|
+
heraspecPath,
|
|
5013
|
+
ideOption,
|
|
5014
|
+
force: options.force
|
|
5015
|
+
});
|
|
3963
5016
|
spinner.stop();
|
|
5017
|
+
if (composePlan.backupPath && await FileSystemUtils.fileExists(composePlan.agentsPath)) {
|
|
5018
|
+
const originalAgents = await FileSystemUtils.readFile(composePlan.agentsPath);
|
|
5019
|
+
await FileSystemUtils.writeFile(composePlan.backupPath, originalAgents);
|
|
5020
|
+
console.log(
|
|
5021
|
+
chalk3.yellow(` ! Created backup: ${path10.basename(composePlan.backupPath)}`)
|
|
5022
|
+
);
|
|
5023
|
+
}
|
|
5024
|
+
if (composePlan.nextCustomContent !== null) {
|
|
5025
|
+
await FileSystemUtils.writeFile(composePlan.customAgentsPath, composePlan.nextCustomContent);
|
|
5026
|
+
if (composePlan.customAction === "create-from-migration") {
|
|
5027
|
+
console.log(
|
|
5028
|
+
chalk3.green(
|
|
5029
|
+
` \u2713 Migrated legacy custom rules to ${HERASPEC_MARKERS.AGENTS_CUSTOM_MD} (sections: ${composePlan.extraction.customSections.length}, inline additions: ${composePlan.extraction.migratedAdditions.length})`
|
|
5030
|
+
)
|
|
5031
|
+
);
|
|
5032
|
+
} else if (composePlan.customAction === "append-migration") {
|
|
5033
|
+
console.log(
|
|
5034
|
+
chalk3.green(
|
|
5035
|
+
` \u2713 Appended inline AGENTS.heraspec.md edits safely into ${HERASPEC_MARKERS.AGENTS_CUSTOM_MD}`
|
|
5036
|
+
)
|
|
5037
|
+
);
|
|
5038
|
+
} else if (composePlan.customAction === "create-starter") {
|
|
5039
|
+
console.log(
|
|
5040
|
+
chalk3.gray(` \u2713 Created project-owned custom rules file: ${HERASPEC_MARKERS.AGENTS_CUSTOM_MD}`)
|
|
5041
|
+
);
|
|
5042
|
+
}
|
|
5043
|
+
} else {
|
|
5044
|
+
console.log(
|
|
5045
|
+
chalk3.gray(` \u2713 Preserved existing ${HERASPEC_MARKERS.AGENTS_CUSTOM_MD} untouched`)
|
|
5046
|
+
);
|
|
5047
|
+
}
|
|
5048
|
+
if (composePlan.agentsAction !== "up-to-date") {
|
|
5049
|
+
await FileSystemUtils.writeFile(composePlan.agentsPath, composePlan.renderedAgents);
|
|
5050
|
+
}
|
|
5051
|
+
const ideSync = await IdeAdapterManager.syncAdaptersAndSkills({
|
|
5052
|
+
projectPath: resolvedPath,
|
|
5053
|
+
ideOption,
|
|
5054
|
+
hasCustomFile: await FileSystemUtils.fileExists(composePlan.customAgentsPath),
|
|
5055
|
+
checkOnly: false,
|
|
5056
|
+
dryRun: false,
|
|
5057
|
+
force: options.force,
|
|
5058
|
+
preserveModifiedSkillTargets: true,
|
|
5059
|
+
recordedMirrors: existingState?.mirroredSkills
|
|
5060
|
+
});
|
|
5061
|
+
for (const report of ideSync.reports) {
|
|
5062
|
+
if (report.status === "created" || report.status === "updated") {
|
|
5063
|
+
console.log(
|
|
5064
|
+
chalk3.cyan(` \u2713 Synced ${report.kind}: ${report.relativePath} (${report.status})`)
|
|
5065
|
+
);
|
|
5066
|
+
} else if (report.status === "preserved") {
|
|
5067
|
+
console.log(
|
|
5068
|
+
chalk3.yellow(` ! Preserved modified IDE skill: ${report.relativePath} (${report.detail})`)
|
|
5069
|
+
);
|
|
5070
|
+
}
|
|
5071
|
+
}
|
|
5072
|
+
await writeHeraspecState(heraspecPath, {
|
|
5073
|
+
schemaVersion: 1,
|
|
5074
|
+
cliVersion: getCliPackageVersion(),
|
|
5075
|
+
updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
|
|
5076
|
+
agentsHeraspecSha256: composePlan.renderedSha256,
|
|
5077
|
+
mirroredSkills: ideSync.updatedMirrors
|
|
5078
|
+
});
|
|
5079
|
+
await this.updateRelatedMarkdownFiles(resolvedPath);
|
|
3964
5080
|
try {
|
|
3965
5081
|
const memoryCommand = new MemoryCommand();
|
|
3966
5082
|
await memoryCommand.index({ depth: "3", yes: true }, resolvedPath);
|
|
3967
5083
|
await memoryCommand.context({ output: "file" }, resolvedPath);
|
|
3968
|
-
} catch
|
|
5084
|
+
} catch {
|
|
3969
5085
|
}
|
|
3970
5086
|
console.log();
|
|
3971
5087
|
console.log(
|
|
3972
|
-
|
|
5088
|
+
chalk3.green(
|
|
3973
5089
|
alreadyInitialized ? "\u2714 HeraSpec updated successfully" : "\u2714 HeraSpec initialized successfully"
|
|
3974
5090
|
)
|
|
3975
5091
|
);
|
|
3976
5092
|
console.log();
|
|
3977
|
-
console.log(
|
|
5093
|
+
console.log(chalk3.cyan("Next steps:"));
|
|
3978
5094
|
console.log(
|
|
3979
|
-
|
|
5095
|
+
chalk3.gray(`1. Put project-specific engineering rules in ${HERASPEC_MARKERS.AGENTS_CUSTOM_MD}`)
|
|
3980
5096
|
);
|
|
3981
5097
|
console.log(
|
|
3982
|
-
|
|
5098
|
+
chalk3.gray("2. Review heraspec/project.md and heraspec/config.yaml for project metadata")
|
|
3983
5099
|
);
|
|
3984
5100
|
console.log(
|
|
3985
|
-
|
|
5101
|
+
chalk3.gray('3. Run "heraspec ide sync --check" anytime to verify IDE adapter & skill parity')
|
|
3986
5102
|
);
|
|
3987
5103
|
} catch (error) {
|
|
3988
|
-
spinner.fail(
|
|
5104
|
+
spinner.fail(chalk3.red(`Error: ${error.message}`));
|
|
3989
5105
|
throw error;
|
|
3990
5106
|
}
|
|
3991
5107
|
}
|
|
5108
|
+
async runDryRunPreview(resolvedPath, heraspecPath, alreadyInitialized, options) {
|
|
5109
|
+
const existingState = await readHeraspecState(heraspecPath);
|
|
5110
|
+
const composePlan = await buildAgentsComposePlan({
|
|
5111
|
+
projectPath: resolvedPath,
|
|
5112
|
+
heraspecPath,
|
|
5113
|
+
ideOption: options.ide || "auto",
|
|
5114
|
+
force: options.force
|
|
5115
|
+
});
|
|
5116
|
+
const willHaveCustom = composePlan.nextCustomContent !== null || await FileSystemUtils.fileExists(composePlan.customAgentsPath);
|
|
5117
|
+
const ideSync = await IdeAdapterManager.syncAdaptersAndSkills({
|
|
5118
|
+
projectPath: resolvedPath,
|
|
5119
|
+
ideOption: options.ide || "auto",
|
|
5120
|
+
hasCustomFile: willHaveCustom,
|
|
5121
|
+
checkOnly: false,
|
|
5122
|
+
dryRun: true,
|
|
5123
|
+
force: options.force,
|
|
5124
|
+
preserveModifiedSkillTargets: true,
|
|
5125
|
+
recordedMirrors: existingState?.mirroredSkills
|
|
5126
|
+
});
|
|
5127
|
+
console.log(chalk3.cyan.bold("\n[Dry-Run] HeraSpec Init Preview (no files written)\n"));
|
|
5128
|
+
console.log(` Target: ${resolvedPath}`);
|
|
5129
|
+
console.log(` Mode: ${alreadyInitialized ? "Re-init / Safe Upgrade" : "Fresh Init"}`);
|
|
5130
|
+
console.log(` AGENTS.heraspec.md: ${composePlan.agentsAction}`);
|
|
5131
|
+
if (composePlan.backupPath) {
|
|
5132
|
+
console.log(` Backup Planned: ${path10.basename(composePlan.backupPath)}`);
|
|
5133
|
+
}
|
|
5134
|
+
console.log(` AGENTS.custom.md: ${composePlan.customAction}`);
|
|
5135
|
+
if (composePlan.extraction.hasCustomContent) {
|
|
5136
|
+
console.log(
|
|
5137
|
+
chalk3.yellow(
|
|
5138
|
+
` Extracted Legacy Rules: ${composePlan.extraction.customSections.length} custom H2 section(s), ${composePlan.extraction.migratedAdditions.length} inline customization group(s)`
|
|
5139
|
+
)
|
|
5140
|
+
);
|
|
5141
|
+
}
|
|
5142
|
+
console.log(` Detected IDE Rule Files: ${ideSync.discovery.detectedFiles.length}`);
|
|
5143
|
+
for (const f of ideSync.discovery.detectedFiles) {
|
|
5144
|
+
console.log(chalk3.gray(` - ${f.relativePath} (${f.label}, ${f.scope})`));
|
|
5145
|
+
}
|
|
5146
|
+
for (const report of ideSync.reports) {
|
|
5147
|
+
console.log(chalk3.gray(` - [${report.kind}] ${report.relativePath}: ${report.status}`));
|
|
5148
|
+
}
|
|
5149
|
+
console.log();
|
|
5150
|
+
}
|
|
3992
5151
|
async createTemplateFiles(heraspecPath, skipExisting) {
|
|
3993
|
-
const projectMdPath =
|
|
3994
|
-
const configYamlPath =
|
|
5152
|
+
const projectMdPath = path10.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
|
|
5153
|
+
const configYamlPath = path10.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
|
|
3995
5154
|
const newProjectTemplate = TemplateManager.getProjectTemplate();
|
|
3996
5155
|
const projectExists = await FileSystemUtils.fileExists(projectMdPath);
|
|
3997
5156
|
if (!projectExists) {
|
|
3998
5157
|
await FileSystemUtils.writeFile(projectMdPath, newProjectTemplate);
|
|
3999
|
-
} else if (skipExisting) {
|
|
4000
|
-
const existingContent = await FileSystemUtils.readFile(projectMdPath);
|
|
4001
|
-
const hasChanges = this.detectTemplateChanges(existingContent, newProjectTemplate);
|
|
4002
|
-
if (hasChanges) {
|
|
4003
|
-
const backupPath = await this.createNumberedBackup(projectMdPath, heraspecPath);
|
|
4004
|
-
const backupName = path8.basename(backupPath);
|
|
4005
|
-
const mergedContent = this.buildMergedProjectMd(existingContent, newProjectTemplate, backupName);
|
|
4006
|
-
await FileSystemUtils.writeFile(projectMdPath, mergedContent);
|
|
4007
|
-
}
|
|
4008
|
-
} else {
|
|
5158
|
+
} else if (!skipExisting) {
|
|
4009
5159
|
await FileSystemUtils.writeFile(projectMdPath, newProjectTemplate);
|
|
4010
5160
|
}
|
|
4011
5161
|
if (!await FileSystemUtils.fileExists(configYamlPath)) {
|
|
@@ -4020,333 +5170,28 @@ var InitCommand = class {
|
|
|
4020
5170
|
}
|
|
4021
5171
|
}
|
|
4022
5172
|
/**
|
|
4023
|
-
* Migrate legacy project.md (extract technical configs to config.yaml)
|
|
5173
|
+
* Migrate legacy project.md (extract technical configs to config.yaml without altering user prose)
|
|
4024
5174
|
*/
|
|
4025
5175
|
async migrateLegacyProjectMd(projectMdPath, configYamlPath) {
|
|
4026
5176
|
const content = await FileSystemUtils.readFile(projectMdPath);
|
|
4027
5177
|
let newYaml = `projectType: generic-webapp
|
|
4028
5178
|
projectName: "HeraSpec Project"
|
|
4029
|
-
description: "A
|
|
5179
|
+
description: "A project using HeraSpec"
|
|
4030
5180
|
skills: []
|
|
4031
5181
|
`;
|
|
4032
|
-
const projectTypeMatch = content.match(/## Project Types
|
|
5182
|
+
const projectTypeMatch = content.match(/## Project Types\s*\n\s*-\s*`?([a-zA-Z0-9-]+)`?/);
|
|
4033
5183
|
if (projectTypeMatch && projectTypeMatch[1]) {
|
|
4034
5184
|
newYaml = newYaml.replace(/projectType:.*/, `projectType: ${projectTypeMatch[1]}`);
|
|
4035
5185
|
}
|
|
4036
|
-
const stackMatch = content.match(/## Tech Stack
|
|
5186
|
+
const stackMatch = content.match(/## Tech Stack\s*\n([^#]+)/);
|
|
4037
5187
|
if (stackMatch && stackMatch[1]) {
|
|
4038
|
-
const stackItems = stackMatch[1].split("
|
|
5188
|
+
const stackItems = stackMatch[1].split("\n").filter((line) => line.trim().startsWith("-")).map((line) => line.replace(/^\s*-\s*/, "").trim()).filter(Boolean);
|
|
4039
5189
|
if (stackItems.length > 0) {
|
|
4040
5190
|
newYaml += `techStack:
|
|
4041
|
-
` + stackItems.map((item) => ` - "${item}"`).join("\n") + "\n";
|
|
5191
|
+
` + stackItems.map((item) => ` - "${item.replace(/"/g, '\\"')}"`).join("\n") + "\n";
|
|
4042
5192
|
}
|
|
4043
5193
|
}
|
|
4044
5194
|
await FileSystemUtils.writeFile(configYamlPath, newYaml);
|
|
4045
|
-
let updatedMd = content;
|
|
4046
|
-
updatedMd = updatedMd.replace(/## Project Types[\\s\\S]*?(?=##|$)/, "");
|
|
4047
|
-
updatedMd = updatedMd.replace(/## Tech Stack[\\s\\S]*?(?=##|$)/, "");
|
|
4048
|
-
if (!updatedMd.includes("<!-- HeraSpec Update: Migrated config to config.yaml -->")) {
|
|
4049
|
-
updatedMd = `<!-- HeraSpec Update: Migrated config to config.yaml -->
|
|
4050
|
-
` + updatedMd.trimStart();
|
|
4051
|
-
}
|
|
4052
|
-
await FileSystemUtils.writeFile(projectMdPath, updatedMd);
|
|
4053
|
-
}
|
|
4054
|
-
/**
|
|
4055
|
-
* Detect if the new template has sections that the existing file lacks
|
|
4056
|
-
*/
|
|
4057
|
-
detectTemplateChanges(existingContent, newTemplate) {
|
|
4058
|
-
const sectionRegex = /^## .+$/gm;
|
|
4059
|
-
const existingSections = new Set(
|
|
4060
|
-
(existingContent.match(sectionRegex) || []).map((s) => s.trim().toLowerCase())
|
|
4061
|
-
);
|
|
4062
|
-
const newSections = (newTemplate.match(sectionRegex) || []).map((s) => s.trim().toLowerCase());
|
|
4063
|
-
for (const section of newSections) {
|
|
4064
|
-
if (!existingSections.has(section)) {
|
|
4065
|
-
return true;
|
|
4066
|
-
}
|
|
4067
|
-
}
|
|
4068
|
-
return false;
|
|
4069
|
-
}
|
|
4070
|
-
/**
|
|
4071
|
-
* Create numbered backup: project.back1.md, project.back2.md, etc.
|
|
4072
|
-
*/
|
|
4073
|
-
async createNumberedBackup(filePath, dirPath) {
|
|
4074
|
-
const ext = path8.extname(filePath);
|
|
4075
|
-
const base = path8.basename(filePath, ext);
|
|
4076
|
-
let backupNumber = 1;
|
|
4077
|
-
while (true) {
|
|
4078
|
-
const backupPath = path8.join(dirPath, `${base}.back${backupNumber}${ext}`);
|
|
4079
|
-
if (!await FileSystemUtils.fileExists(backupPath)) {
|
|
4080
|
-
await FileSystemUtils.copyFile(filePath, backupPath);
|
|
4081
|
-
return backupPath;
|
|
4082
|
-
}
|
|
4083
|
-
backupNumber++;
|
|
4084
|
-
if (backupNumber > 99) break;
|
|
4085
|
-
}
|
|
4086
|
-
const fallbackPath = path8.join(dirPath, `${base}.back99${ext}`);
|
|
4087
|
-
await FileSystemUtils.copyFile(filePath, fallbackPath);
|
|
4088
|
-
return fallbackPath;
|
|
4089
|
-
}
|
|
4090
|
-
/**
|
|
4091
|
-
* Build merged project.md:
|
|
4092
|
-
* - Keeps all existing user content (descriptions, tech stack, conventions)
|
|
4093
|
-
* - Adds any NEW sections from the template that don't exist yet
|
|
4094
|
-
* - Adds a merge note at the top referencing the backup
|
|
4095
|
-
*/
|
|
4096
|
-
buildMergedProjectMd(existingContent, newTemplate, backupFileName) {
|
|
4097
|
-
const existingSections = this.parseSections(existingContent);
|
|
4098
|
-
const templateSections = this.parseSections(newTemplate);
|
|
4099
|
-
const mergedParts = [];
|
|
4100
|
-
const existingSectionHeaders = new Set(
|
|
4101
|
-
existingSections.map((s) => s.header.trim().toLowerCase())
|
|
4102
|
-
);
|
|
4103
|
-
const mergeNote = `<!-- HeraSpec Update: Template updated. Previous version backed up to "${backupFileName}". New sections (if any) have been appended below. -->
|
|
4104
|
-
`;
|
|
4105
|
-
mergedParts.push(mergeNote);
|
|
4106
|
-
mergedParts.push(existingContent.trimEnd());
|
|
4107
|
-
const newSections = [];
|
|
4108
|
-
for (const section of templateSections) {
|
|
4109
|
-
if (!existingSectionHeaders.has(section.header.trim().toLowerCase())) {
|
|
4110
|
-
newSections.push(section);
|
|
4111
|
-
}
|
|
4112
|
-
}
|
|
4113
|
-
if (newSections.length > 0) {
|
|
4114
|
-
mergedParts.push("\n\n<!-- New sections added by HeraSpec update -->");
|
|
4115
|
-
for (const section of newSections) {
|
|
4116
|
-
mergedParts.push(`
|
|
4117
|
-
${section.header}
|
|
4118
|
-
${section.content.trimEnd()}`);
|
|
4119
|
-
}
|
|
4120
|
-
}
|
|
4121
|
-
return mergedParts.join("\n").trimEnd() + "\n";
|
|
4122
|
-
}
|
|
4123
|
-
/**
|
|
4124
|
-
* Parse markdown sections (## headers) from content
|
|
4125
|
-
*/
|
|
4126
|
-
parseSections(content) {
|
|
4127
|
-
const sections = [];
|
|
4128
|
-
const lines = content.split("\n");
|
|
4129
|
-
let currentHeader = "";
|
|
4130
|
-
let currentContent = [];
|
|
4131
|
-
for (const line of lines) {
|
|
4132
|
-
if (line.match(/^## /)) {
|
|
4133
|
-
if (currentHeader) {
|
|
4134
|
-
sections.push({ header: currentHeader, content: currentContent.join("\n") });
|
|
4135
|
-
}
|
|
4136
|
-
currentHeader = line;
|
|
4137
|
-
currentContent = [];
|
|
4138
|
-
} else if (currentHeader) {
|
|
4139
|
-
currentContent.push(line);
|
|
4140
|
-
}
|
|
4141
|
-
}
|
|
4142
|
-
if (currentHeader) {
|
|
4143
|
-
sections.push({ header: currentHeader, content: currentContent.join("\n") });
|
|
4144
|
-
}
|
|
4145
|
-
return sections;
|
|
4146
|
-
}
|
|
4147
|
-
async updateAgentsFile(agentsPath, alreadyInitialized) {
|
|
4148
|
-
const skillsSectionMarker = "## Skills System";
|
|
4149
|
-
if (!alreadyInitialized) {
|
|
4150
|
-
await FileSystemUtils.writeFile(
|
|
4151
|
-
agentsPath,
|
|
4152
|
-
TemplateManager.getAgentsTemplate()
|
|
4153
|
-
);
|
|
4154
|
-
return;
|
|
4155
|
-
}
|
|
4156
|
-
let existingContent = "";
|
|
4157
|
-
if (await FileSystemUtils.fileExists(agentsPath)) {
|
|
4158
|
-
existingContent = await FileSystemUtils.readFile(agentsPath);
|
|
4159
|
-
} else {
|
|
4160
|
-
await FileSystemUtils.writeFile(
|
|
4161
|
-
agentsPath,
|
|
4162
|
-
TemplateManager.getAgentsTemplate()
|
|
4163
|
-
);
|
|
4164
|
-
return;
|
|
4165
|
-
}
|
|
4166
|
-
const latestSkillsSection = await this.getSkillsSection();
|
|
4167
|
-
const safetyMarker = "## Universal Safety Rules";
|
|
4168
|
-
const fullTemplate = TemplateManager.getAgentsTemplate();
|
|
4169
|
-
const safetyEndIndex = fullTemplate.indexOf("## Core Workflow");
|
|
4170
|
-
const safetySection = fullTemplate.substring(fullTemplate.indexOf(safetyMarker), safetyEndIndex).trim();
|
|
4171
|
-
if (existingContent.includes(safetyMarker)) {
|
|
4172
|
-
existingContent = this.replaceSafetyRules(existingContent, safetySection);
|
|
4173
|
-
} else {
|
|
4174
|
-
if (existingContent.startsWith("# ")) {
|
|
4175
|
-
const firstLineEnd = existingContent.indexOf("\n") + 1;
|
|
4176
|
-
existingContent = existingContent.substring(0, firstLineEnd) + "\n" + safetySection + "\n\n" + existingContent.substring(firstLineEnd);
|
|
4177
|
-
} else {
|
|
4178
|
-
existingContent = safetySection + "\n\n" + existingContent;
|
|
4179
|
-
}
|
|
4180
|
-
}
|
|
4181
|
-
const coreWorkflowMarker = "## Core Workflow";
|
|
4182
|
-
const coreWorkflowEndMarker = "## Skills System";
|
|
4183
|
-
const coreWorkflowEndIndex = fullTemplate.indexOf(coreWorkflowEndMarker);
|
|
4184
|
-
const coreWorkflowStartIndex = fullTemplate.indexOf(coreWorkflowMarker);
|
|
4185
|
-
if (coreWorkflowStartIndex !== -1 && coreWorkflowEndIndex !== -1) {
|
|
4186
|
-
const coreWorkflowSection = fullTemplate.substring(coreWorkflowStartIndex, coreWorkflowEndIndex).trim();
|
|
4187
|
-
if (existingContent.includes(coreWorkflowMarker)) {
|
|
4188
|
-
existingContent = this.replaceSection(existingContent, coreWorkflowMarker, coreWorkflowSection);
|
|
4189
|
-
} else {
|
|
4190
|
-
const safetyEndPos = existingContent.indexOf("\n## ", existingContent.indexOf(safetyMarker) + safetyMarker.length);
|
|
4191
|
-
if (safetyEndPos !== -1) {
|
|
4192
|
-
const before = existingContent.substring(0, safetyEndPos).trimEnd();
|
|
4193
|
-
const after = existingContent.substring(safetyEndPos);
|
|
4194
|
-
existingContent = before + "\n\n" + coreWorkflowSection + "\n\n" + after;
|
|
4195
|
-
}
|
|
4196
|
-
}
|
|
4197
|
-
}
|
|
4198
|
-
let updatedContent = existingContent;
|
|
4199
|
-
if (existingContent.includes(skillsSectionMarker) || existingContent.includes("## Skills system")) {
|
|
4200
|
-
updatedContent = this.replaceSkillsSection(existingContent, latestSkillsSection);
|
|
4201
|
-
} else {
|
|
4202
|
-
updatedContent = this.appendSkillsSection(existingContent, latestSkillsSection);
|
|
4203
|
-
}
|
|
4204
|
-
const oldMemoryMarker = "## Memory-Aware Development";
|
|
4205
|
-
const newMemoryMarker = "## Proactive Memory-Aware Development";
|
|
4206
|
-
const memoryStartIndex = fullTemplate.indexOf(newMemoryMarker);
|
|
4207
|
-
if (memoryStartIndex !== -1) {
|
|
4208
|
-
let memoryEndIndex = fullTemplate.indexOf("\n## ", memoryStartIndex + newMemoryMarker.length);
|
|
4209
|
-
if (memoryEndIndex === -1) memoryEndIndex = fullTemplate.length;
|
|
4210
|
-
const memorySection = fullTemplate.substring(memoryStartIndex, memoryEndIndex).trim();
|
|
4211
|
-
if (updatedContent.includes(oldMemoryMarker)) {
|
|
4212
|
-
updatedContent = this.replaceSection(updatedContent, oldMemoryMarker, memorySection);
|
|
4213
|
-
} else if (updatedContent.includes(newMemoryMarker)) {
|
|
4214
|
-
updatedContent = this.replaceSection(updatedContent, newMemoryMarker, memorySection);
|
|
4215
|
-
} else {
|
|
4216
|
-
updatedContent = updatedContent.trimEnd() + "\n\n" + memorySection;
|
|
4217
|
-
}
|
|
4218
|
-
}
|
|
4219
|
-
if (updatedContent !== existingContent) {
|
|
4220
|
-
await FileSystemUtils.writeFile(agentsPath, updatedContent);
|
|
4221
|
-
}
|
|
4222
|
-
}
|
|
4223
|
-
/**
|
|
4224
|
-
* Find the index of the next top-level H2 section in the markdown content.
|
|
4225
|
-
* Tracks fenced code blocks to ignore H2 headers inside code blocks.
|
|
4226
|
-
*/
|
|
4227
|
-
findSectionEndIndex(content, startIndex) {
|
|
4228
|
-
const lines = content.substring(startIndex).split(/\r?\n/);
|
|
4229
|
-
let offset = startIndex;
|
|
4230
|
-
let inCodeBlock = false;
|
|
4231
|
-
for (let i = 0; i < lines.length; i++) {
|
|
4232
|
-
const line = lines[i];
|
|
4233
|
-
const lineLengthWithNewline = line.length + (content.charAt(offset + line.length) === "\r" ? 2 : 1);
|
|
4234
|
-
if (i === 0) {
|
|
4235
|
-
offset += lineLengthWithNewline;
|
|
4236
|
-
continue;
|
|
4237
|
-
}
|
|
4238
|
-
if (line.trim().startsWith("```")) {
|
|
4239
|
-
inCodeBlock = !inCodeBlock;
|
|
4240
|
-
}
|
|
4241
|
-
if (!inCodeBlock && line.startsWith("## ")) {
|
|
4242
|
-
return offset;
|
|
4243
|
-
}
|
|
4244
|
-
offset += lineLengthWithNewline;
|
|
4245
|
-
}
|
|
4246
|
-
return content.length;
|
|
4247
|
-
}
|
|
4248
|
-
/**
|
|
4249
|
-
* Finds the start index of the next standard section in the sequence.
|
|
4250
|
-
* This is used to replace the entire section cleanly, even if there are internal H2s or duplicates.
|
|
4251
|
-
*/
|
|
4252
|
-
findNextSectionIndex(content, startIndex, currentHeader) {
|
|
4253
|
-
const sectionsOrder = [
|
|
4254
|
-
["## Universal Safety Rules"],
|
|
4255
|
-
["## Core Workflow"],
|
|
4256
|
-
["## Skills System", "## Skills system", "### Skills System", "### skills system"],
|
|
4257
|
-
["## Proactive Memory-Aware Development", "## Memory-Aware Development"]
|
|
4258
|
-
];
|
|
4259
|
-
let currentGroupIndex = -1;
|
|
4260
|
-
for (let i = 0; i < sectionsOrder.length; i++) {
|
|
4261
|
-
if (sectionsOrder[i].some((h) => currentHeader.toLowerCase().trim() === h.toLowerCase().trim())) {
|
|
4262
|
-
currentGroupIndex = i;
|
|
4263
|
-
break;
|
|
4264
|
-
}
|
|
4265
|
-
}
|
|
4266
|
-
if (currentGroupIndex === -1) {
|
|
4267
|
-
return this.findSectionEndIndex(content, startIndex);
|
|
4268
|
-
}
|
|
4269
|
-
let nextSectionIndex = -1;
|
|
4270
|
-
for (let i = currentGroupIndex + 1; i < sectionsOrder.length; i++) {
|
|
4271
|
-
const variations = sectionsOrder[i];
|
|
4272
|
-
for (const variation of variations) {
|
|
4273
|
-
const idx = content.indexOf(variation, startIndex + currentHeader.length);
|
|
4274
|
-
if (idx !== -1) {
|
|
4275
|
-
if (nextSectionIndex === -1 || idx < nextSectionIndex) {
|
|
4276
|
-
nextSectionIndex = idx;
|
|
4277
|
-
}
|
|
4278
|
-
}
|
|
4279
|
-
}
|
|
4280
|
-
}
|
|
4281
|
-
if (nextSectionIndex !== -1) {
|
|
4282
|
-
return nextSectionIndex;
|
|
4283
|
-
}
|
|
4284
|
-
return this.findSectionEndIndex(content, startIndex);
|
|
4285
|
-
}
|
|
4286
|
-
/**
|
|
4287
|
-
* Generic section replacer: replace content from marker to next H2 header or endMarker
|
|
4288
|
-
*/
|
|
4289
|
-
replaceSection(content, sectionMarker, newSection, endMarker) {
|
|
4290
|
-
const startIndex = content.indexOf(sectionMarker);
|
|
4291
|
-
if (startIndex === -1) return content;
|
|
4292
|
-
let endIndex = -1;
|
|
4293
|
-
if (endMarker) {
|
|
4294
|
-
endIndex = content.indexOf(endMarker, startIndex + sectionMarker.length);
|
|
4295
|
-
}
|
|
4296
|
-
if (endIndex === -1) {
|
|
4297
|
-
endIndex = this.findNextSectionIndex(content, startIndex, sectionMarker);
|
|
4298
|
-
}
|
|
4299
|
-
const before = content.substring(0, startIndex).trimEnd();
|
|
4300
|
-
const after = content.substring(endIndex);
|
|
4301
|
-
return before + "\n\n" + newSection + (after.trimStart().startsWith("\n") ? "" : "\n\n") + after;
|
|
4302
|
-
}
|
|
4303
|
-
replaceSkillsSection(existingContent, newSkillsSection, endMarker) {
|
|
4304
|
-
const startMarkers = ["## Skills System", "## Skills system", "### Skills System", "### Skills system"];
|
|
4305
|
-
let startIndex = -1;
|
|
4306
|
-
let foundMarker = "";
|
|
4307
|
-
for (const marker of startMarkers) {
|
|
4308
|
-
startIndex = existingContent.indexOf(marker);
|
|
4309
|
-
if (startIndex !== -1) {
|
|
4310
|
-
foundMarker = marker;
|
|
4311
|
-
break;
|
|
4312
|
-
}
|
|
4313
|
-
}
|
|
4314
|
-
if (startIndex === -1) {
|
|
4315
|
-
return this.appendSkillsSection(existingContent, newSkillsSection);
|
|
4316
|
-
}
|
|
4317
|
-
let endIndex = -1;
|
|
4318
|
-
if (endMarker) {
|
|
4319
|
-
endIndex = existingContent.indexOf(endMarker, startIndex + foundMarker.length);
|
|
4320
|
-
}
|
|
4321
|
-
if (endIndex === -1) {
|
|
4322
|
-
endIndex = this.findNextSectionIndex(existingContent, startIndex, foundMarker);
|
|
4323
|
-
}
|
|
4324
|
-
const before = existingContent.substring(0, startIndex).trimEnd();
|
|
4325
|
-
const after = existingContent.substring(endIndex);
|
|
4326
|
-
return before + "\n\n" + newSkillsSection + (after.trimStart().startsWith("\n") ? "" : "\n\n") + after;
|
|
4327
|
-
}
|
|
4328
|
-
replaceSafetyRules(existingContent, newSafetySection) {
|
|
4329
|
-
return this.replaceSection(existingContent, "## Universal Safety Rules", newSafetySection, "## Core Workflow");
|
|
4330
|
-
}
|
|
4331
|
-
appendSkillsSection(existingContent, skillsSection) {
|
|
4332
|
-
const rulesMarker = "\n## Rules\n";
|
|
4333
|
-
const rulesIndex = existingContent.indexOf(rulesMarker);
|
|
4334
|
-
if (rulesIndex !== -1) {
|
|
4335
|
-
const before = existingContent.substring(0, rulesIndex).trimEnd();
|
|
4336
|
-
const after = existingContent.substring(rulesIndex);
|
|
4337
|
-
return before + "\n\n" + skillsSection + "\n\n" + after;
|
|
4338
|
-
}
|
|
4339
|
-
const rulesMarker2 = "## Rules";
|
|
4340
|
-
const rulesIndex2 = existingContent.indexOf(rulesMarker2);
|
|
4341
|
-
if (rulesIndex2 !== -1 && rulesIndex2 > 0) {
|
|
4342
|
-
const before = existingContent.substring(0, rulesIndex2).trimEnd();
|
|
4343
|
-
const after = existingContent.substring(rulesIndex2);
|
|
4344
|
-
return before + "\n\n" + skillsSection + "\n\n" + after;
|
|
4345
|
-
}
|
|
4346
|
-
return existingContent.trimEnd() + "\n\n" + skillsSection;
|
|
4347
|
-
}
|
|
4348
|
-
async getSkillsSection() {
|
|
4349
|
-
return TemplateManager.getSkillsSection();
|
|
4350
5195
|
}
|
|
4351
5196
|
/**
|
|
4352
5197
|
* Resolve core templates directory (same logic as skill.ts)
|
|
@@ -4355,7 +5200,7 @@ ${section.content.trimEnd()}`);
|
|
|
4355
5200
|
const possiblePaths = [];
|
|
4356
5201
|
try {
|
|
4357
5202
|
const packageJsonPath = require3.resolve("../package.json");
|
|
4358
|
-
const packageDir =
|
|
5203
|
+
const packageDir = path10.dirname(packageJsonPath);
|
|
4359
5204
|
possiblePaths.push(
|
|
4360
5205
|
join2(packageDir, "src", "core", "templates", "skills"),
|
|
4361
5206
|
join2(packageDir, "dist", "core", "templates", "skills")
|
|
@@ -4364,7 +5209,7 @@ ${section.content.trimEnd()}`);
|
|
|
4364
5209
|
}
|
|
4365
5210
|
try {
|
|
4366
5211
|
const packageJsonPath = require3.resolve("heraspec/package.json");
|
|
4367
|
-
const packageDir =
|
|
5212
|
+
const packageDir = path10.dirname(packageJsonPath);
|
|
4368
5213
|
possiblePaths.push(
|
|
4369
5214
|
join2(packageDir, "dist", "core", "templates", "skills"),
|
|
4370
5215
|
join2(packageDir, "src", "core", "templates", "skills")
|
|
@@ -4386,26 +5231,26 @@ ${section.content.trimEnd()}`);
|
|
|
4386
5231
|
* Ensures backward compatibility and non-destructive enhancement for existing projects.
|
|
4387
5232
|
*/
|
|
4388
5233
|
async refactorLegacySkills(skillsDir, coreTemplatesDir) {
|
|
4389
|
-
const perfexSkillDir =
|
|
5234
|
+
const perfexSkillDir = path10.join(skillsDir, "perfex-module");
|
|
4390
5235
|
if (await FileSystemUtils.fileExists(perfexSkillDir)) {
|
|
4391
|
-
const rootSkillMd =
|
|
4392
|
-
const rootSkillUpperMd =
|
|
4393
|
-
const templateRootSkill =
|
|
4394
|
-
const templateRootUpper =
|
|
5236
|
+
const rootSkillMd = path10.join(perfexSkillDir, "skill.md");
|
|
5237
|
+
const rootSkillUpperMd = path10.join(perfexSkillDir, "SKILL.md");
|
|
5238
|
+
const templateRootSkill = path10.join(coreTemplatesDir, "perfex-module", "skill.md");
|
|
5239
|
+
const templateRootUpper = path10.join(coreTemplatesDir, "perfex-module", "SKILL.md");
|
|
4395
5240
|
if (!await FileSystemUtils.fileExists(rootSkillMd) && await FileSystemUtils.fileExists(templateRootSkill)) {
|
|
4396
5241
|
await FileSystemUtils.copyFile(templateRootSkill, rootSkillMd);
|
|
4397
5242
|
}
|
|
4398
5243
|
if (!await FileSystemUtils.fileExists(rootSkillUpperMd) && await FileSystemUtils.fileExists(templateRootUpper)) {
|
|
4399
5244
|
await FileSystemUtils.copyFile(templateRootUpper, rootSkillUpperMd);
|
|
4400
5245
|
}
|
|
4401
|
-
const qualityGuidelinesDir =
|
|
4402
|
-
const templateQualityDir =
|
|
5246
|
+
const qualityGuidelinesDir = path10.join(perfexSkillDir, "code-quality-guidelines");
|
|
5247
|
+
const templateQualityDir = path10.join(coreTemplatesDir, "perfex-module", "code-quality-guidelines");
|
|
4403
5248
|
if (!await FileSystemUtils.fileExists(qualityGuidelinesDir) && await FileSystemUtils.fileExists(templateQualityDir)) {
|
|
4404
|
-
console.log(
|
|
5249
|
+
console.log(chalk3.cyan(" \u2713 Refactored perfex-module: added code-quality-guidelines skill"));
|
|
4405
5250
|
await FileSystemUtils.copyDirectory(templateQualityDir, qualityGuidelinesDir);
|
|
4406
5251
|
}
|
|
4407
|
-
const codebaseDir =
|
|
4408
|
-
const templateCodebaseDir =
|
|
5252
|
+
const codebaseDir = path10.join(perfexSkillDir, "module-codebase");
|
|
5253
|
+
const templateCodebaseDir = path10.join(coreTemplatesDir, "perfex-module", "module-codebase");
|
|
4409
5254
|
if (await FileSystemUtils.fileExists(codebaseDir) && await FileSystemUtils.fileExists(templateCodebaseDir)) {
|
|
4410
5255
|
await FileSystemUtils.copyDirectory(templateCodebaseDir, codebaseDir);
|
|
4411
5256
|
}
|
|
@@ -4422,7 +5267,7 @@ ${section.content.trimEnd()}`);
|
|
|
4422
5267
|
* safely preserving any user files in templates/, scripts/, examples/ sub-folders
|
|
4423
5268
|
*/
|
|
4424
5269
|
async updateInstalledSkills(heraspecPath) {
|
|
4425
|
-
const skillsDir =
|
|
5270
|
+
const skillsDir = path10.join(heraspecPath, SKILLS_DIR_NAME);
|
|
4426
5271
|
if (!await FileSystemUtils.fileExists(skillsDir)) return;
|
|
4427
5272
|
const coreTemplatesDir = await this.getCoreTemplatesDir();
|
|
4428
5273
|
if (!coreTemplatesDir) return;
|
|
@@ -4440,7 +5285,7 @@ ${section.content.trimEnd()}`);
|
|
|
4440
5285
|
}
|
|
4441
5286
|
continue;
|
|
4442
5287
|
}
|
|
4443
|
-
const templateFile =
|
|
5288
|
+
const templateFile = path10.join(coreTemplatesDir, templateInfo.templateFileName);
|
|
4444
5289
|
if (!await FileSystemUtils.fileExists(templateFile)) {
|
|
4445
5290
|
const displayName = projectType ? `${projectType}/${skillName}` : skillName;
|
|
4446
5291
|
if (!preservedSkills.includes(displayName)) {
|
|
@@ -4448,38 +5293,38 @@ ${section.content.trimEnd()}`);
|
|
|
4448
5293
|
}
|
|
4449
5294
|
continue;
|
|
4450
5295
|
}
|
|
4451
|
-
await FileSystemUtils.copyFile(templateFile,
|
|
4452
|
-
const upperTemplateFile =
|
|
5296
|
+
await FileSystemUtils.copyFile(templateFile, path10.join(skillPath, "skill.md"));
|
|
5297
|
+
const upperTemplateFile = path10.join(path10.dirname(templateFile), "SKILL.md");
|
|
4453
5298
|
if (await FileSystemUtils.fileExists(upperTemplateFile)) {
|
|
4454
|
-
await FileSystemUtils.copyFile(upperTemplateFile,
|
|
5299
|
+
await FileSystemUtils.copyFile(upperTemplateFile, path10.join(skillPath, "SKILL.md"));
|
|
4455
5300
|
}
|
|
4456
5301
|
if (templateInfo.viFileName) {
|
|
4457
|
-
const viFile =
|
|
5302
|
+
const viFile = path10.join(coreTemplatesDir, templateInfo.viFileName);
|
|
4458
5303
|
if (await FileSystemUtils.fileExists(viFile)) {
|
|
4459
|
-
await FileSystemUtils.copyFile(viFile,
|
|
5304
|
+
await FileSystemUtils.copyFile(viFile, path10.join(skillPath, "skill.vi.md"));
|
|
4460
5305
|
}
|
|
4461
5306
|
}
|
|
4462
5307
|
if (templateInfo.resourceDirs) {
|
|
4463
5308
|
for (const resourceDir of templateInfo.resourceDirs) {
|
|
4464
|
-
const srcResourceDir =
|
|
4465
|
-
const destResourceDir =
|
|
5309
|
+
const srcResourceDir = path10.join(coreTemplatesDir, resourceDir);
|
|
5310
|
+
const destResourceDir = path10.join(skillPath, path10.basename(resourceDir));
|
|
4466
5311
|
if (await FileSystemUtils.fileExists(srcResourceDir)) {
|
|
4467
5312
|
await FileSystemUtils.copyDirectory(srcResourceDir, destResourceDir);
|
|
4468
5313
|
}
|
|
4469
5314
|
}
|
|
4470
5315
|
}
|
|
4471
5316
|
for (const dir of ["templates", "scripts", "examples"]) {
|
|
4472
|
-
await FileSystemUtils.createDirectory(
|
|
5317
|
+
await FileSystemUtils.createDirectory(path10.join(skillPath, dir));
|
|
4473
5318
|
}
|
|
4474
5319
|
updatedCount++;
|
|
4475
5320
|
}
|
|
4476
5321
|
if (updatedCount > 0) {
|
|
4477
|
-
console.log(
|
|
5322
|
+
console.log(chalk3.gray(` \u2713 Updated ${updatedCount} built-in skill(s)`));
|
|
4478
5323
|
}
|
|
4479
5324
|
if (preservedSkills.length > 0) {
|
|
4480
|
-
console.log(
|
|
5325
|
+
console.log(chalk3.green(` \u2713 Preserved ${preservedSkills.length} custom project skill(s) (never deleted or overwritten):`));
|
|
4481
5326
|
for (const skill of preservedSkills) {
|
|
4482
|
-
console.log(
|
|
5327
|
+
console.log(chalk3.gray(` \u2022 ${skill}`));
|
|
4483
5328
|
}
|
|
4484
5329
|
}
|
|
4485
5330
|
}
|
|
@@ -4504,24 +5349,24 @@ ${section.content.trimEnd()}`);
|
|
|
4504
5349
|
];
|
|
4505
5350
|
for (const entry of entries) {
|
|
4506
5351
|
if (entry === "README.md" || entry === "UI_UX_SKILL_QUICK_REFERENCE.md") continue;
|
|
4507
|
-
const entryPath =
|
|
5352
|
+
const entryPath = path10.join(skillsDir, entry);
|
|
4508
5353
|
const stats = await FileSystemUtils.stat(entryPath);
|
|
4509
5354
|
if (!stats.isDirectory()) continue;
|
|
4510
5355
|
if (knownProjectTypes.includes(entry)) {
|
|
4511
5356
|
const subEntries = await FileSystemUtils.readDirectory(entryPath);
|
|
4512
5357
|
for (const sub of subEntries) {
|
|
4513
5358
|
if (["templates", "scripts", "examples", "data", "knowledge", "tests", "docs"].includes(sub)) continue;
|
|
4514
|
-
const subPath =
|
|
5359
|
+
const subPath = path10.join(entryPath, sub);
|
|
4515
5360
|
const subStats = await FileSystemUtils.stat(subPath);
|
|
4516
5361
|
if (subStats.isDirectory()) {
|
|
4517
5362
|
result.push({ skillPath: subPath, skillName: sub, projectType: entry });
|
|
4518
5363
|
}
|
|
4519
5364
|
}
|
|
4520
|
-
if (await FileSystemUtils.fileExists(
|
|
5365
|
+
if (await FileSystemUtils.fileExists(path10.join(entryPath, "skill.md")) || await FileSystemUtils.fileExists(path10.join(entryPath, "SKILL.md"))) {
|
|
4521
5366
|
result.push({ skillPath: entryPath, skillName: entry, projectType: entry });
|
|
4522
5367
|
}
|
|
4523
5368
|
} else {
|
|
4524
|
-
if (await FileSystemUtils.fileExists(
|
|
5369
|
+
if (await FileSystemUtils.fileExists(path10.join(entryPath, "skill.md")) || await FileSystemUtils.fileExists(path10.join(entryPath, "SKILL.md"))) {
|
|
4525
5370
|
result.push({ skillPath: entryPath, skillName: entry });
|
|
4526
5371
|
}
|
|
4527
5372
|
}
|
|
@@ -4532,13 +5377,13 @@ ${section.content.trimEnd()}`);
|
|
|
4532
5377
|
* Prompt user to bootstrap memory if historical specs are found
|
|
4533
5378
|
*/
|
|
4534
5379
|
async checkAndBootstrapMemory(heraspecPath, projectPath, spinner) {
|
|
4535
|
-
const memorySkillDir =
|
|
5380
|
+
const memorySkillDir = path10.join(heraspecPath, SKILLS_DIR_NAME, "project-memory");
|
|
4536
5381
|
if (!await FileSystemUtils.fileExists(memorySkillDir)) {
|
|
4537
5382
|
spinner.stop();
|
|
4538
5383
|
try {
|
|
4539
5384
|
const { SkillCommand: SkillCommand2 } = await Promise.resolve().then(() => (init_skill(), skill_exports));
|
|
4540
5385
|
const skillCommand = new SkillCommand2();
|
|
4541
|
-
console.log(
|
|
5386
|
+
console.log(chalk3.cyan('\n\u{1F4E6} Auto-installing recommended skill: "project-memory"'));
|
|
4542
5387
|
await skillCommand.add("project-memory", void 0, projectPath);
|
|
4543
5388
|
console.log();
|
|
4544
5389
|
} catch (err) {
|
|
@@ -4547,8 +5392,8 @@ ${section.content.trimEnd()}`);
|
|
|
4547
5392
|
}
|
|
4548
5393
|
spinner.start();
|
|
4549
5394
|
}
|
|
4550
|
-
const specsDir =
|
|
4551
|
-
const archivesDir =
|
|
5395
|
+
const specsDir = path10.join(heraspecPath, SPECS_DIR_NAME);
|
|
5396
|
+
const archivesDir = path10.join(heraspecPath, ARCHIVES_DIR_NAME);
|
|
4552
5397
|
let hasHistoricalData = false;
|
|
4553
5398
|
for (const dir of [specsDir, archivesDir]) {
|
|
4554
5399
|
if (await FileSystemUtils.fileExists(dir)) {
|
|
@@ -4559,7 +5404,7 @@ ${section.content.trimEnd()}`);
|
|
|
4559
5404
|
}
|
|
4560
5405
|
if (!hasHistoricalData) {
|
|
4561
5406
|
for (const e of entries) {
|
|
4562
|
-
const fullPath =
|
|
5407
|
+
const fullPath = path10.join(dir, e);
|
|
4563
5408
|
const st = await FileSystemUtils.stat(fullPath);
|
|
4564
5409
|
if (st.isDirectory()) {
|
|
4565
5410
|
const subEntries = await FileSystemUtils.readDirectory(fullPath);
|
|
@@ -4573,12 +5418,15 @@ ${section.content.trimEnd()}`);
|
|
|
4573
5418
|
}
|
|
4574
5419
|
}
|
|
4575
5420
|
if (!hasHistoricalData) return;
|
|
4576
|
-
const memoryDbPath =
|
|
5421
|
+
const memoryDbPath = path10.join(heraspecPath, "memory", "heraspec-memory.db");
|
|
4577
5422
|
if (await FileSystemUtils.fileExists(memoryDbPath)) {
|
|
4578
5423
|
return;
|
|
4579
5424
|
}
|
|
5425
|
+
if (!process.stdin.isTTY) {
|
|
5426
|
+
return;
|
|
5427
|
+
}
|
|
4580
5428
|
spinner.stop();
|
|
4581
|
-
console.log(
|
|
5429
|
+
console.log(chalk3.cyan("\n\u{1F4A1} Tip: Your project has historical specs."));
|
|
4582
5430
|
const { confirm } = await import("@inquirer/prompts");
|
|
4583
5431
|
const answer = await confirm({
|
|
4584
5432
|
message: 'Would you like to bootstrap the "project-memory" system from these existing specs?',
|
|
@@ -4589,7 +5437,7 @@ ${section.content.trimEnd()}`);
|
|
|
4589
5437
|
const memoryCommand = new MemoryCommand();
|
|
4590
5438
|
await memoryCommand.bootstrap({ yes: true }, projectPath);
|
|
4591
5439
|
} catch (error) {
|
|
4592
|
-
console.log(
|
|
5440
|
+
console.log(chalk3.red(`Bootstrap failed: ${error instanceof Error ? error.message : "Unknown"}`));
|
|
4593
5441
|
}
|
|
4594
5442
|
}
|
|
4595
5443
|
spinner.start();
|
|
@@ -4598,8 +5446,8 @@ ${section.content.trimEnd()}`);
|
|
|
4598
5446
|
* Automatically install content-channel skills if project type is content-channel
|
|
4599
5447
|
*/
|
|
4600
5448
|
async checkAndBootstrapContentChannel(heraspecPath, projectPath, spinner) {
|
|
4601
|
-
const configPath =
|
|
4602
|
-
const projectMdPath =
|
|
5449
|
+
const configPath = path10.join(heraspecPath, HERASPEC_MARKERS.CONFIG_YAML);
|
|
5450
|
+
const projectMdPath = path10.join(heraspecPath, HERASPEC_MARKERS.PROJECT_MD);
|
|
4603
5451
|
let isContentChannel = false;
|
|
4604
5452
|
if (await FileSystemUtils.fileExists(configPath)) {
|
|
4605
5453
|
const configContent = await FileSystemUtils.readFile(configPath);
|
|
@@ -4614,9 +5462,9 @@ ${section.content.trimEnd()}`);
|
|
|
4614
5462
|
}
|
|
4615
5463
|
}
|
|
4616
5464
|
if (!isContentChannel) {
|
|
4617
|
-
const hasFacebook = await FileSystemUtils.fileExists(
|
|
4618
|
-
const hasPosts = await FileSystemUtils.fileExists(
|
|
4619
|
-
const hasPrompts = await FileSystemUtils.fileExists(
|
|
5465
|
+
const hasFacebook = await FileSystemUtils.fileExists(path10.join(projectPath, "Facebook"));
|
|
5466
|
+
const hasPosts = await FileSystemUtils.fileExists(path10.join(projectPath, "posts"));
|
|
5467
|
+
const hasPrompts = await FileSystemUtils.fileExists(path10.join(projectPath, "prompts"));
|
|
4620
5468
|
if (hasFacebook || hasPosts && hasPrompts) {
|
|
4621
5469
|
isContentChannel = true;
|
|
4622
5470
|
}
|
|
@@ -4631,18 +5479,18 @@ ${section.content.trimEnd()}`);
|
|
|
4631
5479
|
"content-compliance",
|
|
4632
5480
|
"content-vault-sync"
|
|
4633
5481
|
];
|
|
4634
|
-
const skillsDir =
|
|
5482
|
+
const skillsDir = path10.join(heraspecPath, SKILLS_DIR_NAME);
|
|
4635
5483
|
const missingSkills = [];
|
|
4636
5484
|
for (const skillName of channelSkills) {
|
|
4637
|
-
const flatPath =
|
|
4638
|
-
const scopedPath =
|
|
5485
|
+
const flatPath = path10.join(skillsDir, skillName);
|
|
5486
|
+
const scopedPath = path10.join(skillsDir, "content-channel", skillName);
|
|
4639
5487
|
if (!await FileSystemUtils.fileExists(flatPath) && !await FileSystemUtils.fileExists(scopedPath)) {
|
|
4640
5488
|
missingSkills.push(skillName);
|
|
4641
5489
|
}
|
|
4642
5490
|
}
|
|
4643
5491
|
if (missingSkills.length > 0) {
|
|
4644
5492
|
spinner.stop();
|
|
4645
|
-
console.log(
|
|
5493
|
+
console.log(chalk3.cyan(`
|
|
4646
5494
|
\u{1F3AC} Detected content-channel project. Installing ${missingSkills.length} channel skill(s)...`));
|
|
4647
5495
|
try {
|
|
4648
5496
|
const { SkillCommand: SkillCommand2 } = await Promise.resolve().then(() => (init_skill(), skill_exports));
|
|
@@ -4650,7 +5498,7 @@ ${section.content.trimEnd()}`);
|
|
|
4650
5498
|
for (const skillName of missingSkills) {
|
|
4651
5499
|
await skillCommand.add(skillName, void 0, projectPath);
|
|
4652
5500
|
}
|
|
4653
|
-
console.log(
|
|
5501
|
+
console.log(chalk3.green(`\u2713 Channel skills suite ready for production.
|
|
4654
5502
|
`));
|
|
4655
5503
|
} catch (err) {
|
|
4656
5504
|
}
|
|
@@ -4665,7 +5513,7 @@ ${section.content.trimEnd()}`);
|
|
|
4665
5513
|
const possiblePaths = [];
|
|
4666
5514
|
try {
|
|
4667
5515
|
const packageJsonPath = require3.resolve("../package.json");
|
|
4668
|
-
const packageDir =
|
|
5516
|
+
const packageDir = path10.dirname(packageJsonPath);
|
|
4669
5517
|
possiblePaths.push(
|
|
4670
5518
|
join2(packageDir, "src", "core", "templates", "skills", "knowledge"),
|
|
4671
5519
|
join2(packageDir, "dist", "core", "templates", "skills", "knowledge")
|
|
@@ -4674,7 +5522,7 @@ ${section.content.trimEnd()}`);
|
|
|
4674
5522
|
}
|
|
4675
5523
|
try {
|
|
4676
5524
|
const packageJsonPath = require3.resolve("heraspec/package.json");
|
|
4677
|
-
const packageDir =
|
|
5525
|
+
const packageDir = path10.dirname(packageJsonPath);
|
|
4678
5526
|
possiblePaths.push(
|
|
4679
5527
|
join2(packageDir, "dist", "core", "templates", "skills", "knowledge"),
|
|
4680
5528
|
join2(packageDir, "src", "core", "templates", "skills", "knowledge")
|
|
@@ -4697,34 +5545,34 @@ ${section.content.trimEnd()}`);
|
|
|
4697
5545
|
* Deploy/update built-in knowledge base, preserving custom/ directory
|
|
4698
5546
|
*/
|
|
4699
5547
|
async deployKnowledge(heraspecPath) {
|
|
4700
|
-
const knowledgeDir =
|
|
5548
|
+
const knowledgeDir = path10.join(heraspecPath, KNOWLEDGE_DIR_NAME);
|
|
4701
5549
|
const sourceDir = await this.getKnowledgeSourceDir();
|
|
4702
5550
|
if (!sourceDir) {
|
|
4703
5551
|
return;
|
|
4704
5552
|
}
|
|
4705
5553
|
const builtinFiles = ["index.json", "README.md"];
|
|
4706
5554
|
for (const file of builtinFiles) {
|
|
4707
|
-
const srcFile =
|
|
5555
|
+
const srcFile = path10.join(sourceDir, file);
|
|
4708
5556
|
if (await FileSystemUtils.fileExists(srcFile)) {
|
|
4709
|
-
await FileSystemUtils.copyFile(srcFile,
|
|
5557
|
+
await FileSystemUtils.copyFile(srcFile, path10.join(knowledgeDir, file));
|
|
4710
5558
|
}
|
|
4711
5559
|
}
|
|
4712
5560
|
const builtinCategories = ["frameworks", "apis", "platforms"];
|
|
4713
5561
|
for (const category of builtinCategories) {
|
|
4714
|
-
const srcCategory =
|
|
5562
|
+
const srcCategory = path10.join(sourceDir, category);
|
|
4715
5563
|
if (await FileSystemUtils.fileExists(srcCategory)) {
|
|
4716
|
-
const destCategory =
|
|
5564
|
+
const destCategory = path10.join(knowledgeDir, category);
|
|
4717
5565
|
if (await FileSystemUtils.fileExists(destCategory)) {
|
|
4718
5566
|
await FileSystemUtils.removeDirectory(destCategory, true);
|
|
4719
5567
|
}
|
|
4720
5568
|
await FileSystemUtils.copyDirectory(srcCategory, destCategory);
|
|
4721
5569
|
}
|
|
4722
5570
|
}
|
|
4723
|
-
const customDir =
|
|
5571
|
+
const customDir = path10.join(knowledgeDir, "custom");
|
|
4724
5572
|
if (!await FileSystemUtils.fileExists(customDir)) {
|
|
4725
5573
|
await FileSystemUtils.createDirectory(customDir);
|
|
4726
5574
|
await FileSystemUtils.writeFile(
|
|
4727
|
-
|
|
5575
|
+
path10.join(customDir, "index.json"),
|
|
4728
5576
|
JSON.stringify({
|
|
4729
5577
|
version: "1.0",
|
|
4730
5578
|
description: "Custom knowledge entries \u2014 managed by user, never overwritten by CLI",
|
|
@@ -5023,7 +5871,7 @@ After copying UI/UX skill to your project, see:
|
|
|
5023
5871
|
* Update related markdown files in the project (README.md, etc.)
|
|
5024
5872
|
*/
|
|
5025
5873
|
async updateRelatedMarkdownFiles(projectPath) {
|
|
5026
|
-
const readmePath =
|
|
5874
|
+
const readmePath = path10.join(projectPath, "README.md");
|
|
5027
5875
|
if (await FileSystemUtils.fileExists(readmePath)) {
|
|
5028
5876
|
await this.updateReadmeFile(readmePath);
|
|
5029
5877
|
}
|
|
@@ -5134,7 +5982,8 @@ heraspec validate <change-name>
|
|
|
5134
5982
|
- \`heraspec/specs/\` - Source of truth specifications
|
|
5135
5983
|
- \`heraspec/changes/\` - Active changes in progress
|
|
5136
5984
|
- \`heraspec/skills/\` - Reusable skills for AI agents
|
|
5137
|
-
- \`AGENTS.heraspec.md\` - AI agent instructions
|
|
5985
|
+
- \`AGENTS.heraspec.md\` - CLI-managed AI agent workflow instructions
|
|
5986
|
+
- \`AGENTS.custom.md\` - Project-owned custom rules and engineering gates
|
|
5138
5987
|
|
|
5139
5988
|
### Working with Changes
|
|
5140
5989
|
|
|
@@ -5170,10 +6019,10 @@ For more information, see the [HeraSpec documentation](https://github.com/PolyXG
|
|
|
5170
6019
|
// src/core/list.ts
|
|
5171
6020
|
init_file_system();
|
|
5172
6021
|
init_config();
|
|
5173
|
-
import
|
|
6022
|
+
import path11 from "path";
|
|
5174
6023
|
var ListCommand = class {
|
|
5175
6024
|
async execute(targetPath = ".", mode = "changes") {
|
|
5176
|
-
const heraspecPath =
|
|
6025
|
+
const heraspecPath = path11.join(targetPath, HERASPEC_DIR_NAME);
|
|
5177
6026
|
if (mode === "changes") {
|
|
5178
6027
|
await this.listChanges(heraspecPath);
|
|
5179
6028
|
} else {
|
|
@@ -5181,7 +6030,7 @@ var ListCommand = class {
|
|
|
5181
6030
|
}
|
|
5182
6031
|
}
|
|
5183
6032
|
async listChanges(heraspecPath) {
|
|
5184
|
-
const changesDir =
|
|
6033
|
+
const changesDir = path11.join(heraspecPath, CHANGES_DIR_NAME);
|
|
5185
6034
|
try {
|
|
5186
6035
|
await FileSystemUtils.stat(changesDir);
|
|
5187
6036
|
} catch {
|
|
@@ -5191,7 +6040,7 @@ var ListCommand = class {
|
|
|
5191
6040
|
const entries = await FileSystemUtils.readDirectory(changesDir);
|
|
5192
6041
|
const changeDirs = [];
|
|
5193
6042
|
for (const entry of entries) {
|
|
5194
|
-
const entryPath =
|
|
6043
|
+
const entryPath = path11.join(changesDir, entry);
|
|
5195
6044
|
const stats = await FileSystemUtils.stat(entryPath);
|
|
5196
6045
|
if (stats.isDirectory() && entry !== ARCHIVES_DIR_NAME) {
|
|
5197
6046
|
changeDirs.push(entry);
|
|
@@ -5210,7 +6059,7 @@ var ListCommand = class {
|
|
|
5210
6059
|
console.log();
|
|
5211
6060
|
}
|
|
5212
6061
|
async listSpecs(heraspecPath) {
|
|
5213
|
-
const specsDir =
|
|
6062
|
+
const specsDir = path11.join(heraspecPath, SPECS_DIR_NAME);
|
|
5214
6063
|
try {
|
|
5215
6064
|
await FileSystemUtils.stat(specsDir);
|
|
5216
6065
|
} catch {
|
|
@@ -5234,7 +6083,7 @@ var ListCommand = class {
|
|
|
5234
6083
|
const specs = [];
|
|
5235
6084
|
const entries = await FileSystemUtils.readDirectory(dir);
|
|
5236
6085
|
for (const entry of entries) {
|
|
5237
|
-
const entryPath =
|
|
6086
|
+
const entryPath = path11.join(dir, entry);
|
|
5238
6087
|
const stats = await FileSystemUtils.stat(entryPath);
|
|
5239
6088
|
if (stats.isDirectory()) {
|
|
5240
6089
|
const subSpecs = await this.findSpecFiles(
|
|
@@ -5253,10 +6102,10 @@ var ListCommand = class {
|
|
|
5253
6102
|
// src/core/archive.ts
|
|
5254
6103
|
init_file_system();
|
|
5255
6104
|
init_config();
|
|
5256
|
-
import
|
|
6105
|
+
import path12 from "path";
|
|
5257
6106
|
import ora4 from "ora";
|
|
5258
|
-
import { createHash } from "crypto";
|
|
5259
|
-
import
|
|
6107
|
+
import { createHash as createHash2 } from "crypto";
|
|
6108
|
+
import chalk4 from "chalk";
|
|
5260
6109
|
|
|
5261
6110
|
// src/core/parsers/markdown-parser.ts
|
|
5262
6111
|
var MarkdownParser = class _MarkdownParser {
|
|
@@ -5268,7 +6117,7 @@ var MarkdownParser = class _MarkdownParser {
|
|
|
5268
6117
|
return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
|
|
5269
6118
|
}
|
|
5270
6119
|
parseSpec(name) {
|
|
5271
|
-
const sections = this.parseSections();
|
|
6120
|
+
const sections = this.parseSections(this.lines, 2);
|
|
5272
6121
|
const meta = this.parseMeta(sections);
|
|
5273
6122
|
const purpose = this.findSection(sections, "Purpose")?.content.join("\n").trim() || "";
|
|
5274
6123
|
const requirementsSection = this.findSection(sections, "Requirements");
|
|
@@ -5291,7 +6140,8 @@ var MarkdownParser = class _MarkdownParser {
|
|
|
5291
6140
|
};
|
|
5292
6141
|
}
|
|
5293
6142
|
parseDeltaSpec(content) {
|
|
5294
|
-
const
|
|
6143
|
+
const targetLines = content ? _MarkdownParser.normalizeContent(content).split("\n") : this.lines;
|
|
6144
|
+
const sections = this.parseSections(targetLines, 2);
|
|
5295
6145
|
const added = this.findSection(sections, "ADDED Requirements");
|
|
5296
6146
|
const modified = this.findSection(sections, "MODIFIED Requirements");
|
|
5297
6147
|
const removed = this.findSection(sections, "REMOVED Requirements");
|
|
@@ -5324,12 +6174,17 @@ var MarkdownParser = class _MarkdownParser {
|
|
|
5324
6174
|
}
|
|
5325
6175
|
return Object.keys(meta).length > 0 ? meta : void 0;
|
|
5326
6176
|
}
|
|
5327
|
-
parseSections() {
|
|
6177
|
+
parseSections(lines = this.lines, maxHeadingLevel = 2) {
|
|
5328
6178
|
const sections = [];
|
|
5329
6179
|
let currentSection = null;
|
|
5330
|
-
|
|
5331
|
-
|
|
5332
|
-
|
|
6180
|
+
let inCodeBlock = false;
|
|
6181
|
+
for (const line of lines) {
|
|
6182
|
+
const trimmed = line.trim();
|
|
6183
|
+
if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
|
|
6184
|
+
inCodeBlock = !inCodeBlock;
|
|
6185
|
+
}
|
|
6186
|
+
const headerMatch = !inCodeBlock ? line.match(/^(#{1,6})\s+(.+)$/) : null;
|
|
6187
|
+
if (headerMatch && headerMatch[1].length <= maxHeadingLevel) {
|
|
5333
6188
|
if (currentSection) {
|
|
5334
6189
|
sections.push(currentSection);
|
|
5335
6190
|
}
|
|
@@ -5348,33 +6203,42 @@ var MarkdownParser = class _MarkdownParser {
|
|
|
5348
6203
|
return sections;
|
|
5349
6204
|
}
|
|
5350
6205
|
findSection(sections, title) {
|
|
5351
|
-
|
|
5352
|
-
|
|
5353
|
-
);
|
|
6206
|
+
const target = title.toLowerCase();
|
|
6207
|
+
return sections.find((s) => s.title.toLowerCase() === target) || sections.find((s) => s.title.toLowerCase().includes(target));
|
|
5354
6208
|
}
|
|
5355
6209
|
parseRequirements(section) {
|
|
5356
6210
|
const requirements = [];
|
|
5357
6211
|
const lines = section.content;
|
|
5358
6212
|
let currentRequirement = null;
|
|
5359
|
-
let inRequirement = false;
|
|
5360
6213
|
let inScenario = false;
|
|
5361
6214
|
let currentScenario = null;
|
|
5362
|
-
|
|
5363
|
-
|
|
5364
|
-
|
|
6215
|
+
let inCodeBlock = false;
|
|
6216
|
+
const flushCurrentRequirement = () => {
|
|
6217
|
+
if (!currentRequirement) return;
|
|
6218
|
+
if (currentScenario) {
|
|
6219
|
+
currentRequirement.scenarios.push(currentScenario);
|
|
6220
|
+
currentScenario = null;
|
|
6221
|
+
}
|
|
6222
|
+
requirements.push(currentRequirement);
|
|
6223
|
+
currentRequirement = null;
|
|
6224
|
+
inScenario = false;
|
|
6225
|
+
};
|
|
6226
|
+
for (const line of lines) {
|
|
6227
|
+
const trimmedLine = line.trim();
|
|
6228
|
+
if (trimmedLine.startsWith("```") || trimmedLine.startsWith("~~~")) {
|
|
6229
|
+
inCodeBlock = !inCodeBlock;
|
|
6230
|
+
}
|
|
6231
|
+
const reqMatch = !inCodeBlock ? line.match(/^###\s+Requirement:\s*(.+)$/i) : null;
|
|
5365
6232
|
if (reqMatch) {
|
|
5366
|
-
|
|
5367
|
-
requirements.push(currentRequirement);
|
|
5368
|
-
}
|
|
6233
|
+
flushCurrentRequirement();
|
|
5369
6234
|
currentRequirement = {
|
|
5370
6235
|
name: reqMatch[1].trim(),
|
|
5371
6236
|
description: "",
|
|
5372
6237
|
scenarios: []
|
|
5373
6238
|
};
|
|
5374
|
-
inRequirement = true;
|
|
5375
6239
|
continue;
|
|
5376
6240
|
}
|
|
5377
|
-
const scenarioMatch = line.match(/^####\s+Scenario:\s*(.+)$/i);
|
|
6241
|
+
const scenarioMatch = !inCodeBlock ? line.match(/^####\s+Scenario:\s*(.+)$/i) : null;
|
|
5378
6242
|
if (scenarioMatch && currentRequirement) {
|
|
5379
6243
|
if (currentScenario) {
|
|
5380
6244
|
currentRequirement.scenarios.push(currentScenario);
|
|
@@ -5386,24 +6250,18 @@ var MarkdownParser = class _MarkdownParser {
|
|
|
5386
6250
|
inScenario = true;
|
|
5387
6251
|
continue;
|
|
5388
6252
|
}
|
|
5389
|
-
if (currentScenario &&
|
|
6253
|
+
if (currentScenario && /^-\s*(?:\*\*)?(?:GIVEN|WHEN|THEN|AND|BUT)(?:\*\*)?\b/i.test(trimmedLine)) {
|
|
5390
6254
|
const step = line.replace(/^-\s*/, "").trim();
|
|
5391
6255
|
currentScenario.steps.push(step);
|
|
5392
6256
|
continue;
|
|
5393
6257
|
}
|
|
5394
6258
|
if (currentRequirement && !inScenario) {
|
|
5395
|
-
|
|
5396
|
-
|
|
5397
|
-
currentRequirement.description += (currentRequirement.description ? "\n" : "") + trimmed;
|
|
6259
|
+
if (trimmedLine && (inCodeBlock || !trimmedLine.startsWith("#"))) {
|
|
6260
|
+
currentRequirement.description += (currentRequirement.description ? "\n" : "") + trimmedLine;
|
|
5398
6261
|
}
|
|
5399
6262
|
}
|
|
5400
6263
|
}
|
|
5401
|
-
|
|
5402
|
-
currentRequirement.scenarios.push(currentScenario);
|
|
5403
|
-
}
|
|
5404
|
-
if (currentRequirement) {
|
|
5405
|
-
requirements.push(currentRequirement);
|
|
5406
|
-
}
|
|
6264
|
+
flushCurrentRequirement();
|
|
5407
6265
|
return requirements;
|
|
5408
6266
|
}
|
|
5409
6267
|
parseDeltaRequirements(section) {
|
|
@@ -5420,7 +6278,7 @@ var ArchiveCommand = class {
|
|
|
5420
6278
|
process.exitCode = 1;
|
|
5421
6279
|
return;
|
|
5422
6280
|
}
|
|
5423
|
-
const changePath =
|
|
6281
|
+
const changePath = path12.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, changeName);
|
|
5424
6282
|
if (!await FileSystemUtils.fileExists(changePath)) {
|
|
5425
6283
|
console.error(`Error: Change "${changeName}" not found`);
|
|
5426
6284
|
process.exitCode = 1;
|
|
@@ -5440,7 +6298,7 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
|
|
|
5440
6298
|
}).start();
|
|
5441
6299
|
try {
|
|
5442
6300
|
await this.mergeDeltaSpecs(changePath, changeName);
|
|
5443
|
-
const specsDir =
|
|
6301
|
+
const specsDir = path12.join(
|
|
5444
6302
|
".",
|
|
5445
6303
|
HERASPEC_DIR_NAME,
|
|
5446
6304
|
SPECS_DIR_NAME,
|
|
@@ -5449,26 +6307,26 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
|
|
|
5449
6307
|
if (await FileSystemUtils.fileExists(specsDir)) {
|
|
5450
6308
|
await FileSystemUtils.removeDirectory(specsDir, true);
|
|
5451
6309
|
}
|
|
5452
|
-
const archiveDir =
|
|
6310
|
+
const archiveDir = path12.join(
|
|
5453
6311
|
".",
|
|
5454
6312
|
HERASPEC_DIR_NAME,
|
|
5455
6313
|
ARCHIVES_DIR_NAME
|
|
5456
6314
|
);
|
|
5457
6315
|
await FileSystemUtils.createDirectory(archiveDir);
|
|
5458
6316
|
const datePrefix = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
|
|
5459
|
-
const archivePath =
|
|
6317
|
+
const archivePath = path12.join(archiveDir, `${datePrefix}-${changeName}`);
|
|
5460
6318
|
await FileSystemUtils.createDirectory(archivePath);
|
|
5461
6319
|
await this.moveChangeToArchive(changePath, archivePath);
|
|
5462
6320
|
await FileSystemUtils.removeDirectory(changePath, true);
|
|
5463
|
-
spinner.succeed(
|
|
6321
|
+
spinner.succeed(chalk4.green(`Change "${changeName}" archived successfully`));
|
|
5464
6322
|
await this.autoLogToMemory(changeName, archivePath);
|
|
5465
6323
|
} catch (error) {
|
|
5466
|
-
spinner.fail(
|
|
6324
|
+
spinner.fail(chalk4.red(`Error: ${error.message}`));
|
|
5467
6325
|
throw error;
|
|
5468
6326
|
}
|
|
5469
6327
|
}
|
|
5470
6328
|
async mergeDeltaSpecs(changePath, changeName) {
|
|
5471
|
-
const deltaSpecsDir =
|
|
6329
|
+
const deltaSpecsDir = path12.join(
|
|
5472
6330
|
".",
|
|
5473
6331
|
HERASPEC_DIR_NAME,
|
|
5474
6332
|
SPECS_DIR_NAME,
|
|
@@ -5479,8 +6337,8 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
|
|
|
5479
6337
|
}
|
|
5480
6338
|
const deltaSpecs = await this.findDeltaSpecFiles(deltaSpecsDir);
|
|
5481
6339
|
for (const deltaSpec of deltaSpecs) {
|
|
5482
|
-
const relativePath =
|
|
5483
|
-
const targetSpecPath =
|
|
6340
|
+
const relativePath = path12.relative(deltaSpecsDir, deltaSpec.path);
|
|
6341
|
+
const targetSpecPath = path12.join(
|
|
5484
6342
|
".",
|
|
5485
6343
|
HERASPEC_DIR_NAME,
|
|
5486
6344
|
SPECS_DIR_NAME,
|
|
@@ -5493,7 +6351,7 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
|
|
|
5493
6351
|
if (await FileSystemUtils.fileExists(targetSpecPath)) {
|
|
5494
6352
|
targetContent = await FileSystemUtils.readFile(targetSpecPath);
|
|
5495
6353
|
}
|
|
5496
|
-
const fingerprintsPath =
|
|
6354
|
+
const fingerprintsPath = path12.join(changePath, "fingerprints.json");
|
|
5497
6355
|
let fingerprints = {};
|
|
5498
6356
|
if (await FileSystemUtils.fileExists(fingerprintsPath)) {
|
|
5499
6357
|
fingerprints = JSON.parse(await FileSystemUtils.readFile(fingerprintsPath));
|
|
@@ -5504,7 +6362,7 @@ This will archive "${changeName}" and merge delta specs into source specs.`);
|
|
|
5504
6362
|
const expectedHash = fingerprints[hashKey];
|
|
5505
6363
|
if (expectedHash) {
|
|
5506
6364
|
const currentReqBlock = this.extractRequirementBlock(targetContent, req.name);
|
|
5507
|
-
const currentHash = currentReqBlock ?
|
|
6365
|
+
const currentHash = currentReqBlock ? createHash2("sha256").update(currentReqBlock).digest("hex") : null;
|
|
5508
6366
|
if (currentHash !== expectedHash) {
|
|
5509
6367
|
throw new Error(
|
|
5510
6368
|
`Parallel Merge Conflict: The requirement "${req.name}" in ${relativePath} has been changed by someone else since you started this change.
|
|
@@ -5514,7 +6372,7 @@ Please run "heraspec sync ${changeName}" to update your base and resolve the con
|
|
|
5514
6372
|
}
|
|
5515
6373
|
}
|
|
5516
6374
|
const mergedContent = this.mergeDeltaIntoSpec(targetContent, delta, deltaSpec.name);
|
|
5517
|
-
await FileSystemUtils.createDirectory(
|
|
6375
|
+
await FileSystemUtils.createDirectory(path12.dirname(targetSpecPath));
|
|
5518
6376
|
await FileSystemUtils.writeFile(targetSpecPath, mergedContent);
|
|
5519
6377
|
}
|
|
5520
6378
|
}
|
|
@@ -5587,8 +6445,8 @@ ${req.description}
|
|
|
5587
6445
|
async moveChangeToArchive(sourcePath, archivePath) {
|
|
5588
6446
|
const entries = await FileSystemUtils.readDirectory(sourcePath);
|
|
5589
6447
|
for (const entry of entries) {
|
|
5590
|
-
const sourceEntry =
|
|
5591
|
-
const archiveEntry =
|
|
6448
|
+
const sourceEntry = path12.join(sourcePath, entry);
|
|
6449
|
+
const archiveEntry = path12.join(archivePath, entry);
|
|
5592
6450
|
const stats = await FileSystemUtils.stat(sourceEntry);
|
|
5593
6451
|
if (stats.isDirectory()) {
|
|
5594
6452
|
await FileSystemUtils.createDirectory(archiveEntry);
|
|
@@ -5602,7 +6460,7 @@ ${req.description}
|
|
|
5602
6460
|
const specs = [];
|
|
5603
6461
|
const entries = await FileSystemUtils.readDirectory(dir);
|
|
5604
6462
|
for (const entry of entries) {
|
|
5605
|
-
const entryPath =
|
|
6463
|
+
const entryPath = path12.join(dir, entry);
|
|
5606
6464
|
const stats = await FileSystemUtils.stat(entryPath);
|
|
5607
6465
|
if (stats.isDirectory()) {
|
|
5608
6466
|
const subSpecs = await this.findDeltaSpecFiles(
|
|
@@ -5612,7 +6470,7 @@ ${req.description}
|
|
|
5612
6470
|
specs.push(...subSpecs);
|
|
5613
6471
|
} else if (entry.endsWith(".md")) {
|
|
5614
6472
|
specs.push({
|
|
5615
|
-
name: prefix ||
|
|
6473
|
+
name: prefix || path12.basename(entry, ".md"),
|
|
5616
6474
|
path: entryPath
|
|
5617
6475
|
});
|
|
5618
6476
|
}
|
|
@@ -5621,18 +6479,18 @@ ${req.description}
|
|
|
5621
6479
|
}
|
|
5622
6480
|
async autoLogToMemory(changeName, archivePath) {
|
|
5623
6481
|
try {
|
|
5624
|
-
const memoryDbPath =
|
|
6482
|
+
const memoryDbPath = path12.join(".", HERASPEC_DIR_NAME, "memory", "heraspec-memory.db");
|
|
5625
6483
|
if (!await FileSystemUtils.fileExists(memoryDbPath)) {
|
|
5626
6484
|
return;
|
|
5627
6485
|
}
|
|
5628
6486
|
const { MemoryCommand: MemoryCommand2 } = await Promise.resolve().then(() => (init_memory(), memory_exports));
|
|
5629
6487
|
const memoryCmd = new MemoryCommand2();
|
|
5630
6488
|
let narrative = "";
|
|
5631
|
-
const proposalPath =
|
|
6489
|
+
const proposalPath = path12.join(archivePath, "proposal.md");
|
|
5632
6490
|
if (await FileSystemUtils.fileExists(proposalPath)) {
|
|
5633
6491
|
narrative = await FileSystemUtils.readFile(proposalPath);
|
|
5634
6492
|
}
|
|
5635
|
-
const tasksPath =
|
|
6493
|
+
const tasksPath = path12.join(archivePath, "tasks.md");
|
|
5636
6494
|
if (await FileSystemUtils.fileExists(tasksPath)) {
|
|
5637
6495
|
const tasksContent = await FileSystemUtils.readFile(tasksPath);
|
|
5638
6496
|
if (narrative) narrative += "\n\n---\n\n";
|
|
@@ -5656,10 +6514,10 @@ ${req.description}
|
|
|
5656
6514
|
|
|
5657
6515
|
// src/core/sync.ts
|
|
5658
6516
|
init_file_system();
|
|
5659
|
-
import
|
|
5660
|
-
import
|
|
6517
|
+
import path13 from "path";
|
|
6518
|
+
import chalk5 from "chalk";
|
|
5661
6519
|
import ora5 from "ora";
|
|
5662
|
-
import { createHash as
|
|
6520
|
+
import { createHash as createHash3 } from "crypto";
|
|
5663
6521
|
init_config();
|
|
5664
6522
|
import { readFileSync as readFileSync2 } from "fs";
|
|
5665
6523
|
var SyncCommand = class {
|
|
@@ -5670,7 +6528,7 @@ var SyncCommand = class {
|
|
|
5670
6528
|
process.exitCode = 1;
|
|
5671
6529
|
return;
|
|
5672
6530
|
}
|
|
5673
|
-
const changePath =
|
|
6531
|
+
const changePath = path13.join(".", HERASPEC_DIR_NAME, CHANGES_DIR_NAME, changeName);
|
|
5674
6532
|
if (!await FileSystemUtils.fileExists(changePath)) {
|
|
5675
6533
|
console.error(`Error: Change "${changeName}" not found at ${changePath}`);
|
|
5676
6534
|
process.exitCode = 1;
|
|
@@ -5678,25 +6536,25 @@ var SyncCommand = class {
|
|
|
5678
6536
|
}
|
|
5679
6537
|
const spinner = ora5(`Syncing fingerprints for "${changeName}"...`).start();
|
|
5680
6538
|
try {
|
|
5681
|
-
const fingerprintsPath =
|
|
6539
|
+
const fingerprintsPath = path13.join(changePath, "fingerprints.json");
|
|
5682
6540
|
let fingerprints = {};
|
|
5683
6541
|
if (await FileSystemUtils.fileExists(fingerprintsPath)) {
|
|
5684
6542
|
fingerprints = JSON.parse(readFileSync2(fingerprintsPath, "utf-8"));
|
|
5685
6543
|
} else {
|
|
5686
|
-
spinner.info(
|
|
6544
|
+
spinner.info(chalk5.blue(`No fingerprints.json found for "${changeName}". Run 'heraspec validate ${changeName}' to capture initial fingerprints.`));
|
|
5687
6545
|
return;
|
|
5688
6546
|
}
|
|
5689
|
-
const specsDir =
|
|
5690
|
-
const deltaSpecsDir =
|
|
6547
|
+
const specsDir = path13.join(".", HERASPEC_DIR_NAME, SPECS_DIR_NAME);
|
|
6548
|
+
const deltaSpecsDir = path13.join(specsDir, changeName);
|
|
5691
6549
|
if (!await FileSystemUtils.fileExists(deltaSpecsDir)) {
|
|
5692
|
-
spinner.info(
|
|
6550
|
+
spinner.info(chalk5.yellow(`No delta specs found for "${changeName}". Nothing to sync.`));
|
|
5693
6551
|
return;
|
|
5694
6552
|
}
|
|
5695
6553
|
const deltaSpecs = await this.findDeltaSpecs(deltaSpecsDir);
|
|
5696
6554
|
let updatedCount = 0;
|
|
5697
6555
|
for (const specPath of deltaSpecs) {
|
|
5698
|
-
const relativePath =
|
|
5699
|
-
const sourceSpecPath =
|
|
6556
|
+
const relativePath = path13.relative(path13.resolve(deltaSpecsDir), path13.resolve(specPath));
|
|
6557
|
+
const sourceSpecPath = path13.join(path13.resolve(specsDir), relativePath);
|
|
5700
6558
|
let sourceContent = "";
|
|
5701
6559
|
if (await FileSystemUtils.fileExists(sourceSpecPath)) {
|
|
5702
6560
|
sourceContent = readFileSync2(sourceSpecPath, "utf-8");
|
|
@@ -5710,21 +6568,21 @@ var SyncCommand = class {
|
|
|
5710
6568
|
const expectedHash = fingerprints[hashKey];
|
|
5711
6569
|
if (expectedHash) {
|
|
5712
6570
|
const currentReqBlock = this.extractRequirementBlock(sourceContent, req.name);
|
|
5713
|
-
const currentHash = currentReqBlock ?
|
|
6571
|
+
const currentHash = currentReqBlock ? createHash3("sha256").update(currentReqBlock).digest("hex") : null;
|
|
5714
6572
|
if (currentHash && currentHash !== expectedHash) {
|
|
5715
6573
|
spinner.stop();
|
|
5716
|
-
console.log(
|
|
6574
|
+
console.log(chalk5.yellow(`
|
|
5717
6575
|
\u26A0\uFE0F Conflict detected for requirement "${req.name}" in ${relativePath}`));
|
|
5718
|
-
console.log(
|
|
6576
|
+
console.log(chalk5.gray(`Source spec was updated after your change started.`));
|
|
5719
6577
|
fingerprints[hashKey] = currentHash;
|
|
5720
6578
|
updatedCount++;
|
|
5721
|
-
console.log(
|
|
6579
|
+
console.log(chalk5.green(`\u2713 Fingerprint updated. Please review the delta spec to ensure your modifications still apply correctly to the new source.`));
|
|
5722
6580
|
spinner.start();
|
|
5723
6581
|
} else if (!currentHash) {
|
|
5724
6582
|
spinner.stop();
|
|
5725
|
-
console.log(
|
|
6583
|
+
console.log(chalk5.red(`
|
|
5726
6584
|
\u274C Requirement "${req.name}" no longer exists in source spec ${relativePath}!`));
|
|
5727
|
-
console.log(
|
|
6585
|
+
console.log(chalk5.gray(`You should probably remove this requirement from your delta spec.`));
|
|
5728
6586
|
spinner.start();
|
|
5729
6587
|
}
|
|
5730
6588
|
}
|
|
@@ -5732,12 +6590,12 @@ var SyncCommand = class {
|
|
|
5732
6590
|
}
|
|
5733
6591
|
if (updatedCount > 0) {
|
|
5734
6592
|
await FileSystemUtils.writeFile(fingerprintsPath, JSON.stringify(fingerprints, null, 2));
|
|
5735
|
-
spinner.succeed(
|
|
6593
|
+
spinner.succeed(chalk5.green(`Synced ${updatedCount} fingerprint(s) successfully.`));
|
|
5736
6594
|
} else {
|
|
5737
|
-
spinner.succeed(
|
|
6595
|
+
spinner.succeed(chalk5.green("Already up to date. No conflicts detected."));
|
|
5738
6596
|
}
|
|
5739
6597
|
} catch (error) {
|
|
5740
|
-
spinner.fail(
|
|
6598
|
+
spinner.fail(chalk5.red(`Error: ${error.message}`));
|
|
5741
6599
|
process.exitCode = 1;
|
|
5742
6600
|
}
|
|
5743
6601
|
}
|
|
@@ -5745,7 +6603,7 @@ var SyncCommand = class {
|
|
|
5745
6603
|
const specs = [];
|
|
5746
6604
|
const entries = await FileSystemUtils.readDirectory(dir);
|
|
5747
6605
|
for (const entry of entries) {
|
|
5748
|
-
const entryPath =
|
|
6606
|
+
const entryPath = path13.join(dir, entry);
|
|
5749
6607
|
const stats = await FileSystemUtils.stat(entryPath);
|
|
5750
6608
|
if (stats.isDirectory()) {
|
|
5751
6609
|
const subSpecs = await this.findDeltaSpecs(entryPath);
|
|
@@ -5766,8 +6624,8 @@ var SyncCommand = class {
|
|
|
5766
6624
|
|
|
5767
6625
|
// src/core/validation/validator.ts
|
|
5768
6626
|
import { readFileSync as readFileSync3 } from "fs";
|
|
5769
|
-
import
|
|
5770
|
-
import { createHash as
|
|
6627
|
+
import path14 from "path";
|
|
6628
|
+
import { createHash as createHash4 } from "crypto";
|
|
5771
6629
|
init_file_system();
|
|
5772
6630
|
init_config();
|
|
5773
6631
|
var Validator = class {
|
|
@@ -5832,7 +6690,7 @@ var Validator = class {
|
|
|
5832
6690
|
const errors = [];
|
|
5833
6691
|
const warnings = [];
|
|
5834
6692
|
const suggestions = [];
|
|
5835
|
-
const proposalPath =
|
|
6693
|
+
const proposalPath = path14.join(changePath, "proposal.md");
|
|
5836
6694
|
if (!await FileSystemUtils.fileExists(proposalPath)) {
|
|
5837
6695
|
errors.push({
|
|
5838
6696
|
message: "Change must have a proposal.md file",
|
|
@@ -5848,7 +6706,7 @@ var Validator = class {
|
|
|
5848
6706
|
});
|
|
5849
6707
|
suggestions.push(`Create proposal.md file at ${proposalPath}`);
|
|
5850
6708
|
}
|
|
5851
|
-
const tasksPath =
|
|
6709
|
+
const tasksPath = path14.join(changePath, "tasks.md");
|
|
5852
6710
|
if (!await FileSystemUtils.fileExists(tasksPath)) {
|
|
5853
6711
|
warnings.push({
|
|
5854
6712
|
message: "Change has no tasks.md file",
|
|
@@ -5857,8 +6715,8 @@ var Validator = class {
|
|
|
5857
6715
|
autoFixable: false
|
|
5858
6716
|
});
|
|
5859
6717
|
}
|
|
5860
|
-
const changeName =
|
|
5861
|
-
const specsDir =
|
|
6718
|
+
const changeName = path14.basename(changePath);
|
|
6719
|
+
const specsDir = path14.join(
|
|
5862
6720
|
".",
|
|
5863
6721
|
HERASPEC_DIR_NAME,
|
|
5864
6722
|
SPECS_DIR_NAME,
|
|
@@ -5935,14 +6793,14 @@ var Validator = class {
|
|
|
5935
6793
|
}
|
|
5936
6794
|
}
|
|
5937
6795
|
extractNameFromPath(filePath) {
|
|
5938
|
-
const baseName =
|
|
5939
|
-
return baseName === "spec" ?
|
|
6796
|
+
const baseName = path14.basename(filePath, ".md");
|
|
6797
|
+
return baseName === "spec" ? path14.basename(path14.dirname(filePath)) : baseName;
|
|
5940
6798
|
}
|
|
5941
6799
|
async findDeltaSpecs(dir) {
|
|
5942
6800
|
const specs = [];
|
|
5943
6801
|
const entries = await FileSystemUtils.readDirectory(dir);
|
|
5944
6802
|
for (const entry of entries) {
|
|
5945
|
-
const entryPath =
|
|
6803
|
+
const entryPath = path14.join(dir, entry);
|
|
5946
6804
|
const stats = await FileSystemUtils.stat(entryPath);
|
|
5947
6805
|
if (stats.isDirectory()) {
|
|
5948
6806
|
const subSpecs = await this.findDeltaSpecs(entryPath);
|
|
@@ -5954,16 +6812,16 @@ var Validator = class {
|
|
|
5954
6812
|
return specs;
|
|
5955
6813
|
}
|
|
5956
6814
|
async captureFingerprints(changePath, deltaSpecPath, delta) {
|
|
5957
|
-
const changeName =
|
|
5958
|
-
const specsDir =
|
|
5959
|
-
const deltaSpecsDir =
|
|
5960
|
-
const relativePath =
|
|
5961
|
-
const sourceSpecPath =
|
|
6815
|
+
const changeName = path14.basename(changePath);
|
|
6816
|
+
const specsDir = path14.join(HERASPEC_DIR_NAME, SPECS_DIR_NAME);
|
|
6817
|
+
const deltaSpecsDir = path14.join(specsDir, changeName);
|
|
6818
|
+
const relativePath = path14.relative(path14.resolve(deltaSpecsDir), path14.resolve(deltaSpecPath));
|
|
6819
|
+
const sourceSpecPath = path14.join(path14.resolve(specsDir), relativePath);
|
|
5962
6820
|
let sourceContent = "";
|
|
5963
6821
|
if (await FileSystemUtils.fileExists(sourceSpecPath)) {
|
|
5964
6822
|
sourceContent = readFileSync3(sourceSpecPath, "utf-8");
|
|
5965
6823
|
}
|
|
5966
|
-
const fingerprintsPath =
|
|
6824
|
+
const fingerprintsPath = path14.join(changePath, "fingerprints.json");
|
|
5967
6825
|
let fingerprints = {};
|
|
5968
6826
|
if (await FileSystemUtils.fileExists(fingerprintsPath)) {
|
|
5969
6827
|
fingerprints = JSON.parse(readFileSync3(fingerprintsPath, "utf-8"));
|
|
@@ -5975,7 +6833,7 @@ var Validator = class {
|
|
|
5975
6833
|
if (!fingerprints[hashKey]) {
|
|
5976
6834
|
const reqBlock = this.extractRequirementBlock(sourceContent, req.name);
|
|
5977
6835
|
if (reqBlock) {
|
|
5978
|
-
fingerprints[hashKey] =
|
|
6836
|
+
fingerprints[hashKey] = createHash4("sha256").update(reqBlock).digest("hex");
|
|
5979
6837
|
updated = true;
|
|
5980
6838
|
}
|
|
5981
6839
|
}
|
|
@@ -6000,6 +6858,11 @@ var Validator = class {
|
|
|
6000
6858
|
return void 0;
|
|
6001
6859
|
}
|
|
6002
6860
|
};
|
|
6861
|
+
|
|
6862
|
+
// src/index.ts
|
|
6863
|
+
init_templates();
|
|
6864
|
+
init_ide_adapter();
|
|
6865
|
+
init_agents_composer();
|
|
6003
6866
|
export {
|
|
6004
6867
|
ARCHIVES_DIR_NAME,
|
|
6005
6868
|
ArchiveCommand,
|
|
@@ -6007,12 +6870,18 @@ export {
|
|
|
6007
6870
|
ChangeSchema,
|
|
6008
6871
|
DeltaRequirementSchema,
|
|
6009
6872
|
DeltaTypeSchema,
|
|
6873
|
+
HERASPEC_ADAPTER_END,
|
|
6874
|
+
HERASPEC_ADAPTER_START,
|
|
6010
6875
|
HERASPEC_DIR_NAME,
|
|
6011
6876
|
HERASPEC_MARKERS,
|
|
6877
|
+
HERASPEC_MIGRATION_MARKER,
|
|
6878
|
+
IDE_PROFILES,
|
|
6879
|
+
IdeAdapterManager,
|
|
6012
6880
|
InitCommand,
|
|
6013
6881
|
KNOWLEDGE_DIR_NAME,
|
|
6014
6882
|
ListCommand,
|
|
6015
6883
|
MEMORY_DIR_NAME,
|
|
6884
|
+
MarkdownParser,
|
|
6016
6885
|
PROJECT_TYPES,
|
|
6017
6886
|
ProjectTypeSchema,
|
|
6018
6887
|
RequirementSchema,
|
|
@@ -6023,6 +6892,20 @@ export {
|
|
|
6023
6892
|
SpecMetaSchema,
|
|
6024
6893
|
SpecSchema,
|
|
6025
6894
|
SyncCommand,
|
|
6026
|
-
|
|
6895
|
+
TemplateManager,
|
|
6896
|
+
Validator,
|
|
6897
|
+
appendMigratedCustomContent,
|
|
6898
|
+
buildAgentsComposePlan,
|
|
6899
|
+
computeNormalizedSha256,
|
|
6900
|
+
extractCustomRulesFromLegacyAgents,
|
|
6901
|
+
formatMigratedCustomContent,
|
|
6902
|
+
normalizeLineEndings,
|
|
6903
|
+
parseConfigYamlContent,
|
|
6904
|
+
parseSkillFrontmatter,
|
|
6905
|
+
readHeraspecState,
|
|
6906
|
+
readProjectMetadata,
|
|
6907
|
+
resolveBackupFilePath,
|
|
6908
|
+
toPosixRelative,
|
|
6909
|
+
writeHeraspecState
|
|
6027
6910
|
};
|
|
6028
6911
|
//# sourceMappingURL=index.js.map
|