azcodr 2.6.0 → 2.7.1

package/src/errors.ts

@@ -7,11 +7,17 @@
  * tests/error-codes.test.js.
  */
 export const ERROR_CODES = {
+  /** Target directory matches template repository root itself. */
   E_TARGET_IS_TEMPLATE: 'Cannot scaffold into the azcodr template directory itself',
+  /** Target directory exists and already contains non-empty files without --force. */
   E_TARGET_NOT_EMPTY: 'Target directory is not empty',
+  /** Target path matches protected system, home, or root directory. */
   E_TARGET_IS_PROTECTED: 'Refusing to scaffold into a protected system directory',
+  /** runGit invoked with empty or missing argument array. */
   E_GIT_ARGS_INVALID: 'runGit requires a non-empty argv array',
+  /** Attempted git subcommand not in the explicit allowlist. */
   E_GIT_BLOCKED: 'Blocked git subcommand',
+  /** Relative path navigation escapes allowed root directory. */
   E_PATH_ESCAPE: 'Path escapes allowed root'
 } as const;
 
@@ -24,7 +30,9 @@ export type ScaffoldErrorCode = keyof typeof ERROR_CODES;
  * Structural interface contract for errors thrown by the scaffolder.
  */
 export interface ScaffoldErrorShape extends Error {
+  /** Error class discriminator name. */
   name: 'ScaffoldError';
+  /** Machine-readable error code. */
   code: ScaffoldErrorCode;
 }
 
