azcodr 2.2.0 → 2.4.0

package/src/agent-guard.ts

@@ -0,0 +1,123 @@
+import path from 'node:path';
+import { inspectCommand } from './agent-guard-command.js';
+import type { CommandViolation } from './agent-guard-command.js';
+import { inspectFileWrite } from './agent-guard-file.js';
+import type { FileCheckResult } from './agent-guard-file.js';
+import {
+  inspectTddRequirement,
+  readTddState,
+  writeTddState
+} from './agent-guard-tdd.js';
+import type { SessionTddState } from './agent-guard-tdd.js';
+
+export interface GuardDecision {
+  allowed: boolean;
+  reason?: string;
+  source?: 'command' | 'file' | 'tdd';
+}
+
+export interface ToolEnvelope {
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+}
+
+export interface GuardOptions {
+  workspaceRoot?: string;
+  enforceTestFirst?: boolean;
+  maxFileLines?: number;
+}
+
+function parseEnvelope(raw: string): ToolEnvelope | null {
+  try {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith('{')) return null;
+    return JSON.parse(trimmed) as ToolEnvelope;
+  } catch {
+    return null;
+  }
+}
+
+function extractKey(input: Record<string, unknown>, keys: readonly string[]): string | undefined {
+  for (const k of keys) {
+    if (typeof input[k] === 'string') return input[k];
+  }
+  return undefined;
+}
+
+function extractFilePath(input: Record<string, unknown>): string | undefined {
+  return extractKey(input, ['TargetFile', 'file_path', 'path', 'filePath']);
+}
+
+function extractCommand(input: Record<string, unknown>): string | undefined {
+  return extractKey(input, ['CommandLine', 'command', 'cmd']);
+}
+
+function inspectPreCommand(cmd: string): GuardDecision {
+  const violation = inspectCommand(cmd);
+  if (violation.blocked) {
+    return { allowed: false, reason: violation.reason, source: 'command' };
+  }
+  return { allowed: true };
+}
+
+function inspectPreFile(
+  filePath: string,
+  input: Record<string, unknown>,
+  options: GuardOptions
+): GuardDecision {
+  const incoming = extractKey(input, ['CodeContent', 'content']);
+  const replacement = extractKey(input, ['ReplacementContent', 'replacement']);
+  const target = extractKey(input, ['TargetContent', 'target']);
+
+  const fileDecision = inspectFileWrite({
+    filePath,
+    incomingContent: incoming,
+    replacementContent: replacement,
+    targetContent: target,
+    maxLines: options.maxFileLines
+  });
+  if (fileDecision.blocked) {
+    return { allowed: false, reason: fileDecision.reason, source: 'file' };
+  }
+
+  const root = options.workspaceRoot ?? process.cwd();
+  const statePath = path.join(root, '.agents', '.session-state.json');
+  const state = readTddState(statePath);
+  const tddDecision = inspectTddRequirement(filePath, state, options.enforceTestFirst);
+  if (tddDecision.blocked) {
+    return { allowed: false, reason: tddDecision.reason, source: 'tdd' };
+  }
+
+  return { allowed: true };
+}
+
+/**
+ * Inspects a tool-use request before execution (PreToolUse hook).
+ *
+ * @param rawInput - Raw command string, JSON envelope, or argv slice.
+ * @param options - Guard configuration options.
+ * @returns Guard decision indicating whether tool execution is permitted.
+ */
+export function inspectPreTool(rawInput: string, options: GuardOptions = {}): GuardDecision {
+  const env = parseEnvelope(rawInput);
+
+  if (env && env.tool_input) {
+    const cmd = extractCommand(env.tool_input);
+    if (cmd) return inspectPreCommand(cmd);
+
+    const targetFile = extractFilePath(env.tool_input);
+    if (targetFile) return inspectPreFile(targetFile, env.tool_input, options);
+  }
+
+  return inspectPreCommand(rawInput);
+}
+
+export {
+  inspectCommand,
+  inspectFileWrite,
+  inspectTddRequirement,
+  readTddState,
+  writeTddState
+};
+export type { CommandViolation, FileCheckResult, SessionTddState };
+export default { inspectPreTool, inspectCommand, inspectFileWrite, inspectTddRequirement };

