@ryuenn3123/agentic-senior-core 2.0.19 → 2.0.20

package/lib/cli/project-scaffolder.mjs

@@ -0,0 +1,378 @@
+/**
+ * Project Scaffolder — Dynamic project documentation generator.
+ * Generates project-specific docs during init when the target folder is empty.
+ * Depends on: constants.mjs, utils.mjs
+ */
+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 DOMAIN_CHOICES = [
+  'API service',
+  'Web application',
+  'Mobile app',
+  'CLI tool',
+  'Library / SDK',
+  'Other',
+];
+
+const DATABASE_CHOICES = [
+  'None (stateless service)',
+  'SQL (PostgreSQL, MySQL, SQLite)',
+  'NoSQL (MongoDB, Redis, DynamoDB)',
+  'Both (SQL primary + cache layer)',
+  'Other',
+];
+
+const AUTH_CHOICES = [
+  'None (public service)',
+  'JWT (stateless token auth)',
+  'OAuth 2.0 (third-party login)',
+  'Session-based (server-side sessions)',
+  'API Key (simple key auth)',
+  'Other',
+];
+
+/**
+ * Run the project discovery interview.
+ * Returns a structured object with all user responses.
+ */
+export async function runProjectDiscovery(userInterface) {
+  console.log('\n--- Project Discovery ---');
+  console.log('I will ask a few questions to generate project-specific documentation.');
+  console.log('This helps AI agents understand your project before writing code.\n');
+
+  const projectName = (await userInterface.question('Project name: ')).trim();
+  if (!projectName) {
+    throw new Error('Project name is required for documentation scaffolding.');
+  }
+
+  const projectDescription = (await userInterface.question('One-line description: ')).trim() || `A ${projectName} project.`;
+
+  const domainSelection = await askChoice(
+    'Primary domain:',
+    DOMAIN_CHOICES,
+    userInterface
+  );
+
+  let primaryDomain = domainSelection;
+  if (domainSelection === 'Other') {
+    primaryDomain = (await userInterface.question('Describe your domain: ')).trim() || 'Custom domain';
+  }
+
+  const databaseSelection = await askChoice(
+    'Database needs:',
+    DATABASE_CHOICES,
+    userInterface
+  );
+
+  let databaseChoice = databaseSelection;
+  if (databaseSelection === 'Other') {
+    databaseChoice = (await userInterface.question('Describe your database setup: ')).trim() || 'Custom database';
+  }
+
+  const authSelection = await askChoice(
+    'Auth strategy:',
+    AUTH_CHOICES,
+    userInterface
+  );
+
+  let authStrategy = authSelection;
+  if (authSelection === 'Other') {
+    authStrategy = (await userInterface.question('Describe your auth setup: ')).trim() || 'Custom auth';
+  }
+
+  console.log('\nList your key features (one per line, press Enter twice to finish):');
+  const features = [];
+  let consecutiveEmptyLineCount = 0;
+
+  while (features.length < 10) {
+    const featureLine = (await userInterface.question(`  Feature ${features.length + 1}: `)).trim();
+
+    if (!featureLine) {
+      consecutiveEmptyLineCount += 1;
+      if (consecutiveEmptyLineCount >= 1 && features.length >= 1) {
+        break;
+      }
+      continue;
+    }
+
+    consecutiveEmptyLineCount = 0;
+    features.push(featureLine);
+  }
+
+  if (features.length === 0) {
+    features.push('Core functionality (define during development)');
+  }
+
+  const additionalContext = (await userInterface.question('\nAdditional context (optional, press Enter to skip): ')).trim()
+    || 'No additional context provided.';
+
+  return {
+    projectName,
+    projectDescription,
+    primaryDomain,
+    databaseChoice,
+    authStrategy,
+    features,
+    additionalContext,
+  };
+}
+
+/**
+ * Determine which documents to generate based on project discovery answers.
+ */
+export function resolveDocumentManifest(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 },
+  ];
+
+  if (hasDatabase) {
+    documentManifest.push({
+      templateFileName: 'database-schema.md.tmpl',
+      outputFileName: 'database-schema.md',
+      alwaysInclude: false,
+    });
+  }
+
+  if (isApiOrWebDomain) {
+    documentManifest.push({
+      templateFileName: 'api-contract.md.tmpl',
+      outputFileName: 'api-contract.md',
+      alwaysInclude: false,
+    });
+  }
+
+  return { documentManifest, hasDatabase, hasAuth };
+}
+
+/**
+ * Build template 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');
+
+  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),
+    blueprintFileName: initContext.blueprintFileName,
+    blueprintDisplayName: toTitleCase(initContext.blueprintFileName),
+    cliVersion: CLI_VERSION,
+    generatedAt: new Date().toISOString(),
+    generatedDate: new Date().toISOString().split('T')[0],
+    hasDatabase,
+    hasAuth,
+    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;
+}
+
+/**
+ * Generate project documentation files from templates.
+ */
+export async function generateProjectDocumentation(
+  targetDirectoryPath,
+  discoveryAnswers,
+  initContext
+) {
+  const docsDirectoryPath = path.join(targetDirectoryPath, 'docs');
+  await ensureDirectory(docsDirectoryPath);
+
+  const templateContext = buildTemplateContext(discoveryAnswers, initContext);
+  const { documentManifest } = resolveDocumentManifest(discoveryAnswers);
+  const generatedFileNames = [];
+
+  for (const documentEntry of documentManifest) {
+    const templateFilePath = path.join(TEMPLATES_DIRECTORY_PATH, documentEntry.templateFileName);
+
+    if (!(await pathExists(templateFilePath))) {
+      console.log(`[WARN] Template not found: ${documentEntry.templateFileName}, skipping.`);
+      continue;
+    }
+
+    const templateContent = await fs.readFile(templateFilePath, 'utf8');
+    const renderedContent = renderTemplate(templateContent, templateContext);
+    const outputFilePath = path.join(docsDirectoryPath, documentEntry.outputFileName);
+
+    await fs.writeFile(outputFilePath, renderedContent, 'utf8');
+    generatedFileNames.push(documentEntry.outputFileName);
+  }
+
+  return {
+    docsDirectoryPath,
+    generatedFileNames,
+    templateVersion: '1.0.0',
+    discoveryAnswers,
+  };
+}
+
+/**
+ * Check if the target directory qualifies as "empty" for scaffolding purposes.
+ * A directory with only .git is still considered empty.
+ */
+export async function isDirectoryEffectivelyEmpty(targetDirectoryPath) {
+  try {
+    const directoryEntries = await fs.readdir(targetDirectoryPath);
+    const meaningfulEntries = directoryEntries.filter(
+      (entryName) => entryName !== '.git' && entryName !== '.gitignore'
+    );
+    return meaningfulEntries.length === 0;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Check if project docs already exist in the target directory.
+ */
+export async function hasExistingProjectDocs(targetDirectoryPath) {
+  const projectBriefPath = path.join(targetDirectoryPath, 'docs', 'project-brief.md');
+  return pathExists(projectBriefPath);
+}
+
+/**
+ * Load project config from a YAML-like file for non-interactive mode.
+ * Uses a simple key: value format (one per line) for zero-dependency parsing.
+ */
+export async function loadProjectConfig(configFilePath) {
+  const configContent = await fs.readFile(configFilePath, 'utf8');
+  const configLines = configContent.split(/\r?\n/);
+  const configEntries = {};
+  let currentKey = null;
+  let currentArrayValues = null;
+
+  for (const configLine of configLines) {
+    const trimmedLine = configLine.trim();
+
+    if (!trimmedLine || trimmedLine.startsWith('#')) {
+      continue;
+    }
+
+    if (trimmedLine.startsWith('- ') && currentKey && currentArrayValues !== null) {
+      currentArrayValues.push(trimmedLine.slice(2).trim());
+      continue;
+    }
+
+    if (currentKey && currentArrayValues !== null) {
+      configEntries[currentKey] = currentArrayValues;
+      currentKey = null;
+      currentArrayValues = null;
+    }
+
+    const colonIndex = trimmedLine.indexOf(':');
+    if (colonIndex === -1) {
+      continue;
+    }
+
+    const entryKey = trimmedLine.slice(0, colonIndex).trim();
+    const entryValue = trimmedLine.slice(colonIndex + 1).trim();
+
+    if (!entryValue) {
+      currentKey = entryKey;
+      currentArrayValues = [];
+      continue;
+    }
+
+    configEntries[entryKey] = entryValue;
+  }
+
+  if (currentKey && currentArrayValues !== null) {
+    configEntries[currentKey] = currentArrayValues;
+  }
+
+  return {
+    projectName: configEntries.projectName || configEntries.name || '',
+    projectDescription: configEntries.projectDescription || configEntries.description || '',
+    primaryDomain: configEntries.primaryDomain || configEntries.domain || 'API service',
+    databaseChoice: configEntries.databaseChoice || configEntries.database || 'None (stateless service)',
+    authStrategy: configEntries.authStrategy || configEntries.auth || 'None (public service)',
+    features: Array.isArray(configEntries.features) ? configEntries.features : [],
+    additionalContext: configEntries.additionalContext || configEntries.context || 'No additional context provided.',
+  };
+}

package/lib/cli/templates/api-contract.md.tmpl

@@ -0,0 +1,143 @@
+# API Contract: {{projectName}}
+
+Generated by Agentic-Senior-Core CLI v{{cliVersion}}
+Generated at: {{generatedAt}}
+Template version: 1.0.0
+
+---
+
+## API Design Principles
+
+Per `.agent-context/rules/api-docs.md`:
+- OpenAPI 3.1 specification is mandatory for all HTTP APIs.
+- Every endpoint must have documented request/response schemas.
+- Error responses use typed error codes, never raw strings.
+- Input validation is mandatory on every endpoint.
+
+## Base URL
+
+```
+{{baseUrl}}
+```
+
+---
+
+## Endpoints
+
+### Health Check
+
+```
+GET /health
+```
+
+Response `200`:
+```json
+{
+  "status": "ok",
+  "version": "1.0.0",
+  "timestamp": "2026-01-01T00:00:00Z"
+}
+```
+
+{{#if hasAuth}}
+### Authentication
+
+```
+POST /auth/register
+```
+Request:
+```json
+{
+  "email": "user@example.com",
+  "password": "secure-password",
+  "displayName": "User Name"
+}
+```
+
+```
+POST /auth/login
+```
+Request:
+```json
+{
+  "email": "user@example.com",
+  "password": "secure-password"
+}
+```
+Response `200`:
+```json
+{
+  "token": "jwt-token-here",
+  "expiresIn": 3600
+}
+```
+
+{{/if}}
+### Feature Endpoints
+
+Based on the defined project features, plan these endpoint groups:
+
+{{#each features}}
+#### {{this}}
+
+```
+GET    /api/[resource]         — List
+GET    /api/[resource]/:id     — Detail
+POST   /api/[resource]         — Create
+PUT    /api/[resource]/:id     — Update
+DELETE /api/[resource]/:id     — Delete
+```
+
+{{/each}}
+
+---
+
+## Error Response Format
+
+All error responses follow this structure:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable description",
+    "details": []
+  }
+}
+```
+
+Standard error codes:
+- `VALIDATION_ERROR` (400)
+- `UNAUTHORIZED` (401)
+- `FORBIDDEN` (403)
+- `NOT_FOUND` (404)
+- `CONFLICT` (409)
+- `INTERNAL_ERROR` (500)
+
+---
+
+## Pagination
+
+List endpoints use cursor-based or offset-based pagination:
+
+```
+GET /api/[resource]?page=1&limit=20
+```
+
+Response includes:
+```json
+{
+  "data": [],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+---
+
+This document is a living reference. Update it as API endpoints are implemented.
+Maintain a corresponding OpenAPI 3.1 specification file alongside this document.

package/lib/cli/templates/architecture-decision-record.md.tmpl

@@ -0,0 +1,106 @@
+# Architecture Decision Record: {{projectName}}
+
+Generated by Agentic-Senior-Core CLI v{{cliVersion}}
+Generated at: {{generatedAt}}
+Template version: 1.0.0
+
+---
+
+## ADR-001: Technology Stack Selection
+
+**Status**: Accepted
+**Date**: {{generatedDate}}
+
+### Context
+
+This project requires a {{primaryDomain}} solution. The team evaluated available stack profiles and blueprints from the Agentic-Senior-Core governance repository.
+
+### Decision
+
+- **Language/Runtime**: {{stackDisplayName}} (source: `.agent-context/stacks/{{stackFileName}}`)
+- **Architecture blueprint**: {{blueprintDisplayName}} (source: `.agent-context/blueprints/{{blueprintFileName}}`)
+- **Database**: {{databaseChoice}}
+- **Auth**: {{authStrategy}}
+
+### Rationale
+
+The {{stackDisplayName}} stack was selected because:
+- It matches the project domain ({{primaryDomain}}).
+- The governance repository provides a verified blueprint for this stack.
+- The team has access to skill packs covering this technology.
+
+### Consequences
+
+- All code must follow the conventions in `.agent-context/stacks/{{stackFileName}}`.
+- Module boundaries must follow `.agent-context/blueprints/{{blueprintFileName}}`.
+- Database access must follow `.agent-context/rules/database-design.md`.
+- API contracts must follow `.agent-context/rules/api-docs.md`.
+
+---
+
+## ADR-002: Architecture Pattern
+
+**Status**: Accepted
+**Date**: {{generatedDate}}
+
+### Context
+
+The project needs a clear separation of concerns to remain maintainable as it grows.
+
+### Decision
+
+Follow the **Transport - Service - Repository** layered architecture as defined in `.agent-context/rules/architecture.md`.
+
+{{#if hasDatabase}}
+### Database Layer
+
+- Primary database: {{databaseChoice}}
+- ORM/query strategy: follow stack-specific conventions from the selected stack profile.
+- Migration strategy: safe, reversible migrations per `.agent-context/rules/database-design.md`.
+{{/if}}
+
+{{#if hasAuth}}
+### Authentication Layer
+
+- Strategy: {{authStrategy}}
+- Secrets management: no hardcoded secrets per `.agent-context/rules/security.md`.
+- Input validation: mandatory on all auth endpoints per `.agent-context/rules/security.md`.
+{{/if}}
+
+### Consequences
+
+- Every module must respect the three-layer separation.
+- Cross-layer imports are forbidden (no repository calls from transport layer).
+- Shared logic lives in a dedicated shared module, never in transport handlers.
+
+---
+
+## ADR-003: Project Structure
+
+**Status**: Accepted
+**Date**: {{generatedDate}}
+
+### Decision
+
+The project directory structure follows the selected blueprint (`{{blueprintDisplayName}}`). Key directories:
+
+```
+{{projectName}}/
+  src/
+    modules/          — feature modules (each with transport, service, repository)
+    shared/           — shared utilities, types, constants
+    config/           — environment and app configuration
+  docs/               — project documentation (this directory)
+  tests/              — test suites
+  .agent-context/     — governance rules and policies
+```
+
+### Consequences
+
+- New features are added as self-contained modules.
+- Shared code is extracted only when used by two or more modules.
+- Configuration is centralized and validated at startup.
+
+---
+
+Add new ADR entries below as architectural decisions are made during development.

package/lib/cli/templates/database-schema.md.tmpl

@@ -0,0 +1,74 @@
+# Database Schema: {{projectName}}
+
+Generated by Agentic-Senior-Core CLI v{{cliVersion}}
+Generated at: {{generatedAt}}
+Template version: 1.0.0
+
+---
+
+## Database Technology
+
+**Type**: {{databaseChoice}}
+**Auth strategy**: {{authStrategy}}
+
+## Schema Design Principles
+
+Per `.agent-context/rules/database-design.md`:
+- Default to Third Normal Form (3NF) unless performance evidence justifies denormalization.
+- Use safe, reversible migrations for every schema change.
+- Never use raw SQL in application code without parameterized queries.
+- Add indexes based on measured query patterns, not assumptions.
+
+---
+
+## Core Tables
+
+{{#if hasAuth}}
+### users
+
+| Column | Type | Constraints | Notes |
+|--------|------|-------------|-------|
+| id | UUID / BIGINT | PK, NOT NULL | Primary identifier |
+| email | VARCHAR(255) | UNIQUE, NOT NULL | Login credential |
+| password_hash | VARCHAR(255) | NOT NULL | Hashed with bcrypt/argon2 |
+| display_name | VARCHAR(100) | NOT NULL | Public display name |
+| role | VARCHAR(50) | NOT NULL, DEFAULT 'user' | Role-based access |
+| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Record creation |
+| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Last modification |
+
+{{/if}}
+### [Define your domain tables here]
+
+Based on the project features:
+{{#each features}}
+- **{{this}}** — consider what data this feature needs to store, read, and query.
+{{/each}}
+
+| Column | Type | Constraints | Notes |
+|--------|------|-------------|-------|
+| id | UUID / BIGINT | PK, NOT NULL | Primary identifier |
+| ... | ... | ... | Define based on feature requirements |
+| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Record creation |
+| updated_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | Last modification |
+
+---
+
+## Migration Strategy
+
+1. **Create**: Write a new migration file for every schema change.
+2. **Test**: Run migration on a local/staging database before production.
+3. **Rollback**: Every migration must have a corresponding down/rollback script.
+4. **Review**: Schema changes require review per `.agent-context/review-checklists/pr-checklist.md`.
+
+## Indexes
+
+Add indexes based on actual query patterns observed during development:
+
+| Table | Column(s) | Type | Rationale |
+|-------|-----------|------|-----------|
+| users | email | UNIQUE | Login lookup |
+| ... | ... | ... | Add as query patterns emerge |
+
+---
+
+This document is a living reference. Update it as the data model evolves.