@@ -32,7 +40,9 @@ export interface ScaffoldErrorShape extends Error {
  * Custom error class thrown by scaffolding operations, carrying a machine-readable code.
  */
 export class ScaffoldError extends Error implements ScaffoldErrorShape {
+  /** Error class name identifier. */
   override readonly name: 'ScaffoldError' = 'ScaffoldError';
+  /** Machine-readable error code identifying failure cause. */
   readonly code: ScaffoldErrorCode;
 
   /**

package/src/guards.ts

@@ -19,9 +19,13 @@ export function getTemplateDir(): string {
  * Options for configuring protected target verification.
  */
 export interface ProtectedTargetOptions {
+  /** Optional custom template directory path. */
   templateDir?: string;
+  /** Force overwrite flag. */
   force?: boolean;
+  /** Dry-run execution simulation flag. */
   dryRun?: boolean;
+  /** Allow targeting protected directories (internal testing only). */
   allowProtected?: boolean;
 }
 

package/src/links.ts

@@ -5,9 +5,13 @@ import path from 'node:path';
  * Configuration options for symlink and pointer creation.
  */
 export interface EnsureSymlinkOptions {
+  /** Target directory containing the files and proposed link. */
   targetDir: string;
+  /** Name of the symbolic link or alias pointer file to create. */
   linkName: string;
+  /** Name of the target file that the symlink or pointer points to. */
   targetFileName: string;
+  /** When true, simulate link creation without disk mutations. */
   dryRun?: boolean;
 }
 

package/src/repo.ts

@@ -9,7 +9,9 @@ const INITIAL_COMMIT_MESSAGE = 'chore: initial scaffold from azcodr template';
  * Options controlling git repository initialization.
  */
 export interface InitGitOptions {
+  /** If true, skip git repository initialization entirely. */
   noGit?: boolean;
+  /** If true, simulate git repository initialization without invoking git. */
   dryRun?: boolean;
 }
 

package/src/scaffold.ts

@@ -34,11 +34,17 @@ export const TEMPLATE_ITEMS: readonly string[] = [
  * Configuration options for the primary scaffold orchestration function.
  */
 export interface ScaffoldOptions {
+  /** Target directory path where project will be scaffolded (defaults to process.cwd()). */
   targetDir?: string;
+  /** Force overwrite if target directory exists and is non-empty. */
   force?: boolean;
+  /** Skip git repository initialization. */
   noGit?: boolean;
+  /** Optional custom template directory path. */
   templateDir?: string;
+  /** Simulate scaffolding without writing files to disk. */
   dryRun?: boolean;
+  /** Suppress non-error console output. */
   silent?: boolean;
 }
 
@@ -46,10 +52,15 @@ export interface ScaffoldOptions {
  * Result object returned upon completion of a scaffold operation.
  */
 export interface ScaffoldResult {
+  /** Whether the scaffolding operation completed successfully. */
   success: boolean;
+  /** Absolute filesystem path of the scaffolded target directory. */
   targetDir: string;
+  /** Whether a git repository was initialized and committed. */
   gitInitialized: boolean;
+  /** Whether execution was a dry-run simulation without disk mutations. */
   dryRun: boolean;
+  /** List of recorded scaffolding action descriptions taken. */
   actions: string[];
 }
 
@@ -57,9 +68,13 @@ export interface ScaffoldResult {
  * Options controlling pre-scaffold target directory validation.
  */
 export interface ValidateTargetOptions {
+  /** Custom template root directory path. */
   templateDir?: string;
+  /** Allow non-empty directory when force is true. */
   force?: boolean;
+  /** Simulate validation checks without erroring on non-empty targets. */
   dryRun?: boolean;
+  /** Allow targeting protected directories (internal testing only). */
   allowProtected?: boolean;
 }
 
@@ -67,10 +82,10 @@ export interface ValidateTargetOptions {
  * Options controlling template file copying and file generation.
  */
 export interface CopyTemplateOptions {
+  /** Simulate copying without disk mutations. */
   dryRun?: boolean;
 }
 
-
 function rejectTemplateSelf(resolvedTarget: string, resolvedTemplate: string): void {
   if (resolvedTarget !== resolvedTemplate) return;
   throw new ScaffoldError(
@@ -191,6 +206,7 @@ function starterPackageJson(resolvedTarget: string): Record<string, unknown> {
       'test:coverage': 'jest --coverage',
       lint: 'echo "No linter configured yet. Run /lets-build to configure toolchain."',
       boundaries: 'node .agents/scripts/boundary_guard.js',
+      smoke: 'node .agents/scripts/smoke_test.js',
       validate: 'node scripts/validate-cli.js'
     }
   };
@@ -252,11 +268,8 @@ export function copyTemplate(
  */
 export function scaffold(options: ScaffoldOptions = {}): ScaffoldResult {
   const {
-    targetDir = process.cwd(),
-    force = false,
-    noGit = false,
-    templateDir = getTemplateDir(),
-    dryRun = false
+    targetDir = process.cwd(), force = false,
+    noGit = false, templateDir = getTemplateDir(), dryRun = false
   } = options;
   const resolvedTarget = path.resolve(targetDir);
   validateTarget(resolvedTarget, { templateDir, force, dryRun });
@@ -271,9 +284,11 @@ export {
   makeScriptsExecutable, isInsideGitWorkTree, initGit, runGit,
   assertInside, ScaffoldError, ERROR_CODES, isProtectedTarget
 };
-
 export type { EnsureSymlinkOptions, InitGitOptions, ScaffoldErrorCode, ScaffoldErrorShape };
 
+/**
+ * Unified azcodr scaffolding functions, guards, utilities, and constants module.
+ */
 export default {
   scaffold, validateTarget, copyTemplate, ensureSymlink,
   ensureSymlinkOrPointer, isSameCaseInsensitiveFile, makeScriptsExecutable,

package/src/validate.ts

@@ -1,20 +1,37 @@
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+/**
+ * Tally and results returned by the architecture governance validator.
+ */
 export interface ValidationResult {
+  /** Total count of fatal governance errors encountered. */
   errors: number;
+  /** Total count of non-fatal governance warnings encountered. */
   warnings: number;
+  /** Number of progressive disclosure domain rule files verified. */
   validatedRules: number;
+  /** Number of agent skills verified under .agents/skills/. */
   validatedSkills: number;
+  /** Total count of internal markdown links verified. */
   totalLinks: number;
+  /** List of broken link targets detected across workspace markdown files. */
   brokenLinks: string[];
 }
 
+/**
+ * Pluggable reporter interface receiving live validation events.
+ */
 export interface ValidationReporter {
+  /** Called when a check passes. */
   pass: (msg: string) => void;
+  /** Called when a non-fatal warning is raised. */
   warn: (msg: string) => void;
+  /** Called when a validation check fails. */
   fail: (msg: string) => void;
+  /** Called for informative messages and section spacing. */
   log: (msg: string) => void;
+  /** Called when a new validation phase begins. */
   heading: (msg: string) => void;
 }