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.
Files changed (154) hide show
  1. package/CHANGELOG.md +174 -0
  2. package/INSTALLATION.md +140 -0
  3. package/LICENSE +21 -0
  4. package/QODER.md +88 -0
  5. package/README.md +142 -2
  6. package/UTILISATION.md +188 -0
  7. package/assets/adapters/qoder/agents/aidf-orchestrator.md +30 -0
  8. package/assets/adapters/qoder/rules/00-core.md +28 -0
  9. package/assets/adapters/qoder/rules/10-security.md +33 -0
  10. package/assets/adapters/qoder/rules/20-context.md +39 -0
  11. package/assets/core/AGENTS.fragment.md +18 -0
  12. package/assets/core/AIDF.md +107 -0
  13. package/assets/docs/APPFLOW.md +66 -0
  14. package/assets/docs/BACKEND.md +71 -0
  15. package/assets/docs/CHANGELOG.md +25 -0
  16. package/assets/docs/CONVENTIONS.md +95 -0
  17. package/assets/docs/DECISIONS.md +60 -0
  18. package/assets/docs/PLAN.md +53 -0
  19. package/assets/docs/PRD.md +88 -0
  20. package/assets/docs/SECURITY.md +94 -0
  21. package/assets/docs/TRD.md +78 -0
  22. package/assets/docs/UI-UX.md +71 -0
  23. package/assets/docs/constitution.md +86 -0
  24. package/assets/hooks/audit.mjs +45 -0
  25. package/assets/hooks/session-context.mjs +53 -0
  26. package/assets/integrations/spec-kit/mapping.yaml +92 -0
  27. package/assets/knowledge/best-practices/testing.md +53 -0
  28. package/assets/knowledge/best-practices/web-dev-baseline.md +39 -0
  29. package/assets/knowledge/rules/api.md +45 -0
  30. package/assets/knowledge/rules/sql.md +44 -0
  31. package/assets/knowledge/rules/typescript.md +50 -0
  32. package/assets/knowledge/security-references/owasp-baseline.md +58 -0
  33. package/assets/registry/activation-map.yaml +83 -0
  34. package/assets/registry/dependencies.yaml +35 -0
  35. package/assets/registry/skills.yaml +541 -0
  36. package/assets/registry/sources.yaml +396 -0
  37. package/assets/schemas/architecture/v1.json +110 -0
  38. package/assets/schemas/constraints/v1.json +93 -0
  39. package/assets/schemas/decision/v1.json +106 -0
  40. package/assets/schemas/discovery/v1.json +91 -0
  41. package/assets/schemas/requirement/v1.json +136 -0
  42. package/assets/schemas/security/threat-model/v1.json +127 -0
  43. package/assets/schemas/test-plan/v1.json +108 -0
  44. package/assets/skills/aidf-architecture-review/SKILL.md +49 -0
  45. package/assets/skills/aidf-backend-implementation/SKILL.md +47 -0
  46. package/assets/skills/aidf-database-design/SKILL.md +48 -0
  47. package/assets/skills/aidf-devops-engineering/SKILL.md +41 -0
  48. package/assets/skills/aidf-documentation-maintenance/SKILL.md +41 -0
  49. package/assets/skills/aidf-frontend-implementation/SKILL.md +44 -0
  50. package/assets/skills/aidf-phase-transition/SKILL.md +48 -0
  51. package/assets/skills/aidf-product-analysis/SKILL.md +47 -0
  52. package/assets/skills/aidf-project-context/SKILL.md +57 -0
  53. package/assets/skills/aidf-requirements-engineering/SKILL.md +52 -0
  54. package/assets/skills/aidf-security-review/SKILL.md +57 -0
  55. package/assets/skills/aidf-testing-validation/SKILL.md +48 -0
  56. package/assets/skills/aidf-ui-ux-implementation/SKILL.md +43 -0
  57. package/assets/workflows/gates.yaml +232 -0
  58. package/assets/workflows/phases.yaml +161 -0
  59. package/bin/aidf.mjs +12 -0
  60. package/demo/run-demo.mjs +97 -0
  61. package/docs/aidf/ADR-001-artefacts-architectur.md +126 -0
  62. package/docs/aidf/ADR-002-requirements-registry.md +145 -0
  63. package/docs/aidf/ADR-003-traceability-chain.md +145 -0
  64. package/docs/aidf/ADR-004-markdown-generation.md +134 -0
  65. package/docs/aidf/ADR-005-validation-and-tests.md +170 -0
  66. package/docs/aidf/ADR-006-cli-commands.md +189 -0
  67. package/docs/aidf/ADR-007-compatibility-and-migration.md +119 -0
  68. package/docs/aidf/ADR-008-schema-versioning.md +115 -0
  69. package/docs/aidf/ADR-009-artefacts-scope.md +84 -0
  70. package/docs/aidf/ARCHITECTURE.md +137 -0
  71. package/docs/aidf/COMPATIBILITY.md +90 -0
  72. package/docs/aidf/DECISIONS.md +200 -0
  73. package/docs/aidf/FRAMEWORK.md +38 -0
  74. package/docs/aidf/IDE-QODER.md +61 -0
  75. package/docs/aidf/INSTALL.md +99 -0
  76. package/docs/aidf/INVENTORY.md +72 -0
  77. package/docs/aidf/L1-ARCHITECTURE-RAPPORT.md +353 -0
  78. package/docs/aidf/LIMITATIONS.md +69 -0
  79. package/docs/aidf/MATRICE-0.1.0-vers-0.2.0.md +155 -0
  80. package/docs/aidf/SECURITY.md +86 -0
  81. package/docs/aidf/SKILLS.md +78 -0
  82. package/docs/aidf/SPECKIT.md +67 -0
  83. package/docs/aidf/USAGE.md +113 -0
  84. package/docs/aidf/VALIDATION.md +55 -0
  85. package/package.json +37 -4
  86. package/src/cli.mjs +148 -0
  87. package/src/commands/artefacts.mjs +129 -0
  88. package/src/commands/config.mjs +130 -0
  89. package/src/commands/context.mjs +55 -0
  90. package/src/commands/decision.mjs +142 -0
  91. package/src/commands/design.mjs +141 -0
  92. package/src/commands/docs.mjs +133 -0
  93. package/src/commands/doctor.mjs +210 -0
  94. package/src/commands/evidence.mjs +178 -0
  95. package/src/commands/install.mjs +154 -0
  96. package/src/commands/release.mjs +214 -0
  97. package/src/commands/requirements.mjs +196 -0
  98. package/src/commands/resources.mjs +181 -0
  99. package/src/commands/scan.mjs +139 -0
  100. package/src/commands/security.mjs +97 -0
  101. package/src/commands/setup.mjs +68 -0
  102. package/src/commands/skills.mjs +204 -0
  103. package/src/commands/speckit.mjs +78 -0
  104. package/src/commands/tests.mjs +81 -0
  105. package/src/commands/traceability.mjs +116 -0
  106. package/src/commands/uninstall.mjs +238 -0
  107. package/src/commands/validate.mjs +84 -0
  108. package/src/commands/workflow.mjs +137 -0
  109. package/src/core/adapters/base.mjs +32 -0
  110. package/src/core/adapters/generic.mjs +70 -0
  111. package/src/core/adapters/index.mjs +24 -0
  112. package/src/core/adapters/opencode.mjs +115 -0
  113. package/src/core/adapters/qoder.mjs +228 -0
  114. package/src/core/artefacts/index.mjs +1 -0
  115. package/src/core/artefacts/validation.mjs +161 -0
  116. package/src/core/bootstrap.mjs +179 -0
  117. package/src/core/config.mjs +123 -0
  118. package/src/core/context.mjs +187 -0
  119. package/src/core/design-engineering/complexity-classifier.mjs +78 -0
  120. package/src/core/design-engineering/engine.mjs +197 -0
  121. package/src/core/design-engineering/fallback/mockups.mjs +221 -0
  122. package/src/core/design-engineering/fallback/wireframes.mjs +114 -0
  123. package/src/core/design-engineering/figma/validators.mjs +178 -0
  124. package/src/core/design-engineering/index.mjs +9 -0
  125. package/src/core/design-engineering/visual-parity/capture.mjs +172 -0
  126. package/src/core/detect.mjs +220 -0
  127. package/src/core/docsgen.mjs +175 -0
  128. package/src/core/evidence.mjs +210 -0
  129. package/src/core/installer.mjs +377 -0
  130. package/src/core/manifest.mjs +53 -0
  131. package/src/core/paths.mjs +94 -0
  132. package/src/core/requirements/index.mjs +13 -0
  133. package/src/core/requirements/registry.mjs +234 -0
  134. package/src/core/resource-inventory.mjs +434 -0
  135. package/src/core/resources.mjs +280 -0
  136. package/src/core/security/threat-model.mjs +235 -0
  137. package/src/core/skills.mjs +353 -0
  138. package/src/core/source-skills.mjs +213 -0
  139. package/src/core/speckit.mjs +195 -0
  140. package/src/core/technology-decision/analyzer-deterministic.mjs +240 -0
  141. package/src/core/technology-decision/engine.mjs +157 -0
  142. package/src/core/technology-decision/generator.mjs +204 -0
  143. package/src/core/technology-decision/index.mjs +17 -0
  144. package/src/core/technology-decision/options/index.mjs +10 -0
  145. package/src/core/testplan.mjs +176 -0
  146. package/src/core/traceability/chain.mjs +488 -0
  147. package/src/core/traceability/index.mjs +12 -0
  148. package/src/core/workflow.mjs +471 -0
  149. package/src/util/args.mjs +69 -0
  150. package/src/util/frontmatter.mjs +26 -0
  151. package/src/util/fsx.mjs +208 -0
  152. package/src/util/logger.mjs +74 -0
  153. package/src/util/text.mjs +66 -0
  154. package/src/util/yaml.mjs +379 -0
