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,213 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
import fsp from 'node:fs/promises';
|
|
3
|
+
import { ensureDir, toPosix, exists, resolveInside, writeJson } from '../util/fsx.mjs';
|
|
4
|
+
import { licensePolicy, isSecretPath } from './resource-inventory.mjs';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Skills Engine v2 — source skill catalogue.
|
|
8
|
+
*
|
|
9
|
+
* 0.1.0 only knew the 13 built-in skills. This module turns the verified
|
|
10
|
+
* resource inventory into a catalogue of every third-party SKILL.md, with an
|
|
11
|
+
* explicit status derived from licence policy and validation. Nothing is
|
|
12
|
+
* copied or executed implicitly: enabling a skill is an explicit command.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
export const SOURCE_SKILL_STATUSES = [
|
|
16
|
+
'AVAILABLE', 'INDEX_ONLY', 'BLOCKED', 'DUPLICATE', 'INCOMPATIBLE',
|
|
17
|
+
];
|
|
18
|
+
|
|
19
|
+
const EXECUTABLE_RE = /\.(sh|bash|ps1|bat|cmd|exe|com|msi|jar|py|rb|pl)$/i;
|
|
20
|
+
|
|
21
|
+
export function catalogSourceSkills(inventoryResults) {
|
|
22
|
+
const entries = [];
|
|
23
|
+
for (const resource of inventoryResults) {
|
|
24
|
+
const policy = licensePolicy(resource.license);
|
|
25
|
+
for (const skill of resource.skills ?? []) {
|
|
26
|
+
let status;
|
|
27
|
+
let reason;
|
|
28
|
+
if (!skill.valid) {
|
|
29
|
+
status = 'INCOMPATIBLE';
|
|
30
|
+
reason = (skill.errors ?? []).join('; ') || 'Invalid SKILL.md.';
|
|
31
|
+
} else if (policy.redistribution === 'blocked' || policy.id === 'unknown') {
|
|
32
|
+
status = 'INDEX_ONLY';
|
|
33
|
+
reason = 'Licence unknown or blocked: indexed by reference, never copied.';
|
|
34
|
+
} else if (policy.copy !== true) {
|
|
35
|
+
status = 'INDEX_ONLY';
|
|
36
|
+
reason = policy.note;
|
|
37
|
+
} else {
|
|
38
|
+
status = 'AVAILABLE';
|
|
39
|
+
reason = 'Permissive licence: copy allowed with attribution.';
|
|
40
|
+
}
|
|
41
|
+
entries.push({
|
|
42
|
+
id: skill.name,
|
|
43
|
+
name: skill.name,
|
|
44
|
+
resource: resource.id,
|
|
45
|
+
resourcePath: resource.path,
|
|
46
|
+
license: policy.id,
|
|
47
|
+
redistribution: policy.redistribution,
|
|
48
|
+
path: skill.path,
|
|
49
|
+
sha256: skill.sha256,
|
|
50
|
+
description: skill.description,
|
|
51
|
+
valid: skill.valid,
|
|
52
|
+
status,
|
|
53
|
+
reason,
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
return markDuplicates(entries);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export function markDuplicates(entries) {
|
|
61
|
+
const byName = new Map();
|
|
62
|
+
for (const entry of entries) {
|
|
63
|
+
const list = byName.get(entry.id) ?? [];
|
|
64
|
+
list.push(entry);
|
|
65
|
+
byName.set(entry.id, list);
|
|
66
|
+
}
|
|
67
|
+
for (const [name, list] of byName) {
|
|
68
|
+
if (list.length < 2) continue;
|
|
69
|
+
const canonical = pickCanonical(list);
|
|
70
|
+
for (const entry of list) {
|
|
71
|
+
if (entry === canonical) {
|
|
72
|
+
entry.canonical = true;
|
|
73
|
+
entry.duplicateOf = null;
|
|
74
|
+
continue;
|
|
75
|
+
}
|
|
76
|
+
entry.canonical = false;
|
|
77
|
+
entry.duplicateOf = `${canonical.resource}:${canonical.path}`;
|
|
78
|
+
if (entry.status === 'AVAILABLE') {
|
|
79
|
+
entry.status = 'DUPLICATE';
|
|
80
|
+
entry.reason = `Duplicate of ${canonical.resource}:${canonical.path}.`;
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
void name;
|
|
84
|
+
}
|
|
85
|
+
return entries;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function pickCanonical(list) {
|
|
89
|
+
const rank = (entry) => {
|
|
90
|
+
const copy = entry.status === 'AVAILABLE' ? 0 : 1;
|
|
91
|
+
const valid = entry.valid ? 0 : 1;
|
|
92
|
+
return copy * 10 + valid * 5 + entry.path.length / 1000;
|
|
93
|
+
};
|
|
94
|
+
return [...list].sort((a, b) => rank(a) - rank(b))[0];
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
const DEFAULT_TRIGGERS = {
|
|
98
|
+
security: ['owasp', 'security', 'audit', 'vulnerability', 'threat'],
|
|
99
|
+
accessibility: ['rgaa', 'accessib', 'a11y', 'wcag'],
|
|
100
|
+
design: ['design', 'ui', 'ux', 'wireframe', 'figma'],
|
|
101
|
+
testing: ['test', 'tdd', 'verification'],
|
|
102
|
+
documentation: ['docs', 'documentation', 'article'],
|
|
103
|
+
};
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Select source skills relevant to a task. Selection is deterministic:
|
|
107
|
+
* it lowercases the task, matches known triggers, and never picks a blocked
|
|
108
|
+
* or index-only skill for execution.
|
|
109
|
+
*/
|
|
110
|
+
export function selectSourceSkills(entries, task = '', options = {}) {
|
|
111
|
+
const text = String(task).toLowerCase();
|
|
112
|
+
const limit = options.limit ?? 12;
|
|
113
|
+
const matched = [];
|
|
114
|
+
for (const entry of entries) {
|
|
115
|
+
if (entry.status !== 'AVAILABLE' && entry.status !== 'DUPLICATE') continue;
|
|
116
|
+
const haystack = `${entry.id} ${entry.description}`.toLowerCase();
|
|
117
|
+
let score = 0;
|
|
118
|
+
for (const [group, keywords] of Object.entries(DEFAULT_TRIGGERS)) {
|
|
119
|
+
if (!keywords.some((k) => text.includes(k))) continue;
|
|
120
|
+
if (keywords.some((k) => haystack.includes(k)) || haystack.includes(group)) score += 2;
|
|
121
|
+
}
|
|
122
|
+
if (text && haystack.includes(text.trim())) score += 3;
|
|
123
|
+
if (score > 0) matched.push({ ...entry, score });
|
|
124
|
+
}
|
|
125
|
+
return matched.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, limit);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
export function summarizeSourceSkills(entries) {
|
|
129
|
+
const summary = {};
|
|
130
|
+
for (const status of SOURCE_SKILL_STATUSES) summary[status] = 0;
|
|
131
|
+
for (const entry of entries) summary[entry.status] = (summary[entry.status] ?? 0) + 1;
|
|
132
|
+
summary.total = entries.length;
|
|
133
|
+
summary.unique = new Set(entries.map((e) => e.id)).size;
|
|
134
|
+
summary.canonicalAvailable = entries.filter((e) => e.canonical && e.status === 'AVAILABLE').length;
|
|
135
|
+
return summary;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function isExecutable(rel) {
|
|
139
|
+
return EXECUTABLE_RE.test(rel);
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Copy one source skill directory into a target directory.
|
|
144
|
+
* Only regular support files are copied; executable scripts are refused unless
|
|
145
|
+
* allowScripts is explicitly true. Secret-like files are never copied.
|
|
146
|
+
*/
|
|
147
|
+
export async function copySourceSkill(entry, inventory, targetDir, options = {}) {
|
|
148
|
+
if (!entry || entry.status === 'INDEX_ONLY' || entry.status === 'BLOCKED') {
|
|
149
|
+
return { status: 'BLOCKED', reason: entry?.reason ?? 'Skill is not copyable.' };
|
|
150
|
+
}
|
|
151
|
+
const resource = inventory.resources.find((r) => r.id === entry.resource);
|
|
152
|
+
if (!resource || !resource.path) {
|
|
153
|
+
return { status: 'BLOCKED', reason: 'Resource path is unknown.' };
|
|
154
|
+
}
|
|
155
|
+
if (!resource.licensePolicy?.copy) {
|
|
156
|
+
return { status: 'BLOCKED', reason: `Licence ${resource.license} does not allow copying.` };
|
|
157
|
+
}
|
|
158
|
+
const skillDir = path.posix.dirname(entry.path);
|
|
159
|
+
const prefix = `${skillDir}/`;
|
|
160
|
+
const members = resource.files.filter((file) => file.path.startsWith(prefix));
|
|
161
|
+
const copied = [];
|
|
162
|
+
const skipped = [];
|
|
163
|
+
for (const file of members) {
|
|
164
|
+
if (isSecretPath(file.path)) {
|
|
165
|
+
skipped.push({ path: file.path, reason: 'secret' });
|
|
166
|
+
continue;
|
|
167
|
+
}
|
|
168
|
+
if (isExecutable(file.path) && !options.allowScripts) {
|
|
169
|
+
skipped.push({ path: file.path, reason: 'executable' });
|
|
170
|
+
continue;
|
|
171
|
+
}
|
|
172
|
+
const rel = file.path.slice(prefix.length);
|
|
173
|
+
const destination = path.join(targetDir, rel);
|
|
174
|
+
await ensureDir(path.dirname(destination));
|
|
175
|
+
await fsp.copyFile(path.join(resource.path, file.path), destination);
|
|
176
|
+
copied.push(toPosix(destination));
|
|
177
|
+
}
|
|
178
|
+
await writeJson(path.join(targetDir, 'AIDF-SOURCE.json'), {
|
|
179
|
+
schemaVersion: 1,
|
|
180
|
+
resource: entry.resource,
|
|
181
|
+
skill: entry.id,
|
|
182
|
+
license: entry.license,
|
|
183
|
+
sourcePath: entry.path,
|
|
184
|
+
sha256: entry.sha256,
|
|
185
|
+
copiedAt: new Date().toISOString(),
|
|
186
|
+
scriptsCopied: Boolean(options.allowScripts),
|
|
187
|
+
note: 'Copied from an external resource. The resource remains untrusted data.',
|
|
188
|
+
});
|
|
189
|
+
return { status: 'COPIED', target: toPosix(targetDir), files: copied.length, skipped };
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
export async function loadSourceSkillCatalog(root) {
|
|
193
|
+
const file = path.join(root, '.aidf', 'registry', 'source-skills.json');
|
|
194
|
+
return (await exists(file)) ? JSON.parse(await fsp.readFile(file, 'utf8')) : null;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
export async function saveSourceSkillCatalog(root, entries) {
|
|
198
|
+
const file = path.join(root, '.aidf', 'registry', 'source-skills.json');
|
|
199
|
+
const payload = {
|
|
200
|
+
schemaVersion: 1,
|
|
201
|
+
generatedAt: new Date().toISOString(),
|
|
202
|
+
summary: summarizeSourceSkills(entries),
|
|
203
|
+
skills: entries,
|
|
204
|
+
};
|
|
205
|
+
await writeJson(file, payload);
|
|
206
|
+
return payload;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
export function skillInstallTarget(root, adapter, id) {
|
|
210
|
+
if (adapter === 'opencode') return resolveInside(root, path.posix.join('.opencode', 'skills', id));
|
|
211
|
+
if (adapter === 'qoder') return resolveInside(root, path.posix.join('.qoder', 'skills', id));
|
|
212
|
+
return resolveInside(root, path.posix.join('.aidf', 'skills', id));
|
|
213
|
+
}
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
import { parseYaml } from '../util/yaml.mjs';
|
|
3
|
+
import { readText, exists, writeAtomic, ensureDir, sha256Text } from '../util/fsx.mjs';
|
|
4
|
+
import { FRAMEWORK_ROOT } from './paths.mjs';
|
|
5
|
+
import { runTool } from './detect.mjs';
|
|
6
|
+
|
|
7
|
+
export async function loadSpecKitMapping(frameworkRoot = FRAMEWORK_ROOT) {
|
|
8
|
+
const file = path.join(frameworkRoot, 'assets', 'integrations', 'spec-kit', 'mapping.yaml');
|
|
9
|
+
return parseYaml(await readText(file));
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export async function specKitStatus(root, options = {}) {
|
|
13
|
+
const mapping = await loadSpecKitMapping(options.frameworkRoot);
|
|
14
|
+
const specifyDir = path.join(root, '.specify');
|
|
15
|
+
const present = await exists(specifyDir);
|
|
16
|
+
const constitutionPath = path.join(specifyDir, 'memory', 'constitution.md');
|
|
17
|
+
const constitutionPresent = await exists(constitutionPath);
|
|
18
|
+
const templates = await exists(path.join(specifyDir, 'templates'));
|
|
19
|
+
const qoderSkills = path.join(root, '.qoder', 'skills');
|
|
20
|
+
const integrationSkills = [];
|
|
21
|
+
if (await exists(qoderSkills)) {
|
|
22
|
+
const { readDirSafe } = await import('../util/fsx.mjs');
|
|
23
|
+
const entries = await readDirSafe(qoderSkills);
|
|
24
|
+
for (const entry of entries) {
|
|
25
|
+
if (entry.isDirectory() && /^speckit[.-]/.test(entry.name)) integrationSkills.push(entry.name);
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
const cli = await runTool(options.specifyPath ?? 'specify', ['--version']);
|
|
29
|
+
let constitutionSync = 'NOT_APPLICABLE';
|
|
30
|
+
if (constitutionPresent) {
|
|
31
|
+
const text = await readText(constitutionPath);
|
|
32
|
+
const match = /<!-- AIDF:SOURCE-HASH:([a-f0-9]+) -->/.exec(text);
|
|
33
|
+
if (match) {
|
|
34
|
+
const source = await readText(path.join(root, '.aidf', 'docs', 'constitution.md'));
|
|
35
|
+
constitutionSync = sha256Text(source) === match[1] ? 'IN_SYNC' : 'OUTDATED';
|
|
36
|
+
} else {
|
|
37
|
+
constitutionSync = 'EXTERNAL';
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
return {
|
|
41
|
+
present,
|
|
42
|
+
specifyDir: present ? '.specify' : null,
|
|
43
|
+
templates,
|
|
44
|
+
constitutionPresent,
|
|
45
|
+
constitutionSync,
|
|
46
|
+
integrationSkills,
|
|
47
|
+
integrationConfigured: integrationSkills.length > 0,
|
|
48
|
+
cli: {
|
|
49
|
+
available: cli.ok,
|
|
50
|
+
path: options.specifyPath ?? 'specify',
|
|
51
|
+
version: cli.ok ? cli.stdout.split(/\r?\n/)[0] : null,
|
|
52
|
+
},
|
|
53
|
+
expectedIntegration: mapping?.specKit?.integration?.key ?? 'qodercli',
|
|
54
|
+
mapping: mapping?.mapping ?? [],
|
|
55
|
+
status: present
|
|
56
|
+
? (templates ? 'PRESENT' : 'PARTIAL')
|
|
57
|
+
: 'ABSENT',
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export async function initSpecKit(root, options = {}) {
|
|
62
|
+
const status = await specKitStatus(root, options);
|
|
63
|
+
if (status.present) {
|
|
64
|
+
return { status: 'UNCHANGED', reason: '.specify/ already exists; AIDF does not reinitialize it.' };
|
|
65
|
+
}
|
|
66
|
+
if (!status.cli.available) {
|
|
67
|
+
return { status: 'BLOCKED', reason: 'The `specify` CLI is not installed. Install specify-cli and retry.' };
|
|
68
|
+
}
|
|
69
|
+
const args = ['init', '--here', '--integration', options.integration ?? 'qodercli', '--ignore-agent-tools', '--non-interactive'];
|
|
70
|
+
// `specify init --here` refuses a non-empty directory in --non-interactive
|
|
71
|
+
// mode. An installed project is never empty, so AIDF asks for an explicit
|
|
72
|
+
// opt-in (`--specify-force`) instead of passing --force silently.
|
|
73
|
+
if (!options.dryRun) {
|
|
74
|
+
const { readDirSafe } = await import('../util/fsx.mjs');
|
|
75
|
+
const entries = await readDirSafe(root);
|
|
76
|
+
if (entries.length > 0 && !options.specifyForce) {
|
|
77
|
+
return {
|
|
78
|
+
status: 'BLOCKED',
|
|
79
|
+
reason: 'The project directory is not empty; specify init requires --force to merge. Re-run with --specify-force to explicitly allow Spec Kit to merge into it.',
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
if (options.specifyForce) args.push('--force');
|
|
83
|
+
}
|
|
84
|
+
if (options.dryRun) {
|
|
85
|
+
return { status: 'WOULD_RUN', command: `specify ${args.join(' ')}` };
|
|
86
|
+
}
|
|
87
|
+
if (!options.allowExec) {
|
|
88
|
+
return { status: 'BLOCKED', reason: 'Running the Spec Kit initializer requires --allow-exec.' };
|
|
89
|
+
}
|
|
90
|
+
const result = await runTool(options.specifyPath ?? 'specify', args, { cwd: root, timeout: 180000 });
|
|
91
|
+
if (!result.ok) {
|
|
92
|
+
return { status: 'FAILED', reason: result.stderr || result.message, command: `specify ${args.join(' ')}` };
|
|
93
|
+
}
|
|
94
|
+
return { status: 'CREATED', command: `specify ${args.join(' ')}`, output: result.stdout };
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
export async function syncSpecKit(root, options = {}) {
|
|
98
|
+
const status = await specKitStatus(root, options);
|
|
99
|
+
if (!status.present) {
|
|
100
|
+
return { status: 'NOT_APPLICABLE', reason: '.specify/ does not exist; run `aidf speckit init` first.' };
|
|
101
|
+
}
|
|
102
|
+
const sourcePath = path.join(root, '.aidf', 'docs', 'constitution.md');
|
|
103
|
+
const source = await readText(sourcePath);
|
|
104
|
+
const hash = sha256Text(source);
|
|
105
|
+
const targetPath = path.join(root, '.specify', 'memory', 'constitution.md');
|
|
106
|
+
const targetExists = await exists(targetPath);
|
|
107
|
+
const results = [];
|
|
108
|
+
|
|
109
|
+
if (targetExists) {
|
|
110
|
+
const target = await readText(targetPath);
|
|
111
|
+
const match = /<!-- AIDF:SOURCE-HASH:([a-f0-9]+) -->/.exec(target);
|
|
112
|
+
if (!match) {
|
|
113
|
+
results.push({
|
|
114
|
+
status: 'CONFLICT',
|
|
115
|
+
path: '.specify/memory/constitution.md',
|
|
116
|
+
reason: 'Spec Kit already has its own constitution. AIDF will not overwrite it; merge manually or move it aside.',
|
|
117
|
+
});
|
|
118
|
+
} else if (match[1] === hash) {
|
|
119
|
+
results.push({ status: 'UNCHANGED', path: '.specify/memory/constitution.md' });
|
|
120
|
+
} else if (options.dryRun) {
|
|
121
|
+
results.push({ status: 'WOULD_UPDATE', path: '.specify/memory/constitution.md' });
|
|
122
|
+
} else {
|
|
123
|
+
await writeAtomic(targetPath, generatedConstitution(source, hash));
|
|
124
|
+
results.push({ status: 'UPDATED', path: '.specify/memory/constitution.md' });
|
|
125
|
+
}
|
|
126
|
+
} else if (options.adopt) {
|
|
127
|
+
if (options.dryRun) {
|
|
128
|
+
results.push({ status: 'WOULD_CREATE', path: '.specify/memory/constitution.md' });
|
|
129
|
+
} else {
|
|
130
|
+
await ensureDir(path.dirname(targetPath));
|
|
131
|
+
await writeAtomic(targetPath, generatedConstitution(source, hash));
|
|
132
|
+
results.push({ status: 'CREATED', path: '.specify/memory/constitution.md' });
|
|
133
|
+
}
|
|
134
|
+
} else {
|
|
135
|
+
results.push({
|
|
136
|
+
status: 'NOT_INSTALLED',
|
|
137
|
+
path: '.specify/memory/constitution.md',
|
|
138
|
+
reason: 'No Spec Kit constitution exists. Re-run with --adopt to create a generated copy.',
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
// The mapping document is AIDF-owned: it is recreated when the AIDF
|
|
143
|
+
// constitution hash changes, and left untouched otherwise.
|
|
144
|
+
const mappingPath = path.join(root, '.specify', 'aidf', 'mapping.md');
|
|
145
|
+
if (await exists(mappingPath)) {
|
|
146
|
+
const currentMapping = await readText(mappingPath);
|
|
147
|
+
if (currentMapping.includes(`AIDF constitution hash: \`${hash}\``)) {
|
|
148
|
+
results.push({ status: 'UNCHANGED', path: '.specify/aidf/mapping.md' });
|
|
149
|
+
} else if (options.dryRun) {
|
|
150
|
+
results.push({ status: 'WOULD_WRITE', path: '.specify/aidf/mapping.md' });
|
|
151
|
+
} else {
|
|
152
|
+
await ensureDir(path.dirname(mappingPath));
|
|
153
|
+
await writeAtomic(mappingPath, renderMapping(status.mapping, hash));
|
|
154
|
+
results.push({ status: 'UPDATED', path: '.specify/aidf/mapping.md' });
|
|
155
|
+
}
|
|
156
|
+
} else if (options.dryRun) {
|
|
157
|
+
results.push({ status: 'WOULD_WRITE', path: '.specify/aidf/mapping.md' });
|
|
158
|
+
} else {
|
|
159
|
+
await ensureDir(path.dirname(mappingPath));
|
|
160
|
+
await writeAtomic(mappingPath, renderMapping(status.mapping, hash));
|
|
161
|
+
results.push({ status: 'CREATED', path: '.specify/aidf/mapping.md' });
|
|
162
|
+
}
|
|
163
|
+
return { status: results.some((r) => r.status === 'CONFLICT') ? 'CONFLICT' : 'OK', results, hash };
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
function generatedConstitution(source, hash) {
|
|
167
|
+
const body = source.replace(/^---[\s\S]*?---\n/, '');
|
|
168
|
+
return `<!-- AIDF:SOURCE-HASH:${hash} -->
|
|
169
|
+
<!-- Generated by AIDF from .aidf/docs/constitution.md. Do not edit this copy; edit the source and run \`aidf speckit sync\`. -->
|
|
170
|
+
|
|
171
|
+
${body.trim()}
|
|
172
|
+
`;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
function renderMapping(mapping, hash) {
|
|
176
|
+
const lines = [];
|
|
177
|
+
lines.push('# AIDF ↔ Spec Kit Mapping');
|
|
178
|
+
lines.push('');
|
|
179
|
+
lines.push(`- Generated: ${new Date().toISOString()}`);
|
|
180
|
+
lines.push(`- AIDF constitution hash: \`${hash}\``);
|
|
181
|
+
lines.push('');
|
|
182
|
+
lines.push('AIDF owns product-wide durable truth. Spec Kit owns feature-level change artefacts.');
|
|
183
|
+
lines.push('');
|
|
184
|
+
lines.push('| AIDF | AIDF path | Spec Kit | Spec Kit path | Owner |');
|
|
185
|
+
lines.push('|---|---|---|---|---|');
|
|
186
|
+
for (const row of mapping) {
|
|
187
|
+
lines.push(`| ${row.aidf} | \`${row.aidfPath}\` | ${row.specKit} | \`${row.specKitPath}\` | ${row.owner} |`);
|
|
188
|
+
}
|
|
189
|
+
lines.push('');
|
|
190
|
+
lines.push('## Rule');
|
|
191
|
+
lines.push('');
|
|
192
|
+
lines.push('Do not copy a fact into both places. A feature spec references PRD requirement IDs; it does not restate the PRD.');
|
|
193
|
+
lines.push('');
|
|
194
|
+
return `${lines.join('\n')}\n`;
|
|
195
|
+
}
|
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
import { FRAMEWORKS, databases, servers, cloud } from '../technology-decision/options/index.mjs';
|
|
2
|
+
|
|
3
|
+
export const HARD_CONSTRAINTS = {
|
|
4
|
+
BUDGET: 'budget',
|
|
5
|
+
PLATFORM: 'platform',
|
|
6
|
+
LICENSE: 'license',
|
|
7
|
+
FEATURES: 'features',
|
|
8
|
+
COMPLIANCE: 'compliance'
|
|
9
|
+
};
|
|
10
|
+
|
|
11
|
+
export const SOFT_CONSTRAINTS = {
|
|
12
|
+
SKILL_MATCH: 'skillMatch',
|
|
13
|
+
ECOSYSTEM: 'ecosystem',
|
|
14
|
+
COMMUNITY: 'community',
|
|
15
|
+
SCALABILITY: 'scalability',
|
|
16
|
+
MAINTENANCE: 'maintenance'
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Validate hard constraints against technology options.
|
|
21
|
+
* Eliminates options that don't meet hard requirements.
|
|
22
|
+
*/
|
|
23
|
+
export async function validateHardConstraints(options, projectContext) {
|
|
24
|
+
const validOptions = [];
|
|
25
|
+
const eliminated = [];
|
|
26
|
+
|
|
27
|
+
for (const option of options) {
|
|
28
|
+
const violations = [];
|
|
29
|
+
|
|
30
|
+
// Budget check
|
|
31
|
+
if (projectContext.budget && option.costs) {
|
|
32
|
+
if (option.costs.estimatedCost > projectContext.budget.max) {
|
|
33
|
+
violations.push({
|
|
34
|
+
constraint: HARD_CONSTRAINTS.BUDGET,
|
|
35
|
+
optionValue: option.costs.estimatedCost,
|
|
36
|
+
required: projectContext.budget.max,
|
|
37
|
+
reason: `Option cost ${option.costs.estimatedCost} exceeds budget ${projectContext.budget.max} ${projectContext.budget.currency || 'USD'}`
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// Platform check
|
|
43
|
+
if (projectContext.platform && option.platform) {
|
|
44
|
+
const missing = projectContext.platform.filter(
|
|
45
|
+
p => !option.platform.includes(p)
|
|
46
|
+
);
|
|
47
|
+
if (missing.length > 0) {
|
|
48
|
+
violations.push({
|
|
49
|
+
constraint: HARD_CONSTRAINTS.PLATFORM,
|
|
50
|
+
optionValue: option.platform,
|
|
51
|
+
required: projectContext.platform,
|
|
52
|
+
reason: `Option platform ${option.platform} missing required: ${missing.join(', ')}`
|
|
53
|
+
});
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
// License check
|
|
58
|
+
if (projectContext.license && option.license) {
|
|
59
|
+
if (!projectContext.license.includes(option.license)) {
|
|
60
|
+
violations.push({
|
|
61
|
+
constraint: HARD_CONSTRAINTS.LICENSE,
|
|
62
|
+
optionValue: option.license,
|
|
63
|
+
required: projectContext.license,
|
|
64
|
+
reason: `Option license ${option.license} not in acceptable list`
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// Feature check
|
|
70
|
+
if (projectContext.features && option.features?.required) {
|
|
71
|
+
const missing = option.features.required.filter(
|
|
72
|
+
f => !projectContext.features.includes(f)
|
|
73
|
+
);
|
|
74
|
+
if (missing.length > 0) {
|
|
75
|
+
violations.push({
|
|
76
|
+
constraint: HARD_CONSTRAINTS.FEATURES,
|
|
77
|
+
optionValue: option.features.required,
|
|
78
|
+
required: projectContext.features,
|
|
79
|
+
reason: `Option missing required features: ${missing.join(', ')}`
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// Compliance check
|
|
85
|
+
if (projectContext.compliance && option.compliance) {
|
|
86
|
+
const missingCompliance = projectContext.compliance.filter(
|
|
87
|
+
c => !option.compliance.includes(c)
|
|
88
|
+
);
|
|
89
|
+
if (missingCompliance.length > 0) {
|
|
90
|
+
violations.push({
|
|
91
|
+
constraint: HARD_CONSTRAINTS.COMPLIANCE,
|
|
92
|
+
optionValue: option.compliance,
|
|
93
|
+
required: projectContext.compliance,
|
|
94
|
+
reason: `Option missing compliance: ${missingCompliance.join(', ')}`
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
if (violations.length === 0) {
|
|
100
|
+
validOptions.push(option);
|
|
101
|
+
} else {
|
|
102
|
+
eliminated.push({ option: option.id, violations });
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
return { validOptions, eliminated };
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Calculate soft constraint satisfaction scores.
|
|
111
|
+
*/
|
|
112
|
+
export function calculateSoftConstraints(options, projectContext) {
|
|
113
|
+
return options.map(option => {
|
|
114
|
+
const scores = {};
|
|
115
|
+
|
|
116
|
+
// Skill match
|
|
117
|
+
if (projectContext.skills && option.maintenance?.skillRequirements) {
|
|
118
|
+
const skillCount = option.maintenance.skillRequirements.length;
|
|
119
|
+
if (skillCount === 0) {
|
|
120
|
+
scores.skillMatch = 1.0;
|
|
121
|
+
} else {
|
|
122
|
+
const matchingSkills = projectContext.skills.filter(s =>
|
|
123
|
+
option.maintenance.skillRequirements.includes(s)
|
|
124
|
+
);
|
|
125
|
+
scores.skillMatch = matchingSkills.length / skillCount;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
// Ecosystem quality
|
|
130
|
+
if (option.ecosystem?.documentationQuality) {
|
|
131
|
+
const qualityMap = {
|
|
132
|
+
'poor': 0.2,
|
|
133
|
+
'fair': 0.4,
|
|
134
|
+
'good': 0.7,
|
|
135
|
+
'excellent': 1.0
|
|
136
|
+
};
|
|
137
|
+
scores.ecosystem = qualityMap[option.ecosystem.documentationQuality] || 0.5;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
// Community size
|
|
141
|
+
if (option.ecosystem?.communitySize) {
|
|
142
|
+
const sizeMap = {
|
|
143
|
+
'small': 0.3,
|
|
144
|
+
'medium': 0.5,
|
|
145
|
+
'large': 0.7,
|
|
146
|
+
'huge': 1.0
|
|
147
|
+
};
|
|
148
|
+
scores.community = sizeMap[option.ecosystem.communitySize] || 0.5;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
// Scalability match
|
|
152
|
+
if (projectContext.scalability) {
|
|
153
|
+
if (projectContext.scalability.horizontal && option.scalability?.horizontal) {
|
|
154
|
+
scores.scalability = 1.0;
|
|
155
|
+
} else if (projectContext.scalability.horizontal && !option.scalability?.horizontal) {
|
|
156
|
+
scores.scalability = 0.2;
|
|
157
|
+
} else if (projectContext.scalability.vertical && option.scalability?.vertical) {
|
|
158
|
+
scores.scalability = 1.0;
|
|
159
|
+
} else {
|
|
160
|
+
scores.scalability = 0.7;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// Maintenance complexity
|
|
165
|
+
if (option.maintenance?.complexity) {
|
|
166
|
+
const complexityMap = {
|
|
167
|
+
'simple': 1.0,
|
|
168
|
+
'moderate': 0.7,
|
|
169
|
+
'complex': 0.4
|
|
170
|
+
};
|
|
171
|
+
scores.maintenance = complexityMap[option.maintenance.complexity] || 0.7;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
// Calculate total score (average of all scores)
|
|
175
|
+
const scoreValues = Object.values(scores);
|
|
176
|
+
scores.totalScore = scoreValues.length > 0
|
|
177
|
+
? scoreValues.reduce((a, b) => a + b, 0) / scoreValues.length
|
|
178
|
+
: 0.5; // Default if no scores
|
|
179
|
+
|
|
180
|
+
return {
|
|
181
|
+
option: option.id,
|
|
182
|
+
scores,
|
|
183
|
+
totalScore: scores.totalScore
|
|
184
|
+
};
|
|
185
|
+
});
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* Detect known incompatibilities between options.
|
|
190
|
+
*/
|
|
191
|
+
export function detectIncompatibilities(options) {
|
|
192
|
+
const incompatibilities = [];
|
|
193
|
+
|
|
194
|
+
for (let i = 0; i < options.length; i++) {
|
|
195
|
+
for (let j = i + 1; j < options.length; j++) {
|
|
196
|
+
const opt1 = options[i];
|
|
197
|
+
const opt2 = options[j];
|
|
198
|
+
|
|
199
|
+
const incompatible1 = opt1.compatibility?.incompatibleWith?.includes(opt2.id);
|
|
200
|
+
const incompatible2 = opt2.compatibility?.incompatibleWith?.includes(opt1.id);
|
|
201
|
+
|
|
202
|
+
if (incompatible1 || incompatible2) {
|
|
203
|
+
incompatibilities.push({
|
|
204
|
+
option1: opt1.id,
|
|
205
|
+
option2: opt2.id,
|
|
206
|
+
reason: incompatible1
|
|
207
|
+
? opt1.compatibility.incompatibleWith.find(r => r.includes(opt2.id)) || 'Incompatible versions'
|
|
208
|
+
: opt2.compatibility.incompatibleWith.find(r => r.includes(opt1.id)) || 'Incompatible versions'
|
|
209
|
+
});
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
return incompatibilities;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* Rank options based on scores and incompatibilities.
|
|
219
|
+
*/
|
|
220
|
+
export function rankOptions(validOptions, scores, incompatibilities) {
|
|
221
|
+
// Sort by total score (descending)
|
|
222
|
+
const sorted = [...scores].sort((a, b) => b.totalScore - a.totalScore);
|
|
223
|
+
|
|
224
|
+
// Filter out options that are incompatible with top choices
|
|
225
|
+
const incompatibleOptionIds = new Set();
|
|
226
|
+
for (const inc of incompatibilities) {
|
|
227
|
+
incompatibleOptionIds.add(inc.option1);
|
|
228
|
+
incompatibleOptionIds.add(inc.option2);
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
const shortlisted = sorted.filter(s => s.totalScore >= 0.6 && !incompatibleOptionIds.has(s.option));
|
|
232
|
+
|
|
233
|
+
// Include all incompatible options for tracking
|
|
234
|
+
const incompatible = incompatibilities;
|
|
235
|
+
|
|
236
|
+
return {
|
|
237
|
+
shortlisted,
|
|
238
|
+
incompatible
|
|
239
|
+
};
|
|
240
|
+
}
|