package/src/boundaries.ts

@@ -0,0 +1,198 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface BoundaryRule {
+  fromLayer: string;
+  disallowImportsFrom: readonly string[];
+}
+
+export interface BoundaryViolation {
+  file: string;
+  importedFile: string;
+  fromLayer: string;
+  toLayer: string;
+}
+
+export interface BoundaryReport {
+  moduleCount: number;
+  cycles: string[][];
+  violations: BoundaryViolation[];
+  ok: boolean;
+}
+
+export const DEFAULT_BOUNDARY_RULES: readonly BoundaryRule[] = [
+  {
+    fromLayer: 'domain',
+    disallowImportsFrom: ['infrastructure', 'infra', 'adapters', 'cli', 'transport', 'controllers']
+  },
+  {
+    fromLayer: 'core',
+    disallowImportsFrom: ['infrastructure', 'infra', 'adapters', 'presentation', 'ui']
+  }
+];
+
+function isSkippedDir(name: string): boolean {
+  return name.startsWith('.') || name === 'node_modules' || name === 'lib';
+}
+
+function isEligibleSource(name: string): boolean {
+  const isScript = name.endsWith('.ts') || name.endsWith('.js');
+  if (!isScript || name.endsWith('.d.ts')) return false;
+  return !name.includes('.test.') && !name.includes('.spec.');
+}
+
+export function findSourceFiles(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  const results: string[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (isSkippedDir(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findSourceFiles(full));
+    } else if (isEligibleSource(entry.name)) {
+      results.push(path.resolve(full));
+    }
+  }
+
+  return results.sort();
+}
+
+function resolveImportTarget(sourceFile: string, specifier: string): string | null {
+  const dir = path.dirname(sourceFile);
+  const candidate = path.resolve(dir, specifier);
+  if (fs.existsSync(candidate)) return candidate;
+
+  if (specifier.endsWith('.js')) {
+    const tsCandidate = path.resolve(dir, specifier.slice(0, -3) + '.ts');
+    if (fs.existsSync(tsCandidate)) return tsCandidate;
+  }
+  return null;
+}
+
+export function extractLocalImports(filePath: string): string[] {
+  if (!fs.existsSync(filePath)) return [];
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const imports: string[] = [];
+  const regex = /(?:import|export)\s+(?:(?:[\s\S]*?from\s+)|)['"](\.[^'"]+)['"]|import\s*\(\s*['"](\.[^'"]+)['"]\s*\)/g;
+
+  for (const match of content.matchAll(regex)) {
+    const spec = match[1] ?? match[2];
+    if (spec) {
+      const resolved = resolveImportTarget(filePath, spec);
+      if (resolved && !imports.includes(resolved)) {
+        imports.push(resolved);
+      }
+    }
+  }
+
+  return imports.sort();
+}
+
+export function buildDependencyGraph(files: readonly string[]): Map<string, string[]> {
+  const graph = new Map<string, string[]>();
+  for (const file of files) {
+    graph.set(file, extractLocalImports(file));
+  }
+  return graph;
+}
+
+export function detectDependencyCycles(graph: Map<string, string[]>): string[][] {
+  const cycles: string[][] = [];
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+  const pathStack: string[] = [];
+
+  function dfs(node: string): void {
+    visited.add(node);
+    inStack.add(node);
+    pathStack.push(node);
+
+    for (const neighbor of graph.get(node) ?? []) {
+      if (!visited.has(neighbor)) {
+        dfs(neighbor);
+      } else if (inStack.has(neighbor)) {
+        const startIdx = pathStack.indexOf(neighbor);
+        if (startIdx !== -1) {
+          cycles.push([...pathStack.slice(startIdx), neighbor]);
+        }
+      }
+    }
+
+    inStack.delete(node);
+    pathStack.pop();
+  }
+
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) dfs(node);
+  }
+
+  return cycles;
+}
+
+function hasLayerSegment(pathStr: string, segment: string): boolean {
+  return new RegExp(`(^|[/\\\\])${segment}([/\\\\]|$)`, 'i').test(pathStr);
+}
+
+export function detectBoundaryViolations(
+  graph: Map<string, string[]>,
+  rules: readonly BoundaryRule[] = DEFAULT_BOUNDARY_RULES
+): BoundaryViolation[] {
+  const violations: BoundaryViolation[] = [];
+
+  for (const [file, imports] of graph.entries()) {
+    for (const rule of rules) {
+      if (hasLayerSegment(file, rule.fromLayer)) {
+        for (const imported of imports) {
+          for (const disallowed of rule.disallowImportsFrom) {
+            if (hasLayerSegment(imported, disallowed)) {
+              violations.push({
+                file,
+                importedFile: imported,
+                fromLayer: rule.fromLayer,
+                toLayer: disallowed
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Inspects a source tree for architectural boundary violations and circular dependency cycles.
+ *
+ * @param sourceDir - Directory containing source code (e.g. src/).
+ * @param rules - Architectural boundary rules.
+ * @returns Report summarizing cycle and boundary findings.
+ */
+export function inspectBoundaries(
+  sourceDir: string,
+  rules: readonly BoundaryRule[] = DEFAULT_BOUNDARY_RULES
+): BoundaryReport {
+  const files = findSourceFiles(sourceDir);
+  const graph = buildDependencyGraph(files);
+  const cycles = detectDependencyCycles(graph);
+  const violations = detectBoundaryViolations(graph, rules);
+
+  return {
+    moduleCount: files.length,
+    cycles,
+    violations,
+    ok: cycles.length === 0 && violations.length === 0
+  };
+}
+
+export default {
+  DEFAULT_BOUNDARY_RULES,
+  findSourceFiles,
+  extractLocalImports,
+  buildDependencyGraph,
+  detectDependencyCycles,
+  detectBoundaryViolations,
+  inspectBoundaries
+};

package/src/cli-boundaries.ts

@@ -0,0 +1,67 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { inspectBoundaries } from './boundaries.js';
+import type { BoundaryReport } from './boundaries.js';
+import type { CliParsedOptions } from './cli-parse.js';
+
+export interface BoundaryIo {
+  out: (msg: string) => void;
+  err: (msg: string) => void;
+  exit: (code: number) => void | number;
+  cwd: string;
+}
+
+export function resolveBoundaryTarget(targetDir: string | null, cwd: string): string {
+  if (targetDir) {
+    return path.resolve(cwd, targetDir);
+  }
+  const defaultSrc = path.join(cwd, 'src');
+  return fs.existsSync(defaultSrc) ? defaultSrc : cwd;
+}
+
+function printViolations(report: BoundaryReport, out: (msg: string) => void): void {
+  const total = report.cycles.length + report.violations.length;
+  out(`🚨 ARCHITECTURAL VIOLATIONS DETECTED (${total}):`);
+  for (const cycle of report.cycles) {
+    out(`   - Circular Dependency: ${cycle.join(' -> ')}`);
+  }
+  for (const v of report.violations) {
+    out(`   - Layer Boundary Breach: ${v.file} illegally imports ${v.importedFile} (${v.fromLayer} -> ${v.toLayer})`);
+  }
+  out('   Action Required: Invert dependencies via Ports or extract shared modules.\n');
+}
+
+export function formatBoundaryReport(
+  targetDir: string,
+  report: BoundaryReport,
+  out: (msg: string) => void
+): void {
+  out(`\n🔍 Inspecting Architectural Boundaries in: ${targetDir}`);
+  out('--------------------------------------------------------------');
+  if (report.ok) {
+    out(`✅ Analyzed ${report.moduleCount} modules: 0 circular cycles, 0 boundary violations.`);
+    out('🎉 SUCCESS: Architecture is clean and drift-free! (0 violations)\n');
+  } else {
+    printViolations(report, out);
+  }
+}
+
+export async function handleBoundariesCommand(
+  parsed: CliParsedOptions,
+  io: BoundaryIo
+): Promise<void | number> {
+  const targetDir = resolveBoundaryTarget(parsed.targetDir, io.cwd);
+  const report = inspectBoundaries(targetDir);
+
+  if (!parsed.silent) {
+    formatBoundaryReport(targetDir, report, io.out);
+  }
+
+  return io.exit(report.ok ? 0 : 1);
+}
+
+export default {
+  resolveBoundaryTarget,
+  formatBoundaryReport,
+  handleBoundariesCommand
+};

package/src/cli-parse.ts

@@ -5,7 +5,10 @@
  * raise the complexity of the parser itself.
  */
 
+export type CliCommand = 'scaffold' | 'check' | 'boundaries';
+
 export interface CliParsedOptions {
+  command: CliCommand;
   targetDir: string | null;
   force: boolean;
   noGit: boolean;
@@ -18,9 +21,19 @@ export interface CliParsedOptions {
 export type BooleanFlagKey = 'force' | 'noGit' | 'dryRun' | 'silent';
 
 export function emptyOptions(): Omit<CliParsedOptions, 'terminal' | 'message'> {
-  return { targetDir: null, force: false, noGit: false, dryRun: false, silent: false };
+  return {
+    command: 'scaffold',
+    targetDir: null,
+    force: false,
+    noGit: false,
+    dryRun: false,
+    silent: false
+  };
 }
 
+export const CHECK_COMMANDS = new Set(['check', 'validate', 'audit']);
+export const BOUNDARY_COMMANDS = new Set(['boundaries', 'boundary', 'cycles']);
+
 export const BOOLEAN_FLAGS = new Map<string, BooleanFlagKey>([
   ['-f', 'force'],
   ['--force', 'force'],
@@ -36,12 +49,34 @@ export interface ArgOutcome {
   message?: string;
 }
 
+function checkSpecialFlag(arg: string): 'help' | 'version' | null {
+  if (arg === '-h' || arg === '--help') return 'help';
+  if (arg === '-v' || arg === '--version') return 'version';
+  return null;
+}
+
+function checkCommandKeyword(
+  arg: string,
+  state: Omit<CliParsedOptions, 'terminal' | 'message'>
+): boolean {
+  if (state.targetDir !== null || state.command !== 'scaffold') return false;
+  if (CHECK_COMMANDS.has(arg)) {
+    state.command = 'check';
+    return true;
+  }
+  if (BOUNDARY_COMMANDS.has(arg)) {
+    state.command = 'boundaries';
+    return true;
+  }
+  return false;
+}
+
 export function applyArg(
   state: Omit<CliParsedOptions, 'terminal' | 'message'>,
   arg: string
 ): ArgOutcome {
-  if (arg === '-h' || arg === '--help') return { terminal: 'help' };
-  if (arg === '-v' || arg === '--version') return { terminal: 'version' };
+  const special = checkSpecialFlag(arg);
+  if (special !== null) return { terminal: special };
   const flag = BOOLEAN_FLAGS.get(arg);
   if (flag !== undefined) {
     state[flag] = true;
@@ -53,6 +88,7 @@ export function applyArg(
       message: `Unknown argument '${arg}'. Run 'npx azcodr --help' for available options.`
     };
   }
+  if (checkCommandKeyword(arg, state)) return { terminal: null };
   if (!state.targetDir) {
     state.targetDir = arg;
     return { terminal: null };
@@ -74,4 +110,4 @@ export function parseArgs(rawArgs: readonly string[]): CliParsedOptions {
   return { ...state, terminal: null, message: undefined };
 }
 
-export default { emptyOptions, BOOLEAN_FLAGS, applyArg, parseArgs };
+export default { emptyOptions, BOOLEAN_FLAGS, CHECK_COMMANDS, applyArg, parseArgs };

package/src/cli.ts

@@ -4,6 +4,8 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { scaffold, getTemplateDir } from './scaffold.js';
 import type { ScaffoldOptions, ScaffoldResult } from './scaffold.js';
+import { validate, createSilentReporter } from './validate.js';
+import { handleBoundariesCommand } from './cli-boundaries.js';
 import { parseArgs } from './cli-parse.js';
 import type { CliParsedOptions } from './cli-parse.js';
 import { askQuestion, resolveTargetDir, ensureWritableTarget } from './cli-target.js';
@@ -26,9 +28,13 @@ Enterprise Multi-Tenant Architecture & Agentic Engineering Starter Template
 
 Usage:
   npx azcodr [directory] [options]
+  npx azcodr check [directory] [options]
+  npx azcodr boundaries [directory] [options]
 
 Commands:
-  [directory]     Scaffold azcodr template into directory (default: current directory)
+  [directory]            Scaffold azcodr template into directory (default: current directory)
+  check [directory]      Validate architecture and governance rules (alias: validate, audit)
+  boundaries [directory] Inspect dependency cycles and layer boundaries (alias: boundary, cycles)
 
 Options:
   -d, --dry-run   Simulate scaffolding without modifying filesystem
@@ -40,8 +46,10 @@ Options:
 
 Examples:
   npx azcodr my-project
+  npx azcodr check
+  npx azcodr boundaries ./src
+  npx azcodr check ./existing-repo
   npx azcodr . --dry-run
-  npx azcodr . --force
 `);
 }
 
@@ -58,6 +66,8 @@ export interface CliIo {
   cwd?: string;
   templateDir?: string;
   scaffold?: (options?: ScaffoldOptions) => ScaffoldResult;
+  validate?: (workspaceRoot: string, reporter?: any) => { errors: number; warnings: number } | Promise<{ errors: number; warnings: number }>;
+  boundaries?: (parsed: CliParsedOptions, io: any) => Promise<void | number>;
 }
 
 export interface NormalizedCliIo {
@@ -69,20 +79,30 @@ export interface NormalizedCliIo {
   cwd: string;
   templateDir: string;
   scaffoldFn: (options?: ScaffoldOptions) => ScaffoldResult;
+  validateFn: (workspaceRoot: string, reporter?: any) => { errors: number; warnings: number } | Promise<{ errors: number; warnings: number }>;
+  boundariesFn: (parsed: CliParsedOptions, io: any) => Promise<void | number>;
 }
 
-function normalizeIo(io: CliIo = {}): NormalizedCliIo {
-  const {
-    out = console.log,
-    err = console.error,
-    exit = process.exit,
-    stdin = process.stdin,
-    stdout = process.stdout,
-    cwd = process.cwd(),
-    templateDir = getTemplateDir(),
-    scaffold: scaffoldFn = scaffold
-  } = io;
-  return { out, err, exit, stdin, stdout, cwd, templateDir, scaffoldFn };
+function defaultStreams(io: CliIo) {
+  return {
+    out: io.out ?? console.log,
+    err: io.err ?? console.error,
+    exit: io.exit ?? process.exit,
+    stdin: io.stdin ?? process.stdin,
+    stdout: io.stdout ?? process.stdout
+  };
+}
+
+function normalizeIo(io: CliIo): NormalizedCliIo {
+  const streams = defaultStreams(io);
+  return {
+    ...streams,
+    cwd: io.cwd ?? process.cwd(),
+    templateDir: io.templateDir ?? getTemplateDir(),
+    scaffoldFn: io.scaffold ?? scaffold,
+    validateFn: io.validate ?? validate,
+    boundariesFn: io.boundaries ?? handleBoundariesCommand
+  };
 }
 
 function outBanner(fullIo: NormalizedCliIo): void {
@@ -103,6 +123,22 @@ function handleTerminal(parsed: CliParsedOptions, io: NormalizedCliIo): void | n
   return exit(1);
 }
 
+async function handleCheckCommand(
+  parsed: CliParsedOptions,
+  fullIo: NormalizedCliIo
+): Promise<void | number> {
+  const checkDir = parsed.targetDir ? path.resolve(fullIo.cwd, parsed.targetDir) : fullIo.cwd;
+  const reporter = parsed.silent ? createSilentReporter() : undefined;
+  const result = await fullIo.validateFn(checkDir, reporter);
+  if (result.errors !== 0) return fullIo.exit(1);
+
+  const srcDir = path.join(checkDir, 'src');
+  if (fs.existsSync(srcDir)) {
+    return fullIo.boundariesFn({ ...parsed, targetDir: srcDir }, fullIo);
+  }
+  return fullIo.exit(0);
+}
+
 function reportDryRun(result: ScaffoldResult, out: (msg: string) => void): void {
   for (const action of result.actions) {
     out(`  [preview] ${action}`);
@@ -199,10 +235,16 @@ export async function runCli(
   io: CliIo = {}
 ): Promise<void | number> {
   const fullIo = normalizeIo(io);
-
   const parsed = parseArgs(rawArgs);
   if (parsed.terminal !== null) return handleTerminal(parsed, fullIo);
 
+  if (parsed.command === 'check') {
+    return handleCheckCommand(parsed, fullIo);
+  }
+  if (parsed.command === 'boundaries') {
+    return fullIo.boundariesFn(parsed, fullIo);
+  }
+
   if (!parsed.silent) {
     outBanner(fullIo);
   }

package/src/guards.ts

@@ -2,8 +2,18 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
 import { ScaffoldError, ERROR_CODES } from './errors.js';
-import { getTemplateDir } from './scaffold.js';
+
+/**
+ * Resolves the root filesystem directory of the azcodr template files.
+ *
+ * @returns Absolute filesystem path to the template root directory.
+ */
+export function getTemplateDir(): string {
+  const currentDir = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(currentDir, '..');
+}
 
 /**
  * Options for configuring protected target verification.

package/src/index.ts

@@ -39,6 +39,46 @@ export {
   ERROR_CODES
 } from './scaffold.js';
 
+/**
+ * Standalone architecture validation engine.
+ */
+export { validate, createSilentReporter } from './validate.js';
+export type { ValidationResult, ValidationReporter } from './validate.js';
+
+/**
+ * Agent-runtime architectural enforcement and safety guards.
+ */
+export {
+  inspectPreTool,
+  inspectCommand,
+  inspectFileWrite,
+  inspectTddRequirement,
+  readTddState,
+  writeTddState
+} from './agent-guard.js';
+export type {
+  GuardDecision,
+  GuardOptions,
+  ToolEnvelope,
+  CommandViolation,
+  FileCheckResult,
+  SessionTddState
+} from './agent-guard.js';
+
+/**
+ * Architectural boundary enforcement and dependency cycle prevention.
+ */
+export {
+  inspectBoundaries,
+  detectDependencyCycles,
+  detectBoundaryViolations,
+  findSourceFiles,
+  extractLocalImports,
+  buildDependencyGraph,
+  DEFAULT_BOUNDARY_RULES
+} from './boundaries.js';
+export type { BoundaryRule, BoundaryViolation, BoundaryReport } from './boundaries.js';
+
 /**
  * Type definitions and option interfaces for scaffolding operations.
  */

package/src/repo.ts

@@ -59,10 +59,10 @@ function commitWithFallbackIdentity(targetDir: string): void {
       ...options,
       env: {
         ...process.env,
-        GIT_AUTHOR_NAME: 'Subodh Khanal',
-        GIT_AUTHOR_EMAIL: 'prosubodh@gmail.com',
-        GIT_COMMITTER_NAME: 'Subodh Khanal',
-        GIT_COMMITTER_EMAIL: 'prosubodh@gmail.com'
+        GIT_AUTHOR_NAME: 'azcodr[bot]',
+        GIT_AUTHOR_EMAIL: 'bot@azcodr.internal',
+        GIT_COMMITTER_NAME: 'azcodr[bot]',
+        GIT_COMMITTER_EMAIL: 'bot@azcodr.internal'
       }
     });
   }