azcodr 2.1.0 → 2.3.0

package/src/agent-guard-tdd.ts

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface SessionTddState {
+  lastFailingTestRecorded: boolean;
+  lastTestRunTime?: number;
+  lastTestPath?: string;
+}
+
+export interface TddCheckResult {
+  blocked: boolean;
+  reason?: string;
+  isProductionFile: boolean;
+}
+
+export function isTestFile(filePath: string): boolean {
+  const norm = filePath.replace(/\\/g, '/').toLowerCase();
+  if (/(^|\/)(tests?|__tests__)(\/|$)/i.test(norm)) {
+    return true;
+  }
+  return /\.(test|spec)\.[a-z0-9]+$/i.test(norm);
+}
+
+export function isNonCodeFile(filePath: string): boolean {
+  const ext = path.extname(filePath).toLowerCase();
+  const nonCodeExts = new Set(['.md', '.json', '.yml', '.yaml', '.txt', '.toml', '.lock', '.svg', '.png']);
+  return nonCodeExts.has(ext);
+}
+
+export function isProductionFile(filePath: string): boolean {
+  if (isNonCodeFile(filePath)) return false;
+  if (isTestFile(filePath)) return false;
+  const norm = filePath.replace(/\\/g, '/').toLowerCase();
+  return norm.includes('src/') || norm.includes('lib/') || norm.includes('app/');
+}
+
+export function readTddState(stateFile: string): SessionTddState {
+  if (!fs.existsSync(stateFile)) {
+    return { lastFailingTestRecorded: false };
+  }
+  try {
+    const raw = fs.readFileSync(stateFile, 'utf-8');
+    return JSON.parse(raw) as SessionTddState;
+  } catch {
+    return { lastFailingTestRecorded: false };
+  }
+}
+
+export function writeTddState(stateFile: string, state: SessionTddState): void {
+  try {
+    const dir = path.dirname(stateFile);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf-8');
+  } catch {
+    // Fail-safe write: do not crash agent if state cannot be persisted
+  }
+}
+
+/**
+ * Checks whether an edit to a file is allowed under RED-before-GREEN TDD rules.
+ *
+ * @param filePath - Path to file being edited.
+ * @param state - Current session TDD state.
+ * @param enforceTestFirst - Whether test-first enforcement is strictly enabled.
+ * @returns Decision result indicating whether edit is blocked.
+ */
+export function inspectTddRequirement(
+  filePath: string,
+  state: SessionTddState,
+  enforceTestFirst: boolean = false
+): TddCheckResult {
+  const prod = isProductionFile(filePath);
+  if (!enforceTestFirst || !prod) {
+    return { blocked: false, isProductionFile: prod };
+  }
+
+  if (!state.lastFailingTestRecorded) {
+    const baseName = path.basename(filePath);
+    return {
+      blocked: true,
+      isProductionFile: true,
+      reason: `Test-First (RED-before-GREEN) requirement: Production file '${baseName}' cannot be edited before a failing test (RED) is recorded. Author a failing unit or acceptance test first, verify failure output, then edit production code.`
+    };
+  }
+
+  return { blocked: false, isProductionFile: true };
+}
+
+export default {
+  isTestFile,
+  isNonCodeFile,
+  isProductionFile,
+  readTddState,
+  writeTddState,
+  inspectTddRequirement
+};

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-parse.ts

@@ -5,7 +5,10 @@
  * raise the complexity of the parser itself.
  */
 
