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,208 @@
1
+ import fs from 'node:fs';
2
+ import fsp from 'node:fs/promises';
3
+ import path from 'node:path';
4
+ import crypto from 'node:crypto';
5
+
6
+ const WINDOWS_RESERVED = new Set([
7
+ 'con', 'prn', 'aux', 'nul',
8
+ 'com1', 'com2', 'com3', 'com4', 'com5', 'com6', 'com7', 'com8', 'com9',
9
+ 'lpt1', 'lpt2', 'lpt3', 'lpt4', 'lpt5', 'lpt6', 'lpt7', 'lpt8', 'lpt9',
10
+ ]);
11
+
12
+ export class PathSafetyError extends Error {
13
+ constructor(message) {
14
+ super(message);
15
+ this.name = 'PathSafetyError';
16
+ }
17
+ }
18
+
19
+ /** Convert a project-relative path to a safe absolute path inside root. */
20
+ export function resolveInside(root, relativePath) {
21
+ if (typeof relativePath !== 'string' || relativePath.trim() === '') {
22
+ throw new PathSafetyError('Path must be a non-empty string');
23
+ }
24
+ if (relativePath.includes('\0')) {
25
+ throw new PathSafetyError('Path contains a null byte');
26
+ }
27
+ if (path.isAbsolute(relativePath) || /^[A-Za-z]:/.test(relativePath)) {
28
+ throw new PathSafetyError(`Absolute paths are not allowed: ${relativePath}`);
29
+ }
30
+ const normalized = path.normalize(relativePath).replace(/\\/g, '/');
31
+ if (normalized === '..' || normalized.startsWith('../') || normalized.includes('/../')) {
32
+ throw new PathSafetyError(`Path traversal is not allowed: ${relativePath}`);
33
+ }
34
+ const rootResolved = path.resolve(root);
35
+ const target = path.resolve(rootResolved, normalized);
36
+ const rel = path.relative(rootResolved, target);
37
+ if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
38
+ throw new PathSafetyError(`Path escapes project root: ${relativePath}`);
39
+ }
40
+ for (const segment of normalized.split('/')) {
41
+ const base = segment.split('.')[0].toLowerCase();
42
+ if (WINDOWS_RESERVED.has(base)) {
43
+ throw new PathSafetyError(`Reserved Windows path segment: ${segment}`);
44
+ }
45
+ if (/[<>:"|?*]/.test(segment)) {
46
+ throw new PathSafetyError(`Invalid path character in: ${segment}`);
47
+ }
48
+ }
49
+ return target;
50
+ }
51
+
52
+ export function toPosix(p) {
53
+ return p.replace(/\\/g, '/');
54
+ }
55
+
56
+ export function relativeTo(root, target) {
57
+ return toPosix(path.relative(path.resolve(root), path.resolve(target)));
58
+ }
59
+
60
+ export async function exists(p) {
61
+ try {
62
+ await fsp.access(p);
63
+ return true;
64
+ } catch {
65
+ return false;
66
+ }
67
+ }
68
+
69
+ export function existsSync(p) {
70
+ try {
71
+ fs.accessSync(p);
72
+ return true;
73
+ } catch {
74
+ return false;
75
+ }
76
+ }
77
+
78
+ export async function ensureDir(dir) {
79
+ await fsp.mkdir(dir, { recursive: true });
80
+ }
81
+
82
+ export async function readText(p) {
83
+ return fsp.readFile(p, 'utf8');
84
+ }
85
+
86
+ export async function readJson(p, fallback = null) {
87
+ try {
88
+ const text = await fsp.readFile(p, 'utf8');
89
+ return JSON.parse(text);
90
+ } catch (error) {
91
+ if (error && error.code === 'ENOENT') return fallback;
92
+ throw error;
93
+ }
94
+ }
95
+
96
+ export async function writeAtomic(p, content) {
97
+ await ensureDir(path.dirname(p));
98
+ const tmp = `${p}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
99
+ await fsp.writeFile(tmp, content, 'utf8');
100
+ await fsp.rename(tmp, p);
101
+ }
102
+
103
+ export async function writeJson(p, value) {
104
+ await writeAtomic(p, `${JSON.stringify(value, null, 2)}\n`);
105
+ }
106
+
107
+ export function sha256Buffer(buffer) {
108
+ return crypto.createHash('sha256').update(buffer).digest('hex');
109
+ }
110
+
111
+ export function sha256Text(text) {
112
+ return sha256Buffer(Buffer.from(text, 'utf8'));
113
+ }
114
+
115
+ export async function sha256File(p) {
116
+ const buffer = await fsp.readFile(p);
117
+ return sha256Buffer(buffer);
118
+ }
119
+
120
+ export async function listFiles(root, options = {}) {
121
+ const { ignore = [], maxFiles = 20000 } = options;
122
+ const results = [];
123
+ const ignoreSet = new Set(ignore.map((p) => toPosix(p)));
124
+ async function walk(dir, rel) {
125
+ if (results.length >= maxFiles) return;
126
+ let entries;
127
+ try {
128
+ entries = await fsp.readdir(dir, { withFileTypes: true });
129
+ } catch {
130
+ return;
131
+ }
132
+ for (const entry of entries) {
133
+ const childRel = rel ? `${rel}/${entry.name}` : entry.name;
134
+ if (ignoreSet.has(childRel)) continue;
135
+ if (entry.name === '.git' || entry.name === 'node_modules') continue;
136
+ const childAbs = path.join(dir, entry.name);
137
+ if (entry.isDirectory()) {
138
+ await walk(childAbs, childRel);
139
+ } else if (entry.isFile()) {
140
+ results.push(childRel);
141
+ }
142
+ if (results.length >= maxFiles) return;
143
+ }
144
+ }
145
+ await walk(path.resolve(root), '');
146
+ return results;
147
+ }
148
+
149
+ export async function copyFileSafe(source, target) {
150
+ await ensureDir(path.dirname(target));
151
+ await fsp.copyFile(source, target);
152
+ }
153
+
154
+ export async function removeFile(p) {
155
+ try {
156
+ await fsp.unlink(p);
157
+ return true;
158
+ } catch (error) {
159
+ if (error && error.code === 'ENOENT') return false;
160
+ throw error;
161
+ }
162
+ }
163
+
164
+ export async function removeDir(p) {
165
+ try {
166
+ await fsp.rm(p, { recursive: true, force: false });
167
+ return true;
168
+ } catch (error) {
169
+ if (error && error.code === 'ENOENT') return false;
170
+ throw error;
171
+ }
172
+ }
173
+
174
+ export async function readDirSafe(p) {
175
+ try {
176
+ return await fsp.readdir(p, { withFileTypes: true });
177
+ } catch {
178
+ return [];
179
+ }
180
+ }
181
+
182
+ export function timestampSlug(date = new Date()) {
183
+ return date.toISOString().replace(/[:.]/g, '-');
184
+ }
185
+
186
+ export function shortHash(text, length = 12) {
187
+ return sha256Text(text).slice(0, length);
188
+ }
189
+
190
+ /** Recursively merge patch into base. Existing scalar values in base win unless overwrite is true. */
191
+ export function deepMerge(base, patch, overwrite = false) {
192
+ if (Array.isArray(base) || Array.isArray(patch)) {
193
+ return patch === undefined ? base : patch;
194
+ }
195
+ if (base && typeof base === 'object' && patch && typeof patch === 'object') {
196
+ const out = { ...base };
197
+ for (const [key, value] of Object.entries(patch)) {
198
+ if (!(key in out)) out[key] = value;
199
+ else if (out[key] && typeof out[key] === 'object' && value && typeof value === 'object') {
200
+ out[key] = deepMerge(out[key], value, overwrite);
201
+ } else if (overwrite) {
202
+ out[key] = value;
203
+ }
204
+ }
205
+ return out;
206
+ }
207
+ return base === undefined ? patch : base;
208
+ }
@@ -0,0 +1,74 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { ensureDir } from './fsx.mjs';
4
+
5
+ const LEVELS = { debug: 10, info: 20, warn: 30, error: 40, silent: 100 };
6
+
7
+ export class Logger {
8
+ constructor(options = {}) {
9
+ this.level = options.level ?? 'info';
10
+ this.json = Boolean(options.json);
11
+ this.logFile = options.logFile ?? null;
12
+ this.records = [];
13
+ this.redact = options.redact ?? [];
14
+ }
15
+
16
+ setLogFile(file) {
17
+ this.logFile = file;
18
+ }
19
+
20
+ write(level, message, data) {
21
+ const record = {
22
+ ts: new Date().toISOString(),
23
+ level,
24
+ message,
25
+ ...(data ? { data } : {}),
26
+ };
27
+ this.records.push(record);
28
+ if (this.logFile) {
29
+ try {
30
+ fs.mkdirSync(path.dirname(this.logFile), { recursive: true });
31
+ fs.appendFileSync(this.logFile, `${JSON.stringify(record)}\n`, 'utf8');
32
+ } catch {
33
+ // Logging must never break the command.
34
+ }
35
+ }
36
+ if (LEVELS[level] < LEVELS[this.level]) return;
37
+ if (this.json) {
38
+ process.stdout.write(`${JSON.stringify(record)}\n`);
39
+ return;
40
+ }
41
+ const stream = level === 'error' || level === 'warn' ? process.stderr : process.stdout;
42
+ const prefix = level === 'error' ? 'ERROR' : level === 'warn' ? 'WARN' : level === 'debug' ? 'DEBUG' : 'INFO';
43
+ stream.write(`[${prefix}] ${message}${data ? ` ${JSON.stringify(data)}` : ''}\n`);
44
+ }
45
+
46
+ debug(message, data) { this.write('debug', message, data); }
47
+ info(message, data) { this.write('info', message, data); }
48
+ warn(message, data) { this.write('warn', message, data); }
49
+ error(message, data) { this.write('error', message, data); }
50
+
51
+ table(rows, columns) {
52
+ if (this.json) {
53
+ this.info('table', { rows });
54
+ return;
55
+ }
56
+ const widths = columns.map((c) => Math.max(c.label.length, ...rows.map((r) => String(r[c.key] ?? '').length)));
57
+ const line = (cells) => cells.map((cell, i) => String(cell ?? '').padEnd(widths[i])).join(' ');
58
+ process.stdout.write(`${line(columns.map((c) => c.label))}\n`);
59
+ process.stdout.write(`${line(widths.map((w) => '-'.repeat(w)))}\n`);
60
+ for (const row of rows) process.stdout.write(`${line(columns.map((c) => row[c.key]))}\n`);
61
+ }
62
+ }
63
+
64
+ export function createLogger(options) {
65
+ return new Logger(options);
66
+ }
67
+
68
+ export async function attachLogFile(logger, root) {
69
+ const dir = path.join(root, '.aidf', 'logs');
70
+ await ensureDir(dir);
71
+ const file = path.join(dir, `aidf-${new Date().toISOString().slice(0, 10)}.jsonl`);
72
+ logger.setLogFile(file);
73
+ return file;
74
+ }
@@ -0,0 +1,66 @@
1
+ export const AIDF_BLOCK_BEGIN = '<!-- AIDF:BEGIN managed by aidf - do not edit inside this block -->';
2
+ export const AIDF_BLOCK_END = '<!-- AIDF:END -->';
3
+
4
+ export function hasManagedBlock(text) {
5
+ return text.includes(AIDF_BLOCK_BEGIN) && text.includes(AIDF_BLOCK_END);
6
+ }
7
+
8
+ export function replaceManagedBlock(text, content, blockId = 'default') {
9
+ const begin = blockId === 'default'
10
+ ? AIDF_BLOCK_BEGIN
11
+ : `<!-- AIDF:BEGIN ${blockId} managed by aidf - do not edit inside this block -->`;
12
+ const end = blockId === 'default' ? AIDF_BLOCK_END : `<!-- AIDF:END ${blockId} -->`;
13
+ const block = `${begin}\n${content.trim()}\n${end}`;
14
+ const beginIndex = text.indexOf(begin);
15
+ const endIndex = text.indexOf(end);
16
+ if (beginIndex !== -1 && endIndex !== -1 && endIndex > beginIndex) {
17
+ return `${text.slice(0, beginIndex)}${block}${text.slice(endIndex + end.length)}`;
18
+ }
19
+ if (beginIndex !== -1 || endIndex !== -1) {
20
+ throw new Error(`Malformed AIDF managed block "${blockId}" in file.`);
21
+ }
22
+ const separator = text.trim() === '' ? '' : text.endsWith('\n') ? '\n' : '\n\n';
23
+ return `${text}${separator}${block}\n`;
24
+ }
25
+
26
+ export function removeManagedBlock(text, blockId = 'default') {
27
+ const begin = blockId === 'default'
28
+ ? AIDF_BLOCK_BEGIN
29
+ : `<!-- AIDF:BEGIN ${blockId} managed by aidf - do not edit inside this block -->`;
30
+ const end = blockId === 'default' ? AIDF_BLOCK_END : `<!-- AIDF:END ${blockId} -->`;
31
+ const beginIndex = text.indexOf(begin);
32
+ const endIndex = text.indexOf(end);
33
+ if (beginIndex === -1 || endIndex === -1 || endIndex < beginIndex) return text;
34
+ const before = text.slice(0, beginIndex).replace(/\s+$/, '');
35
+ const after = text.slice(endIndex + end.length).replace(/^\s+/, '');
36
+ if (!before) return after ? `${after}\n` : '';
37
+ if (!after) return `${before}\n`;
38
+ return `${before}\n\n${after}\n`;
39
+ }
40
+
41
+ export function slugify(value) {
42
+ return String(value)
43
+ .normalize('NFKD')
44
+ .replace(/[\u0300-\u036f]/g, '')
45
+ .toLowerCase()
46
+ .replace(/[^a-z0-9]+/g, '-')
47
+ .replace(/^-+|-+$/g, '')
48
+ .slice(0, 64) || 'project';
49
+ }
50
+
51
+ export function truncate(text, max) {
52
+ const value = String(text ?? '');
53
+ return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
54
+ }
55
+
56
+ export function indentBlock(text, spaces = 2) {
57
+ const pad = ' '.repeat(spaces);
58
+ return String(text)
59
+ .split('\n')
60
+ .map((line) => (line ? `${pad}${line}` : line))
61
+ .join('\n');
62
+ }
63
+
64
+ export function stripAnsi(text) {
65
+ return String(text).replace(/\u001B\[[0-9;]*m/g, '');
66
+ }