@ryuenn3123/agentic-senior-core 2.5.22 → 3.0.2

package/lib/cli/init-selection.mjs

@@ -0,0 +1,100 @@
+/**
+ * Init Selection Helpers — stack/blueprint filtering and scope normalization.
+ */
+import {
+  BLUEPRINT_RECOMMENDATIONS,
+  PROJECT_SCOPE_CHOICES,
+  PROJECT_SCOPE_STACK_FILTERS,
+  WEB_FRONTEND_BLUEPRINT_CANDIDATES,
+  WEB_BACKEND_BLUEPRINT_CANDIDATES,
+} from './constants.mjs';
+
+export function filterStackFileNamesByCandidates(allStackFileNames, preferredStackFileNames) {
+  if (!Array.isArray(preferredStackFileNames) || preferredStackFileNames.length === 0) {
+    return allStackFileNames;
+  }
+
+  const filteredStackFileNames = preferredStackFileNames.filter((stackFileName) => allStackFileNames.includes(stackFileName));
+  return filteredStackFileNames.length > 0 ? filteredStackFileNames : allStackFileNames;
+}
+
+export function filterBlueprintFileNamesByCandidates(allBlueprintFileNames, preferredBlueprintFileNames) {
+  if (!Array.isArray(preferredBlueprintFileNames) || preferredBlueprintFileNames.length === 0) {
+    return allBlueprintFileNames;
+  }
+
+  const filteredBlueprintFileNames = preferredBlueprintFileNames.filter(
+    (blueprintFileName) => allBlueprintFileNames.includes(blueprintFileName)
+  );
+
+  return filteredBlueprintFileNames.length > 0 ? filteredBlueprintFileNames : allBlueprintFileNames;
+}
+
+export function resolveProjectScopeKeyFromLabel(selectedProjectScopeLabel) {
+  const projectScopeEntry = PROJECT_SCOPE_CHOICES.find((scopeChoice) => scopeChoice.label === selectedProjectScopeLabel);
+  return projectScopeEntry?.key || 'both';
+}
+
+export function normalizeAdditionalStackSelection(selectedStackFileName, additionalStackFileNames) {
+  if (!Array.isArray(additionalStackFileNames) || additionalStackFileNames.length === 0) {
+    return [];
+  }
+
+  return Array.from(new Set(additionalStackFileNames.filter((stackFileName) => stackFileName && stackFileName !== selectedStackFileName)));
+}
+
+export function normalizeAdditionalBlueprintSelection(selectedBlueprintFileName, additionalBlueprintFileNames) {
+  if (!Array.isArray(additionalBlueprintFileNames) || additionalBlueprintFileNames.length === 0) {
+    return [];
+  }
+
+  return Array.from(new Set(additionalBlueprintFileNames.filter(
+    (blueprintFileName) => blueprintFileName && blueprintFileName !== selectedBlueprintFileName
+  )));
+}
+
+export function deriveAdditionalBlueprintFileNamesFromStacks(
+  additionalStackFileNames,
+  allBlueprintFileNames,
+  selectedBlueprintFileName
+) {
+  const derivedBlueprintFileNames = [];
+
+  for (const additionalStackFileName of additionalStackFileNames || []) {
+    const mappedBlueprintFileName = BLUEPRINT_RECOMMENDATIONS[additionalStackFileName];
+    if (!mappedBlueprintFileName) {
+      continue;
+    }
+
+    if (!allBlueprintFileNames.includes(mappedBlueprintFileName)) {
+      continue;
+    }
+
+    if (mappedBlueprintFileName === selectedBlueprintFileName) {
+      continue;
+    }
+
+    derivedBlueprintFileNames.push(mappedBlueprintFileName);
+  }
+
+  return Array.from(new Set(derivedBlueprintFileNames));
+}
+
+export function resolveScopeStackCandidates(projectScopeKey) {
+  return PROJECT_SCOPE_STACK_FILTERS[projectScopeKey] || null;
+}
+
+export function resolveScopeBlueprintCandidates(projectScopeKey) {
+  if (projectScopeKey === 'frontend-only') {
+    return WEB_FRONTEND_BLUEPRINT_CANDIDATES;
+  }
+
+  if (projectScopeKey === 'backend-only') {
+    return WEB_BACKEND_BLUEPRINT_CANDIDATES;
+  }
+
+  return Array.from(new Set([
+    ...WEB_FRONTEND_BLUEPRINT_CANDIDATES,
+    ...WEB_BACKEND_BLUEPRINT_CANDIDATES,
+  ]));
+}

