framework-aidf 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +174 -0
- package/INSTALLATION.md +140 -0
- package/LICENSE +21 -0
- package/QODER.md +88 -0
- package/README.md +142 -2
- package/UTILISATION.md +188 -0
- package/assets/adapters/qoder/agents/aidf-orchestrator.md +30 -0
- package/assets/adapters/qoder/rules/00-core.md +28 -0
- package/assets/adapters/qoder/rules/10-security.md +33 -0
- package/assets/adapters/qoder/rules/20-context.md +39 -0
- package/assets/core/AGENTS.fragment.md +18 -0
- package/assets/core/AIDF.md +107 -0
- package/assets/docs/APPFLOW.md +66 -0
- package/assets/docs/BACKEND.md +71 -0
- package/assets/docs/CHANGELOG.md +25 -0
- package/assets/docs/CONVENTIONS.md +95 -0
- package/assets/docs/DECISIONS.md +60 -0
- package/assets/docs/PLAN.md +53 -0
- package/assets/docs/PRD.md +88 -0
- package/assets/docs/SECURITY.md +94 -0
- package/assets/docs/TRD.md +78 -0
- package/assets/docs/UI-UX.md +71 -0
- package/assets/docs/constitution.md +86 -0
- package/assets/hooks/audit.mjs +45 -0
- package/assets/hooks/session-context.mjs +53 -0
- package/assets/integrations/spec-kit/mapping.yaml +92 -0
- package/assets/knowledge/best-practices/testing.md +53 -0
- package/assets/knowledge/best-practices/web-dev-baseline.md +39 -0
- package/assets/knowledge/rules/api.md +45 -0
- package/assets/knowledge/rules/sql.md +44 -0
- package/assets/knowledge/rules/typescript.md +50 -0
- package/assets/knowledge/security-references/owasp-baseline.md +58 -0
- package/assets/registry/activation-map.yaml +83 -0
- package/assets/registry/dependencies.yaml +35 -0
- package/assets/registry/skills.yaml +541 -0
- package/assets/registry/sources.yaml +396 -0
- package/assets/schemas/architecture/v1.json +110 -0
- package/assets/schemas/constraints/v1.json +93 -0
- package/assets/schemas/decision/v1.json +106 -0
- package/assets/schemas/discovery/v1.json +91 -0
- package/assets/schemas/requirement/v1.json +136 -0
- package/assets/schemas/security/threat-model/v1.json +127 -0
- package/assets/schemas/test-plan/v1.json +108 -0
- package/assets/skills/aidf-architecture-review/SKILL.md +49 -0
- package/assets/skills/aidf-backend-implementation/SKILL.md +47 -0
- package/assets/skills/aidf-database-design/SKILL.md +48 -0
- package/assets/skills/aidf-devops-engineering/SKILL.md +41 -0
- package/assets/skills/aidf-documentation-maintenance/SKILL.md +41 -0
- package/assets/skills/aidf-frontend-implementation/SKILL.md +44 -0
- package/assets/skills/aidf-phase-transition/SKILL.md +48 -0
- package/assets/skills/aidf-product-analysis/SKILL.md +47 -0
- package/assets/skills/aidf-project-context/SKILL.md +57 -0
- package/assets/skills/aidf-requirements-engineering/SKILL.md +52 -0
- package/assets/skills/aidf-security-review/SKILL.md +57 -0
- package/assets/skills/aidf-testing-validation/SKILL.md +48 -0
- package/assets/skills/aidf-ui-ux-implementation/SKILL.md +43 -0
- package/assets/workflows/gates.yaml +232 -0
- package/assets/workflows/phases.yaml +161 -0
- package/bin/aidf.mjs +12 -0
- package/demo/run-demo.mjs +97 -0
- package/docs/aidf/ADR-001-artefacts-architectur.md +126 -0
- package/docs/aidf/ADR-002-requirements-registry.md +145 -0
- package/docs/aidf/ADR-003-traceability-chain.md +145 -0
- package/docs/aidf/ADR-004-markdown-generation.md +134 -0
- package/docs/aidf/ADR-005-validation-and-tests.md +170 -0
- package/docs/aidf/ADR-006-cli-commands.md +189 -0
- package/docs/aidf/ADR-007-compatibility-and-migration.md +119 -0
- package/docs/aidf/ADR-008-schema-versioning.md +115 -0
- package/docs/aidf/ADR-009-artefacts-scope.md +84 -0
- package/docs/aidf/ARCHITECTURE.md +137 -0
- package/docs/aidf/COMPATIBILITY.md +90 -0
- package/docs/aidf/DECISIONS.md +200 -0
- package/docs/aidf/FRAMEWORK.md +38 -0
- package/docs/aidf/IDE-QODER.md +61 -0
- package/docs/aidf/INSTALL.md +99 -0
- package/docs/aidf/INVENTORY.md +72 -0
- package/docs/aidf/L1-ARCHITECTURE-RAPPORT.md +353 -0
- package/docs/aidf/LIMITATIONS.md +69 -0
- package/docs/aidf/MATRICE-0.1.0-vers-0.2.0.md +155 -0
- package/docs/aidf/SECURITY.md +86 -0
- package/docs/aidf/SKILLS.md +78 -0
- package/docs/aidf/SPECKIT.md +67 -0
- package/docs/aidf/USAGE.md +113 -0
- package/docs/aidf/VALIDATION.md +55 -0
- package/package.json +37 -4
- package/src/cli.mjs +148 -0
- package/src/commands/artefacts.mjs +129 -0
- package/src/commands/config.mjs +130 -0
- package/src/commands/context.mjs +55 -0
- package/src/commands/decision.mjs +142 -0
- package/src/commands/design.mjs +141 -0
- package/src/commands/docs.mjs +133 -0
- package/src/commands/doctor.mjs +210 -0
- package/src/commands/evidence.mjs +178 -0
- package/src/commands/install.mjs +154 -0
- package/src/commands/release.mjs +214 -0
- package/src/commands/requirements.mjs +196 -0
- package/src/commands/resources.mjs +181 -0
- package/src/commands/scan.mjs +139 -0
- package/src/commands/security.mjs +97 -0
- package/src/commands/setup.mjs +68 -0
- package/src/commands/skills.mjs +204 -0
- package/src/commands/speckit.mjs +78 -0
- package/src/commands/tests.mjs +81 -0
- package/src/commands/traceability.mjs +116 -0
- package/src/commands/uninstall.mjs +238 -0
- package/src/commands/validate.mjs +84 -0
- package/src/commands/workflow.mjs +137 -0
- package/src/core/adapters/base.mjs +32 -0
- package/src/core/adapters/generic.mjs +70 -0
- package/src/core/adapters/index.mjs +24 -0
- package/src/core/adapters/opencode.mjs +115 -0
- package/src/core/adapters/qoder.mjs +228 -0
- package/src/core/artefacts/index.mjs +1 -0
- package/src/core/artefacts/validation.mjs +161 -0
- package/src/core/bootstrap.mjs +179 -0
- package/src/core/config.mjs +123 -0
- package/src/core/context.mjs +187 -0
- package/src/core/design-engineering/complexity-classifier.mjs +78 -0
- package/src/core/design-engineering/engine.mjs +197 -0
- package/src/core/design-engineering/fallback/mockups.mjs +221 -0
- package/src/core/design-engineering/fallback/wireframes.mjs +114 -0
- package/src/core/design-engineering/figma/validators.mjs +178 -0
- package/src/core/design-engineering/index.mjs +9 -0
- package/src/core/design-engineering/visual-parity/capture.mjs +172 -0
- package/src/core/detect.mjs +220 -0
- package/src/core/docsgen.mjs +175 -0
- package/src/core/evidence.mjs +210 -0
- package/src/core/installer.mjs +377 -0
- package/src/core/manifest.mjs +53 -0
- package/src/core/paths.mjs +94 -0
- package/src/core/requirements/index.mjs +13 -0
- package/src/core/requirements/registry.mjs +234 -0
- package/src/core/resource-inventory.mjs +434 -0
- package/src/core/resources.mjs +280 -0
- package/src/core/security/threat-model.mjs +235 -0
- package/src/core/skills.mjs +353 -0
- package/src/core/source-skills.mjs +213 -0
- package/src/core/speckit.mjs +195 -0
- package/src/core/technology-decision/analyzer-deterministic.mjs +240 -0
- package/src/core/technology-decision/engine.mjs +157 -0
- package/src/core/technology-decision/generator.mjs +204 -0
- package/src/core/technology-decision/index.mjs +17 -0
- package/src/core/technology-decision/options/index.mjs +10 -0
- package/src/core/testplan.mjs +176 -0
- package/src/core/traceability/chain.mjs +488 -0
- package/src/core/traceability/index.mjs +12 -0
- package/src/core/workflow.mjs +471 -0
- package/src/util/args.mjs +69 -0
- package/src/util/frontmatter.mjs +26 -0
- package/src/util/fsx.mjs +208 -0
- package/src/util/logger.mjs +74 -0
- package/src/util/text.mjs +66 -0
- package/src/util/yaml.mjs +379 -0
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
import { aidfPaths } from '../paths.mjs';
|
|
3
|
+
import { exists, writeJson, ensureDir, readJson } from '../../util/fsx.mjs';
|
|
4
|
+
import { detectProject } from '../detect.mjs';
|
|
5
|
+
import { loadConfig, defaultConfig } from '../config.mjs';
|
|
6
|
+
import { loadRequirementsRegistry } from '../requirements/registry.mjs';
|
|
7
|
+
import { collectArtefactFiles } from '../traceability/chain.mjs';
|
|
8
|
+
|
|
9
|
+
const SECRET_CANDIDATES = [
|
|
10
|
+
'.env', '.env.local', '.env.production', '.env.development',
|
|
11
|
+
'id_rsa', 'id_ed25519', '.npmrc', '.pypirc',
|
|
12
|
+
];
|
|
13
|
+
|
|
14
|
+
const AUTH_DEPENDENCIES = [
|
|
15
|
+
'passport', 'next-auth', '@auth/core', 'jsonwebtoken', 'jose',
|
|
16
|
+
'better-auth', 'lucia', 'auth0', '@clerk/nextjs', 'firebase-admin',
|
|
17
|
+
];
|
|
18
|
+
|
|
19
|
+
const WEB_FRAMEWORKS = ['Express', 'Fastify', 'Koa', 'Next.js', 'Nuxt', 'NestJS', 'Hono', 'Remix'];
|
|
20
|
+
|
|
21
|
+
async function listSecretFileNames(root) {
|
|
22
|
+
const names = [];
|
|
23
|
+
for (const name of SECRET_CANDIDATES) {
|
|
24
|
+
if (await exists(path.join(root, name))) names.push(name);
|
|
25
|
+
}
|
|
26
|
+
return names;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function nextThreatModelId(existingIds) {
|
|
30
|
+
let max = 0;
|
|
31
|
+
for (const id of existingIds) {
|
|
32
|
+
const m = /^TM-(\d+)$/.exec(id);
|
|
33
|
+
if (m) max = Math.max(max, parseInt(m[1], 10));
|
|
34
|
+
}
|
|
35
|
+
return `TM-${String(max + 1).padStart(3, '0')}`;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Generate a deterministic STRIDE threat model artefact from detected project
|
|
40
|
+
* facts. Everything emitted is derived from real detection results; threats
|
|
41
|
+
* that cannot be grounded in detected surface are not invented.
|
|
42
|
+
*/
|
|
43
|
+
export async function generateThreatModel(root, options = {}) {
|
|
44
|
+
const now = new Date().toISOString();
|
|
45
|
+
const project = await detectProject(root);
|
|
46
|
+
const config = await loadConfig(root).catch(() => defaultConfig({}));
|
|
47
|
+
const requirements = await loadRequirementsRegistry(root);
|
|
48
|
+
const secretFiles = await listSecretFileNames(root);
|
|
49
|
+
const files = await collectArtefactFiles(root);
|
|
50
|
+
|
|
51
|
+
const hasPackageJson = Boolean(project.packageJson);
|
|
52
|
+
const deps = options.dependencies ?? null;
|
|
53
|
+
const allDeps = deps ?? {};
|
|
54
|
+
const hasAuth = AUTH_DEPENDENCIES.some((d) => allDeps[d]);
|
|
55
|
+
const isWeb = project.frameworks.some((f) => WEB_FRAMEWORKS.includes(f));
|
|
56
|
+
|
|
57
|
+
const assets = [];
|
|
58
|
+
const pushAsset = (a) => { if (!assets.some((x) => x.id === a.id)) assets.push(a); };
|
|
59
|
+
pushAsset({
|
|
60
|
+
id: 'AST-SRC', name: 'Source code and project configuration',
|
|
61
|
+
classification: 'internal', owner: 'project', storage: 'git repository',
|
|
62
|
+
});
|
|
63
|
+
if (isWeb || hasPackageJson) {
|
|
64
|
+
pushAsset({
|
|
65
|
+
id: 'AST-DATA', name: 'Application data',
|
|
66
|
+
classification: 'confidential', owner: 'project', storage: 'project data stores',
|
|
67
|
+
});
|
|
68
|
+
}
|
|
69
|
+
pushAsset({
|
|
70
|
+
id: 'AST-SEC', name: 'Secrets and credentials',
|
|
71
|
+
classification: 'restricted', owner: 'project',
|
|
72
|
+
storage: secretFiles.length ? `files: ${secretFiles.join(', ')}` : 'secret stores / env vars',
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
const trustBoundaries = [
|
|
76
|
+
{
|
|
77
|
+
id: 'TB-EXT', name: 'External actors to application',
|
|
78
|
+
components: ['external users', 'AI coding agents', 'third-party APIs'],
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
id: 'TB-APP', name: 'Application boundary',
|
|
82
|
+
components: ['application runtime', ...(isWeb ? ['HTTP/API surface'] : [])],
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
id: 'TB-DATA', name: 'Data boundary',
|
|
86
|
+
components: ['databases', 'file system', 'secret stores'],
|
|
87
|
+
},
|
|
88
|
+
];
|
|
89
|
+
|
|
90
|
+
const threats = [];
|
|
91
|
+
const addThreat = (t) => threats.push({
|
|
92
|
+
likelihood: 'medium', impact: 'medium', status: 'open',
|
|
93
|
+
...t, id: `THR-${String(threats.length + 1).padStart(3, '0')}`,
|
|
94
|
+
});
|
|
95
|
+
|
|
96
|
+
if (secretFiles.length > 0) {
|
|
97
|
+
addThreat({
|
|
98
|
+
name: 'Secret material exposure',
|
|
99
|
+
description: `Secret-like files present at project root: ${secretFiles.join(', ')}. Content was not read.`,
|
|
100
|
+
stride: 'Information Disclosure', asset: 'AST-SEC',
|
|
101
|
+
likelihood: 'medium', impact: 'high',
|
|
102
|
+
mitigation: 'Verify files are git-ignored, rotate any committed secrets, and use a secret manager.',
|
|
103
|
+
status: 'open',
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
if (hasPackageJson) {
|
|
108
|
+
addThreat({
|
|
109
|
+
name: 'Supply-chain tampering via dependencies',
|
|
110
|
+
description: 'Project declares npm dependencies; a compromised or typosquatted package could alter behaviour.',
|
|
111
|
+
stride: 'Tampering', asset: 'AST-SRC',
|
|
112
|
+
mitigation: 'Pin versions, commit the lockfile, run dependency audits in CI.',
|
|
113
|
+
status: 'open',
|
|
114
|
+
});
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
if (isWeb) {
|
|
118
|
+
addThreat({
|
|
119
|
+
name: 'Unauthenticated remote access',
|
|
120
|
+
description: 'A web-facing surface was detected; without verified authentication, actors may reach protected functionality.',
|
|
121
|
+
stride: 'Spoofing', asset: 'AST-DATA',
|
|
122
|
+
mitigation: hasAuth
|
|
123
|
+
? `Authentication dependency detected (${AUTH_DEPENDENCIES.find((d) => allDeps[d])}); verify coverage of all routes.`
|
|
124
|
+
: 'No authentication dependency detected; define an authn/authz strategy before exposing routes.',
|
|
125
|
+
status: hasAuth ? 'mitigated' : 'open',
|
|
126
|
+
});
|
|
127
|
+
addThreat({
|
|
128
|
+
name: 'Service denial via unbounded input',
|
|
129
|
+
description: 'Public endpoints may be flooded with requests or oversized payloads.',
|
|
130
|
+
stride: 'Denial of Service', asset: 'AST-DATA',
|
|
131
|
+
mitigation: 'Rate limiting, body-size limits and timeouts at the edge or framework layer.',
|
|
132
|
+
status: 'open',
|
|
133
|
+
});
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
if (project.git.repository && project.git.dirty > 0) {
|
|
137
|
+
addThreat({
|
|
138
|
+
name: 'Uncommitted work loss or tampering',
|
|
139
|
+
description: `${project.git.dirty} uncommitted change(s) detected; work in progress is not protected by history.`,
|
|
140
|
+
stride: 'Repudiation', asset: 'AST-SRC',
|
|
141
|
+
mitigation: 'Commit or stash work before releases; keep the working tree reviewable.',
|
|
142
|
+
status: 'open',
|
|
143
|
+
});
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
addThreat({
|
|
147
|
+
name: 'Agent tool misuse elevating privileges',
|
|
148
|
+
description: 'AI agents operate with filesystem and shell access; misconfigured permissions could allow destructive actions.',
|
|
149
|
+
stride: 'Elevation of Privilege', asset: 'AST-SRC',
|
|
150
|
+
mitigation: config.security?.allowCommandExecution
|
|
151
|
+
? 'Command execution is ENABLED in .aidf/config.json; restrict allowedCommands and require human approval for risky operations.'
|
|
152
|
+
: 'Command execution is disabled by default (security.allowCommandExecution=false); keep it that way unless justified.',
|
|
153
|
+
status: config.security?.allowCommandExecution ? 'open' : 'mitigated',
|
|
154
|
+
});
|
|
155
|
+
|
|
156
|
+
const requirementIds = (requirements.requirements ?? [])
|
|
157
|
+
.filter((r) => r.status !== 'BLOCKED')
|
|
158
|
+
.map((r) => r.id);
|
|
159
|
+
|
|
160
|
+
const artefact = {
|
|
161
|
+
id: nextThreatModelId(files.map((f) => f.id)),
|
|
162
|
+
schemaVersion: '1.0.0',
|
|
163
|
+
type: 'security-threat-model',
|
|
164
|
+
createdAt: now,
|
|
165
|
+
updatedAt: now,
|
|
166
|
+
status: 'DRAFT',
|
|
167
|
+
assets,
|
|
168
|
+
threats,
|
|
169
|
+
trustBoundaries,
|
|
170
|
+
source: {
|
|
171
|
+
type: 'generated',
|
|
172
|
+
author: 'aidf',
|
|
173
|
+
createdAt: now,
|
|
174
|
+
generator: 'security-threat-model@0.2.0',
|
|
175
|
+
},
|
|
176
|
+
links: {
|
|
177
|
+
references: requirementIds,
|
|
178
|
+
},
|
|
179
|
+
validation: {
|
|
180
|
+
schemaVersion: '1.0.0',
|
|
181
|
+
timestamp: now,
|
|
182
|
+
valid: true,
|
|
183
|
+
errors: [],
|
|
184
|
+
warnings: ['Generated threat model requires human review before VALIDATED.'],
|
|
185
|
+
},
|
|
186
|
+
detection: {
|
|
187
|
+
frameworks: project.frameworks,
|
|
188
|
+
languages: project.languages.map((l) => l.language),
|
|
189
|
+
secretFiles,
|
|
190
|
+
hasAuth,
|
|
191
|
+
isWeb,
|
|
192
|
+
generatedBy: 'detectProject',
|
|
193
|
+
},
|
|
194
|
+
};
|
|
195
|
+
|
|
196
|
+
return artefact;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
export async function saveThreatModel(root, artefact) {
|
|
200
|
+
const file = aidfPaths(root).artefacts['security/threat-model'];
|
|
201
|
+
await ensureDir(path.dirname(file));
|
|
202
|
+
await writeJson(file, artefact);
|
|
203
|
+
return file;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
export async function loadThreatModel(root) {
|
|
207
|
+
const file = aidfPaths(root).artefacts['security/threat-model'];
|
|
208
|
+
return readJson(file, null);
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
export function renderThreatModelMarkdown(tm) {
|
|
212
|
+
const lines = [];
|
|
213
|
+
lines.push(`# Threat Model ${tm.id}`);
|
|
214
|
+
lines.push('');
|
|
215
|
+
lines.push(`- Status: ${tm.status}`);
|
|
216
|
+
lines.push(`- Generated: ${tm.createdAt}`);
|
|
217
|
+
lines.push('');
|
|
218
|
+
lines.push('## Assets');
|
|
219
|
+
lines.push('');
|
|
220
|
+
lines.push('| ID | Name | Classification | Storage |');
|
|
221
|
+
lines.push('|---|---|---|---|');
|
|
222
|
+
for (const a of tm.assets ?? []) lines.push(`| ${a.id} | ${a.name} | ${a.classification} | ${a.storage} |`);
|
|
223
|
+
lines.push('');
|
|
224
|
+
lines.push('## Threats (STRIDE)');
|
|
225
|
+
lines.push('');
|
|
226
|
+
lines.push('| ID | Name | STRIDE | Asset | Likelihood | Impact | Status | Mitigation |');
|
|
227
|
+
lines.push('|---|---|---|---|---|---|---|---|');
|
|
228
|
+
for (const t of tm.threats ?? []) {
|
|
229
|
+
lines.push(`| ${t.id} | ${t.name} | ${t.stride} | ${t.asset} | ${t.likelihood} | ${t.impact} | ${t.status} | ${t.mitigation} |`);
|
|
230
|
+
}
|
|
231
|
+
lines.push('');
|
|
232
|
+
lines.push('> Generated deterministically from project detection. Human review required before VALIDATED.');
|
|
233
|
+
lines.push('');
|
|
234
|
+
return `${lines.join('\n')}\n`;
|
|
235
|
+
}
|
|
@@ -0,0 +1,353 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
import os from 'node:os';
|
|
3
|
+
import fsp from 'node:fs/promises';
|
|
4
|
+
import { parseYaml, dumpYaml } from '../util/yaml.mjs';
|
|
5
|
+
import { splitFrontmatter } from '../util/frontmatter.mjs';
|
|
6
|
+
import { readText, readDirSafe, exists, sha256File, sha256Text, writeAtomic, toPosix, resolveInside } from '../util/fsx.mjs';
|
|
7
|
+
import { aidfPaths, FRAMEWORK_ROOT } from './paths.mjs';
|
|
8
|
+
|
|
9
|
+
export const SKILL_STATUSES = [
|
|
10
|
+
'DISCOVERED', 'VALIDATED', 'REGISTERED', 'AVAILABLE', 'BLOCKED', 'INCOMPATIBLE',
|
|
11
|
+
];
|
|
12
|
+
|
|
13
|
+
const NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
|
|
14
|
+
|
|
15
|
+
export async function loadSkillCatalog(frameworkRoot = FRAMEWORK_ROOT) {
|
|
16
|
+
const file = path.join(frameworkRoot, 'assets', 'registry', 'skills.yaml');
|
|
17
|
+
const parsed = parseYaml(await readText(file));
|
|
18
|
+
return parsed?.skills ?? [];
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export async function loadDependencies(frameworkRoot = FRAMEWORK_ROOT) {
|
|
22
|
+
const file = path.join(frameworkRoot, 'assets', 'registry', 'dependencies.yaml');
|
|
23
|
+
const parsed = parseYaml(await readText(file));
|
|
24
|
+
return parsed?.skills ?? {};
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export async function loadActivationMap(frameworkRoot = FRAMEWORK_ROOT) {
|
|
28
|
+
const file = path.join(frameworkRoot, 'assets', 'registry', 'activation-map.yaml');
|
|
29
|
+
return parseYaml(await readText(file));
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function validateSkillContent(content, options = {}) {
|
|
33
|
+
const errors = [];
|
|
34
|
+
const warnings = [];
|
|
35
|
+
const { frontmatter, body } = splitFrontmatter(content);
|
|
36
|
+
if (!frontmatter) {
|
|
37
|
+
errors.push('Missing YAML frontmatter (--- ... ---).');
|
|
38
|
+
return { valid: false, errors, warnings, frontmatter: null, body };
|
|
39
|
+
}
|
|
40
|
+
const name = frontmatter.name;
|
|
41
|
+
const description = frontmatter.description;
|
|
42
|
+
if (typeof name !== 'string' || !NAME_RE.test(name)) {
|
|
43
|
+
errors.push('Frontmatter "name" must match ^[a-z0-9][a-z0-9-]{0,63}$.');
|
|
44
|
+
}
|
|
45
|
+
if (typeof description !== 'string' || description.trim() === '') {
|
|
46
|
+
errors.push('Frontmatter "description" is required.');
|
|
47
|
+
} else if (description.length > 1024) {
|
|
48
|
+
errors.push(`Frontmatter "description" is ${description.length} chars (max 1024).`);
|
|
49
|
+
}
|
|
50
|
+
if (typeof body !== 'string' || body.trim().length < 20) {
|
|
51
|
+
warnings.push('Skill body is very short; instructions may be insufficient.');
|
|
52
|
+
}
|
|
53
|
+
if (options.directoryName && name && options.directoryName !== name) {
|
|
54
|
+
warnings.push(`Directory name "${options.directoryName}" does not match skill name "${name}".`);
|
|
55
|
+
}
|
|
56
|
+
return {
|
|
57
|
+
valid: errors.length === 0,
|
|
58
|
+
errors,
|
|
59
|
+
warnings,
|
|
60
|
+
frontmatter,
|
|
61
|
+
body,
|
|
62
|
+
name,
|
|
63
|
+
description,
|
|
64
|
+
aidf: frontmatter?.metadata?.aidf ?? null,
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export async function discoverSkills(roots) {
|
|
69
|
+
const discovered = [];
|
|
70
|
+
const seenPaths = new Set();
|
|
71
|
+
for (const root of roots) {
|
|
72
|
+
if (!root || !(await exists(root))) continue;
|
|
73
|
+
const stack = [{ dir: root, depth: 0 }];
|
|
74
|
+
while (stack.length > 0) {
|
|
75
|
+
const { dir, depth } = stack.pop();
|
|
76
|
+
if (depth > 4) continue;
|
|
77
|
+
const entries = await readDirSafe(dir);
|
|
78
|
+
for (const entry of entries) {
|
|
79
|
+
if (entry.name === 'node_modules' || entry.name === '.git') continue;
|
|
80
|
+
const full = path.join(dir, entry.name);
|
|
81
|
+
if (entry.isDirectory()) {
|
|
82
|
+
stack.push({ dir: full, depth: depth + 1 });
|
|
83
|
+
} else if (entry.isFile() && entry.name === 'SKILL.md') {
|
|
84
|
+
const posix = toPosix(full);
|
|
85
|
+
if (seenPaths.has(posix)) continue;
|
|
86
|
+
seenPaths.add(posix);
|
|
87
|
+
try {
|
|
88
|
+
const content = await readText(full);
|
|
89
|
+
const validation = validateSkillContent(content, { directoryName: path.basename(dir) });
|
|
90
|
+
discovered.push({
|
|
91
|
+
path: posix,
|
|
92
|
+
root: toPosix(root),
|
|
93
|
+
name: validation.name ?? path.basename(dir),
|
|
94
|
+
description: validation.description ?? '',
|
|
95
|
+
aidf: validation.aidf,
|
|
96
|
+
errors: validation.errors,
|
|
97
|
+
warnings: validation.warnings,
|
|
98
|
+
valid: validation.valid,
|
|
99
|
+
hash: await sha256File(full),
|
|
100
|
+
size: Buffer.byteLength(content, 'utf8'),
|
|
101
|
+
});
|
|
102
|
+
} catch (error) {
|
|
103
|
+
discovered.push({
|
|
104
|
+
path: posix,
|
|
105
|
+
root: toPosix(root),
|
|
106
|
+
name: path.basename(dir),
|
|
107
|
+
errors: [`Cannot read skill: ${error.message}`],
|
|
108
|
+
warnings: [],
|
|
109
|
+
valid: false,
|
|
110
|
+
});
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
const byName = new Map();
|
|
117
|
+
for (const skill of discovered) {
|
|
118
|
+
const list = byName.get(skill.name) ?? [];
|
|
119
|
+
list.push(skill);
|
|
120
|
+
byName.set(skill.name, list);
|
|
121
|
+
}
|
|
122
|
+
for (const [name, list] of byName) {
|
|
123
|
+
if (list.length > 1) {
|
|
124
|
+
for (const skill of list) {
|
|
125
|
+
skill.warnings.push(`Duplicate skill name "${name}" found in ${list.length} locations.`);
|
|
126
|
+
skill.duplicate = true;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
return discovered;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
export function defaultSkillRoots(root, frameworkRoot = FRAMEWORK_ROOT) {
|
|
134
|
+
const parent = path.dirname(frameworkRoot);
|
|
135
|
+
return [
|
|
136
|
+
path.join(root, '.qoder', 'skills'),
|
|
137
|
+
path.join(root, '.opencode', 'skills'),
|
|
138
|
+
path.join(root, '.aidf', 'skills'),
|
|
139
|
+
path.join(root, '.claude', 'skills'),
|
|
140
|
+
path.join(root, '.agents', 'skills'),
|
|
141
|
+
path.join(root, '.agent', 'skills'),
|
|
142
|
+
path.join(root, 'skills', 'skills'),
|
|
143
|
+
path.join(os.homedir(), '.qoder', 'skills'),
|
|
144
|
+
path.join(parent, 'skills', 'skills'),
|
|
145
|
+
path.join(parent, 'superpowers', 'skills'),
|
|
146
|
+
];
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
export async function loadProjectSkillRegistry(root) {
|
|
150
|
+
const file = path.join(aidfPaths(root).registry, 'skills.yaml');
|
|
151
|
+
if (!(await exists(file))) {
|
|
152
|
+
return { schemaVersion: 1, updatedAt: null, skills: [] };
|
|
153
|
+
}
|
|
154
|
+
return parseYaml(await readText(file)) ?? { schemaVersion: 1, skills: [] };
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
export async function saveProjectSkillRegistry(root, registry) {
|
|
158
|
+
const file = path.join(aidfPaths(root).registry, 'skills.yaml');
|
|
159
|
+
registry.updatedAt = new Date().toISOString();
|
|
160
|
+
await writeAtomic(file, dumpYaml(registry));
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
export async function buildSkillRegistry(root, options = {}) {
|
|
164
|
+
const frameworkRoot = options.frameworkRoot ?? FRAMEWORK_ROOT;
|
|
165
|
+
const catalog = await loadSkillCatalog(frameworkRoot);
|
|
166
|
+
const deps = await loadDependencies(frameworkRoot);
|
|
167
|
+
const roots = [...defaultSkillRoots(root, frameworkRoot), ...(options.extraRoots ?? [])];
|
|
168
|
+
const discovered = await discoverSkills(roots);
|
|
169
|
+
const entries = [];
|
|
170
|
+
const adapter = options.adapter ?? 'qoder';
|
|
171
|
+
|
|
172
|
+
for (const catalogSkill of catalog) {
|
|
173
|
+
const name = catalogSkill.name;
|
|
174
|
+
const candidates = discovered.filter((s) => s.name === name);
|
|
175
|
+
const compatible = (catalogSkill.ide ?? ['generic']).includes(adapter)
|
|
176
|
+
|| (catalogSkill.ide ?? []).includes('generic');
|
|
177
|
+
let base;
|
|
178
|
+
if (candidates.length === 0) {
|
|
179
|
+
base = {
|
|
180
|
+
status: 'BLOCKED',
|
|
181
|
+
path: null,
|
|
182
|
+
hash: null,
|
|
183
|
+
errors: ['Skill file is not installed for any adapter.'],
|
|
184
|
+
warnings: [],
|
|
185
|
+
};
|
|
186
|
+
} else {
|
|
187
|
+
const chosen = candidates[0];
|
|
188
|
+
let status = chosen.valid ? 'VALIDATED' : 'INCOMPATIBLE';
|
|
189
|
+
if (status === 'VALIDATED' && !compatible) status = 'INCOMPATIBLE';
|
|
190
|
+
if (status === 'VALIDATED' && chosen.duplicate) status = 'BLOCKED';
|
|
191
|
+
base = {
|
|
192
|
+
status,
|
|
193
|
+
path: chosen.path,
|
|
194
|
+
hash: chosen.hash,
|
|
195
|
+
errors: chosen.errors,
|
|
196
|
+
warnings: chosen.warnings,
|
|
197
|
+
};
|
|
198
|
+
}
|
|
199
|
+
entries.push({
|
|
200
|
+
id: catalogSkill.id,
|
|
201
|
+
name,
|
|
202
|
+
version: catalogSkill.version,
|
|
203
|
+
source: 'builtin',
|
|
204
|
+
description: catalogSkill.description,
|
|
205
|
+
phases: catalogSkill.phases ?? [],
|
|
206
|
+
documents: catalogSkill.documents ?? [],
|
|
207
|
+
triggers: catalogSkill.triggers ?? [],
|
|
208
|
+
ide: catalogSkill.ide ?? [],
|
|
209
|
+
dependencies: deps[catalogSkill.id]?.requires ?? [],
|
|
210
|
+
_baseStatus: base.status,
|
|
211
|
+
...base,
|
|
212
|
+
});
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
// Resolve dependencies independently of catalog order.
|
|
216
|
+
const byId = new Map(entries.map((e) => [e.id, e]));
|
|
217
|
+
for (let pass = 0; pass < entries.length + 1; pass += 1) {
|
|
218
|
+
let changed = false;
|
|
219
|
+
for (const entry of entries) {
|
|
220
|
+
if (entry._baseStatus !== 'VALIDATED') continue;
|
|
221
|
+
const required = entry.dependencies ?? [];
|
|
222
|
+
if (required.length === 0) {
|
|
223
|
+
if (entry.status !== 'AVAILABLE') {
|
|
224
|
+
entry.status = 'AVAILABLE';
|
|
225
|
+
changed = true;
|
|
226
|
+
}
|
|
227
|
+
continue;
|
|
228
|
+
}
|
|
229
|
+
const depStatuses = required.map((dep) => byId.get(dep)?.status ?? 'MISSING');
|
|
230
|
+
const allReady = depStatuses.every((s) => s === 'AVAILABLE');
|
|
231
|
+
const next = allReady ? 'AVAILABLE' : 'BLOCKED';
|
|
232
|
+
if (entry.status !== next) {
|
|
233
|
+
entry.status = next;
|
|
234
|
+
if (!allReady) {
|
|
235
|
+
entry.errors = [
|
|
236
|
+
...(entry.errors ?? []).filter((e) => !e.startsWith('Dependencies not ready')),
|
|
237
|
+
`Dependencies not ready: ${required.filter((dep, i) => depStatuses[i] !== 'AVAILABLE').join(', ')}`,
|
|
238
|
+
];
|
|
239
|
+
}
|
|
240
|
+
changed = true;
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
if (!changed) break;
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
const external = discovered
|
|
247
|
+
.filter((s) => !catalog.some((c) => c.name === s.name))
|
|
248
|
+
.map((s) => {
|
|
249
|
+
const inQoder = toPosix(s.path).includes('/.qoder/skills/');
|
|
250
|
+
return {
|
|
251
|
+
id: s.aidf?.id ?? s.name,
|
|
252
|
+
name: s.name,
|
|
253
|
+
version: s.aidf?.version ?? 'unknown',
|
|
254
|
+
status: s.valid ? (s.duplicate ? 'BLOCKED' : inQoder ? 'AVAILABLE' : 'VALIDATED') : 'INCOMPATIBLE',
|
|
255
|
+
source: 'external',
|
|
256
|
+
path: s.path,
|
|
257
|
+
description: s.description,
|
|
258
|
+
phases: s.aidf?.phases ?? [],
|
|
259
|
+
documents: s.aidf?.documents ?? [],
|
|
260
|
+
triggers: s.aidf?.triggers ?? [],
|
|
261
|
+
ide: ['qoder', 'generic'],
|
|
262
|
+
hash: s.hash,
|
|
263
|
+
errors: s.errors,
|
|
264
|
+
warnings: s.warnings,
|
|
265
|
+
};
|
|
266
|
+
});
|
|
267
|
+
|
|
268
|
+
return {
|
|
269
|
+
schemaVersion: 1,
|
|
270
|
+
updatedAt: new Date().toISOString(),
|
|
271
|
+
adapter,
|
|
272
|
+
skills: [...entries, ...external].map(({ _baseStatus, ...rest }) => rest),
|
|
273
|
+
summary: summarizeSkills([...entries, ...external]),
|
|
274
|
+
};
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
export function summarizeSkills(skills) {
|
|
278
|
+
const summary = {};
|
|
279
|
+
for (const status of SKILL_STATUSES) summary[status] = 0;
|
|
280
|
+
for (const skill of skills) summary[skill.status] = (summary[skill.status] ?? 0) + 1;
|
|
281
|
+
summary.total = skills.length;
|
|
282
|
+
return summary;
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
export function findDependencyCycles(deps) {
|
|
286
|
+
const cycles = [];
|
|
287
|
+
const visiting = new Set();
|
|
288
|
+
const visited = new Set();
|
|
289
|
+
const stack = [];
|
|
290
|
+
function visit(node) {
|
|
291
|
+
if (visiting.has(node)) {
|
|
292
|
+
const index = stack.indexOf(node);
|
|
293
|
+
cycles.push([...stack.slice(index), node]);
|
|
294
|
+
return;
|
|
295
|
+
}
|
|
296
|
+
if (visited.has(node)) return;
|
|
297
|
+
visiting.add(node);
|
|
298
|
+
stack.push(node);
|
|
299
|
+
for (const dep of deps[node]?.requires ?? []) visit(dep);
|
|
300
|
+
stack.pop();
|
|
301
|
+
visiting.delete(node);
|
|
302
|
+
visited.add(node);
|
|
303
|
+
}
|
|
304
|
+
for (const node of Object.keys(deps)) visit(node);
|
|
305
|
+
return cycles;
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
export async function validateRegistry(root, registry, deps) {
|
|
309
|
+
const errors = [];
|
|
310
|
+
const warnings = [];
|
|
311
|
+
const cycles = findDependencyCycles(deps);
|
|
312
|
+
for (const cycle of cycles) errors.push(`Dependency cycle: ${cycle.join(' -> ')}`);
|
|
313
|
+
const byId = new Map(registry.skills.map((s) => [s.id, s]));
|
|
314
|
+
for (const skill of registry.skills) {
|
|
315
|
+
if (skill.source !== 'builtin') continue;
|
|
316
|
+
if (skill.status === 'INCOMPATIBLE' || skill.status === 'BLOCKED') {
|
|
317
|
+
errors.push(`${skill.id}: ${skill.status} (${(skill.errors ?? []).join('; ') || 'dependency or compatibility issue'})`);
|
|
318
|
+
}
|
|
319
|
+
for (const dep of deps[skill.id]?.requires ?? []) {
|
|
320
|
+
if (!byId.has(dep)) errors.push(`${skill.id}: missing dependency "${dep}"`);
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
for (const skill of registry.skills) {
|
|
324
|
+
if (skill.duplicate) warnings.push(`${skill.name}: duplicate name`);
|
|
325
|
+
}
|
|
326
|
+
return { valid: errors.length === 0, errors, warnings, cycles };
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
export async function linkSkill(root, registry, skillId, options = {}) {
|
|
330
|
+
const skill = registry.skills.find((s) => s.id === skillId || s.name === skillId);
|
|
331
|
+
if (!skill) throw new Error(`Unknown skill: ${skillId}`);
|
|
332
|
+
if (!skill.path) throw new Error(`Skill "${skillId}" has no discovered path.`);
|
|
333
|
+
if (skill.source === 'builtin') {
|
|
334
|
+
throw new Error('Built-in skills are installed by the adapter; no link is required.');
|
|
335
|
+
}
|
|
336
|
+
const target = path.resolve(skill.path, '..');
|
|
337
|
+
const adapter = options.adapter ?? 'qoder';
|
|
338
|
+
const linkPath = adapter === 'opencode'
|
|
339
|
+
? path.join('.opencode', 'skills', skill.name)
|
|
340
|
+
: path.join('.qoder', 'skills', skill.name);
|
|
341
|
+
const abs = resolveInside(root, linkPath);
|
|
342
|
+
if (await exists(abs)) {
|
|
343
|
+
return { status: 'UNCHANGED', path: linkPath, target: toPosix(target) };
|
|
344
|
+
}
|
|
345
|
+
if (options.dryRun) return { status: 'WOULD_LINK', path: linkPath, target: toPosix(target) };
|
|
346
|
+
await fsp.mkdir(path.dirname(abs), { recursive: true });
|
|
347
|
+
await fsp.symlink(target, abs, process.platform === 'win32' ? 'junction' : 'dir');
|
|
348
|
+
return { status: 'LINKED', path: linkPath, target: toPosix(target) };
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
export function hashSkillContent(content) {
|
|
352
|
+
return sha256Text(content);
|
|
353
|
+
}
|