azcodr 2.1.0 → 2.3.0

package/src/guards.ts

@@ -2,9 +2,22 @@ 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.
+ */
 export interface ProtectedTargetOptions {
   templateDir?: string;
   force?: boolean;
@@ -14,7 +27,12 @@ export interface ProtectedTargetOptions {
 
 /**
  * Filesystem scope guard (Supply Chain: filesystem access).
- * Constrains all reads/writes to targetDir / templateDir.
+ * Constrains all reads/writes to targetDir / templateDir, throwing if candidate escapes root.
+ *
+ * @param root - Absolute base directory.
+ * @param candidate - Candidate file or directory path to check.
+ * @param message - Optional custom error message.
+ * @throws {ScaffoldError} When candidate path escapes root directory.
  */
 export function assertInside(root: string, candidate: string, message?: string): void {
   const resolvedRoot = path.resolve(root);
@@ -29,6 +47,9 @@ export function assertInside(root: string, candidate: string, message?: string):
  * Normalizes a path for protected-target comparison. On Windows the filesystem
  * is case-insensitive, so `C:\Users\Name` and `c:\users\name` are the same
  * directory and must compare equal.
+ *
+ * @param p - File or directory path to normalize.
+ * @returns Normalized path string.
  */
 export function normalizeForComparison(p: string): string {
   const resolved = path.resolve(p);
@@ -82,6 +103,10 @@ function resolvesToProtectedLocation(resolvedTarget: string, home: string): bool
  *
  * Lexical comparison is not enough: a symlink pointing at home must also be
  * caught, so an existing target is resolved with realpath before comparing.
+ *
+ * @param targetDir - The target directory path to evaluate.
+ * @param options - Optional configuration for protected target evaluation.
+ * @returns True if target is a protected location, false otherwise.
  */
 export function isProtectedTarget(targetDir: string, options: ProtectedTargetOptions = {}): boolean {
   const resolvedTarget = path.resolve(targetDir);

package/src/index.ts

@@ -1,3 +1,14 @@
+/**
+ * @module @azcodr/azcodr
+ * Enterprise Architecture & Agentic Engineering Starter Template.
+ *
+ * Provides problem-first, topology-aligned project scaffolding with strict systemic atomicity,
+ * filesystem scope guards, git worktree initialization, and multi-agent harness parity.
+ */
+
+/**
+ * Union type of all valid machine-readable error codes.
+ */
 export type ScaffoldErrorCode =
   | 'E_TARGET_IS_TEMPLATE'
   | 'E_TARGET_NOT_EMPTY'
@@ -6,6 +17,9 @@ export type ScaffoldErrorCode =
   | 'E_GIT_BLOCKED'
   | 'E_PATH_ESCAPE';
 
+/**
+ * Core scaffolding functions, guards, utilities, error classes, and constants.
+ */
 export {
   scaffold,
   validateTarget,
@@ -25,6 +39,49 @@ 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.
+ */
 export type {
   ScaffoldOptions,
   ScaffoldResult,
@@ -36,4 +93,8 @@ export type {
 } from './scaffold.js';
 
 import scaffoldModule from './scaffold.js';
+
+/**
+ * Default export providing the unified azcodr scaffolding module.
+ */
 export default scaffoldModule;

package/src/links.ts

@@ -1,6 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+/**
+ * Configuration options for symlink and pointer creation.
+ */
 export interface EnsureSymlinkOptions {
   targetDir: string;
   linkName: string;
@@ -70,6 +73,11 @@ function copyFallback(targetDir: string, linkName: string, targetFileName: strin
 /**
  * Detects whether linkName and targetFileName refer to the same entry on a case-insensitive filesystem.
  * Uses exact directory listing (not existsSync, which lies on case-insensitive systems).
+ *
+ * @param targetDir - Directory containing the file entries.
+ * @param linkName - Name of the proposed symlink or alias entry.
+ * @param targetFileName - Target file name to match against.
+ * @returns True if both names resolve to the same disk file on a case-insensitive filesystem.
  */
 export function isSameCaseInsensitiveFile(
   targetDir: string,
@@ -90,6 +98,9 @@ export function isSameCaseInsensitiveFile(
 
 /**
  * Safely creates or updates a symbolic link, falling back to a file copy if symlinks are unsupported.
+ *
+ * @param options - Options specifying target directory, link name, target file name, and dry-run mode.
+ * @returns True if the symlink or copy fallback was successfully established.
  */
 export function ensureSymlink(options: EnsureSymlinkOptions): boolean {
   const { targetDir, linkName, targetFileName, dryRun = false } = options;
@@ -110,6 +121,9 @@ export function ensureSymlink(options: EnsureSymlinkOptions): boolean {
  * Creates a symlink, falling back to a text pointer (not a full copy).
  * Used for .github/copilot-instructions.md where a full AGENTS.md copy would
  * break relative markdown links (they resolve from .github/, not root).
+ *
+ * @param options - Options specifying target directory, link name, target file name, and dry-run mode.
+ * @returns True if the symlink or pointer fallback was successfully established.
  */
 export function ensureSymlinkOrPointer(options: EnsureSymlinkOptions): boolean {
   const { targetDir, linkName, targetFileName, dryRun = false } = options;

package/src/permissions.ts

@@ -25,6 +25,10 @@ function chmodShFilesIn(scriptsDir: string, dryRun: boolean): string[] {
 
 /**
  * Ensures all bash scripts in agent and skill directories have executable permissions (0o755).
+ *
+ * @param targetDir - Root directory containing .agents and skills.
+ * @param dryRun - When true, simulates permission changes without modifying disk.
+ * @returns Array of file paths that were modified or would be modified.
  */
 export function makeScriptsExecutable(targetDir: string, dryRun = false): string[] {
   const agentScriptsDir = path.join(targetDir, '.agents', 'scripts');

package/src/repo.ts

@@ -5,6 +5,9 @@ import { runGit } from './git.js';
 
 const INITIAL_COMMIT_MESSAGE = 'chore: initial scaffold from azcodr template';
 
+/**
+ * Options controlling git repository initialization.
+ */
 export interface InitGitOptions {
   noGit?: boolean;
   dryRun?: boolean;
@@ -13,6 +16,9 @@ export interface InitGitOptions {
 /**
  * Detects whether targetDir is already inside an existing Git worktree.
  * Socket note: shell access is limited to `git rev-parse` via runGit (no shell).
+ *
+ * @param targetDir - Directory path to inspect.
+ * @returns True if target directory is within a git worktree, false otherwise.
  */
 export function isInsideGitWorkTree(targetDir: string): boolean {
   try {
@@ -53,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'
       }
     });
   }
@@ -74,6 +80,10 @@ function initialCommit(targetDir: string): void {
 /**
  * Initializes a git repository in the target directory if not already inside one.
  * Socket note: only allowlisted `git init/branch/add/commit` via execFileSync, cwd scoped.
+ *
+ * @param targetDir - Directory where git repository should be initialized.
+ * @param options - Configuration options for git initialization.
+ * @returns True if repository was initialized and committed, false otherwise.
  */
 export function initGit(targetDir: string, options: InitGitOptions = {}): boolean {
   const { noGit = false, dryRun = false } = options;

package/src/scaffold.ts

@@ -1,17 +1,21 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { fileURLToPath } from 'node:url';
 import { ScaffoldError, ERROR_CODES } from './errors.js';
 import type { ScaffoldErrorCode, ScaffoldErrorShape } from './errors.js';
 import { runGit } from './git.js';
-import { assertInside, isProtectedTarget } from './guards.js';
+import { assertInside, isProtectedTarget, getTemplateDir } from './guards.js';
 import { ensureSymlink, ensureSymlinkOrPointer, isSameCaseInsensitiveFile } from './links.js';
 import type { EnsureSymlinkOptions } from './links.js';
 import { makeScriptsExecutable } from './permissions.js';
 import { isInsideGitWorkTree, initGit } from './repo.js';
 import type { InitGitOptions } from './repo.js';
 
+export { getTemplateDir };
+
+/**
+ * Canonical list of template files and directories copied into a new workspace.
+ */
 export const TEMPLATE_ITEMS: readonly string[] = [
   'AGENTS.md',
   'memory.md',
@@ -25,6 +29,9 @@ export const TEMPLATE_ITEMS: readonly string[] = [
   'LICENSE'
 ];
 
+/**
+ * Configuration options for the primary scaffold orchestration function.
+ */
 export interface ScaffoldOptions {
   targetDir?: string;
   force?: boolean;
@@ -34,6 +41,9 @@ export interface ScaffoldOptions {
   silent?: boolean;
 }
 
+/**
+ * Result object returned upon completion of a scaffold operation.
+ */
 export interface ScaffoldResult {
   success: boolean;
   targetDir: string;
@@ -42,6 +52,9 @@ export interface ScaffoldResult {
   actions: string[];
 }
 
+/**
+ * Options controlling pre-scaffold target directory validation.
+ */
 export interface ValidateTargetOptions {
   templateDir?: string;
   force?: boolean;
@@ -49,16 +62,13 @@ export interface ValidateTargetOptions {
   allowProtected?: boolean;
 }
 
+/**
+ * Options controlling template file copying and file generation.
+ */
 export interface CopyTemplateOptions {
   dryRun?: boolean;
 }
 
-/**
- * Returns the root path to the azcodr template files.
- */
-export function getTemplateDir(): string {
-  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-}
 
 function rejectTemplateSelf(resolvedTarget: string, resolvedTemplate: string): void {
   if (resolvedTarget !== resolvedTemplate) return;
@@ -94,6 +104,10 @@ function rejectNonEmptyTarget(resolvedTarget: string, force: boolean): void {
 
 /**
  * Validates the target directory to ensure it is suitable for scaffolding.
+ *
+ * @param targetDir - Target directory path to validate.
+ * @param options - Validation options including force, dry-run, and protected overrides.
+ * @throws {ScaffoldError} When target is invalid, protected, or non-empty without force.
  */
 export function validateTarget(targetDir: string, options: ValidateTargetOptions = {}): void {
   const { templateDir = getTemplateDir(), force = false, dryRun = false, allowProtected = false } = options;
@@ -109,6 +123,10 @@ export function validateTarget(targetDir: string, options: ValidateTargetOptions
 }
 
 function resolveTemplateItem(resolvedTemplate: string, item: string): string {
+  if (item === 'memory.md') {
+    const memTpl = path.join(resolvedTemplate, 'data', 'memory.template');
+    if (fs.existsSync(memTpl)) return memTpl;
+  }
   let srcPath = path.join(resolvedTemplate, item);
   if (item === '.gitignore' && !fs.existsSync(srcPath)) {
     const npmIgnorePath = path.join(resolvedTemplate, '.npmignore');
@@ -169,7 +187,7 @@ function starterPackageJson(resolvedTarget: string): Record<string, unknown> {
     description: 'Scaffolded with azcodr enterprise architecture template',
     scripts: {
       test: 'node --test',
-      'test:coverage': 'node scripts/test_coverage.js',
+      'test:coverage': 'jest --coverage',
       lint: 'echo "No linter configured yet. Run /lets-build to configure toolchain."',
       validate: 'node scripts/validate-cli.js'
     }
@@ -197,6 +215,11 @@ function chmodTemplateScripts(inspectDir: string, dryRun: boolean): string[] {
 /**
  * Recursively copies template files into the target directory and sets up symlinks and permissions.
  * Socket note: filesystem access is scoped to templateDir -> targetDir only (assertInside).
+ *
+ * @param targetDir - Destination directory path.
+ * @param templateDir - Source template directory path.
+ * @param options - Copy options including dry-run flag.
+ * @returns Array of recorded scaffolding action descriptions.
  */
 export function copyTemplate(
   targetDir: string,
@@ -220,6 +243,9 @@ export function copyTemplate(
 
 /**
  * High-level orchestration function to scaffold the azcodr workspace into targetDir.
+ *
+ * @param options - Scaffolding options.
+ * @returns Result object containing success flag, target directory, and action log.
  */
 export function scaffold(options: ScaffoldOptions = {}): ScaffoldResult {
   const {
@@ -238,36 +264,16 @@ export function scaffold(options: ScaffoldOptions = {}): ScaffoldResult {
 }
 
 export {
-  ensureSymlink,
-  ensureSymlinkOrPointer,
-  isSameCaseInsensitiveFile,
-  makeScriptsExecutable,
-  isInsideGitWorkTree,
-  initGit,
-  runGit,
-  assertInside,
-  ScaffoldError,
-  ERROR_CODES,
-  isProtectedTarget
+  ensureSymlink, ensureSymlinkOrPointer, isSameCaseInsensitiveFile,
+  makeScriptsExecutable, isInsideGitWorkTree, initGit, runGit,
+  assertInside, ScaffoldError, ERROR_CODES, isProtectedTarget
 };
 
 export type { EnsureSymlinkOptions, InitGitOptions, ScaffoldErrorCode, ScaffoldErrorShape };
 
 export default {
-  scaffold,
-  validateTarget,
-  copyTemplate,
-  ensureSymlink,
-  ensureSymlinkOrPointer,
-  isSameCaseInsensitiveFile,
-  makeScriptsExecutable,
-  isInsideGitWorkTree,
-  initGit,
-  getTemplateDir,
-  runGit,
-  assertInside,
-  TEMPLATE_ITEMS,
-  ScaffoldError,
-  ERROR_CODES,
-  isProtectedTarget
+  scaffold, validateTarget, copyTemplate, ensureSymlink,
+  ensureSymlinkOrPointer, isSameCaseInsensitiveFile, makeScriptsExecutable,
+  isInsideGitWorkTree, initGit, getTemplateDir, runGit,
+  assertInside, TEMPLATE_ITEMS, ScaffoldError, ERROR_CODES, isProtectedTarget
 };

package/src/validate.ts

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export interface ValidationResult {
+  errors: number;
+  warnings: number;
+  validatedRules: number;
+  validatedSkills: number;
+  totalLinks: number;
+  brokenLinks: string[];
+}
+
+export interface ValidationReporter {
+  pass: (msg: string) => void;
+  warn: (msg: string) => void;
+  fail: (msg: string) => void;
+  log: (msg: string) => void;
+  heading: (msg: string) => void;
+}
+
+/**
+ * Validates the agentic architecture and governance files of a workspace.
+ *
+ * @param workspaceRoot - Path to the workspace directory (defaults to cwd).
+ * @param reporter - Optional custom reporter hooks.
+ * @returns Object containing error and warning tallies and validation counts.
+ */
+export async function validate(
+  workspaceRoot: string = process.cwd(),
+  reporter?: ValidationReporter
+): Promise<ValidationResult> {
+  const baseDir = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+  const scriptPath = path.resolve(baseDir, '../scripts/validate.js');
+  const mod = await import(pathToFileURL(scriptPath).href);
+  return mod.runValidation(path.resolve(workspaceRoot), reporter);
+}
+
+const noop = (): void => {};
+
+/**
+ * Creates a silent reporter that suppresses all status reports.
+ */
+export function createSilentReporter(): ValidationReporter {
+  return { pass: noop, warn: noop, fail: noop, log: noop, heading: noop };
+}
+
+export default { validate, createSilentReporter };

package/scripts/test_coverage.js

@@ -1,66 +0,0 @@
-#!/usr/bin/env node
-
-import { spawnSync } from 'node:child_process';
-import process from 'node:process';
-
-// Native threshold flags and include filtering were added in Node v22.8.0.
-// Fail closed on older runtimes instead of silently passing without a gate.
-const [major, minor] = process.versions.node.split('.').map(Number);
-const supportsThresholds = major > 22 || (major === 22 && minor >= 8);
-if (!supportsThresholds) {
-  console.error(
-    `test:coverage requires Node >=22.8.0 for threshold enforcement (current: ${process.versions.node}). ` +
-    `Upgrade Node, or invoke the runner directly: node --test --experimental-test-coverage.`
-  );
-  process.exit(1);
-}
-
-const args = [
-  '--test',
-  '--experimental-test-coverage',
-  '--test-coverage-include=bin/**',
-  '--test-coverage-include=lib/**',
-  // Explicit file, not scripts/**: validate-cli.js is a two-line process entry
-  // that only runs when invoked directly, so it cannot be covered in-process.
-  // Every other script IS gated.
-  '--test-coverage-include=scripts/validate.js',
-  '--test-coverage-include=scripts/validate/io.js',
-  '--test-coverage-include=scripts/validate/text.js',
-  '--test-coverage-include=scripts/validate/parity.js',
-  '--test-coverage-include=scripts/validate/adr.js',
-  '--test-coverage-include=scripts/validate/root.js',
-  '--test-coverage-include=scripts/validate/rules.js',
-  '--test-coverage-include=scripts/validate/skills.js',
-  '--test-coverage-include=scripts/validate/links.js',
-  '--test-coverage-include=scripts/test_coverage.js',
-  // bin/, lib/ and test_coverage.js hold no environment-dependent defensive
-  // branches and are held at 100%. validate.js is a filesystem auditor: it
-  // contains fault handlers for conditions this host cannot produce (creating
-  // symlinks requires Developer Mode; a RangeError needs a tree thousands of
-  // levels deep). Those are exercised by tests/validate-faults.test.js where
-  // the fault can be injected, so the gate here is deliberately lower rather
-  // than silently passing.
-  '--test-coverage-branches=98',
-  '--test-coverage-functions=97',
-  '--test-coverage-lines=100'
-];
-
-const result = spawnSync(process.execPath, args, {
-  stdio: 'inherit',
-  env: process.env
-});
-
-if (result.error) {
-  console.error(result.error);
-  process.exit(1);
-}
-
-// A null status means the child was killed by a signal (OOM, SIGKILL from a
-// runner timeout). `status ?? 0` reported success for a crashed runner, which
-// is how a green build can carry zero coverage data.
-if (result.signal) {
-  console.error(`test runner terminated by signal ${result.signal}; coverage gate could not be evaluated.`);
-  process.exit(1);
-}
-
-process.exit(result.status ?? 1);