@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/bin/build.js

@@ -23,6 +23,41 @@ const SKILLS_DIR = path.join(ROOT, 'skills');
 // Cache for step file contents
 const stepCache = {};
 
+// ── Step nào ĐỌC LÚC CHẠY thay vì nướng vào từng lệnh (GAPS-v3 G45) ──────────
+//
+// Vì sao: build inline `{{include:}}` vào TỪNG file lệnh, nên 32 lệnh = 2069 KB mà chỉ
+// 580 KB là nội dung riêng của chúng — 72% là vài step giống hệt nhau, chép 30 lần.
+// `/generate-code` = 108 KB ≈ 27.000 token đọc TRƯỚC khi làm gì; gần một nửa không nói
+// gì về việc sinh code. `/refine-prd` thì 75% là nội dung dùng chung.
+//
+// Cái giá thật không phải tiền: trên PRD nhiều UC, nạp 27k token chỉ để đọc chỉ dẫn làm
+// tăng rủi ro CẠN CONTEXT GIỮA CHỪNG — mà thứ đang được ghi lúc đó là sổ trace.
+//
+// PHẠM VI CÓ CHỦ Ý — chỉ hai step, không phải tất cả:
+//   context-loader (64% lãng phí) · report-footer (16%)  → đọc lúc chạy
+//   gate (15%)                                            → GIỮ INLINE
+// Gate là lưới an toàn (model check · resolve target · CHECKPOINT). Bỏ sót gate thì lệnh
+// VẪN CHẠY, chỉ là không còn cổng nào — hỏng ÂM THẦM. Bỏ sót context-loader thì lệnh dừng
+// ngay vì thiếu path/config — hỏng ỒN ÀO, thấy liền. Đổi 15% lấy một lưới an toàn là lỗ.
+//
+// MỘT biến thể duy nhất kể từ khi G50 gỡ legacy mode. Trước đó phải build hai bản —
+// `commands/*.md` inline đầy đủ cho legacy (nó copy thẳng file đó mà KHÔNG cài `.agent/`,
+// nên không có `.agent/steps/` để đọc) và `core/commands/*.md` slim cho `--init`. Legacy
+// đi rồi thì mọi bản cài đều có `.agent/steps/`, và nhánh build thứ hai là nợ chờ lệch.
+const RUNTIME_READ = {
+  'steps/context-loader.md':
+    '**BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,\n' +
+    'rồi mới tiếp tục phần bên dưới.\n' +
+    '\n' +
+    'Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, guardrail từ\n' +
+    '`project-lessons`, và routing service (chế độ umbrella) đều **chưa được phân giải** — mọi\n' +
+    'placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.',
+
+  'steps/report-footer.md':
+    '**Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·\n' +
+    'Output Artifacts · Next) cho report cuối, kèm khối bên dưới.',
+};
+
 /**
  * Load a step file by name, caching the result.
  * @param {string} stepPath - e.g. "steps/gate.md"
@@ -54,10 +89,11 @@ function buildTemplate(tmplFile, label) {
   try {
     let content = fs.readFileSync(tmplFile, 'utf8');
 
-    // Replace all {{include:...}} markers
+    // Replace all {{include:...}} markers — trừ những step nằm trong RUNTIME_READ,
+    // chúng được thay bằng một chỉ dẫn ĐỌC LÚC CHẠY thay vì nướng 33 KB vào đây (G45).
     content = content.replace(/\{\{include:([^}]+)\}\}/g, (match, includePath) => {
-      const trimmed = includePath.trim();
-      return loadStep(trimmed);
+      const key = includePath.trim();
+      return RUNTIME_READ[key] !== undefined ? RUNTIME_READ[key] : loadStep(key);
     });
 
     fs.writeFileSync(outFile, content, 'utf8');
@@ -155,6 +191,8 @@ if (skillTmplFiles.length === 0) {
 // It is gitignored but included in the npm package (via "files" whitelist).
 
 const CORE_DIR = path.join(ROOT, 'core');
+const CORE_TMP = path.join(ROOT, 'core.tmp');
+const CORE_BAK = path.join(ROOT, 'core.bak');
 const pkg      = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
 const VERSION  = pkg.version;
 
@@ -162,11 +200,48 @@ console.log('');
 console.log('Populating core/ (distributable) ...');
 console.log('');
 
-// Clean and recreate core/
-if (fs.existsSync(CORE_DIR)) {
-  fs.rmSync(CORE_DIR, { recursive: true });
+// Dựng vào core.tmp/ rồi SWAP — không bao giờ xoá core/ trước khi có bản thay thế
+// hoàn chỉnh (GAPS-v3 G43).
+//
+// Bản cũ làm `rmSync(core/)` rồi mới dựng lại. Nếu bước dựng fail nửa đường — đĩa đầy,
+// thư mục read-only, Ctrl-C — thì core/ ĐÃ MẤT và không có gì thay thế. Với consumer thì
+// hậu quả nặng hơn hẳn: `--init` chạy build ngay trong thư mục npx cache, nên một lần fail
+// làm hỏng package trong cache VĨNH VIỄN, và mọi lần chạy sau đều báo "core/ not found.
+// The package may not have been built correctly" — một thông điệp dẫn sai hướng, vì package
+// được build đúng, chính installer đã xoá nó.
+//
+// Dọn rác của lần chạy trước (nếu có) — không thì swap sẽ trượt vào thư mục cũ.
+for (const stale of [CORE_TMP, CORE_BAK]) {
+  if (fs.existsSync(stale)) fs.rmSync(stale, { recursive: true, force: true });
+}
+
+// Kiểm quyền ghi TRƯỚC khi làm gì cả: fail ở đây thì chưa có gì bị đụng tới.
+try {
+  fs.mkdirSync(CORE_TMP, { recursive: true });
+} catch (err) {
+  console.error('');
+  console.error(`❌ Không ghi được vào thư mục package: ${ROOT}`);
+  console.error(`   (${err.code || err.message})`);
+  console.error('');
+  console.error('   Đây là bản cài read-only. core/ hiện tại KHÔNG bị đụng tới.');
+  console.error('   Thử:  npx -y @educa-corp/sdd-framework@latest --init');
+  console.error('   Hoặc xoá cache npx:  rm -rf ~/.npm/_npx');
+  console.error('');
+  process.exit(1);
+}
+
+/** Đưa core.tmp/ vào chỗ core/. Fail ở bất kỳ đâu thì khôi phục bản cũ. */
+function swapCoreIntoPlace() {
+  const hadOld = fs.existsSync(CORE_DIR);
+  if (hadOld) fs.renameSync(CORE_DIR, CORE_BAK);
+  try {
+    fs.renameSync(CORE_TMP, CORE_DIR);
+  } catch (err) {
+    if (hadOld) fs.renameSync(CORE_BAK, CORE_DIR);   // core/ trở lại nguyên trạng
+    throw err;
+  }
+  if (hadOld) fs.rmSync(CORE_BAK, { recursive: true, force: true });
 }
