azcodr 2.4.0 → 2.6.0

package/.agents/hooks.json

@@ -1,6 +1,6 @@
 {
   "safety-guard": {
-    "enabled": false,
+    "enabled": true,
     "PreToolUse": [
       {
         "matcher": "run_command",
@@ -14,8 +14,23 @@
       }
     ]
   },
+  "architectural-guard": {
+    "enabled": true,
+    "PreToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./.agents/scripts/agent_guard.js",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  },
   "post-tool-lint": {
-    "enabled": false,
+    "enabled": true,
     "PostToolUse": [
       {
         "matcher": "run_command",
@@ -30,7 +45,7 @@
     ]
   },
   "stop-verifier": {
-    "enabled": false,
+    "enabled": true,
     "Stop": [
       {
         "type": "command",

package/.agents/hooks.json.example

@@ -1,6 +1,6 @@
 {
   "safety-guard": {
-    "enabled": false,
+    "enabled": true,
     "PreToolUse": [
       {
         "matcher": "run_command",
@@ -14,8 +14,23 @@
       }
     ]
   },
+  "architectural-guard": {
+    "enabled": true,
+    "PreToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./.agents/scripts/agent_guard.js",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  },
   "post-tool-lint": {
-    "enabled": false,
+    "enabled": true,
     "PostToolUse": [
       {
         "matcher": "run_command",
@@ -30,7 +45,7 @@
     ]
   },
   "stop-verifier": {
-    "enabled": false,
+    "enabled": true,
     "Stop": [
       {
         "type": "command",

package/.agents/lib/agent-guard-command.js

@@ -0,0 +1,103 @@
+/**
+ * Command safety guard inspecting shell commands against a destructive denylist.
+ */
+export const DESTRUCTIVE_RULES = [
+    {
+        pattern: /\brm\s+(-[a-z-]*[rf][a-z-]*\s+)+(\/|\/\*|~|~\/\*|\$home|\$\{home\}|\.|\.\.|\.\/|[a-z]:\\|[a-z]:\/)/i,
+        reason: 'destructive rm targeting root, home, drive, or the current directory'
+    },
+    {
+        pattern: /(^|\s)rm\s+(-[a-z-]*\s+)*(\/|~|[a-z]:\\|[a-z]:\/)($|\s)/i,
+        reason: 'destructive rm targeting root or home'
+    },
+    {
+        pattern: /\brm\s+--recursive.*--force\s+(\/|~|\$home|\.)/i,
+        reason: 'destructive rm using long-form flags'
+    },
+    {
+        pattern: /\brm\s+.*--no-preserve-root/i,
+        reason: 'rm --no-preserve-root is forbidden under agent execution'
+    },
+    {
+        pattern: /\b(wipefs\s+-a|shred\s+-u|find\s+.*-delete)\b/i,
+        reason: 'irreversible disk or mass-delete operation'
+    },
+    {
+        pattern: /\bgit\s+push\s+.*(-f|--force|--mirror)\b/i,
+        reason: 'force-push or mirror-push can destroy remote history'
+    },
+    {
+        pattern: /\bgit\s+push\b.*--force-with-lease\b/i,
+        reason: 'force-push variant detected'
+    },
+    {
+        pattern: /\bgit\s+(reset\s+--hard|clean\s+-[a-z]*[fd])/i,
+        reason: 'destructive git worktree operation (reset --hard / clean)'
+    },
+    {
+        pattern: /\bgit\s+checkout\s+--\s+\./i,
+        reason: 'git checkout -- . discards all uncommitted work'
+    },
+    {
+        pattern: /\bgit\s+branch\s+-D\b/i,
+        reason: 'force branch delete'
+    },
+    {
+        pattern: /\b(drop\s+(database|schema|table)|truncate\s+(table\s+)?[a-z_])/i,
+        reason: 'destructive SQL DDL'
+    },
+    {
+        pattern: /\b(delete\s+from|update\s+[a-z_]+\s+set|alter\s+table)\b/i,
+        reason: 'destructive SQL DML'
+    },
+    {
+        pattern: /\b(grant\s+all|revoke\s+all)\b/i,
+        reason: 'privilege escalation in SQL'
+    },
+    {
+        pattern: /\b(mkfs|dd\s+if=|fdisk|parted\s+\/dev)\b/i,
+        reason: 'raw disk operation'
+    },
+    {
+        pattern: /(:[\s]*\([\s]*\)[\s]*\{|:[\s]*\|[\s]*:)/,
+        reason: 'fork bomb'
+    },
+    {
+        pattern: /\b(curl|wget)\s+.*\|\s*(sudo\s+)?(ba)?sh\b/i,
+        reason: 'piping download directly into shell execution'
+    },
+    {
+        pattern: /\b(base64\s+-d|base64\s+--decode)\s+.*\|/i,
+        reason: 'decoding encoded payload into a pipe'
+    },
+    {
+        pattern: /\b(npm|yarn|pnpm)\s+publish\b/i,
+        reason: 'package publish must run via release workflow, not ad-hoc tool call'
+    }
+];
+export function normalizeCommand(raw) {
+    return raw.replace(/[\r\n\t]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+/**
+ * Checks a command string against the safety denylist.
+ *
+ * @param command - Raw shell command string.
+ * @returns Violation details if blocked, or clean outcome.
+ */
+export function inspectCommand(command) {
+    const normalized = normalizeCommand(command);
+    if (!normalized)
+        return { blocked: false };
+    for (const rule of DESTRUCTIVE_RULES) {
+        if (rule.pattern.test(normalized)) {
+            return {
+                blocked: true,
+                reason: rule.reason,
+                command: normalized.slice(0, 300)
+            };
+        }
+    }
+    return { blocked: false, command: normalized };
+}
+export default { DESTRUCTIVE_RULES, normalizeCommand, inspectCommand };
+//# sourceMappingURL=agent-guard-command.js.map

package/.agents/lib/agent-guard-file.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const DEFAULT_MAX_FILE_LINES = 300;
+export function countLines(text) {
+    if (!text)
+        return 0;
+    return text.split('\n').length;
+}
+export function readExistingLines(filePath) {
+    if (!fs.existsSync(filePath))
+        return 0;
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return countLines(content);
+    }
+    catch {
+        return 0;
+    }
+}
+function calculateProjectedLines(currentLines, input) {
+    if (input.incomingContent !== undefined) {
+        return countLines(input.incomingContent);
+    }
+    if (input.replacementContent !== undefined) {
+        const addedLines = countLines(input.replacementContent);
+        const removedLines = input.targetContent !== undefined ? countLines(input.targetContent) : 1;
+        return Math.max(0, currentLines + addedLines - removedLines);
+    }
+    return currentLines;
+}
+function evaluateLineThresholds(params) {
+    const { filePath, currentLines, projectedLines, maxLines } = params;
+    const base = { currentLines, projectedLines, maxLines };
+    const relPath = path.basename(filePath);
+    if (currentLines > maxLines) {
+        if (projectedLines >= currentLines) {
+            return {
+                ...base,
+                blocked: true,
+                reason: `Refactor-Before-Add violation: '${relPath}' currently has ${currentLines} lines (limit: ${maxLines}). Adding or maintaining lines in an overflowing file is blocked. Refactor into modular units under green tests first.`
+            };
+        }
+        return { ...base, blocked: false };
+    }
+    if (projectedLines > maxLines) {
+        return {
+            ...base,
+            blocked: true,
+            reason: `File line budget exceeded: '${relPath}' would grow to ${projectedLines} lines (limit: ${maxLines}). Decompose into modular components before appending more code.`
+        };
+    }
+    return { ...base, blocked: false };
+}
+/**
+ * Checks a proposed file write or edit against Refactor-Before-Add rules.
+ *
+ * @param input - File path and proposed content.
+ * @returns Decision result indicating whether the write is blocked.
+ */
+export function inspectFileWrite(input) {
+    const maxLines = input.maxLines ?? DEFAULT_MAX_FILE_LINES;
+    const currentLines = readExistingLines(input.filePath);
+    const projectedLines = calculateProjectedLines(currentLines, input);
+    return evaluateLineThresholds({
+        filePath: input.filePath,
+        currentLines,
+        projectedLines,
+        maxLines
+    });
+}
+export default {
+    DEFAULT_MAX_FILE_LINES,
+    countLines,
+    readExistingLines,
+    inspectFileWrite
+};
+//# sourceMappingURL=agent-guard-file.js.map

package/.agents/lib/agent-guard-tdd.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function isTestFile(filePath) {
+    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) {
+    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) {
+    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) {
+    if (!fs.existsSync(stateFile)) {
+        return { lastFailingTestRecorded: false };
+    }
+    try {
+        const raw = fs.readFileSync(stateFile, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return { lastFailingTestRecorded: false };
+    }
+}
+export function writeTddState(stateFile, state) {
+    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, state, enforceTestFirst = false) {
+    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
+};
+//# sourceMappingURL=agent-guard-tdd.js.map

package/.agents/lib/agent-guard.js

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import { inspectCommand } from './agent-guard-command.js';
+import { inspectFileWrite } from './agent-guard-file.js';
+import { inspectTddRequirement, readTddState, writeTddState } from './agent-guard-tdd.js';
+function parseEnvelope(raw) {
+    try {
+        const trimmed = raw.trim();
+        if (!trimmed.startsWith('{'))
+            return null;
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+}
+function extractKey(input, keys) {
+    for (const k of keys) {
+        if (typeof input[k] === 'string')
+            return input[k];
+    }
+    return undefined;
+}
+function extractFilePath(input) {
+    return extractKey(input, ['TargetFile', 'file_path', 'path', 'filePath']);
+}
+function extractCommand(input) {
+    return extractKey(input, ['CommandLine', 'command', 'cmd']);
+}
+function inspectPreCommand(cmd) {
+    const violation = inspectCommand(cmd);
+    if (violation.blocked) {
+        return { allowed: false, reason: violation.reason, source: 'command' };
+    }
+    return { allowed: true };
+}
+function inspectPreFile(filePath, input, options) {
+    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, options = {}) {
+    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 default { inspectPreTool, inspectCommand, inspectFileWrite, inspectTddRequirement };
+//# sourceMappingURL=agent-guard.js.map

package/.agents/lib/boundaries.js

@@ -0,0 +1,158 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const DEFAULT_BOUNDARY_RULES = [
+    {
+        fromLayer: 'domain',
+        disallowImportsFrom: ['infrastructure', 'infra', 'adapters', 'cli', 'transport', 'controllers']
+    },
+    {
+        fromLayer: 'core',
+        disallowImportsFrom: ['infrastructure', 'infra', 'adapters', 'presentation', 'ui']
+    }
+];
+function isSkippedDir(name) {
+    return name.startsWith('.') || name === 'node_modules' || name === 'lib';
+}
+function isEligibleSource(name) {
+    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) {
+    if (!fs.existsSync(dir))
+        return [];
+    const results = [];
+    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, specifier) {
+    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) {
+    if (!fs.existsSync(filePath))
+        return [];
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const imports = [];
+    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) {
+    const graph = new Map();
+    for (const file of files) {
+        graph.set(file, extractLocalImports(file));
+    }
+    return graph;
+}
+export function detectDependencyCycles(graph) {
+    const cycles = [];
+    const visited = new Set();
+    const inStack = new Set();
+    const pathStack = [];
+    function dfs(node) {
+        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, segment) {
+    return new RegExp(`(^|[/\\\\])${segment}([/\\\\]|$)`, 'i').test(pathStr);
+}
+export function detectBoundaryViolations(graph, rules = DEFAULT_BOUNDARY_RULES) {
+    const violations = [];
+    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, rules = DEFAULT_BOUNDARY_RULES) {
+    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
+};
+//# sourceMappingURL=boundaries.js.map

package/.agents/scripts/agent_guard.js

@@ -14,10 +14,39 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const selfDir = path.dirname(fileURLToPath(import.meta.url));
-const guardModulePath = path.resolve(selfDir, '../../lib/agent-guard.js');
+
+// Resolution order (first existing file wins):
+//   1. AZCODR_GUARD_ENGINE override (tests, embedders).
+//   2. ../lib/agent-guard.js — vendored engine shipped inside `.agents/`
+//      (present in scaffolded projects; `.agents` is copied recursively).
+//   3. ../../lib/agent-guard.js — azcodr repo dev layout (fallback only).
+const guardCandidates = [
+  process.env.AZCODR_GUARD_ENGINE,
+  path.resolve(selfDir, '../lib/agent-guard.js'),
+  path.resolve(selfDir, '../../lib/agent-guard.js')
+].filter(Boolean);
 
 async function getGuardModule() {
-  return import(pathToFileURL(guardModulePath).href);
+  const tried = [];
+  for (const candidate of guardCandidates) {
+    if (!fs.existsSync(candidate)) {
+      tried.push(candidate);
+      continue;
+    }
+    try {
+      return await import(pathToFileURL(candidate).href);
+    } catch (err) {
+      tried.push(`${candidate} (unreadable: ${err.message})`);
+    }
+  }
+  // Fail CLOSED: a guard with no engine must be loud, never a silent allow.
+  // (Unparseable tool payloads still fail open inside inspectPreTool per
+  // ADR-005; a missing engine is a broken install, not an ambiguous input.)
+  console.error(
+    '🚨 Architectural Guard misconfigured: engine module not found, refusing to fail open. Tried:\n' +
+    tried.map((t) => `  - ${t}`).join('\n')
+  );
+  process.exit(2);
 }
 
 async function readStdin(timeoutMs = 1500) {
@@ -60,4 +89,7 @@ async function main() {
   process.exit(0);
 }
 
-main().catch(() => process.exit(0));
+main().catch((err) => {
+  console.error(`🚨 Architectural Guard crashed: ${err?.message || err}`);
+  process.exit(2);
+});