+export type CliCommand = 'scaffold' | 'check';
+
 export interface CliParsedOptions {
+  command: CliCommand;
   targetDir: string | null;
   force: boolean;
   noGit: boolean;
@@ -18,9 +21,18 @@ 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 BOOLEAN_FLAGS = new Map<string, BooleanFlagKey>([
   ['-f', 'force'],
   ['--force', 'force'],
@@ -36,12 +48,18 @@ 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;
+}
+
 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 +71,10 @@ export function applyArg(
       message: `Unknown argument '${arg}'. Run 'npx azcodr --help' for available options.`
     };
   }
+  if (state.targetDir === null && state.command === 'scaffold' && CHECK_COMMANDS.has(arg)) {
+    state.command = 'check';
+    return { terminal: null };
+  }
   if (!state.targetDir) {
     state.targetDir = arg;
     return { terminal: null };
@@ -74,4 +96,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,7 @@ 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 { parseArgs } from './cli-parse.js';
 import type { CliParsedOptions } from './cli-parse.js';
 import { askQuestion, resolveTargetDir, ensureWritableTarget } from './cli-target.js';
@@ -26,9 +27,11 @@ Enterprise Multi-Tenant Architecture & Agentic Engineering Starter Template
 
 Usage:
   npx azcodr [directory] [options]
+  npx azcodr check [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)
 
 Options:
   -d, --dry-run   Simulate scaffolding without modifying filesystem
@@ -40,8 +43,9 @@ Options:
 
 Examples:
   npx azcodr my-project
+  npx azcodr check
+  npx azcodr check ./existing-repo
   npx azcodr . --dry-run
-  npx azcodr . --force
 `);
 }
 
@@ -58,6 +62,7 @@ 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 }>;
 }
 
 export interface NormalizedCliIo {
@@ -69,20 +74,28 @@ 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 }>;
 }
 
-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
+  };
 }
 
 function outBanner(fullIo: NormalizedCliIo): void {
@@ -103,6 +116,16 @@ 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);
+  return fullIo.exit(result.errors === 0 ? 0 : 1);
+}
+
 function reportDryRun(result: ScaffoldResult, out: (msg: string) => void): void {
   for (const action of result.actions) {
     out(`  [preview] ${action}`);
@@ -199,10 +222,13 @@ 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.silent) {
     outBanner(fullIo);
   }

package/src/errors.ts

@@ -15,17 +15,32 @@ export const ERROR_CODES = {
   E_PATH_ESCAPE: 'Path escapes allowed root'
 } as const;
 
+/**
+ * Union of valid machine-readable error codes for scaffolding failures.
+ */
 export type ScaffoldErrorCode = keyof typeof ERROR_CODES;
 
+/**
+ * Structural interface contract for errors thrown by the scaffolder.
+ */
 export interface ScaffoldErrorShape extends Error {
   name: 'ScaffoldError';
   code: ScaffoldErrorCode;
 }
 
+/**
+ * Custom error class thrown by scaffolding operations, carrying a machine-readable code.
+ */
 export class ScaffoldError extends Error implements ScaffoldErrorShape {
   override readonly name: 'ScaffoldError' = 'ScaffoldError';
   readonly code: ScaffoldErrorCode;
 
+  /**
+   * Constructs a new ScaffoldError instance.
+   *
+   * @param code - Machine-readable error code.
+   * @param message - Human-readable explanation of the error.
+   */
   constructor(code: ScaffoldErrorCode, message: string) {
     super(message);
     this.code = code;

package/src/git.ts

@@ -15,6 +15,14 @@ export const GIT_ALLOWED_SUBCOMMANDS = new Set([
   'commit'
 ]);
 
+/**
+ * Safely executes an allowlisted git subcommand using execFileSync with an argument array and shell disabled.
+ *
+ * @param args - Subcommand and arguments array to pass to git.
+ * @param options - Child process execution options.
+ * @returns Standard output from git as a string.
+ * @throws {ScaffoldError} When args is empty or the subcommand is not in GIT_ALLOWED_SUBCOMMANDS.
+ */
 export function runGit(args: string[], options: cp.ExecFileSyncOptions = {}): string {
   if (!Array.isArray(args) || args.length === 0) {
     throw new ScaffoldError('E_GIT_ARGS_INVALID', ERROR_CODES.E_GIT_ARGS_INVALID);