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,471 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
import { spawn } from 'node:child_process';
|
|
3
|
+
import { parseYaml } from '../util/yaml.mjs';
|
|
4
|
+
import { splitFrontmatter } from '../util/frontmatter.mjs';
|
|
5
|
+
import { readText, readJson, writeJson, exists, resolveInside } from '../util/fsx.mjs';
|
|
6
|
+
import { aidfPaths, FRAMEWORK_ROOT, PHASES } from './paths.mjs';
|
|
7
|
+
import { loadConfig } from './config.mjs';
|
|
8
|
+
import { loadEvidenceIndex, recordEvidence } from './evidence.mjs';
|
|
9
|
+
|
|
10
|
+
export const GATE_STATUSES = ['PASS', 'BLOCKED', 'FAIL', 'NOT_PROVEN', 'NOT_APPLICABLE'];
|
|
11
|
+
|
|
12
|
+
export async function loadPhases(frameworkRoot = FRAMEWORK_ROOT) {
|
|
13
|
+
const file = path.join(frameworkRoot, 'assets', 'workflows', 'phases.yaml');
|
|
14
|
+
const parsed = parseYaml(await readText(file));
|
|
15
|
+
return parsed?.phases ?? [];
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export async function loadGates(frameworkRoot = FRAMEWORK_ROOT) {
|
|
19
|
+
const file = path.join(frameworkRoot, 'assets', 'workflows', 'gates.yaml');
|
|
20
|
+
const parsed = parseYaml(await readText(file));
|
|
21
|
+
return parsed?.gates ?? [];
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export async function loadWorkflowState(root) {
|
|
25
|
+
const file = path.join(aidfPaths(root).state, 'workflow.json');
|
|
26
|
+
return (await readJson(file, null)) ?? {
|
|
27
|
+
schemaVersion: 1,
|
|
28
|
+
currentPhase: 'intake',
|
|
29
|
+
completed: false,
|
|
30
|
+
updatedAt: null,
|
|
31
|
+
gates: {},
|
|
32
|
+
history: [],
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export async function saveWorkflowState(root, state) {
|
|
37
|
+
state.updatedAt = new Date().toISOString();
|
|
38
|
+
await writeJson(path.join(aidfPaths(root).state, 'workflow.json'), state);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export function phaseById(phases, id) {
|
|
42
|
+
return phases.find((p) => p.id === id) ?? null;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export function nextPhase(phases, id) {
|
|
46
|
+
const index = phases.findIndex((p) => p.id === id);
|
|
47
|
+
if (index === -1 || index === phases.length - 1) return null;
|
|
48
|
+
return phases[index + 1].id;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export function tokenizeCommand(command) {
|
|
52
|
+
const tokens = [];
|
|
53
|
+
const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
|
|
54
|
+
let match;
|
|
55
|
+
while ((match = re.exec(command)) !== null) {
|
|
56
|
+
tokens.push(match[1] ?? match[2] ?? match[3]);
|
|
57
|
+
}
|
|
58
|
+
return tokens;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
const SHELL_OPERATORS = /[|&;<>`]|\$\(/;
|
|
62
|
+
|
|
63
|
+
export async function runCommand(command, options = {}) {
|
|
64
|
+
if (typeof command !== 'string' || command.trim() === '') {
|
|
65
|
+
return { ok: false, status: 'BLOCKED', reason: 'Empty command.' };
|
|
66
|
+
}
|
|
67
|
+
if (SHELL_OPERATORS.test(command)) {
|
|
68
|
+
return {
|
|
69
|
+
ok: false,
|
|
70
|
+
status: 'BLOCKED',
|
|
71
|
+
reason: 'Shell operators are not allowed in AIDF command checks. Configure a single executable and arguments.',
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
const tokens = tokenizeCommand(command);
|
|
75
|
+
const executable = tokens.shift();
|
|
76
|
+
const cwd = options.cwd ?? process.cwd();
|
|
77
|
+
const timeoutMs = options.timeoutMs ?? 300000;
|
|
78
|
+
return new Promise((resolve) => {
|
|
79
|
+
const started = Date.now();
|
|
80
|
+
let stdout = '';
|
|
81
|
+
let stderr = '';
|
|
82
|
+
let settled = false;
|
|
83
|
+
const child = spawn(executable, tokens, {
|
|
84
|
+
cwd,
|
|
85
|
+
shell: false,
|
|
86
|
+
windowsHide: true,
|
|
87
|
+
env: { ...process.env },
|
|
88
|
+
});
|
|
89
|
+
const timer = setTimeout(() => {
|
|
90
|
+
if (!settled) {
|
|
91
|
+
child.kill('SIGKILL');
|
|
92
|
+
}
|
|
93
|
+
}, timeoutMs);
|
|
94
|
+
child.stdout.on('data', (chunk) => {
|
|
95
|
+
stdout += chunk.toString();
|
|
96
|
+
if (stdout.length > 400000) stdout = stdout.slice(-400000);
|
|
97
|
+
});
|
|
98
|
+
child.stderr.on('data', (chunk) => {
|
|
99
|
+
stderr += chunk.toString();
|
|
100
|
+
if (stderr.length > 400000) stderr = stderr.slice(-400000);
|
|
101
|
+
});
|
|
102
|
+
child.on('error', (error) => {
|
|
103
|
+
if (settled) return;
|
|
104
|
+
settled = true;
|
|
105
|
+
clearTimeout(timer);
|
|
106
|
+
resolve({ ok: false, status: 'BLOCKED', reason: error.message, command, durationMs: Date.now() - started });
|
|
107
|
+
});
|
|
108
|
+
child.on('close', (code) => {
|
|
109
|
+
if (settled) return;
|
|
110
|
+
settled = true;
|
|
111
|
+
clearTimeout(timer);
|
|
112
|
+
resolve({
|
|
113
|
+
ok: code === 0,
|
|
114
|
+
status: code === 0 ? 'PASS' : 'FAIL',
|
|
115
|
+
exitCode: code,
|
|
116
|
+
command,
|
|
117
|
+
cwd,
|
|
118
|
+
durationMs: Date.now() - started,
|
|
119
|
+
stdout,
|
|
120
|
+
stderr,
|
|
121
|
+
});
|
|
122
|
+
});
|
|
123
|
+
});
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function statusFromChecks(checks, options = {}) {
|
|
127
|
+
const blocking = checks.filter((c) => c.blocking !== false);
|
|
128
|
+
const applicable = blocking.filter((c) => c.status !== 'NOT_APPLICABLE');
|
|
129
|
+
|
|
130
|
+
// A gate with no blocking checks is informative by default. It only PASSes
|
|
131
|
+
// when it declares that intent explicitly; otherwise it cannot silently pass.
|
|
132
|
+
if (blocking.length === 0) {
|
|
133
|
+
if (options.applicability !== 'informative') return 'NOT_PROVEN';
|
|
134
|
+
if (checks.some((c) => c.status === 'FAIL')) return 'FAIL';
|
|
135
|
+
if (checks.some((c) => c.status === 'BLOCKED')) return 'BLOCKED';
|
|
136
|
+
return 'PASS';
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
// Blocking checks that are NOT_APPLICABLE cannot prove anything: a gate made
|
|
140
|
+
// only of not-applicable blocking checks is NOT_PROVEN, never PASS.
|
|
141
|
+
if (applicable.length === 0) return 'NOT_PROVEN';
|
|
142
|
+
|
|
143
|
+
if (applicable.some((c) => c.status === 'FAIL')) return 'FAIL';
|
|
144
|
+
if (applicable.some((c) => c.status === 'BLOCKED')) return 'BLOCKED';
|
|
145
|
+
if (applicable.some((c) => c.status === 'NOT_PROVEN')) return 'NOT_PROVEN';
|
|
146
|
+
return 'PASS';
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
async function checkFileExists(root, check) {
|
|
150
|
+
try {
|
|
151
|
+
const abs = resolveInside(root, check.path);
|
|
152
|
+
if (await exists(abs)) return { status: 'PASS', reason: `${check.path} exists.` };
|
|
153
|
+
return { status: 'NOT_PROVEN', reason: `${check.path} does not exist.` };
|
|
154
|
+
} catch (error) {
|
|
155
|
+
return { status: 'BLOCKED', reason: error.message };
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
async function checkDocStatus(root, config, check) {
|
|
160
|
+
const docs = check.documents ?? (check.document ? [check.document] : []);
|
|
161
|
+
if (docs.length === 0) return { status: 'BLOCKED', reason: 'No document configured for doc-status check.' };
|
|
162
|
+
const results = [];
|
|
163
|
+
for (const doc of docs) {
|
|
164
|
+
const entry = config.documents?.[doc];
|
|
165
|
+
if (!entry) {
|
|
166
|
+
results.push({ doc, status: 'BLOCKED', reason: `${doc} is not configured.` });
|
|
167
|
+
continue;
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
// The file is canonical: a status recorded in config.json is only trusted
|
|
171
|
+
// when the document frontmatter says the same. This closes the historical
|
|
172
|
+
// hole where a config could claim VALIDATED while the file stayed a template.
|
|
173
|
+
const file = path.join(root, '.aidf', 'docs', `${doc}.md`);
|
|
174
|
+
if (!(await exists(file))) {
|
|
175
|
+
results.push({ doc, status: 'BLOCKED', reason: `${doc} file is missing (.aidf/docs/${doc}.md).` });
|
|
176
|
+
continue;
|
|
177
|
+
}
|
|
178
|
+
let fileStatus = null;
|
|
179
|
+
try {
|
|
180
|
+
const frontmatter = splitFrontmatter(await readText(file)).frontmatter;
|
|
181
|
+
fileStatus = frontmatter && typeof frontmatter === 'object' ? frontmatter.status : null;
|
|
182
|
+
} catch (error) {
|
|
183
|
+
results.push({ doc, status: 'BLOCKED', reason: `${doc} file is unreadable: ${error.message}` });
|
|
184
|
+
continue;
|
|
185
|
+
}
|
|
186
|
+
if (!fileStatus) {
|
|
187
|
+
results.push({ doc, status: 'BLOCKED', reason: `${doc} file has no frontmatter status.` });
|
|
188
|
+
continue;
|
|
189
|
+
}
|
|
190
|
+
if (String(fileStatus) !== String(entry.status)) {
|
|
191
|
+
results.push({
|
|
192
|
+
doc,
|
|
193
|
+
status: 'FAIL',
|
|
194
|
+
reason: `${doc} status mismatch: file=${fileStatus} config=${entry.status}.`,
|
|
195
|
+
});
|
|
196
|
+
continue;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
const status = String(fileStatus);
|
|
200
|
+
if (check.disallowed?.includes(status)) {
|
|
201
|
+
results.push({ doc, status: 'FAIL', reason: `${doc} is ${status}.` });
|
|
202
|
+
} else if (check.allowed && !check.allowed.includes(status)) {
|
|
203
|
+
results.push({ doc, status: 'NOT_PROVEN', reason: `${doc} is ${status}; requires ${check.allowed.join(' or ')}.` });
|
|
204
|
+
} else {
|
|
205
|
+
results.push({ doc, status: 'PASS', reason: `${doc} is ${status}.` });
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
const status = statusFromChecks(results.map((r) => ({ ...r, blocking: true })));
|
|
209
|
+
return { status, reason: results.map((r) => `${r.doc}: ${r.reason}`).join(' '), details: results };
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
async function checkEvidence(root, check, config = {}) {
|
|
213
|
+
const index = await loadEvidenceIndex(root);
|
|
214
|
+
const requireAuth = config.security?.requireAuthenticatedApproval === true;
|
|
215
|
+
const matches = index.entries.filter((e) => {
|
|
216
|
+
if (check.evidenceType && e.type !== check.evidenceType) return false;
|
|
217
|
+
if (check.gate && e.gate !== check.gate) return false;
|
|
218
|
+
if (e.status !== 'PASS') return false;
|
|
219
|
+
if (check.requireHumanApproval && !e.humanApproval) return false;
|
|
220
|
+
if (check.requireHumanApproval && requireAuth && !e.authenticatedApproval) return false;
|
|
221
|
+
if (check.maxAgeDays) {
|
|
222
|
+
const age = (Date.now() - new Date(e.createdAt).getTime()) / 86400000;
|
|
223
|
+
if (age > check.maxAgeDays) return false;
|
|
224
|
+
}
|
|
225
|
+
return true;
|
|
226
|
+
});
|
|
227
|
+
if (matches.length > 0) {
|
|
228
|
+
const declaredOnly = matches.filter((e) => e.humanApproval && !e.authenticatedApproval).length;
|
|
229
|
+
return {
|
|
230
|
+
status: 'PASS',
|
|
231
|
+
reason: `Found ${matches.length} matching evidence record(s).`
|
|
232
|
+
+ (declaredOnly > 0 ? ` ${declaredOnly} approval(s) are declared, not authenticated.` : ''),
|
|
233
|
+
evidence: matches.slice(0, 5).map((m) => m.file),
|
|
234
|
+
approval: check.requireHumanApproval
|
|
235
|
+
? (declaredOnly === 0 ? 'authenticated' : 'declared')
|
|
236
|
+
: null,
|
|
237
|
+
};
|
|
238
|
+
}
|
|
239
|
+
const anyType = index.entries.filter((e) => !check.evidenceType || e.type === check.evidenceType);
|
|
240
|
+
if (check.requireHumanApproval && anyType.some((e) => e.status === 'PASS' && !e.humanApproval)) {
|
|
241
|
+
return {
|
|
242
|
+
status: 'BLOCKED',
|
|
243
|
+
reason: `Evidence exists for "${check.evidenceType}" but lacks human approval.`,
|
|
244
|
+
};
|
|
245
|
+
}
|
|
246
|
+
if (check.requireHumanApproval && requireAuth
|
|
247
|
+
&& anyType.some((e) => e.status === 'PASS' && e.humanApproval && !e.authenticatedApproval)) {
|
|
248
|
+
return {
|
|
249
|
+
status: 'NOT_PROVEN',
|
|
250
|
+
reason: `Evidence for "${check.evidenceType}" has a declared approval only; authenticated approval is required.`,
|
|
251
|
+
};
|
|
252
|
+
}
|
|
253
|
+
return {
|
|
254
|
+
status: 'NOT_PROVEN',
|
|
255
|
+
reason: `No PASS evidence of type "${check.evidenceType}"${check.requireHumanApproval ? ' with human approval' : ''}.`,
|
|
256
|
+
};
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
async function checkCommand(root, config, check, options) {
|
|
260
|
+
const key = check.commandKey;
|
|
261
|
+
const command = config.commands?.[key];
|
|
262
|
+
if (!command) {
|
|
263
|
+
if (check.missing === 'NOT_APPLICABLE' && check.blocking === false) {
|
|
264
|
+
return { status: 'NOT_APPLICABLE', reason: `No "${key}" command is configured (informative check).` };
|
|
265
|
+
}
|
|
266
|
+
return {
|
|
267
|
+
status: 'BLOCKED',
|
|
268
|
+
reason: `No "${key}" command is configured in .aidf/config.json.`
|
|
269
|
+
+ (check.missing === 'NOT_APPLICABLE' ? ' A blocking check cannot be NOT_APPLICABLE.' : ''),
|
|
270
|
+
};
|
|
271
|
+
}
|
|
272
|
+
const allowedByConfig = config.security?.allowedCommands ?? [];
|
|
273
|
+
if (allowedByConfig.length > 0 && !allowedByConfig.includes(key)) {
|
|
274
|
+
return { status: 'BLOCKED', reason: `Command "${key}" is not in security.allowedCommands.` };
|
|
275
|
+
}
|
|
276
|
+
const permitted = options.allowExec || config.security?.allowCommandExecution === true;
|
|
277
|
+
if (!permitted) {
|
|
278
|
+
return {
|
|
279
|
+
status: 'NOT_PROVEN',
|
|
280
|
+
reason: `Command "${key}" was not executed. Re-run with --allow-exec or set security.allowCommandExecution=true.`,
|
|
281
|
+
command,
|
|
282
|
+
};
|
|
283
|
+
}
|
|
284
|
+
const result = await runCommand(command, { cwd: root, timeoutMs: check.timeoutMs ?? 300000 });
|
|
285
|
+
return {
|
|
286
|
+
status: result.status,
|
|
287
|
+
reason: result.status === 'PASS' ? `Command exited 0 in ${result.durationMs}ms.` : result.reason ?? `Command exited ${result.exitCode}.`,
|
|
288
|
+
command: {
|
|
289
|
+
key,
|
|
290
|
+
command,
|
|
291
|
+
exitCode: result.exitCode ?? null,
|
|
292
|
+
durationMs: result.durationMs ?? null,
|
|
293
|
+
stdout: result.stdout ?? '',
|
|
294
|
+
stderr: result.stderr ?? '',
|
|
295
|
+
},
|
|
296
|
+
};
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
function checkPreviousGate(state, check) {
|
|
300
|
+
const gates = check.gates ?? (check.gate ? [check.gate] : []);
|
|
301
|
+
if (gates.length === 0) return { status: 'BLOCKED', reason: 'No gate configured.' };
|
|
302
|
+
const missing = gates.filter((g) => state.gates?.[g]?.status !== 'PASS');
|
|
303
|
+
if (missing.length === 0) return { status: 'PASS', reason: `Prior gates PASS: ${gates.join(', ')}.` };
|
|
304
|
+
return {
|
|
305
|
+
status: 'NOT_PROVEN',
|
|
306
|
+
reason: `Prior gates not PASS: ${missing.map((g) => `${g}=${state.gates?.[g]?.status ?? 'UNKNOWN'}`).join(', ')}.`,
|
|
307
|
+
};
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
export async function evaluateGate(root, gate, options = {}) {
|
|
311
|
+
const config = options.config ?? (await loadConfig(root));
|
|
312
|
+
const state = options.state ?? (await loadWorkflowState(root));
|
|
313
|
+
const checks = [];
|
|
314
|
+
for (const check of gate.checks ?? []) {
|
|
315
|
+
let result;
|
|
316
|
+
switch (check.type) {
|
|
317
|
+
case 'file-exists':
|
|
318
|
+
result = await checkFileExists(root, check);
|
|
319
|
+
break;
|
|
320
|
+
case 'doc-status':
|
|
321
|
+
result = await checkDocStatus(root, config, check);
|
|
322
|
+
break;
|
|
323
|
+
case 'evidence':
|
|
324
|
+
result = await checkEvidence(root, check, config);
|
|
325
|
+
break;
|
|
326
|
+
case 'command':
|
|
327
|
+
result = await checkCommand(root, config, check, options);
|
|
328
|
+
break;
|
|
329
|
+
case 'previous-gate':
|
|
330
|
+
result = checkPreviousGate(state, check);
|
|
331
|
+
break;
|
|
332
|
+
case 'manual':
|
|
333
|
+
result = { status: 'NOT_PROVEN', reason: check.description ?? 'Manual validation required.' };
|
|
334
|
+
break;
|
|
335
|
+
default:
|
|
336
|
+
result = { status: 'BLOCKED', reason: `Unknown check type: ${check.type}` };
|
|
337
|
+
}
|
|
338
|
+
checks.push({
|
|
339
|
+
id: check.id,
|
|
340
|
+
type: check.type,
|
|
341
|
+
blocking: check.blocking !== false,
|
|
342
|
+
status: result.status,
|
|
343
|
+
reason: result.reason,
|
|
344
|
+
evidence: result.evidence ?? null,
|
|
345
|
+
command: result.command ?? null,
|
|
346
|
+
details: result.details ?? null,
|
|
347
|
+
});
|
|
348
|
+
}
|
|
349
|
+
const status = statusFromChecks(checks, { applicability: gate.applicability });
|
|
350
|
+
const blocking = checks.filter((c) => c.blocking !== false);
|
|
351
|
+
const applicableBlocking = blocking.filter((c) => c.status !== 'NOT_APPLICABLE');
|
|
352
|
+
let reason = null;
|
|
353
|
+
if (blocking.length === 0 && gate.applicability !== 'informative') {
|
|
354
|
+
reason = 'Gate has no blocking check and is not declared informative; it cannot silently PASS.';
|
|
355
|
+
} else if (blocking.length > 0 && applicableBlocking.length === 0) {
|
|
356
|
+
reason = 'No applicable blocking check: the gate cannot be proven from NOT_APPLICABLE checks alone.';
|
|
357
|
+
}
|
|
358
|
+
return {
|
|
359
|
+
gate: gate.id,
|
|
360
|
+
phase: gate.phase,
|
|
361
|
+
kind: gate.kind,
|
|
362
|
+
description: gate.description,
|
|
363
|
+
status,
|
|
364
|
+
reason,
|
|
365
|
+
blockingChecks: blocking.length,
|
|
366
|
+
applicableBlockingChecks: applicableBlocking.length,
|
|
367
|
+
checks,
|
|
368
|
+
evaluatedAt: new Date().toISOString(),
|
|
369
|
+
};
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
export async function recordGateRun(root, report, options = {}) {
|
|
373
|
+
const commands = report.checks
|
|
374
|
+
.filter((c) => c.command)
|
|
375
|
+
.map((c) => ({
|
|
376
|
+
key: c.command.key,
|
|
377
|
+
command: c.command.command,
|
|
378
|
+
exitCode: c.command.exitCode,
|
|
379
|
+
durationMs: c.command.durationMs,
|
|
380
|
+
stdout: String(c.command.stdout ?? '').slice(-8000),
|
|
381
|
+
stderr: String(c.command.stderr ?? '').slice(-8000),
|
|
382
|
+
}));
|
|
383
|
+
const evidence = await recordEvidence(root, {
|
|
384
|
+
type: 'gate-run',
|
|
385
|
+
status: report.status,
|
|
386
|
+
gate: report.gate,
|
|
387
|
+
phase: report.phase,
|
|
388
|
+
summary: `${report.gate} (${report.kind}) -> ${report.status}`,
|
|
389
|
+
createdBy: options.createdBy ?? 'aidf',
|
|
390
|
+
checks: report.checks.map((c) => ({
|
|
391
|
+
id: c.id,
|
|
392
|
+
type: c.type,
|
|
393
|
+
status: c.status,
|
|
394
|
+
reason: c.reason,
|
|
395
|
+
evidence: c.evidence,
|
|
396
|
+
})),
|
|
397
|
+
commands,
|
|
398
|
+
limitations: options.limitations ?? [],
|
|
399
|
+
});
|
|
400
|
+
return evidence;
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
export async function runGate(root, gateId, options = {}) {
|
|
404
|
+
const gates = options.gates ?? (await loadGates(options.frameworkRoot));
|
|
405
|
+
const gate = gates.find((g) => g.id === gateId);
|
|
406
|
+
if (!gate) throw new Error(`Unknown gate: ${gateId}`);
|
|
407
|
+
const state = options.state ?? (await loadWorkflowState(root));
|
|
408
|
+
const report = await evaluateGate(root, gate, { ...options, state });
|
|
409
|
+
const evidence = options.record === false ? null : await recordGateRun(root, report, options);
|
|
410
|
+
if (evidence) report.evidence = { id: evidence.id, file: evidence.file, hash: evidence.hash };
|
|
411
|
+
state.gates[gateId] = {
|
|
412
|
+
status: report.status,
|
|
413
|
+
at: report.evaluatedAt,
|
|
414
|
+
evidence: evidence?.file ?? state.gates[gateId]?.evidence ?? null,
|
|
415
|
+
};
|
|
416
|
+
await saveWorkflowState(root, state);
|
|
417
|
+
report.state = state;
|
|
418
|
+
return report;
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
export async function enterPhase(root, phaseId, options = {}) {
|
|
422
|
+
const phases = await loadPhases(options.frameworkRoot);
|
|
423
|
+
const phase = phaseById(phases, phaseId);
|
|
424
|
+
if (!phase) throw new Error(`Unknown phase: ${phaseId}. Allowed: ${PHASES.join(', ')}`);
|
|
425
|
+
const state = await loadWorkflowState(root);
|
|
426
|
+
if (state.currentPhase === phaseId) {
|
|
427
|
+
return { status: 'PASS', alreadyInPhase: true, phase: phaseId, state };
|
|
428
|
+
}
|
|
429
|
+
const gate = await runGate(root, `${phaseId}-entry`, { ...options, state });
|
|
430
|
+
if (gate.status !== 'PASS') {
|
|
431
|
+
return { status: gate.status, phase: phaseId, gate };
|
|
432
|
+
}
|
|
433
|
+
state.currentPhase = phaseId;
|
|
434
|
+
state.history.push({ ts: new Date().toISOString(), event: 'enter', phase: phaseId, gate: gate.gate, status: gate.status });
|
|
435
|
+
await saveWorkflowState(root, state);
|
|
436
|
+
return { status: 'PASS', phase: phaseId, gate, state };
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
export async function exitPhase(root, phaseId, options = {}) {
|
|
440
|
+
const phases = await loadPhases(options.frameworkRoot);
|
|
441
|
+
const phase = phaseById(phases, phaseId);
|
|
442
|
+
if (!phase) throw new Error(`Unknown phase: ${phaseId}`);
|
|
443
|
+
const state = await loadWorkflowState(root);
|
|
444
|
+
const gate = await runGate(root, `${phaseId}-exit`, { ...options, state });
|
|
445
|
+
if (gate.status !== 'PASS') {
|
|
446
|
+
return { status: gate.status, phase: phaseId, gate, state };
|
|
447
|
+
}
|
|
448
|
+
const next = nextPhase(phases, phaseId);
|
|
449
|
+
state.history.push({ ts: new Date().toISOString(), event: 'exit', phase: phaseId, gate: gate.gate, status: gate.status });
|
|
450
|
+
if (next) {
|
|
451
|
+
state.currentPhase = next;
|
|
452
|
+
state.completed = false;
|
|
453
|
+
} else {
|
|
454
|
+
state.completed = true;
|
|
455
|
+
}
|
|
456
|
+
await saveWorkflowState(root, state);
|
|
457
|
+
return { status: 'PASS', phase: phaseId, nextPhase: next, gate, state };
|
|
458
|
+
}
|
|
459
|
+
|
|
460
|
+
export async function workflowStatus(root, options = {}) {
|
|
461
|
+
const phases = await loadPhases(options.frameworkRoot);
|
|
462
|
+
const state = await loadWorkflowState(root);
|
|
463
|
+
const rows = phases.map((phase) => ({
|
|
464
|
+
phase: phase.id,
|
|
465
|
+
name: phase.name,
|
|
466
|
+
entry: state.gates?.[`${phase.id}-entry`]?.status ?? 'UNKNOWN',
|
|
467
|
+
exit: state.gates?.[`${phase.id}-exit`]?.status ?? 'UNKNOWN',
|
|
468
|
+
current: state.currentPhase === phase.id ? 'yes' : '',
|
|
469
|
+
}));
|
|
470
|
+
return { currentPhase: state.currentPhase, completed: state.completed, phases: rows, state };
|
|
471
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Deterministic argv parser. Supports:
|
|
3
|
+
* --flag, --key value, --key=value, --no-key, -h
|
|
4
|
+
* Boolean flags are declared so `--target foo` never consumes a flag.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
export function parseArgs(argv, spec = {}) {
|
|
8
|
+
const booleans = new Set(spec.booleans ?? []);
|
|
9
|
+
const aliases = spec.aliases ?? {};
|
|
10
|
+
const result = { _: [] };
|
|
11
|
+
for (let i = 0; i < argv.length; i += 1) {
|
|
12
|
+
let token = argv[i];
|
|
13
|
+
if (token === '--') {
|
|
14
|
+
result._.push(...argv.slice(i + 1));
|
|
15
|
+
break;
|
|
16
|
+
}
|
|
17
|
+
if (token.startsWith('-') && token !== '-') {
|
|
18
|
+
let name;
|
|
19
|
+
let inlineValue;
|
|
20
|
+
if (token.startsWith('--')) {
|
|
21
|
+
const body = token.slice(2);
|
|
22
|
+
const eq = body.indexOf('=');
|
|
23
|
+
name = eq >= 0 ? body.slice(0, eq) : body;
|
|
24
|
+
inlineValue = eq >= 0 ? body.slice(eq + 1) : undefined;
|
|
25
|
+
} else {
|
|
26
|
+
name = token.slice(1);
|
|
27
|
+
if (aliases[name]) name = aliases[name];
|
|
28
|
+
}
|
|
29
|
+
if (name.startsWith('no-') && booleans.has(name.slice(3))) {
|
|
30
|
+
result[name.slice(3)] = false;
|
|
31
|
+
continue;
|
|
32
|
+
}
|
|
33
|
+
if (booleans.has(name)) {
|
|
34
|
+
result[name] = inlineValue === undefined ? true : inlineValue !== 'false';
|
|
35
|
+
continue;
|
|
36
|
+
}
|
|
37
|
+
if (inlineValue !== undefined) {
|
|
38
|
+
result[name] = inlineValue;
|
|
39
|
+
continue;
|
|
40
|
+
}
|
|
41
|
+
const next = argv[i + 1];
|
|
42
|
+
if (next !== undefined && (!next.startsWith('-') || next === '-')) {
|
|
43
|
+
result[name] = next;
|
|
44
|
+
i += 1;
|
|
45
|
+
} else {
|
|
46
|
+
result[name] = true;
|
|
47
|
+
}
|
|
48
|
+
continue;
|
|
49
|
+
}
|
|
50
|
+
result._.push(token);
|
|
51
|
+
}
|
|
52
|
+
return result;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
export function requirePositional(args, index, label) {
|
|
56
|
+
const value = args._[index];
|
|
57
|
+
if (typeof value !== 'string' || value.trim() === '') {
|
|
58
|
+
throw new Error(`Missing ${label}.`);
|
|
59
|
+
}
|
|
60
|
+
return value;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export function assertEnum(value, allowed, label) {
|
|
64
|
+
if (value === undefined) return undefined;
|
|
65
|
+
if (!allowed.includes(value)) {
|
|
66
|
+
throw new Error(`Invalid ${label} "${value}". Allowed: ${allowed.join(', ')}`);
|
|
67
|
+
}
|
|
68
|
+
return value;
|
|
69
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { parseYaml, dumpYaml } from './yaml.mjs';
|
|
2
|
+
|
|
3
|
+
export function splitFrontmatter(text) {
|
|
4
|
+
const source = String(text ?? '').replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
|
|
5
|
+
if (!source.startsWith('---\n')) {
|
|
6
|
+
return { frontmatter: null, body: source, raw: '' };
|
|
7
|
+
}
|
|
8
|
+
const end = source.indexOf('\n---', 4);
|
|
9
|
+
if (end === -1) {
|
|
10
|
+
return { frontmatter: null, body: source, raw: '' };
|
|
11
|
+
}
|
|
12
|
+
const raw = source.slice(4, end + 1);
|
|
13
|
+
const bodyStart = source.indexOf('\n', end + 4);
|
|
14
|
+
const body = bodyStart === -1 ? '' : source.slice(bodyStart + 1);
|
|
15
|
+
return { frontmatter: parseYaml(raw), body, raw };
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export function joinFrontmatter(frontmatter, body) {
|
|
19
|
+
return `---\n${dumpYaml(frontmatter)}---\n\n${String(body).replace(/^\n+/, '')}`;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export function updateFrontmatter(text, updater) {
|
|
23
|
+
const { frontmatter, body } = splitFrontmatter(text);
|
|
24
|
+
const next = updater(frontmatter ?? {}) ?? frontmatter ?? {};
|
|
25
|
+
return joinFrontmatter(next, body);
|
|
26
|
+
}
|