@@ -0,0 +1,214 @@
1
+ import path from 'node:path';
2
+ import { parseArgs } from '../util/args.mjs';
3
+ import { resolveProjectRoot, isInitialized, aidfPaths } from '../core/paths.mjs';
4
+ import { attachLogFile } from '../util/logger.mjs';
5
+ import { writeJson, writeAtomic, ensureDir, exists, toPosix } from '../util/fsx.mjs';
6
+ import { loadGates, loadWorkflowState, evaluateGate } from '../core/workflow.mjs';
7
+ import { loadConfig, defaultConfig } from '../core/config.mjs';
8
+ import { loadEvidenceIndex } from '../core/evidence.mjs';
9
+ import { detectProject } from '../core/detect.mjs';
10
+ import { collectArtefactFiles } from '../core/traceability/chain.mjs';
11
+ import { recordEvidence } from '../core/evidence.mjs';
12
+
13
+ export function releaseArgSpec() {
14
+ return {
15
+ booleans: ['json', 'help', 'record', 'strict', 'allow-exec'],
16
+ aliases: { h: 'help', t: 'target' },
17
+ };
18
+ }
19
+
20
+ /**
21
+ * Build a release readiness report. Read-only unless --record is passed:
22
+ * gates are evaluated without recording gate-run evidence, and no workflow
23
+ * state is mutated.
24
+ */
25
+ export async function buildReleaseReport(root, options = {}) {
26
+ const now = new Date().toISOString();
27
+ const gates = await loadGates(options.frameworkRoot);
28
+ const state = await loadWorkflowState(root);
29
+ const config = await loadConfig(root).catch(() => defaultConfig({}));
30
+
31
+ const gateResults = [];
32
+ for (const gate of gates) {
33
+ const report = await evaluateGate(root, gate, {
34
+ ...options,
35
+ config,
36
+ state,
37
+ allowExec: Boolean(options['allow-exec'] ?? options.allowExec),
38
+ });
39
+ gateResults.push({
40
+ id: report.gate,
41
+ phase: report.phase,
42
+ kind: report.kind,
43
+ status: report.status,
44
+ reason: report.reason,
45
+ checks: report.checks.map((c) => ({ id: c.id, type: c.type, status: c.status, reason: c.reason })),
46
+ });
47
+ }
48
+
49
+ const blockers = gateResults.filter(
50
+ (g) => (g.status === 'BLOCKED' || g.status === 'FAIL')
51
+ && g.checks.some((c) => c.status === 'BLOCKED' || c.status === 'FAIL'),
52
+ );
53
+ const notProven = gateResults.filter((g) => g.status === 'NOT_PROVEN');
54
+ const passed = gateResults.filter((g) => g.status === 'PASS');
55
+ const ready = blockers.length === 0 && notProven.length === 0;
56
+
57
+ const evidenceIndex = await loadEvidenceIndex(root);
58
+ const evidenceByStatus = {};
59
+ for (const e of evidenceIndex.entries ?? []) {
60
+ evidenceByStatus[e.status] = (evidenceByStatus[e.status] ?? 0) + 1;
61
+ }
62
+
63
+ const project = await detectProject(root);
64
+ const artefacts = await collectArtefactFiles(root);
65
+
66
+ const docs = Object.entries(config.documents ?? {}).map(([doc, entry]) => ({
67
+ doc,
68
+ status: entry.status,
69
+ validatedBy: entry.validatedBy ?? null,
70
+ validatedAt: entry.validatedAt ?? null,
71
+ }));
72
+
73
+ const changelogPath = path.join(root, '.aidf', 'docs', 'CHANGELOG.md');
74
+ const changelog = await exists(changelogPath);
75
+
76
+ return {
77
+ schemaVersion: 1,
78
+ generatedAt: now,
79
+ root,
80
+ verdict: ready ? 'READY' : 'NOT_READY',
81
+ summary: {
82
+ gates: gateResults.length,
83
+ pass: passed.length,
84
+ blocked: blockers.length,
85
+ notProven: notProven.length,
86
+ notApplicable: gateResults.filter((g) => g.status === 'NOT_APPLICABLE').length,
87
+ },
88
+ blockers: blockers.map((g) => ({ id: g.id, phase: g.phase, kind: g.kind, reason: g.reason })),
89
+ notProvenGates: notProven.map((g) => ({ id: g.id, phase: g.phase, kind: g.kind, reason: g.reason })),
90
+ gates: gateResults,
91
+ documents: docs,
92
+ changelog: { present: changelog, path: toPosix(path.join('.aidf', 'docs', 'CHANGELOG.md')) },
93
+ evidence: {
94
+ total: evidenceIndex.entries?.length ?? 0,
95
+ byStatus: evidenceByStatus,
96
+ },
97
+ artefacts: {
98
+ total: artefacts.length,
99
+ byType: artefacts.reduce((acc, f) => {
100
+ const t = f.body?.type ?? 'unknown';
101
+ acc[t] = (acc[t] ?? 0) + 1;
102
+ return acc;
103
+ }, {}),
104
+ },
105
+ project: {
106
+ git: project.git,
107
+ tests: { runners: project.tests.runners, directories: project.tests.directories },
108
+ frameworks: project.frameworks,
109
+ },
110
+ limitations: [
111
+ 'Gate evaluation is read-only: no gate-run evidence is recorded and workflow state is not mutated.',
112
+ 'Command checks report NOT_PROVEN unless --allow-exec (or security.allowCommandExecution) permits execution.',
113
+ 'READY means every gate evaluated PASS or NOT_APPLICABLE; it is not a deployment authorization.',
114
+ ],
115
+ };
116
+ }
117
+
118
+ function renderReleaseMarkdown(report) {
119
+ const lines = [];
120
+ lines.push(`# AIDF Release Report`);
121
+ lines.push('');
122
+ lines.push(`- Generated: ${report.generatedAt}`);
123
+ lines.push(`- Verdict: **${report.verdict}**`);
124
+ lines.push(`- Gates: ${report.summary.pass} PASS / ${report.summary.blocked} BLOCKED / ${report.summary.notProven} NOT_PROVEN / ${report.summary.notApplicable} NOT_APPLICABLE`);
125
+ lines.push('');
126
+ lines.push('## Blockers');
127
+ lines.push('');
128
+ if (report.blockers.length === 0) lines.push('_None._');
129
+ for (const b of report.blockers) lines.push(`- ${b.id} (${b.phase}/${b.kind}): ${b.reason}`);
130
+ lines.push('');
131
+ lines.push('## Gates');
132
+ lines.push('');
133
+ lines.push('| Gate | Phase | Kind | Status | Reason |');
134
+ lines.push('|---|---|---|---|---|');
135
+ for (const g of report.gates) lines.push(`| ${g.id} | ${g.phase} | ${g.kind} | ${g.status} | ${g.reason} |`);
136
+ lines.push('');
137
+ lines.push('## Documents');
138
+ lines.push('');
139
+ lines.push('| Document | Status | Validated by |');
140
+ lines.push('|---|---|---|');
141
+ for (const d of report.documents) lines.push(`| ${d.doc} | ${d.status} | ${d.validatedBy ?? '-'} |`);
142
+ lines.push('');
143
+ lines.push(`CHANGELOG.md: ${report.changelog.present ? 'present' : 'MISSING'}`);
144
+ lines.push('');
145
+ lines.push(`Evidence records: ${report.evidence.total} (${Object.entries(report.evidence.byStatus).map(([k, v]) => `${k}:${v}`).join(', ') || 'none'})`);
146
+ lines.push(`Artefacts: ${report.artefacts.total}`);
147
+ lines.push('');
148
+ lines.push('## Limitations');
149
+ lines.push('');
150
+ for (const l of report.limitations) lines.push(`- ${l}`);
151
+ lines.push('');
152
+ return `${lines.join('\n')}\n`;
153
+ }
154
+
155
+ export async function releaseCommand(argv, ctx) {
156
+ const args = parseArgs(argv, releaseArgSpec());
157
+ if (args.help || args._[0] === 'help') {
158
+ ctx.logger.info('Usage: aidf release report [--allow-exec] [--record] [--strict] [--json]');
159
+ return 0;
160
+ }
161
+ const root = resolveProjectRoot({ target: args.target, cwd: process.cwd() });
162
+ if (!isInitialized(root)) {
163
+ ctx.logger.error(`AIDF is not initialized in ${root}. Run "aidf install" first.`);
164
+ return 1;
165
+ }
166
+ await attachLogFile(ctx.logger, root).catch(() => null);
167
+
168
+ const sub = args._[0] ?? 'report';
169
+ if (sub !== 'report') {
170
+ ctx.logger.error(`Unknown release subcommand: ${sub}`);
171
+ return 1;
172
+ }
173
+
174
+ const report = await buildReleaseReport(root, {
175
+ frameworkRoot: ctx.frameworkRoot,
176
+ 'allow-exec': args['allow-exec'],
177
+ allowExec: args['allow-exec'],
178
+ });
179
+
180
+ const reportsDir = aidfPaths(root).reports;
181
+ await ensureDir(reportsDir);
182
+ const stamp = report.generatedAt.slice(0, 10);
183
+ const jsonPath = path.join(reportsDir, `RELEASE-${stamp}.json`);
184
+ const mdPath = path.join(reportsDir, `RELEASE-${stamp}.md`);
185
+ await writeJson(jsonPath, report);
186
+ await writeAtomic(mdPath, renderReleaseMarkdown(report));
187
+
188
+ let evidence = null;
189
+ if (args.record) {
190
+ evidence = await recordEvidence(root, {
191
+ type: 'release-report',
192
+ status: report.verdict === 'READY' ? 'PASS' : 'NOT_PROVEN',
193
+ summary: `Release report ${stamp}: ${report.verdict} (${report.summary.pass} PASS gates, ${report.summary.blocked} blocked, ${report.summary.notProven} not proven).`,
194
+ createdBy: 'aidf',
195
+ files: [toPosix(jsonPath), toPosix(mdPath)],
196
+ checks: report.gates.map((g) => ({ id: g.id, status: g.status, reason: g.reason })),
197
+ limitations: report.limitations,
198
+ });
199
+ }
200
+
201
+ if (ctx.json) {
202
+ process.stdout.write(`${JSON.stringify({ report, files: { json: toPosix(jsonPath), markdown: toPosix(mdPath) }, evidence }, null, 2)}\n`);
203
+ } else {
204
+ ctx.logger.info(`Release report: ${report.verdict}`);
205
+ ctx.logger.info(` gates ${report.summary.pass}/${report.summary.gates} PASS, ${report.summary.blocked} blocked, ${report.summary.notProven} NOT_PROVEN`);
206
+ for (const b of report.blockers.slice(0, 10)) ctx.logger.error(` blocker ${b.id}: ${b.reason}`);
207
+ ctx.logger.info(` written: ${toPosix(mdPath)}`);
208
+ if (evidence) ctx.logger.info(` evidence: ${evidence.id}`);
209
+ if (report.verdict !== 'READY') ctx.logger.warn('NOT_READY is not a failure of the report itself; resolve blockers or NOT_PROVEN gates.');
210
+ }
211
+
212
+ if (args.strict && report.verdict !== 'READY') return 1;
213
+ return 0;
214
+ }
@@ -0,0 +1,196 @@
1
+ import { parseArgs, assertEnum } from '../util/args.mjs';
2
+ import { resolveProjectRoot, isInitialized } from '../core/paths.mjs';
3
+ import { attachLogFile } from '../util/logger.mjs';
4
+ import {
5
+ loadRequirementsRegistry,
6
+ addRequirement,
7
+ updateRequirement,
8
+ deleteRequirement,
9
+ calculateCoverage,
10
+ filterRequirements,
11
+ REQUIREMENT_TYPES,
12
+ REQUIREMENT_STATUSES,
13
+ REQUIREMENT_PRIORITIES,
14
+ } from '../core/requirements/registry.mjs';
15
+
16
+ export function requirementsArgSpec() {
17
+ return {
18
+ booleans: ['json', 'help', 'human', 'yes'],
19
+ aliases: { h: 'help', t: 'target' },
20
+ };
21
+ }
22
+
23
+ function printJson(value) {
24
+ process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
25
+ }
26
+
27
+ function parseCriteria(raw) {
28
+ if (!raw) return [];
29
+ try {
30
+ const parsed = JSON.parse(raw);
31
+ if (Array.isArray(parsed)) return parsed;
32
+ } catch {
33
+ // fall through: treat as a single criterion text
34
+ }
35
+ return [{ id: 'AC-1', description: String(raw) }];
36
+ }
37
+
38
+ export async function requirementsCommand(argv, ctx) {
39
+ const args = parseArgs(argv, requirementsArgSpec());
40
+ const sub = args._[0] ?? 'list';
41
+ if (args.help) {
42
+ ctx.logger.info(
43
+ 'Usage: aidf requirements <list|show|add|update|delete|coverage> '
44
+ + '[--type FUNCTIONAL|NON_FUNCTIONAL] [--status S] [--priority P] [--title t] [--ac "..."]',
45
+ );
46
+ return 0;
47
+ }
48
+ const root = resolveProjectRoot({ target: args.target, cwd: process.cwd() });
49
+ if (!isInitialized(root)) {
50
+ ctx.logger.error(`AIDF is not initialized in ${root}. Run "aidf install" first.`);
51
+ return 1;
52
+ }
53
+ await attachLogFile(ctx.logger, root).catch(() => null);
54
+
55
+ if (sub === 'list') {
56
+ const registry = await loadRequirementsRegistry(root);
57
+ const rows = filterRequirements(registry, {
58
+ type: args.type ? assertEnum(args.type, REQUIREMENT_TYPES, 'type') : undefined,
59
+ status: args.status ? assertEnum(args.status, REQUIREMENT_STATUSES, 'status') : undefined,
60
+ priority: args.priority ? assertEnum(args.priority, REQUIREMENT_PRIORITIES, 'priority') : undefined,
61
+ }).map((r) => ({
62
+ id: r.id,
63
+ type: r.type,
64
+ status: r.status,
65
+ priority: r.priority,
66
+ title: r.title,
67
+ }));
68
+ if (ctx.json) {
69
+ printJson({ count: rows.length, requirements: rows });
70
+ } else {
71
+ ctx.logger.info(`Requirements (${rows.length})`);
72
+ ctx.logger.table(rows, [
73
+ { key: 'id', label: 'ID' },
74
+ { key: 'type', label: 'Type' },
75
+ { key: 'status', label: 'Status' },
76
+ { key: 'priority', label: 'Priority' },
77
+ { key: 'title', label: 'Title' },
78
+ ]);
79
+ }
80
+ return 0;
81
+ }
82
+
83
+ if (sub === 'show') {
84
+ const id = args._[1];
85
+ if (!id) {
86
+ ctx.logger.error('Usage: aidf requirements show <id>');
87
+ return 1;
88
+ }
89
+ const registry = await loadRequirementsRegistry(root);
90
+ const req = registry.requirements.find((r) => r.id === id);
91
+ if (!req) {
92
+ ctx.logger.error(`Requirement not found: ${id}`);
93
+ return 1;
94
+ }
95
+ printJson(req);
96
+ return 0;
97
+ }
98
+
99
+ if (sub === 'add') {
100
+ const type = assertEnum(args.type, REQUIREMENT_TYPES, 'type');
101
+ if (!type || !args.title) {
102
+ ctx.logger.error('Usage: aidf requirements add --type FUNCTIONAL|NON_FUNCTIONAL --title "..." [--description "..."] [--priority must|should|could] [--ac "criterion"]');
103
+ return 1;
104
+ }
105
+ const requirement = {
106
+ type,
107
+ title: args.title,
108
+ description: args.description ?? '',
109
+ priority: assertEnum(args.priority, REQUIREMENT_PRIORITIES, 'priority') ?? 'should',
110
+ acceptanceCriteria: parseCriteria(args.ac),
111
+ };
112
+ try {
113
+ const created = await addRequirement(root, requirement, { human: Boolean(args.human), by: args.by });
114
+ ctx.logger.info(`Created ${created.id} (${created.status})`);
115
+ if (ctx.json) printJson(created);
116
+ return 0;
117
+ } catch (error) {
118
+ ctx.logger.error(error.message);
119
+ return 1;
120
+ }
121
+ }
122
+
123
+ if (sub === 'update') {
124
+ const id = args._[1];
125
+ if (!id) {
126
+ ctx.logger.error('Usage: aidf requirements update <id> [--status S] [--title t] [--description d] [--priority P]');
127
+ return 1;
128
+ }
129
+ const updates = {};
130
+ if (args.status) updates.status = assertEnum(args.status, REQUIREMENT_STATUSES, 'status');
131
+ if (args.title) updates.title = args.title;
132
+ if (args.description !== undefined) updates.description = args.description;
133
+ if (args.priority) updates.priority = assertEnum(args.priority, REQUIREMENT_PRIORITIES, 'priority');
134
+ if (Object.keys(updates).length === 0) {
135
+ ctx.logger.error('Nothing to update. Provide --status, --title, --description or --priority.');
136
+ return 1;
137
+ }
138
+ try {
139
+ const updated = await updateRequirement(root, id, updates);
140
+ ctx.logger.info(`Updated ${updated.id}`);
141
+ if (ctx.json) printJson(updated);
142
+ return 0;
143
+ } catch (error) {
144
+ ctx.logger.error(error.message);
145
+ return 1;
146
+ }
147
+ }
148
+
149
+ if (sub === 'delete') {
150
+ const id = args._[1];
151
+ if (!id) {
152
+ ctx.logger.error('Usage: aidf requirements delete <id> (marks the requirement BLOCKED; it is never removed)');
153
+ return 1;
154
+ }
155
+ try {
156
+ const req = await deleteRequirement(root, id);
157
+ ctx.logger.info(`${req.id} marked BLOCKED (soft delete; use update --status to restore)`);
158
+ return 0;
159
+ } catch (error) {
160
+ ctx.logger.error(error.message);
161
+ return 1;
162
+ }
163
+ }
164
+
165
+ if (sub === 'coverage') {
166
+ const result = await calculateCoverage(root);
167
+ if (ctx.json) {
168
+ printJson(result);
169
+ } else {
170
+ ctx.logger.info(
171
+ `Coverage: ${result.coverage.covered}/${result.coverage.total} covered, `
172
+ + `${result.coverage.untested} untested, ${result.coverage.testedButNotPassing} tested-but-failing`,
173
+ );
174
+ ctx.logger.table(
175
+ result.details.map((d) => ({
176
+ id: d.id,
177
+ status: d.status,
178
+ type: d.type,
179
+ criteria: d.tests,
180
+ covered: d.covered ? 'YES' : 'NO',
181
+ })),
182
+ [
183
+ { key: 'id', label: 'ID' },
184
+ { key: 'status', label: 'Status' },
185
+ { key: 'type', label: 'Type' },
186
+ { key: 'criteria', label: 'Criteria' },
187
+ { key: 'covered', label: 'Covered' },
188
+ ],
189
+ );
190
+ }
191
+ return 0;
192
+ }
193
+
194
+ ctx.logger.error(`Unknown requirements subcommand: ${sub}`);
195
+ return 1;
196
+ }
@@ -0,0 +1,181 @@
1
+ import path from 'node:path';
2
+ import { parseArgs } from '../util/args.mjs';
3
+ import { resolveProjectRoot, isInitialized, FRAMEWORK_ROOT } from '../core/paths.mjs';
4
+ import { loadSources, resourcesStatus, setupResources } from '../core/resources.mjs';
5
+ import {
6
+ inventoryAll, coverageReport, summarizeInventory, writeInventory, readInventory, reconcile,
7
+ } from '../core/resource-inventory.mjs';
8
+ import { attachLogFile } from '../util/logger.mjs';
9
+
10
+ export function resourcesArgSpec() {
11
+ return {
12
+ booleans: ['json', 'dry-run', 'help', 'write', 'reconcile'],
13
+ aliases: { h: 'help', t: 'target' },
14
+ };
15
+ }
16
+
17
+ function candidateRoots(root, frameworkRoot) {
18
+ return [root, path.dirname(root), path.dirname(frameworkRoot), frameworkRoot];
19
+ }
20
+
21
+ async function buildInventory(root, ctx, args = {}) {
22
+ const sources = await loadSources(ctx.frameworkRoot ?? FRAMEWORK_ROOT);
23
+ const maxFileBytes = args['max-file-bytes'] ? Number(args['max-file-bytes']) : undefined;
24
+ const results = await inventoryAll(sources, {
25
+ roots: candidateRoots(root, ctx.frameworkRoot ?? FRAMEWORK_ROOT),
26
+ maxFileBytes,
27
+ });
28
+ return { sources, results };
29
+ }
30
+
31
+ export async function resourcesCommand(argv, ctx) {
32
+ const args = parseArgs(argv, resourcesArgSpec());
33
+ const sub = args._[0] ?? 'list';
34
+ if (args.help) {
35
+ ctx.logger.info('Usage: aidf resources <list|inspect|inventory|coverage|reconcile> [--write] [--json]');
36
+ return 0;
37
+ }
38
+ const root = resolveProjectRoot({ target: args.target, cwd: process.cwd() });
39
+ if (!isInitialized(root)) {
40
+ ctx.logger.error(`AIDF is not initialized in ${root}. Run "aidf install" first.`);
41
+ return 1;
42
+ }
43
+ await attachLogFile(ctx.logger, root).catch(() => null);
44
+
45
+ if (sub === 'list') {
46
+ const lock = await resourcesStatus(root);
47
+ if (!lock) {
48
+ ctx.logger.warn('No resources lock found. Run `aidf setup resources`.');
49
+ return 1;
50
+ }
51
+ const rows = Object.values(lock.resources ?? {}).map((r) => ({
52
+ id: r.id,
53
+ status: r.status,
54
+ license: r.license,
55
+ version: r.version,
56
+ commit: r.commit ? String(r.commit).slice(0, 8) : '-',
57
+ path: r.path ?? '-',
58
+ }));
59
+ if (ctx.json) process.stdout.write(`${JSON.stringify({ lock, rows }, null, 2)}\n`);
60
+ else {
61
+ ctx.logger.info(`Resources (${rows.length}) — lock generated ${lock.generatedAt ?? 'never'}`);
62
+ ctx.logger.table(rows, [
63
+ { key: 'id', label: 'Resource' },
64
+ { key: 'status', label: 'Status' },
65
+ { key: 'license', label: 'Licence' },
66
+ { key: 'version', label: 'Version' },
67
+ { key: 'commit', label: 'Commit' },
68
+ { key: 'path', label: 'Path' },
69
+ ]);
70
+ }
71
+ return 0;
72
+ }
73
+
74
+ if (sub === 'inspect') {
75
+ const { results } = await setupResources(root, {
76
+ dryRun: true,
77
+ frameworkRoot: ctx.frameworkRoot,
78
+ });
79
+ if (ctx.json) process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
80
+ else {
81
+ ctx.logger.table(
82
+ results.map((r) => ({
83
+ id: r.id,
84
+ status: r.status,
85
+ kind: r.kind,
86
+ license: r.license,
87
+ path: r.path ?? '-',
88
+ })),
89
+ [
90
+ { key: 'id', label: 'Resource' },
91
+ { key: 'status', label: 'Status' },
92
+ { key: 'kind', label: 'Kind' },
93
+ { key: 'license', label: 'Licence' },
94
+ { key: 'path', label: 'Path' },
95
+ ],
96
+ );
97
+ for (const r of results.filter((x) => x.status === 'BLOCKED')) {
98
+ ctx.logger.warn(`${r.id}: ${r.note}`);
99
+ }
100
+ }
101
+ return 0;
102
+ }
103
+
104
+ if (sub === 'inventory') {
105
+ const { results } = await buildInventory(root, ctx, args);
106
+ const summary = summarizeInventory(results);
107
+ let written = null;
108
+ if (args.write && !args['dry-run']) {
109
+ written = await writeInventory(root, results);
110
+ }
111
+ if (ctx.json) {
112
+ process.stdout.write(`${JSON.stringify({ summary, written: written?.file ?? null, resources: results }, null, 2)}\n`);
113
+ } else {
114
+ ctx.logger.info(`Inventory: ${summary.resources} resources, ${summary.files} files, ${summary.skills} skills`);
115
+ ctx.logger.table(
116
+ results.map((r) => ({
117
+ id: r.id,
118
+ status: r.status,
119
+ license: r.license,
120
+ files: r.fileCount,
121
+ mb: Math.round((r.totalBytes / (1024 * 1024)) * 10) / 10,
122
+ hash: r.treeHash ? r.treeHash.slice(0, 12) : '-',
123
+ })),
124
+ [
125
+ { key: 'id', label: 'Resource' },
126
+ { key: 'status', label: 'Status' },
127
+ { key: 'license', label: 'Licence' },
128
+ { key: 'files', label: 'Files' },
129
+ { key: 'mb', label: 'MB' },
130
+ { key: 'hash', label: 'Tree hash' },
131
+ ],
132
+ );
133
+ if (written) ctx.logger.info(`Manifest written: ${written.file}`);
134
+ else ctx.logger.info('Dry run: manifest not written (add --write).');
135
+ }
136
+ return 0;
137
+ }
138
+
139
+ if (sub === 'coverage') {
140
+ const { sources, results } = await buildInventory(root, ctx, args);
141
+ const coverage = coverageReport(sources, results);
142
+ if (ctx.json) process.stdout.write(`${JSON.stringify(coverage, null, 2)}\n`);
143
+ else {
144
+ ctx.logger.info(
145
+ `Coverage: ${coverage.inventoriedResources}/${coverage.declaredResources} resources, `
146
+ + `${coverage.uniqueSkills} unique skills, ${coverage.totalSkillFiles} SKILL.md files`,
147
+ );
148
+ if (coverage.missing.length > 0) ctx.logger.error(`Missing from inventory: ${coverage.missing.join(', ')}`);
149
+ if (coverage.blockedResources.length > 0) ctx.logger.warn(`Blocked: ${coverage.blockedResources.join(', ')}`);
150
+ if (coverage.duplicateSkills.length > 0) {
151
+ ctx.logger.info(`Duplicate skill names: ${coverage.duplicateSkills.map((d) => d.name).join(', ')}`);
152
+ }
153
+ ctx.logger.info(`Complete: ${coverage.complete ? 'YES' : 'NO'}`);
154
+ }
155
+ return coverage.complete ? 0 : 1;
156
+ }
157
+
158
+ if (sub === 'reconcile') {
159
+ const lock = await resourcesStatus(root);
160
+ if (!lock) {
161
+ ctx.logger.warn('No resources lock found. Run `aidf setup resources` first.');
162
+ return 1;
163
+ }
164
+ let manifest = await readInventory(root);
165
+ if (!manifest || args.reconcile) {
166
+ const { results } = await buildInventory(root, ctx, args);
167
+ if (args.write && !args['dry-run']) await writeInventory(root, results);
168
+ manifest = { resources: results };
169
+ }
170
+ const report = reconcile(lock, manifest);
171
+ if (ctx.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
172
+ else {
173
+ ctx.logger.info(`Reconcile: ${report.checked} locked resources, ${report.drift.length} drift(s)`);
174
+ for (const item of report.drift) ctx.logger.warn(`${item.id}: ${item.kind}`);
175
+ }
176
+ return report.drift.length === 0 ? 0 : 1;
177
+ }
178
+
179
+ ctx.logger.error(`Unknown resources subcommand: ${sub}`);
180
+ return 1;
181
+ }