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,130 @@
1
+ import { parseArgs } from '../util/args.mjs';
2
+ import { resolveProjectRoot, isInitialized, DOCUMENTS, DOC_STATUSES } from '../core/paths.mjs';
3
+ import { loadConfig, saveConfig, validateConfig } from '../core/config.mjs';
4
+ import { ADAPTER_KEYS } from '../core/adapters/index.mjs';
5
+ import { attachLogFile } from '../util/logger.mjs';
6
+
7
+ export function configArgSpec() {
8
+ return {
9
+ booleans: ['json', 'help'],
10
+ aliases: { h: 'help', t: 'target' },
11
+ };
12
+ }
13
+
14
+ const PROTECTED = new Set(['schemaVersion', 'createdAt', 'updatedAt', 'framework.version']);
15
+
16
+ function getPath(object, dotted) {
17
+ return dotted.split('.').reduce((acc, key) => (acc == null ? undefined : acc[key]), object);
18
+ }
19
+
20
+ function setPath(object, dotted, value) {
21
+ const parts = dotted.split('.');
22
+ let current = object;
23
+ for (const part of parts.slice(0, -1)) {
24
+ if (current[part] == null || typeof current[part] !== 'object') current[part] = {};
25
+ current = current[part];
26
+ }
27
+ current[parts[parts.length - 1]] = value;
28
+ }
29
+
30
+ function parseValue(raw) {
31
+ if (raw === 'true') return true;
32
+ if (raw === 'false') return false;
33
+ if (raw === 'null') return null;
34
+ if (/^-?\d+$/.test(raw)) return Number.parseInt(raw, 10);
35
+ if (/^-?\d+\.\d+$/.test(raw)) return Number.parseFloat(raw);
36
+ if ((raw.startsWith('[') && raw.endsWith(']')) || (raw.startsWith('{') && raw.endsWith('}'))) {
37
+ try {
38
+ return JSON.parse(raw);
39
+ } catch {
40
+ return raw;
41
+ }
42
+ }
43
+ return raw;
44
+ }
45
+
46
+ export async function configCommand(argv, ctx) {
47
+ const args = parseArgs(argv, configArgSpec());
48
+ const sub = args._[0] ?? 'list';
49
+ if (args.help) {
50
+ ctx.logger.info('Usage: aidf config <list|get|set|validate> [path] [value] [--json]');
51
+ return 0;
52
+ }
53
+ const root = resolveProjectRoot({ target: args.target, cwd: process.cwd() });
54
+ if (!isInitialized(root)) {
55
+ ctx.logger.error(`AIDF is not initialized in ${root}. Run "aidf install" first.`);
56
+ return 1;
57
+ }
58
+ await attachLogFile(ctx.logger, root).catch(() => null);
59
+ const config = await loadConfig(root);
60
+
61
+ if (sub === 'list') {
62
+ if (ctx.json) process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
63
+ else process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
64
+ return 0;
65
+ }
66
+
67
+ if (sub === 'get') {
68
+ const key = args._[1];
69
+ if (!key) {
70
+ ctx.logger.error('Usage: aidf config get <path>');
71
+ return 1;
72
+ }
73
+ const value = getPath(config, key);
74
+ if (value === undefined) {
75
+ ctx.logger.error(`Unknown configuration path: ${key}`);
76
+ return 1;
77
+ }
78
+ process.stdout.write(`${typeof value === 'string' ? value : JSON.stringify(value, null, 2)}\n`);
79
+ return 0;
80
+ }
81
+
82
+ if (sub === 'set') {
83
+ const key = args._[1];
84
+ const raw = args._.slice(2).join(' ');
85
+ if (!key || raw === '') {
86
+ ctx.logger.error('Usage: aidf config set <path> <value>');
87
+ return 1;
88
+ }
89
+ if (PROTECTED.has(key)) {
90
+ ctx.logger.error(`Refusing to set protected path "${key}".`);
91
+ return 1;
92
+ }
93
+ if (key === 'adapter' && !ADAPTER_KEYS.includes(raw)) {
94
+ ctx.logger.error(`Invalid adapter "${raw}". Allowed: ${ADAPTER_KEYS.join(', ')}`);
95
+ return 1;
96
+ }
97
+ if (key.startsWith('documents.')) {
98
+ const [, doc, field] = key.split('.');
99
+ if (!DOCUMENTS.includes(doc)) {
100
+ ctx.logger.error(`Unknown document "${doc}".`);
101
+ return 1;
102
+ }
103
+ if (field === 'status' && !DOC_STATUSES.includes(raw)) {
104
+ ctx.logger.error(`Invalid status "${raw}". Allowed: ${DOC_STATUSES.join(', ')}`);
105
+ return 1;
106
+ }
107
+ }
108
+ const value = parseValue(raw);
109
+ setPath(config, key, value);
110
+ const errors = validateConfig(config);
111
+ if (errors.length > 0) {
112
+ ctx.logger.error(`Configuration rejected: ${errors.join('; ')}`);
113
+ return 1;
114
+ }
115
+ await saveConfig(root, config);
116
+ ctx.logger.info(`${key} = ${typeof value === 'string' ? value : JSON.stringify(value)}`);
117
+ return 0;
118
+ }
119
+
120
+ if (sub === 'validate') {
121
+ const errors = validateConfig(config);
122
+ if (ctx.json) process.stdout.write(`${JSON.stringify({ valid: errors.length === 0, errors }, null, 2)}\n`);
123
+ else if (errors.length === 0) ctx.logger.info('Configuration: PASS');
124
+ else for (const error of errors) ctx.logger.error(error);
125
+ return errors.length === 0 ? 0 : 1;
126
+ }
127
+
128
+ ctx.logger.error(`Unknown config subcommand: ${sub}`);
129
+ return 1;
130
+ }
@@ -0,0 +1,55 @@
1
+ import { parseArgs } from '../util/args.mjs';
2
+ import { resolveProjectRoot, isInitialized } from '../core/paths.mjs';
3
+ import { loadConfig } from '../core/config.mjs';
4
+ import { assembleContext, renderContextMarkdown, writeContext } from '../core/context.mjs';
5
+ import { attachLogFile } from '../util/logger.mjs';
6
+ import { resolveInside, writeAtomic } from '../util/fsx.mjs';
7
+
8
+ export function contextArgSpec() {
9
+ return {
10
+ booleans: ['json', 'help', 'no-write'],
11
+ aliases: { h: 'help', t: 'target' },
12
+ };
13
+ }
14
+
15
+ export async function contextCommand(argv, ctx) {
16
+ const args = parseArgs(argv, contextArgSpec());
17
+ if (args.help) {
18
+ ctx.logger.info('Usage: aidf context --task "<request>" [--write <file>] [--json]');
19
+ return 0;
20
+ }
21
+ const task = args.task ?? args._.join(' ');
22
+ if (!task) {
23
+ ctx.logger.error('Missing --task "<request>".');
24
+ return 1;
25
+ }
26
+ const root = resolveProjectRoot({ target: args.target, cwd: process.cwd() });
27
+ if (!isInitialized(root)) {
28
+ ctx.logger.error(`AIDF is not initialized in ${root}. Run "aidf install" first.`);
29
+ return 1;
30
+ }
31
+ await attachLogFile(ctx.logger, root).catch(() => null);
32
+ const config = await loadConfig(root);
33
+ const context = await assembleContext(root, task, { config, frameworkRoot: ctx.frameworkRoot });
34
+ let written = null;
35
+ if (!args['no-write']) {
36
+ const result = await writeContext(root, context, config);
37
+ written = result.markdownPath;
38
+ }
39
+ if (args.write) {
40
+ const target = resolveInside(root, args.write);
41
+ await writeAtomic(target, renderContextMarkdown(context, config));
42
+ written = args.write;
43
+ }
44
+ if (ctx.json) {
45
+ process.stdout.write(`${JSON.stringify({ context, written }, null, 2)}\n`);
46
+ } else {
47
+ process.stdout.write(renderContextMarkdown(context, config));
48
+ if (written) ctx.logger.info(`Context written to ${written}`);
49
+ }
50
+ if (context.status === 'BLOCKED') {
51
+ ctx.logger.error('Contradiction-sensitive documents are BLOCKED or OUTDATED. Affected decisions are blocked until resolved.');
52
+ return 2;
53
+ }
54
+ return 0;
55
+ }
@@ -0,0 +1,142 @@
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 { readJson, writeJson, writeAtomic, ensureDir, resolveInside, toPosix } from '../util/fsx.mjs';
6
+ import { evaluateTechnologyDecision, exportToJSON, exportToMarkdown } from '../core/technology-decision/index.mjs';
7
+ import { validateArtefact } from '../core/artefacts/index.mjs';
8
+
9
+ export function decisionArgSpec() {
10
+ return {
11
+ booleans: ['json', 'help', 'write', 'markdown'],
12
+ aliases: { h: 'help', t: 'target' },
13
+ };
14
+ }
15
+
16
+ async function loadJsonFile(root, file, label) {
17
+ if (!file) throw new Error(`Missing ${label} file.`);
18
+ const abs = path.isAbsolute(file) ? file : resolveInside(root, file);
19
+ return readJson(abs, null);
20
+ }
21
+
22
+ function toArtefact(document, root) {
23
+ const now = new Date().toISOString();
24
+ const id = String(document.meta?.id ?? `TECH-DECISION-${Date.now()}`).replace(/[^A-Za-z0-9_-]/g, '-');
25
+ return {
26
+ id,
27
+ schemaVersion: '1.0.0',
28
+ createdAt: now,
29
+ updatedAt: now,
30
+ status: 'DRAFT',
31
+ type: 'decision',
32
+ title: document.meta?.id ?? 'Technology decision',
33
+ source: {
34
+ type: 'generated',
35
+ author: 'aidf',
36
+ createdAt: now,
37
+ generator: 'technology-decision@0.2.0',
38
+ },
39
+ links: {},
40
+ document,
41
+ validation: {
42
+ schemaVersion: '1.0.0',
43
+ timestamp: now,
44
+ valid: true,
45
+ errors: [],
46
+ warnings: ['Decision requires human approval before VALIDATED (see document.humanApproval).'],
47
+ },
48
+ };
49
+ }
50
+
51
+ export async function decisionCommand(argv, ctx) {
52
+ const args = parseArgs(argv, decisionArgSpec());
53
+ const sub = args._[0] ?? 'evaluate';
54
+ if (args.help || sub === 'help') {
55
+ ctx.logger.info(
56
+ 'Usage: aidf decision evaluate --context <file.json> --options <file.json> [--write] [--markdown] [--out <file>]',
57
+ );
58
+ return 0;
59
+ }
60
+ const root = resolveProjectRoot({ target: args.target, cwd: process.cwd() });
61
+ if (!isInitialized(root)) {
62
+ ctx.logger.error(`AIDF is not initialized in ${root}. Run "aidf install" first.`);
63
+ return 1;
64
+ }
65
+ await attachLogFile(ctx.logger, root).catch(() => null);
66
+
67
+ if (sub !== 'evaluate') {
68
+ ctx.logger.error(`Unknown decision subcommand: ${sub}`);
69
+ return 1;
70
+ }
71
+
72
+ let context;
73
+ let options;
74
+ try {
75
+ context = await loadJsonFile(root, args.context, '--context');
76
+ const raw = await loadJsonFile(root, args.options, '--options');
77
+ options = { technologyOptions: Array.isArray(raw) ? raw : (raw?.technologyOptions ?? []) };
78
+ } catch (error) {
79
+ ctx.logger.error(error.message);
80
+ return 1;
81
+ }
82
+ if (!context || typeof context !== 'object') {
83
+ ctx.logger.error('--context must be a JSON object (projectType, constraints, skills, ...).');
84
+ return 1;
85
+ }
86
+ if (options.technologyOptions.length === 0) {
87
+ ctx.logger.error('--options must contain at least one technology option.');
88
+ return 1;
89
+ }
90
+
91
+ const document = await evaluateTechnologyDecision(context, options);
92
+
93
+ if (args.out) {
94
+ try {
95
+ const abs = path.isAbsolute(args.out) ? args.out : resolveInside(root, args.out);
96
+ await ensureDir(path.dirname(abs));
97
+ if (args.markdown) {
98
+ await writeAtomic(abs, exportToMarkdown(document));
99
+ } else {
100
+ await writeJson(abs, JSON.parse(exportToJSON(document)));
101
+ }
102
+ ctx.logger.info(`Decision written to ${toPosix(abs)}`);
103
+ } catch (error) {
104
+ ctx.logger.error(`Cannot write --out: ${error.message}`);
105
+ return 1;
106
+ }
107
+ }
108
+
109
+ let artefactPath = null;
110
+ if (args.write) {
111
+ const artefact = toArtefact(document, root);
112
+ const validation = await validateArtefact(artefact);
113
+ if (!validation.valid) {
114
+ ctx.logger.error(`Generated artefact failed validation: ${validation.errors.join('; ')}`);
115
+ return 1;
116
+ }
117
+ const dir = aidfPaths(root).artefacts.decisions;
118
+ await ensureDir(dir);
119
+ artefactPath = path.join(dir, `${artefact.id}.json`);
120
+ await writeJson(artefactPath, artefact);
121
+ }
122
+
123
+ if (ctx.json) {
124
+ process.stdout.write(`${JSON.stringify({ document, artefact: artefactPath ? toPosix(artefactPath) : null }, null, 2)}\n`);
125
+ return 0;
126
+ }
127
+
128
+ const rec = document.recommendation ?? {};
129
+ ctx.logger.info(`Decision ${document.meta?.id ?? ''} — confidence ${rec.confidence ?? 'unknown'}`);
130
+ for (const s of rec.stack ?? []) ctx.logger.info(` ${s.component}: ${s.option} (${s.reason ?? ''})`);
131
+ ctx.logger.info(
132
+ `Options: ${document.analysis?.deterministic?.summary?.totalOptions ?? '?'} total, `
133
+ + `${document.analysis?.deterministic?.summary?.validOptions ?? '?'} valid, `
134
+ + `${document.analysis?.deterministic?.summary?.eliminatedOptions ?? '?'} eliminated`,
135
+ );
136
+ for (const u of rec.uncertainties ?? []) ctx.logger.warn(`uncertainty: ${JSON.stringify(u)}`);
137
+ if (document.humanApproval?.required && !document.humanApproval?.approved) {
138
+ ctx.logger.warn('Human approval required before this decision is VALIDATED.');
139
+ }
140
+ if (artefactPath) ctx.logger.info(`Artefact: ${toPosix(artefactPath)}`);
141
+ return 0;
142
+ }
@@ -0,0 +1,141 @@
1
+ import path from 'node:path';
2
+ import { parseArgs } from '../util/args.mjs';
3
+ import { resolveProjectRoot, isInitialized } from '../core/paths.mjs';
4
+ import { attachLogFile } from '../util/logger.mjs';
5
+ import { readJson, writeAtomic, writeJson, ensureDir, resolveInside, toPosix, timestampSlug } from '../util/fsx.mjs';
6
+ import { runDesignWorkflow } from '../core/design-engineering/index.mjs';
7
+ import { classifyComplexity, getWorkflow } from '../core/design-engineering/complexity-classifier.mjs';
8
+
9
+ export function designArgSpec() {
10
+ return {
11
+ booleans: ['json', 'help', 'write'],
12
+ aliases: { h: 'help', t: 'target' },
13
+ };
14
+ }
15
+
16
+ function slugify(name) {
17
+ return String(name ?? 'screen').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'screen';
18
+ }
19
+
20
+ /**
21
+ * Persist fallback outputs (wireframes, mockups, documentation) under
22
+ * .aidf/reports/design/<timestamp>/. Returns the list of written files.
23
+ */
24
+ async function writeOutputs(root, result, outDir) {
25
+ const files = [];
26
+ const outputs = result.outputs ?? {};
27
+ const base = outDir ?? path.join(root, '.aidf', 'reports', 'design', timestampSlug());
28
+ await ensureDir(base);
29
+
30
+ for (const wireframe of outputs.wireframes ?? []) {
31
+ const file = path.join(base, `${slugify(wireframe.name)}.svg`);
32
+ await writeAtomic(file, wireframe.svg ?? '');
33
+ files.push(toPosix(file));
34
+ }
35
+ if (outputs.mockups) {
36
+ const file = path.join(base, 'mockup.css');
37
+ await writeAtomic(file, typeof outputs.mockups === 'string' ? outputs.mockups : JSON.stringify(outputs.mockups, null, 2));
38
+ files.push(toPosix(file));
39
+ }
40
+ if (outputs.documentation) {
41
+ const file = path.join(base, 'FALLBACK.md');
42
+ await writeAtomic(file, outputs.documentation);
43
+ files.push(toPosix(file));
44
+ }
45
+ await writeJson(path.join(base, 'result.json'), {
46
+ status: result.status,
47
+ complexity: result.complexity,
48
+ workflow: result.workflow,
49
+ figmaStatus: result.figmaStatus,
50
+ files,
51
+ });
52
+ files.push(toPosix(path.join(base, 'result.json')));
53
+ return { dir: toPosix(base), files };
54
+ }
55
+
56
+ export async function designCommand(argv, ctx) {
57
+ const args = parseArgs(argv, designArgSpec());
58
+ const sub = args._[0] ?? 'run';
59
+ if (args.help) {
60
+ ctx.logger.info(
61
+ 'Usage: aidf design <run|classify> --context <file.json> [--out <dir>] [--write]',
62
+ );
63
+ return 0;
64
+ }
65
+ const root = resolveProjectRoot({ target: args.target, cwd: process.cwd() });
66
+ if (!isInitialized(root)) {
67
+ ctx.logger.error(`AIDF is not initialized in ${root}. Run "aidf install" first.`);
68
+ return 1;
69
+ }
70
+ await attachLogFile(ctx.logger, root).catch(() => null);
71
+
72
+ let context;
73
+ if (args.context) {
74
+ try {
75
+ const abs = path.isAbsolute(args.context) ? args.context : resolveInside(root, args.context);
76
+ context = await readJson(abs, null);
77
+ } catch (error) {
78
+ ctx.logger.error(`Cannot read --context: ${error.message}`);
79
+ return 1;
80
+ }
81
+ }
82
+ if (!context || typeof context !== 'object') {
83
+ ctx.logger.error('--context <file.json> is required (featureCount, teamSize, timelineWeeks, budget, screens, theme, figma, ...).');
84
+ return 1;
85
+ }
86
+
87
+ if (sub === 'classify') {
88
+ const complexity = classifyComplexity(context);
89
+ const workflow = getWorkflow(complexity.complexity);
90
+ const payload = { complexity, workflow };
91
+ if (ctx.json) {
92
+ process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
93
+ } else {
94
+ ctx.logger.info(`Complexity: ${complexity.complexity} (score ${complexity.score}) → workflow '${workflow}'`);
95
+ }
96
+ return 0;
97
+ }
98
+
99
+ if (sub === 'run') {
100
+ const result = await runDesignWorkflow(context);
101
+ let written = null;
102
+ if (args.write || args.out) {
103
+ try {
104
+ const outDir = args.out
105
+ ? (path.isAbsolute(args.out) ? args.out : resolveInside(root, args.out))
106
+ : undefined;
107
+ written = await writeOutputs(root, result, outDir);
108
+ } catch (error) {
109
+ ctx.logger.error(`Cannot write outputs: ${error.message}`);
110
+ return 1;
111
+ }
112
+ }
113
+ const payload = {
114
+ status: result.status,
115
+ complexity: result.complexity,
116
+ workflow: result.workflow,
117
+ figmaStatus: result.figmaStatus,
118
+ reasons: result.reasons ?? [],
119
+ written,
120
+ };
121
+ if (ctx.json) {
122
+ process.stdout.write(`${JSON.stringify({ ...payload, outputs: result.outputs ? Object.keys(result.outputs) : [] }, null, 2)}\n`);
123
+ } else {
124
+ ctx.logger.info(`Design workflow: ${result.status} (complexity ${result.complexity?.complexity}, workflow ${result.workflow})`);
125
+ for (const r of result.reasons ?? []) ctx.logger.warn(` - ${r}`);
126
+ if (result.figmaStatus && result.figmaStatus.status !== 'fully_verified') {
127
+ ctx.logger.warn(`Figma: ${result.figmaStatus.status} — fallback outputs only; no real Figma file was created.`);
128
+ }
129
+ if (written) {
130
+ ctx.logger.info(`Outputs written to ${written.dir}:`);
131
+ for (const f of written.files) ctx.logger.info(` - ${f}`);
132
+ } else {
133
+ ctx.logger.info('Dry run: outputs not written (add --write or --out <dir>).');
134
+ }
135
+ }
136
+ return 0;
137
+ }
138
+
139
+ ctx.logger.error(`Unknown design subcommand: ${sub}`);
140
+ return 1;
141
+ }
@@ -0,0 +1,133 @@
1
+ import path from 'node:path';
2
+ import { parseArgs, assertEnum } from '../util/args.mjs';
3
+ import { resolveProjectRoot, isInitialized, DOCUMENTS, DOC_STATUSES } from '../core/paths.mjs';
4
+ import { loadConfig, saveConfig, setDocumentStatus, defaultConfig } from '../core/config.mjs';
5
+ import { loadManifest, saveManifest, recordFile } from '../core/manifest.mjs';
6
+ import { readText, writeAtomic, sha256Text, exists } from '../util/fsx.mjs';
7
+ import { splitFrontmatter, joinFrontmatter } from '../util/frontmatter.mjs';
8
+ import { attachLogFile } from '../util/logger.mjs';
9
+ import { generateDocs } from '../core/docsgen.mjs';
10
+
11
+ export function docsArgSpec() {
12
+ return {
13
+ booleans: ['json', 'help', 'check'],
14
+ aliases: { h: 'help', t: 'target' },
15
+ };
16
+ }
17
+
18
+ export async function docsCommand(argv, ctx) {
19
+ const args = parseArgs(argv, docsArgSpec());
20
+ const sub = args._[0] ?? 'list';
21
+ if (args.help) {
22
+ ctx.logger.info('Usage: aidf docs <list|show|status|generate> [DOC] [STATUS] [--by <name>] [--note "..."] [--check]');
23
+ return 0;
24
+ }
25
+ const root = resolveProjectRoot({ target: args.target, cwd: process.cwd() });
26
+ if (!isInitialized(root)) {
27
+ ctx.logger.error(`AIDF is not initialized in ${root}. Run "aidf install" first.`);
28
+ return 1;
29
+ }
30
+ await attachLogFile(ctx.logger, root).catch(() => null);
31
+ const config = await loadConfig(root).catch(() => defaultConfig({}));
32
+
33
+ if (sub === 'list') {
34
+ const rows = Object.entries(config.documents).map(([doc, entry]) => ({
35
+ doc,
36
+ status: entry.status,
37
+ by: entry.validatedBy ?? '-',
38
+ at: entry.validatedAt ? entry.validatedAt.slice(0, 10) : '-',
39
+ }));
40
+ if (ctx.json) process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
41
+ else {
42
+ ctx.logger.info('AIDF documents');
43
+ ctx.logger.table(rows, [
44
+ { key: 'doc', label: 'Document' },
45
+ { key: 'status', label: 'Status' },
46
+ { key: 'by', label: 'Validated by' },
47
+ { key: 'at', label: 'Date' },
48
+ ]);
49
+ }
50
+ return 0;
51
+ }
52
+
53
+ if (sub === 'show') {
54
+ const doc = assertEnum(args._[1], DOCUMENTS, 'document');
55
+ if (!doc) {
56
+ ctx.logger.error('Usage: aidf docs show <DOCUMENT>');
57
+ return 1;
58
+ }
59
+ const file = path.join(root, '.aidf', 'docs', `${doc}.md`);
60
+ if (!(await exists(file))) {
61
+ ctx.logger.error(`Missing document file: .aidf/docs/${doc}.md`);
62
+ return 1;
63
+ }
64
+ process.stdout.write(await readText(file));
65
+ return 0;
66
+ }
67
+
68
+ if (sub === 'generate') {
69
+ const result = await generateDocs(root, { check: Boolean(args.check) });
70
+ if (ctx.json) {
71
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
72
+ } else {
73
+ ctx.logger.info(
74
+ `${args.check ? 'Checked' : 'Generated'} ${result.generated.length} document(s) in ${result.directory}`,
75
+ );
76
+ for (const g of result.generated) {
77
+ ctx.logger.info(` ${g.action.padEnd(11)} ${g.file} (from ${g.sourceId})`);
78
+ if (g.diverged) ctx.logger.warn(` manual edit detected — regenerate overwrites it`);
79
+ }
80
+ if (result.generated.length === 0) {
81
+ ctx.logger.warn('No artefacts found to render. Create requirements/test-plan/threat-model/decision artefacts first.');
82
+ }
83
+ }
84
+ return 0;
85
+ }
86
+
87
+ if (sub === 'status') {
88
+ const doc = assertEnum(args._[1], DOCUMENTS, 'document');
89
+ const status = assertEnum(args._[2], DOC_STATUSES, 'status');
90
+ if (!doc || !status) {
91
+ ctx.logger.error(`Usage: aidf docs status <DOCUMENT> <${DOC_STATUSES.join('|')}> [--by <name>] [--note "..."]`);
92
+ return 1;
93
+ }
94
+ if (status === 'VALIDATED' && !args.by) {
95
+ ctx.logger.error('VALIDATED requires --by "<name>" to record human accountability.');
96
+ return 1;
97
+ }
98
+ if (status === 'NOT_APPLICABLE' && !args.note) {
99
+ ctx.logger.error('NOT_APPLICABLE requires --note "<reason>".');
100
+ return 1;
101
+ }
102
+ setDocumentStatus(config, doc, status, { by: args.by, note: args.note });
103
+ await saveConfig(root, config);
104
+ const file = path.join(root, '.aidf', 'docs', `${doc}.md`);
105
+ if (await exists(file)) {
106
+ const text = await readText(file);
107
+ const { frontmatter, body } = splitFrontmatter(text);
108
+ const next = joinFrontmatter({
109
+ ...(frontmatter ?? {}),
110
+ doc,
111
+ status,
112
+ version: frontmatter?.version ?? '0.2.0',
113
+ updated: new Date().toISOString().slice(0, 10),
114
+ ...(args.by ? { validated_by: args.by } : {}),
115
+ }, body);
116
+ await writeAtomic(file, next);
117
+ const manifest = await loadManifest(root);
118
+ if (manifest.files[`.aidf/docs/${doc}.md`]) {
119
+ recordFile(manifest, `.aidf/docs/${doc}.md`, {
120
+ ...manifest.files[`.aidf/docs/${doc}.md`],
121
+ sha256: sha256Text(next),
122
+ updatedAt: new Date().toISOString(),
123
+ });
124
+ await saveManifest(root, manifest);
125
+ }
126
+ }
127
+ ctx.logger.info(`${doc}: ${status}${args.by ? ` (by ${args.by})` : ''}`);
128
+ return 0;
129
+ }
130
+
131
+ ctx.logger.error(`Unknown docs subcommand: ${sub}`);
132
+ return 1;
133
+ }