package/lib/cli/preflight.mjs

@@ -34,7 +34,7 @@ export async function runPreflightChecks(targetDirectoryPath, operationMode) {
        try {
            await fs.access(parentDir, constants.W_OK);
            result.checks.push(`Target parent directory is writable: ${parentDir}`);
-       } catch (parentErr) {
+         } catch {
            result.passed = false;
            result.errors.push(`Target directory does not exist and parent is read-only: ${parentDir}`);
        }

package/lib/cli/profile-packs.mjs

@@ -8,6 +8,7 @@ import path from 'node:path';
 import {
   PROFILE_PACK_REQUIRED_FIELDS,
   PROFILE_PACKS_DIRECTORY_NAME,
+  FALLBACK_PROFILE_PACK_DEFINITIONS,
 } from './constants.mjs';
 
 import {
@@ -19,6 +20,15 @@ import {
   parseBlockingSeverities,
 } from './utils.mjs';
 
+function cloneProfilePackDefinition(profilePackDefinition) {
+  return {
+    ...profilePackDefinition,
+    blockingSeverities: Array.isArray(profilePackDefinition.blockingSeverities)
+      ? [...profilePackDefinition.blockingSeverities]
+      : [],
+  };
+}
+
 export function parseProfilePackContent(fileName, profilePackContent) {
   const parsedFields = {};
   const profilePackLines = profilePackContent.split(/\r?\n/);
@@ -64,10 +74,14 @@ export function parseProfilePackContent(fileName, profilePackContent) {
 export async function collectProfilePacks(targetDirectoryPath) {
   const profilePackDirectoryPath = path.join(targetDirectoryPath, '.agent-context', PROFILE_PACKS_DIRECTORY_NAME);
   if (!(await pathExists(profilePackDirectoryPath))) {
-    return [];
+    return FALLBACK_PROFILE_PACK_DEFINITIONS.map(cloneProfilePackDefinition);
   }
 
   const profilePackFileNames = await collectFileNames(profilePackDirectoryPath);
+  if (profilePackFileNames.length === 0) {
+    return FALLBACK_PROFILE_PACK_DEFINITIONS.map(cloneProfilePackDefinition);
+  }
+
   const profilePackDefinitions = [];
 
   for (const profilePackFileName of profilePackFileNames) {

package/lib/cli/project-scaffolder.mjs

@@ -5,14 +5,9 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
-import { CLI_VERSION } from './constants.mjs';
 import { ensureDirectory, askChoice, askYesNo, toTitleCase, pathExists } from './utils.mjs';
 
-const CURRENT_FILE_PATH = fileURLToPath(import.meta.url);
-const CURRENT_DIRECTORY_PATH = path.dirname(CURRENT_FILE_PATH);
-const TEMPLATES_DIRECTORY_PATH = path.join(CURRENT_DIRECTORY_PATH, 'templates');
 const SUPPORTED_DOC_LANGUAGES = new Set(['en', 'id']);
 const PROJECT_DOC_FILE_NAMES = [
   'project-brief.md',
@@ -22,6 +17,7 @@ const PROJECT_DOC_FILE_NAMES = [
   'flow-overview.md',
 ];
 
+// Legacy project docs may still carry this version header; keep for upgrade staleness checks.
 export const PROJECT_DOC_TEMPLATE_VERSION = '1.2.0';
 export const PROJECT_DOC_SYNTHESIS_PROMPT_VERSION = '2.0.0';
 
@@ -224,30 +220,6 @@ export function normalizeDocsLanguage(rawDocsLanguage = 'en') {
   return SUPPORTED_DOC_LANGUAGES.has(normalizedDocsLanguage) ? normalizedDocsLanguage : null;
 }
 
-function resolveLocalizedTemplateFileName(templateFileName, docsLanguage) {
-  if (docsLanguage === 'en') {
-    return templateFileName;
-  }
-
-  return templateFileName.replace(/\.md\.tmpl$/i, `.md.${docsLanguage}.tmpl`);
-}
-
-async function resolveTemplateFilePath(templateFileName, docsLanguage) {
-  const localizedTemplateFileName = resolveLocalizedTemplateFileName(templateFileName, docsLanguage);
-  const localizedTemplateFilePath = path.join(TEMPLATES_DIRECTORY_PATH, localizedTemplateFileName);
-
-  if (await pathExists(localizedTemplateFilePath)) {
-    return localizedTemplateFilePath;
-  }
-
-  const defaultTemplateFilePath = path.join(TEMPLATES_DIRECTORY_PATH, templateFileName);
-  if (await pathExists(defaultTemplateFilePath)) {
-    return defaultTemplateFilePath;
-  }
-
-  return null;
-}
-
 /**
  * Run the project discovery interview.
  * Returns a structured object with all user responses.
@@ -444,160 +416,52 @@ export async function runProjectDiscovery(userInterface, options = {}) {
 }
 
 /**
- * Determine which documents to generate based on project discovery answers.
+ * Determine required docs based on project discovery answers.
  */
-export function resolveDocumentManifest(discoveryAnswers) {
+export function resolveProjectDocTargets(discoveryAnswers) {
   const hasDatabase = !discoveryAnswers.databaseChoice.toLowerCase().startsWith('none');
-  const hasAuth = !discoveryAnswers.authStrategy.toLowerCase().startsWith('none');
   const isApiOrWebDomain = ['API service', 'Web application'].includes(discoveryAnswers.primaryDomain)
     || discoveryAnswers.primaryDomain.toLowerCase().includes('api')
     || discoveryAnswers.primaryDomain.toLowerCase().includes('web');
 
-  const documentManifest = [
-    { templateFileName: 'project-brief.md.tmpl', outputFileName: 'project-brief.md', alwaysInclude: true },
-    { templateFileName: 'architecture-decision-record.md.tmpl', outputFileName: 'architecture-decision-record.md', alwaysInclude: true },
-    { templateFileName: 'flow-overview.md.tmpl', outputFileName: 'flow-overview.md', alwaysInclude: true },
+  const requiredDocFileNames = [
+    'project-brief.md',
+    'architecture-decision-record.md',
+    'flow-overview.md',
   ];
 
   if (hasDatabase) {
-    documentManifest.push({
-      templateFileName: 'database-schema.md.tmpl',
-      outputFileName: 'database-schema.md',
-      alwaysInclude: false,
-    });
+    requiredDocFileNames.push('database-schema.md');
   }
 
   if (isApiOrWebDomain) {
-    documentManifest.push({
-      templateFileName: 'api-contract.md.tmpl',
-      outputFileName: 'api-contract.md',
-      alwaysInclude: false,
-    });
+    requiredDocFileNames.push('api-contract.md');
   }
 
-  return { documentManifest, hasDatabase, hasAuth };
+  return { requiredDocFileNames };
 }
 
 /**
- * Build template context from discovery answers and init selections.
+ * Build synthesis context from discovery answers and init selections.
  */
-export function buildTemplateContext(discoveryAnswers, initContext) {
-  const hasDatabase = !discoveryAnswers.databaseChoice.toLowerCase().startsWith('none');
-  const hasAuth = !discoveryAnswers.authStrategy.toLowerCase().startsWith('none');
+export function buildSynthesisContext(_discoveryAnswers, initContext) {
   const additionalStackFileNames = Array.isArray(initContext.additionalStackFileNames)
     ? initContext.additionalStackFileNames
     : [];
   const additionalBlueprintFileNames = Array.isArray(initContext.additionalBlueprintFileNames)
     ? initContext.additionalBlueprintFileNames
     : [];
-  const parsedDockerStrategy = parseDockerStrategy(discoveryAnswers.dockerStrategy);
-
-  const baseUrlMap = {
-    'API service': 'http://localhost:3000',
-    'Web application': 'http://localhost:3000/api',
-    'Mobile app': 'http://localhost:3000/api',
-    'CLI tool': 'N/A',
-    'Library / SDK': 'N/A',
-  };
 
   return {
-    projectName: discoveryAnswers.projectName,
-    projectDescription: discoveryAnswers.projectDescription,
-    primaryDomain: discoveryAnswers.primaryDomain,
-    databaseChoice: discoveryAnswers.databaseChoice,
-    authStrategy: discoveryAnswers.authStrategy,
-    features: discoveryAnswers.features,
-    additionalContext: discoveryAnswers.additionalContext,
     stackFileName: initContext.stackFileName,
-    stackDisplayName: toTitleCase(initContext.stackFileName),
     additionalStackFileNames,
-    additionalStackDisplayNames: additionalStackFileNames.length > 0
-      ? additionalStackFileNames.map((stackFileName) => toTitleCase(stackFileName))
-      : null,
     blueprintFileName: initContext.blueprintFileName,
-    blueprintDisplayName: toTitleCase(initContext.blueprintFileName),
     additionalBlueprintFileNames,
-    additionalBlueprintDisplayNames: additionalBlueprintFileNames.length > 0
-      ? additionalBlueprintFileNames.map((blueprintFileName) => toTitleCase(blueprintFileName))
-      : null,
     runtimeEnvironmentKey: initContext.runtimeEnvironmentKey || 'linux',
     runtimeEnvironmentLabel: initContext.runtimeEnvironmentLabel || 'Linux',
-    cliVersion: CLI_VERSION,
-    templateVersion: PROJECT_DOC_TEMPLATE_VERSION,
-    generatedAt: new Date().toISOString(),
-    generatedDate: new Date().toISOString().split('T')[0],
-    hasDatabase,
-    hasAuth,
-    hasDocker: parsedDockerStrategy.hasDocker,
-    dockerStrategy: parsedDockerStrategy.dockerStrategy,
-    useDockerDevelopment: parsedDockerStrategy.useDockerDevelopment,
-    useDockerProduction: parsedDockerStrategy.useDockerProduction,
-    dockerDevelopmentGuidance: parsedDockerStrategy.useDockerDevelopment
-      ? '- Development containers are required: optimize for fast rebuilds, bind mounts, and debug-friendly startup.'
-      : '',
-    dockerProductionGuidance: parsedDockerStrategy.useDockerProduction
-      ? '- Production containers are required: use multi-stage builds, non-root runtime, and minimal image footprint.'
-      : '',
-    baseUrl: baseUrlMap[discoveryAnswers.primaryDomain] || 'http://localhost:3000',
   };
 }
 
-/**
- * Render a template string by replacing {{placeholder}} tokens with context values.
- * Supports:
- * - {{key}} for simple values
- * - {{#each key}}...{{this}}...{{/each}} for arrays
- * - {{#if key}}...{{/if}} for conditionals
- */
-export function renderTemplate(templateContent, templateContext) {
-  let renderedContent = templateContent;
-
-  // Process {{#each key}}...{{/each}} blocks
-  renderedContent = renderedContent.replace(
-    /\{\{#each\s+(\w+)\}\}([\s\S]*?)\{\{\/each\}\}/g,
-    (_fullMatch, iteratorKey, iteratorBody) => {
-      const iteratorValues = templateContext[iteratorKey];
-
-      if (!Array.isArray(iteratorValues) || iteratorValues.length === 0) {
-        return '';
-      }
-
-      return iteratorValues
-        .map((iteratorValue) => iteratorBody.replace(/\{\{this\}\}/g, iteratorValue))
-        .join('');
-    }
-  );
-
-  // Process {{#if key}}...{{/if}} blocks
-  renderedContent = renderedContent.replace(
-    /\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g,
-    (_fullMatch, conditionKey, conditionBody) => {
-      const conditionValue = templateContext[conditionKey];
-      return conditionValue ? conditionBody : '';
-    }
-  );
-
-  // Process simple {{key}} replacements
-  renderedContent = renderedContent.replace(
-    /\{\{(\w+)\}\}/g,
-    (_fullMatch, placeholderKey) => {
-      const placeholderValue = templateContext[placeholderKey];
-
-      if (placeholderValue === undefined || placeholderValue === null) {
-        return `{{${placeholderKey}}}`;
-      }
-
-      if (Array.isArray(placeholderValue)) {
-        return placeholderValue.join(', ');
-      }
-
-      return String(placeholderValue);
-    }
-  );
-
-  return renderedContent;
-}
-
 function shouldBootstrapDesignDocument(discoveryAnswers, initContext) {
   const normalizedDomain = String(discoveryAnswers.primaryDomain || '').trim().toLowerCase();
   const normalizedBlueprint = String(initContext.blueprintFileName || '').trim().toLowerCase();
@@ -670,6 +534,7 @@ function buildProjectContextBootstrapPrompt({
     '2. Every major section must explain rationale and tradeoffs.',
     '3. Keep stack, database, and auth aligned with the project constraints below unless user explicitly requests migration.',
     '4. Output must be implementation-ready for engineers, not generic textbook explanation.',
+    '5. For any research-backed claim, include citation metadata (source + fetchedAt timestamp) from the Architect Engine Snapshot.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -764,7 +629,6 @@ function buildDesignBootstrapPrompt({
 
 /**
  * Generate AI-first bootstrap prompts for dynamic project documentation synthesis.
- * Legacy template rendering utilities are retained for backward compatibility checks.
  */
 export async function generateProjectDocumentation(
   targetDirectoryPath,
@@ -781,16 +645,16 @@ export async function generateProjectDocumentation(
   const promptsDirectoryPath = path.join(targetDirectoryPath, '.agent-context', 'prompts');
   await ensureDirectory(promptsDirectoryPath);
 
-  const templateContext = buildTemplateContext(discoveryAnswers, initContext);
-  const { documentManifest } = resolveDocumentManifest(discoveryAnswers);
-  const expectedDocFileNames = documentManifest.map((documentEntry) => documentEntry.outputFileName);
+  const synthesisContext = buildSynthesisContext(discoveryAnswers, initContext);
+  const { requiredDocFileNames } = resolveProjectDocTargets(discoveryAnswers);
+  const expectedDocFileNames = [...requiredDocFileNames];
   const generatedPromptFileNames = [];
 
   const projectContextPromptFileName = 'bootstrap-project-context.md';
   const architectureRecommendation = initContext.architectureRecommendation || null;
   const projectContextPromptContent = buildProjectContextBootstrapPrompt({
     discoveryAnswers,
-    initContext: templateContext,
+    initContext: synthesisContext,
     expectedDocFileNames,
     docsLanguage: normalizedDocsLanguage,
     architectureRecommendation,
@@ -806,7 +670,7 @@ export async function generateProjectDocumentation(
     const designPromptFileName = 'bootstrap-design.md';
     const designPromptContent = buildDesignBootstrapPrompt({
       discoveryAnswers,
-      initContext: templateContext,
+      initContext: synthesisContext,
       docsLanguage: normalizedDocsLanguage,
       architectureRecommendation,
     });