-fs.mkdirSync(CORE_DIR, { recursive: true });
 
 /**
  * Recursively copy src → dest, optionally filtering files by name.
@@ -190,29 +265,31 @@ function copyDirToCore(src, dest, fileFilter) {
 
 const coreMappings = [
   // Built command .md files (not .tmpl sources)
-  { src: COMMANDS_DIR,              dest: path.join(CORE_DIR, 'commands'),  filter: f => f.endsWith('.md') },
+  { src: COMMANDS_DIR,              dest: path.join(CORE_TMP, 'commands'),  filter: f => f.endsWith('.md') },
   // Step files (gate, context-loader, spawn-agent, report-footer)
-  { src: path.join(ROOT, 'steps'),  dest: path.join(CORE_DIR, 'steps'),    filter: null },
+  { src: path.join(ROOT, 'steps'),  dest: path.join(CORE_TMP, 'steps'),    filter: null },
   // Hook scripts
-  { src: path.join(ROOT, 'hooks'),  dest: path.join(CORE_DIR, 'hooks'),    filter: null },
+  { src: path.join(ROOT, 'hooks'),  dest: path.join(CORE_TMP, 'hooks'),    filter: null },
   // Data-protection and workflow rules
-  { src: path.join(ROOT, 'rules'),  dest: path.join(CORE_DIR, 'rules'),    filter: null },
+  { src: path.join(ROOT, 'rules'),  dest: path.join(CORE_TMP, 'rules'),    filter: null },
   // PRD / architecture templates
-  { src: path.join(ROOT, 'templates'), dest: path.join(CORE_DIR, 'templates'), filter: null },
+  { src: path.join(ROOT, 'templates'), dest: path.join(CORE_TMP, 'templates'), filter: null },
   // Stack module profiles
-  { src: path.join(ROOT, 'modules'),   dest: path.join(CORE_DIR, 'modules'),   filter: null },
+  { src: path.join(ROOT, 'modules'),   dest: path.join(CORE_TMP, 'modules'),   filter: null },
   // Built skill .md files (not .tmpl sources)
-  { src: SKILLS_DIR,                dest: path.join(CORE_DIR, 'skills'),   filter: f => !f.endsWith('.tmpl') },
+  { src: SKILLS_DIR,                dest: path.join(CORE_TMP, 'skills'),   filter: f => !f.endsWith('.tmpl') },
 ];
 
 for (const { src, dest, filter } of coreMappings) {
   copyDirToCore(src, dest, filter);
-  const rel = path.relative(ROOT, dest);
-  console.log(`  ✅ ${rel}/`);
+  // Báo theo ĐÍCH CUỐI (core/…), không phải thư mục dựng trung gian. core.tmp/ là chi
+  // tiết của bước swap (G43) — người đọc log quan tâm cái gì được cài, không quan tâm
+  // nó đi qua đâu.
+  console.log(`  ✅ core/${path.basename(dest)}/`);
 }
 
-// Write FRAMEWORK_VERSION so upgrade.sh can compare installed vs latest
-fs.writeFileSync(path.join(CORE_DIR, 'FRAMEWORK_VERSION'), VERSION + '\n', 'utf8');
+// Write FRAMEWORK_VERSION so /update-framework can compare installed vs latest
+fs.writeFileSync(path.join(CORE_TMP, 'FRAMEWORK_VERSION'), VERSION + '\n', 'utf8');
 console.log(`  ✅ core/FRAMEWORK_VERSION  (v${VERSION})`);
 
 // .agent/README.md — which paths under .agent/ a project may edit, and which the
@@ -220,10 +297,27 @@ console.log(`  ✅ core/FRAMEWORK_VERSION  (v${VERSION})`);
 // land inside .agent/templates/.
 const agentReadmeSrc = path.join(ROOT, 'AGENT_README.md');
 if (fs.existsSync(agentReadmeSrc)) {
-  fs.copyFileSync(agentReadmeSrc, path.join(CORE_DIR, 'README.md'));
+  fs.copyFileSync(agentReadmeSrc, path.join(CORE_TMP, 'README.md'));
   console.log('  ✅ core/README.md  (← AGENT_README.md)');
 }
 
+// ── 3b. Swap core.tmp/ → core/ ───────────────────────────────────────────────
+//
+// Tới đây core.tmp/ đã hoàn chỉnh. Đây là điểm duy nhất core/ bị thay, và nó là
+// một phép rename — gần như nguyên tử, không có cửa sổ nào core/ vắng mặt-và-không-
+// có-bản-thay-thế. Fail thì swapCoreIntoPlace() khôi phục bản cũ (G43).
+try {
+  swapCoreIntoPlace();
+} catch (err) {
+  console.error('');
+  console.error(`❌ Không thay được core/: ${err.code || err.message}`);
+  console.error('   core/ cũ đã được khôi phục — package vẫn dùng được.');
+  console.error(`   Bản vừa dựng còn ở: ${path.relative(ROOT, CORE_TMP)}/`);
+  console.error('   Nguyên nhân thường gặp: file trong core/ đang bị process khác giữ (antivirus, editor).');
+  console.error('');
+  process.exit(1);
+}
+
 // ── 4. Sync local dogfood .agent/ (dev repo only) ────────────────────────────
 //
 // In THIS framework repo, .agent/ is a pure mirror of core/ used to dogfood the