azcodr 1.0.1 → 1.1.0

package/.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh

@@ -45,21 +45,37 @@ if [[ -L "${CLAUDE_FILE}" ]]; then
   else
     log_fail "CLAUDE.md points to '${TARGET}' instead of 'AGENTS.md'."
   fi
+elif [[ -f "${CLAUDE_FILE}" ]] && [[ "$(< "${CLAUDE_FILE}")" == "AGENTS.md" ]]; then
+  log_pass "CLAUDE.md is a text pointer to AGENTS.md (symlink fallback)."
 else
   log_fail "CLAUDE.md is not a symbolic link."
 fi
 
-# Check agents.md symlink
+# Check agents.md symlink (case-insensitive filesystem aware)
 AGENTS_LOWER="${WORKSPACE_ROOT}/agents.md"
-if [[ -L "${AGENTS_LOWER}" ]]; then
-  TARGET=$(readlink "${AGENTS_LOWER}")
-  if [[ "${TARGET}" == "AGENTS.md" ]]; then
-    log_pass "agents.md is a valid symlink to AGENTS.md."
+IS_CASE_INSENSITIVE=false
+if [[ "$(uname -s)" == "Darwin" ]] || [[ "$(uname -s)" =~ (MINGW|MSYS|CYGWIN) ]]; then
+  IS_CASE_INSENSITIVE=true
+elif [[ -f "${AGENTS_FILE}" ]] && [[ -f "${AGENTS_LOWER}" ]] && [[ ! -L "${AGENTS_LOWER}" ]]; then
+  IS_CASE_INSENSITIVE=true
+fi
+
+if [[ "${IS_CASE_INSENSITIVE}" == "true" ]]; then
+  log_pass "agents.md is satisfied natively by AGENTS.md (case-insensitive filesystem)."
+else
+  if [[ ! -L "${AGENTS_LOWER}" ]] && [[ ! -e "${AGENTS_LOWER}" ]] && [[ -f "${AGENTS_FILE}" ]]; then
+    ln -sf "AGENTS.md" "${AGENTS_LOWER}"
+  fi
+  if [[ -L "${AGENTS_LOWER}" ]]; then
+    TARGET=$(readlink "${AGENTS_LOWER}")
+    if [[ "${TARGET}" == "AGENTS.md" ]]; then
+      log_pass "agents.md is a valid symlink to AGENTS.md."
+    else
+      log_fail "agents.md points to '${TARGET}' instead of 'AGENTS.md'."
+    fi
   else
-    log_fail "agents.md points to '${TARGET}' instead of 'AGENTS.md'."
+    log_fail "agents.md is not a symbolic link."
   fi
-else
-  log_fail "agents.md is not a symbolic link."
 fi
 
 # 2. Checking Progressive Disclosure Rules (docs/rules)

package/.editorconfig

@@ -0,0 +1,19 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[*.go]
+indent_style = tab

package/.gitignore

@@ -18,3 +18,6 @@ Thumbs.db
 .env
 .env.local
 .env.*.local
+
+# Case-insensitive filesystem parity (agents.md is generated/symlinked on Linux, native on macOS/Windows)
+agents.md

package/bin/azcodr.js

@@ -3,13 +3,12 @@
 
 const path = require('node:path');
 const readline = require('node:readline');
+const fs = require('node:fs');
 const { scaffold, logChange, getTemplateDir } = require('../lib/scaffold.js');
 const pkg = require('../package.json');
 
-const args = process.argv.slice(2);
-
-function printHelp() {
-  console.log(`
+function printHelp(out = console.log) {
+  out(`
 azcodr v${pkg.version}
 Enterprise Multi-Tenant Architecture & Agentic Engineering Starter Template
 
@@ -22,208 +21,282 @@ Commands:
   change <title>  Log a generic architectural change to changes.md
 
 Scaffold Options:
+  -d, --dry-run   Simulate scaffolding without modifying filesystem
+  -s, --silent    Suppress console output messages
   -f, --force     Overwrite existing files in target directory without confirmation
   --no-git        Do not initialize a git repository
   -v, --version   Display version number
   -h, --help      Display this help message
 
 Change Options:
-  -c, --category  Category (Rule | Skill | Infrastructure | CLI | Knowledge Hub)
+  -c, --category  Category (Architecture | Rule | Skill | Infrastructure | CLI | Knowledge Hub)
   -f, --files     Target file(s) affected (e.g. "docs/rules/caching.md")
   -r, --rationale Rationale for upstream template incorporation
   -d, --desc      Detailed description of the change
 
 Examples:
   npx azcodr my-project
+  npx azcodr . --dry-run
   npx azcodr . --force
   npx azcodr change "Add Wasm plugin interface" -c Architecture
 `);
 }
 
-function printVersion() {
-  console.log(pkg.version);
+function printVersion(out = console.log) {
+  out(pkg.version);
 }
 
-function askQuestion(query) {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
+function askQuestion(query, { input = process.stdin, output = process.stdout } = {}) {
+  const rl = readline.createInterface({ input, output });
 
   return new Promise((resolve) => {
+    let resolved = false;
     rl.question(query, (answer) => {
-      rl.close();
-      resolve(answer.trim());
+      if (!resolved) {
+        resolved = true;
+        rl.close();
+        resolve(answer.trim());
+      }
+    });
+    rl.on('close', () => {
+      if (!resolved) {
+        resolved = true;
+        resolve('');
+      }
     });
   });
 }
 
-async function handleLogChange() {
+async function handleLogChange(rawArgs = process.argv.slice(2), io = {}) {
+  const {
+    out = console.log,
+    err = console.error,
+    exit = process.exit,
+    stdin = process.stdin,
+    stdout = process.stdout,
+    cwd = process.cwd(),
+    logChange: logChangeFn = logChange
+  } = io;
+
   let title = null;
   let category = 'Architecture';
   let targetFiles = 'docs/rules/';
   let rationale = 'Generic architectural enhancement';
   let description = '';
 
-  for (let i = 1; i < args.length; i++) {
-    const a = args[i];
+  for (let i = 1; i < rawArgs.length; i++) {
+    const a = rawArgs[i];
     if (a === '-c' || a === '--category') {
-      category = args[++i] || category;
+      category = rawArgs[++i] || category;
     } else if (a === '-f' || a === '--files') {
-      targetFiles = args[++i] || targetFiles;
+      targetFiles = rawArgs[++i] || targetFiles;
     } else if (a === '-r' || a === '--rationale') {
-      rationale = args[++i] || rationale;
+      rationale = rawArgs[++i] || rationale;
     } else if (a === '-d' || a === '--desc' || a === '--description') {
-      description = args[++i] || description;
-    } else if (!a.startsWith('-')) {
-      if (!title) {
-        title = a;
-      }
+      description = rawArgs[++i] || description;
+    } else if (a.startsWith('-')) {
+      err(`❌ Error: Unknown argument '${a}'. Run 'npx azcodr --help' for available options.`);
+      return exit(1);
+    } else if (!title) {
+      title = a;
     }
   }
 
   if (!title) {
-    if (process.stdin.isTTY) {
-      title = await askQuestion('? Change title: ');
+    if (stdin.isTTY) {
+      title = await askQuestion('? Change title: ', { input: stdin, output: stdout });
     }
   }
 
   if (!title) {
-    console.error('❌ Error: A title is required to log an upstream change.');
-    console.error('Usage: npx azcodr change "<title>" [-c Category] [-f Files] [-r Rationale] [-d Description]');
-    process.exit(1);
+    err('❌ Error: A title is required to log an upstream change.');
+    err('Usage: npx azcodr change "<title>" [-c Category] [-f Files] [-r Rationale] [-d Description]');
+    return exit(1);
   }
 
   try {
-    const res = logChange({
+    const res = logChangeFn({
       title,
       category,
       targetFiles,
       rationale,
       description,
-      targetDir: process.cwd()
+      targetDir: cwd
     });
-    console.log(`\n✅ Upstream change logged to ${res.filePath}\n`);
-    process.exit(0);
-  } catch (err) {
-    console.error(`\n❌ Failed to log change: ${err.message}\n`);
-    process.exit(1);
+    out(`\n✅ Upstream change logged to ${res.filePath}\n`);
+    return exit(0);
+  } catch (error) {
+    err(`\n❌ Failed to log change: ${error.message}\n`);
+    return exit(1);
   }
 }
 
-async function main() {
-  if (args.length > 0 && (args[0] === '-h' || args[0] === '--help')) {
-    printHelp();
-    process.exit(0);
-  }
-
-  if (args.length > 0 && (args[0] === '-v' || args[0] === '--version')) {
-    printVersion();
-    process.exit(0);
-  }
+async function runCli(rawArgs = process.argv.slice(2), io = {}) {
+  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;
 
-  if (args.length > 0 && (args[0] === 'change' || args[0] === 'log-change')) {
-    await handleLogChange();
-    return;
+  if (rawArgs[0] === 'change' || rawArgs[0] === 'log-change') {
+    return handleLogChange(rawArgs, io);
   }
 
   let targetDir = null;
   let force = false;
   let noGit = false;
+  let dryRun = false;
+  let silent = false;
 
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
     if (arg === '-h' || arg === '--help') {
-      printHelp();
-      process.exit(0);
+      printHelp(out);
+      return exit(0);
     } else if (arg === '-v' || arg === '--version') {
-      printVersion();
-      process.exit(0);
+      printVersion(out);
+      return exit(0);
     } else if (arg === '-f' || arg === '--force') {
       force = true;
     } else if (arg === '--no-git') {
       noGit = true;
-    } else if (!arg.startsWith('-')) {
-      if (!targetDir) {
-        targetDir = arg;
-      }
+    } else if (arg === '-d' || arg === '--dry-run') {
+      dryRun = true;
+    } else if (arg === '-s' || arg === '--silent') {
+      silent = true;
+    } else if (arg.startsWith('-')) {
+      err(`❌ Error: Unknown argument '${arg}'. Run 'npx azcodr --help' for available options.`);
+      return exit(1);
+    } else if (!targetDir) {
+      targetDir = arg;
     }
   }
 
-  console.log('\n🚀 azcodr - Enterprise Multi-Tenant Architecture & Agentic Engineering\n');
+  if (!silent) {
+    out('\n🚀 azcodr - Enterprise Multi-Tenant Architecture & Agentic Engineering\n');
+  }
 
   if (!targetDir) {
-    if (process.stdin.isTTY) {
-      const answer = await askQuestion('? Where would you like to initialize your project? (./) ');
+    if (stdin.isTTY) {
+      const answer = await askQuestion('? Where would you like to initialize your project? (./) ', {
+        input: stdin,
+        output: stdout
+      });
       targetDir = answer || '.';
     } else {
       targetDir = '.';
     }
   }
 
-  const resolvedTarget = path.resolve(process.cwd(), targetDir);
-  const templateDir = getTemplateDir();
+  const resolvedTarget = path.resolve(cwd, targetDir);
 
   if (resolvedTarget === templateDir) {
-    console.error(`❌ Error: Cannot scaffold into the template directory itself: ${resolvedTarget}`);
-    process.exit(1);
+    err(`❌ Error: Cannot scaffold into the template directory itself: ${resolvedTarget}`);
+    return exit(1);
   }
 
-  const fs = require('node:fs');
   if (fs.existsSync(resolvedTarget)) {
+    const stat = fs.statSync(resolvedTarget);
+    if (!stat.isDirectory()) {
+      err(`❌ Error: Target '${resolvedTarget}' already exists and is not a directory.`);
+      return exit(1);
+    }
     const entries = fs.readdirSync(resolvedTarget);
     if (entries.length > 0 && !force) {
-      if (process.stdin.isTTY) {
+      if (stdin.isTTY) {
         const confirm = await askQuestion(
-          `⚠️  Target directory '${targetDir}' is not empty (${entries.length} items). Continue? (y/N) `
+          `⚠️  Target directory '${targetDir}' is not empty (${entries.length} items). Continue? (y/N) `,
+          { input: stdin, output: stdout }
         );
         if (confirm.toLowerCase() !== 'y' && confirm.toLowerCase() !== 'yes') {
-          console.log('Scaffolding aborted.');
-          process.exit(0);
+          out('Scaffolding aborted.');
+          return exit(0);
         }
         force = true;
       } else {
-        console.error(
-          `❌ Error: Target directory '${resolvedTarget}' is not empty. Use --force to proceed.`
-        );
-        process.exit(1);
+        err(`❌ Error: Target directory '${resolvedTarget}' is not empty. Use --force to proceed.`);
+        return exit(1);
       }
     }
   }
 
-  console.log(`📦 Scaffolding azcodr into: ${resolvedTarget}`);
+  if (dryRun) {
+    if (!silent) {
+      out(`🔍 DRY RUN: Simulating azcodr scaffolding into: ${resolvedTarget}\n`);
+    }
+  } else if (!silent) {
+    out(`📦 Scaffolding azcodr into: ${resolvedTarget}`);
+  }
 
   try {
-    const result = scaffold({
+    const result = scaffoldFn({
       targetDir: resolvedTarget,
       force,
       noGit,
-      templateDir
+      templateDir,
+      dryRun,
+      silent
     });
 
-    console.log('  ✅ Progressive disclosure rules copied (docs/rules/)');
-    console.log('  ✅ Workspace knowledge hub and ADR ledger copied (docs/knowledge/, memory.md)');
-    console.log('  ✅ Specialized agentic skills copied (.agents/skills/)');
-    console.log('  ✅ Upstream changes ledger initialized (changes.md)');
-    console.log('  ✅ Agent directives and harness symlinks established (AGENTS.md, CLAUDE.md, agents.md)');
-    if (result.gitInitialized) {
-      console.log('  ✅ Git repository initialized');
+    if (dryRun) {
+      if (!silent) {
+        for (const action of result.actions) {
+          out(`  [preview] ${action}`);
+        }
+        out('\n🎉 Dry run completed. 0 files modified on disk.\n');
+      }
+      return exit(0);
     }
 
-    console.log('\n🎉 azcodr initialized successfully!\n');
-    console.log('Next steps:');
-    if (targetDir !== '.' && targetDir !== './') {
-      console.log(`  1. cd ${targetDir}`);
+    if (!silent) {
+      out('  ✅ Progressive disclosure rules copied (docs/rules/)');
+      out('  ✅ Workspace knowledge hub and ADR ledger copied (docs/knowledge/, memory.md)');
+      out('  ✅ Specialized agentic skills copied (.agents/skills/)');
+      out('  ✅ Upstream changes ledger initialized (changes.md)');
+      out('  ✅ Editor formatting standards initialized (.editorconfig)');
+      out('  ✅ Agent directives and harness symlinks established (AGENTS.md, CLAUDE.md, agents.md)');
+      if (result.gitInitialized) {
+        out('  ✅ Git repository initialized');
+      }
+
+      out('\n🎉 azcodr initialized successfully!\n');
+      out('Next steps:');
+      if (targetDir !== '.' && targetDir !== './') {
+        out(`  1. cd ${targetDir}`);
+      }
+      out('  2. Open the project in your AI coding assistant (Antigravity, Claude Code, Cursor, OpenHands)');
+      out('  3. Run /lets-build to start the architectural interview and scaffold your application stack!\n');
     }
-    console.log('  2. Open the project in your AI coding assistant (Antigravity, Claude Code, Cursor, OpenHands)');
-    console.log('  3. Run /lets-build to start the architectural interview and scaffold your application stack!\n');
+    return exit(0);
+  } catch (error) {
+    err(`\n❌ Scaffolding failed: ${error.message}\n`);
+    return exit(1);
+  }
+}
+
+async function main() {
+  try {
+    await runCli(process.argv.slice(2));
   } catch (err) {
-    console.error(`\n❌ Scaffolding failed: ${err.message}\n`);
+    console.error('Unexpected error:', err);
     process.exit(1);
   }
 }
 
-main().catch((err) => {
-  console.error('Unexpected error:', err);
-  process.exit(1);
-});
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  runCli,
+  handleLogChange,
+  askQuestion,
+  printHelp,
+  printVersion,
+  main
+};

package/changes.md

@@ -34,3 +34,17 @@ When an AI agent or engineer discovers a generic architectural improvement, bug
 - **Rationale:** Remove fragile git repo resolution and merge scripts; replace with atomic change logging in `changes.md`.
 - **Description:** Retired `merge-ai` skill and removed machine-specific hardcoded paths. All upstream improvements are now recorded atomically in `changes.md`.
 - **Domain Filter Verification:** Verified 100% generic.
+
+### [2026-09-25] Harden CLI, achieve 100% test coverage gates, add multi-OS CI workflow, and TypeScript declarations
+- **Category:** CLI
+- **Target File(s):** bin/azcodr.js, lib/scaffold.js, lib/index.d.ts, .github/workflows/ci.yml
+- **Rationale:** Fulfill 100.00% test coverage mandate, cross-platform CI matrix, and library type safety
+- **Description:** Remediate gap assessment findings: add --dry-run and --silent flags, enforce 100.00% line/branch/function coverage gates, add GitHub Actions CI matrix across Node 18/20/22/24 and Linux/macOS/Windows, add .editorconfig template item, and export ambient TypeScript typings.
+- **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.
+
+### [2026-09-25] Resolve macOS/Windows Git Case-Collision and Cross-Version CI Matrix Coverage
+- **Category:** Infrastructure & CI
+- **Target File(s):** .gitignore, lib/scaffold.js, scripts/test_coverage.js, validate_agentic_configs.sh
+- **Rationale:** Ensure flawless cross-platform and multi-version Node execution across macOS, Windows, and Linux on Node 18, 20, 22, 24.
+- **Description:** Untracked agents.md from Git to prevent cyclic symlink overwrite on case-insensitive filesystems; hardened ensureSymlink with isSameCaseInsensitiveFile check; added cross-version test coverage runner script; updated npm test runner to use native discovery.
+- **Domain Filter Verification:** Verified 100% generic; purged of all project-specific business entities and models.

package/lib/index.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Enterprise Multi-Tenant Architecture & Agentic Engineering Starter Template
+ * Programmatic API Definitions
+ */
+
+export interface ScaffoldOptions {
+  /** Target directory path where template should be scaffolded (default: process.cwd()) */
+  targetDir?: string;
+  /** Force overwrite if target directory is non-empty (default: false) */
+  force?: boolean;
+  /** Skip git repository initialization (default: false) */
+  noGit?: boolean;
+  /** Custom template root directory (default: azcodr root) */
+  templateDir?: string;
+  /** Simulate scaffolding without writing files or running git (default: false) */
+  dryRun?: boolean;
+  /** Suppress console output messages (default: false) */
+  silent?: boolean;
+}
+
+export interface ScaffoldResult {
+  /** Whether the scaffolding succeeded */
+  success: boolean;
+  /** Absolute resolved path of the target directory */
+  targetDir: string;
+  /** Whether git init was successfully executed */
+  gitInitialized: boolean;
+  /** Whether execution ran in dry-run simulation mode */
+  dryRun: boolean;
+  /** List of files, directories, and symlinks created or simulated */
+  actions: string[];
+}
+
+export interface LogChangeOptions {
+  /** Short title describing the architectural change */
+  title: string;
+  /** Category of change (Architecture | Rule | Skill | Infrastructure | CLI | Knowledge Hub) */
+  category?: string;
+  /** Target file(s) affected by the change */
+  targetFiles?: string;
+  /** Architectural rationale for upstream template incorporation */
+  rationale?: string;
+  /** Detailed description of the change */
+  description?: string;
+  /** Working directory containing changes.md (default: process.cwd()) */
+  targetDir?: string;
+}
+
+export interface LogChangeResult {
+  /** Whether the log entry was successfully recorded */
+  success: boolean;
+  /** Absolute path to changes.md */
+  filePath: string;
+  /** Markdown entry text that was appended */
+  entry: string;
+}
+
+export interface ValidateTargetOptions {
+  /** Custom template root directory */
+  templateDir?: string;
+  /** Force allow non-empty directory */
+  force?: boolean;
+}
+
+export interface InitGitOptions {
+  /** If true, skips git initialization */
+  noGit?: boolean;
+  /** If true, simulates git initialization without executing */
+  dryRun?: boolean;
+}
+
+export interface CopyTemplateOptions {
+  /** If true, simulates copy without writing to disk */
+  dryRun?: boolean;
+}
+
+/**
+ * High-level orchestration function to scaffold the azcodr workspace into targetDir.
+ */
+export function scaffold(options?: ScaffoldOptions): ScaffoldResult;
+
+/**
+ * Appends a standardized upstream change entry to changes.md.
+ */
+export function logChange(options: LogChangeOptions): LogChangeResult;
+
+/**
+ * Validates the target directory to ensure it is suitable for scaffolding.
+ */
+export function validateTarget(targetDir: string, options?: ValidateTargetOptions): void;
+
+/**
+ * Copies template items into target directory and sets up symlinks and permissions.
+ */
+export function copyTemplate(
+  targetDir: string,
+  templateDir?: string,
+  options?: CopyTemplateOptions
+): string[];
+
+/**
+ * Safely creates or updates a symbolic link, falling back to a file copy if symlinks are unsupported.
+ */
+export function ensureSymlink(
+  targetDir: string,
+  linkName: string,
+  targetFileName: string,
+  dryRun?: boolean
+): boolean;
+
+/**
+ * Detects whether linkName and targetFileName refer to the same entry on a case-insensitive filesystem.
+ */
+export function isSameCaseInsensitiveFile(
+  targetDir: string,
+  linkName: string,
+  targetFileName: string
+): boolean;
+
+/**
+ * Ensures all bash scripts in skill directories have executable permissions (0o755).
+ */
+export function makeScriptsExecutable(targetDir: string, dryRun?: boolean): string[];
+
+/**
+ * Initializes a git repository in the target directory if not already inside one.
+ */
+export function initGit(targetDir: string, options?: InitGitOptions): boolean;
+
+/**
+ * Returns the root path to the azcodr template files.
+ */
+export function getTemplateDir(): string;
+
+/**
+ * Array of essential template files and directories copied during scaffolding.
+ */
+export const TEMPLATE_ITEMS: readonly string[];
+
+declare const defaultExport: {
+  scaffold: typeof scaffold;
+  logChange: typeof logChange;
+  validateTarget: typeof validateTarget;
+  copyTemplate: typeof copyTemplate;
+  ensureSymlink: typeof ensureSymlink;
+  isSameCaseInsensitiveFile: typeof isSameCaseInsensitiveFile;
+  makeScriptsExecutable: typeof makeScriptsExecutable;
+  initGit: typeof initGit;
+  getTemplateDir: typeof getTemplateDir;
+  TEMPLATE_ITEMS: typeof TEMPLATE_ITEMS;
+};
+
+export default defaultExport;

package/lib/scaffold.js

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { execSync } = require('node:child_process');
+const cp = require('node:child_process');
 
 const TEMPLATE_ITEMS = [
   'AGENTS.md',
@@ -11,7 +11,8 @@ const TEMPLATE_ITEMS = [
   'README.md',
   'docs',
   '.agents',
-  '.gitignore'
+  '.gitignore',
+  '.editorconfig'
 ];
 
 /**
@@ -25,7 +26,7 @@ function getTemplateDir() {
  * Validates the target directory to ensure it is suitable for scaffolding.
  */
 function validateTarget(targetDir, options = {}) {
-  const { templateDir = getTemplateDir(), force = false } = options;
+  const { templateDir = getTemplateDir(), force = false, dryRun = false } = options;
   const resolvedTarget = path.resolve(targetDir);
   const resolvedTemplate = path.resolve(templateDir);
 
@@ -34,7 +35,9 @@ function validateTarget(targetDir, options = {}) {
   }
 
   if (!fs.existsSync(resolvedTarget)) {
-    fs.mkdirSync(resolvedTarget, { recursive: true });
+    if (!dryRun) {
+      fs.mkdirSync(resolvedTarget, { recursive: true });
+    }
     return;
   }
 
@@ -47,10 +50,35 @@ function validateTarget(targetDir, options = {}) {
   }
 }
 
+/**
+ * Detects whether linkName and targetFileName refer to the same entry on a case-insensitive filesystem.
+ */
+function isSameCaseInsensitiveFile(targetDir, linkName, targetFileName) {
+  if (linkName.toLowerCase() !== targetFileName.toLowerCase()) {
+    return false;
+  }
+  const targetPath = path.join(targetDir, targetFileName);
+  const linkPath = path.join(targetDir, linkName);
+  try {
+    if (fs.existsSync(targetPath) && fs.existsSync(linkPath)) {
+      return !fs.lstatSync(linkPath).isSymbolicLink();
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
 /**
  * Safely creates or updates a symbolic link, falling back to a file copy if symlinks are unsupported.
  */
-function ensureSymlink(targetDir, linkName, targetFileName) {
+function ensureSymlink(targetDir, linkName, targetFileName, dryRun = false) {
+  if (dryRun) return true;
+
+  if (isSameCaseInsensitiveFile(targetDir, linkName, targetFileName)) {
+    return true;
+  }
+
   const linkPath = path.join(targetDir, linkName);
   try {
     const stat = fs.lstatSync(linkPath);
@@ -63,21 +91,24 @@ function ensureSymlink(targetDir, linkName, targetFileName) {
 
   try {
     fs.symlinkSync(targetFileName, linkPath);
+    return true;
   } catch {
     // Fallback if environment (e.g., certain Windows configs) prevents symlink creation
     const sourceFile = path.join(targetDir, targetFileName);
     if (fs.existsSync(sourceFile)) {
       fs.copyFileSync(sourceFile, linkPath);
     }
+    return true;
   }
 }
 
 /**
  * Ensures all bash scripts in skill directories have executable permissions (0o755).
  */
-function makeScriptsExecutable(targetDir) {
+function makeScriptsExecutable(targetDir, dryRun = false) {
+  const modified = [];
   const skillsDir = path.join(targetDir, '.agents', 'skills');
-  if (!fs.existsSync(skillsDir)) return;
+  if (!fs.existsSync(skillsDir)) return modified;
 
   const skills = fs.readdirSync(skillsDir);
   for (const skill of skills) {
@@ -87,25 +118,31 @@ function makeScriptsExecutable(targetDir) {
       for (const file of files) {
         if (file.endsWith('.sh')) {
           const filePath = path.join(scriptsDir, file);
-          try {
-            fs.chmodSync(filePath, 0o755);
-          } catch {
-            // Non-critical if filesystem does not support POSIX permissions
+          modified.push(filePath);
+          if (!dryRun) {
+            try {
+              fs.chmodSync(filePath, 0o755);
+            } catch {
+              // Non-critical if filesystem does not support POSIX permissions
+            }
           }
         }
       }
     }
   }
+  return modified;
 }
 
 /**
  * Recursively copies template files into the target directory and sets up symlinks and permissions.
  */
-function copyTemplate(targetDir, templateDir = getTemplateDir()) {
+function copyTemplate(targetDir, templateDir = getTemplateDir(), options = {}) {
+  const { dryRun = false } = options;
   const resolvedTarget = path.resolve(targetDir);
   const resolvedTemplate = path.resolve(templateDir);
+  const actions = [];
 
-  if (!fs.existsSync(resolvedTarget)) {
+  if (!dryRun && !fs.existsSync(resolvedTarget)) {
     fs.mkdirSync(resolvedTarget, { recursive: true });
   }
 
@@ -114,29 +151,46 @@ function copyTemplate(targetDir, templateDir = getTemplateDir()) {
     if (!fs.existsSync(srcPath)) continue;
 
     const destPath = path.join(resolvedTarget, item);
-    fs.cpSync(srcPath, destPath, { recursive: true, force: true, dereference: false });
+    actions.push(`copy: ${item} -> ${destPath}`);
+
+    if (!dryRun) {
+      fs.cpSync(srcPath, destPath, { recursive: true, force: true, dereference: false });
+    }
   }
 
   // Ensure harness parity symlinks per AGENTS.md mandate
-  ensureSymlink(resolvedTarget, 'CLAUDE.md', 'AGENTS.md');
-  ensureSymlink(resolvedTarget, 'agents.md', 'AGENTS.md');
+  actions.push(`symlink: CLAUDE.md -> AGENTS.md`);
+  ensureSymlink(resolvedTarget, 'CLAUDE.md', 'AGENTS.md', dryRun);
+
+  actions.push(`symlink: agents.md -> AGENTS.md`);
+  ensureSymlink(resolvedTarget, 'agents.md', 'AGENTS.md', dryRun);
 
   // Ensure scripts are executable
-  makeScriptsExecutable(resolvedTarget);
+  const inspectDir = dryRun ? resolvedTemplate : resolvedTarget;
+  const scripts = makeScriptsExecutable(inspectDir, dryRun);
+  for (const script of scripts) {
+    actions.push(`chmod: +x ${path.relative(inspectDir, script)}`);
+  }
+
+  return actions;
 }
 
 /**
  * Initializes a git repository in the target directory if not already inside one.
  */
 function initGit(targetDir, options = {}) {
-  const { noGit = false } = options;
+  const { noGit = false, dryRun = false } = options;
   if (noGit) return false;
 
   const gitDir = path.join(targetDir, '.git');
   if (fs.existsSync(gitDir)) return false;
 
+  if (dryRun) {
+    return true;
+  }
+
   try {
-    execSync('git init -q', { cwd: targetDir, stdio: 'ignore' });
+    cp.execSync('git init -q', { cwd: targetDir, stdio: 'ignore' });
     return true;
   } catch {
     return false;
@@ -151,18 +205,25 @@ function scaffold(options = {}) {
     targetDir = process.cwd(),
     force = false,
     noGit = false,
-    templateDir = getTemplateDir()
+    templateDir = getTemplateDir(),
+    dryRun = false,
+    silent = false
   } = options;
 
   const resolvedTarget = path.resolve(targetDir);
-  validateTarget(resolvedTarget, { templateDir, force });
-  copyTemplate(resolvedTarget, templateDir);
-  const gitInitialized = initGit(resolvedTarget, { noGit });
+  validateTarget(resolvedTarget, { templateDir, force, dryRun });
+  const actions = copyTemplate(resolvedTarget, templateDir, { dryRun });
+  const gitInitialized = initGit(resolvedTarget, { noGit, dryRun });
+  if (gitInitialized) {
+    actions.push('git: initialize repository');
+  }
 
   return {
     success: true,
     targetDir: resolvedTarget,
-    gitInitialized
+    gitInitialized,
+    dryRun,
+    actions
   };
 }
 
@@ -216,6 +277,7 @@ module.exports = {
   validateTarget,
   copyTemplate,
   ensureSymlink,
+  isSameCaseInsensitiveFile,
   makeScriptsExecutable,
   initGit,
   getTemplateDir,

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "azcodr",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Enterprise Multi-Tenant Architecture & Agentic Engineering Starter Template",
   "bin": {
     "azcodr": "bin/azcodr.js"
   },
   "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin",
     "lib",
@@ -16,6 +24,7 @@
     "docs",
     ".agents",
     ".gitignore",
+    ".editorconfig",
     "LICENSE"
   ],
   "keywords": [
@@ -42,9 +51,10 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test tests/**/*.test.js",
-    "test:coverage": "node --test --experimental-test-coverage tests/**/*.test.js",
+    "test": "node --test",
+    "test:coverage": "node scripts/test_coverage.js",
+    "lint": "node --check bin/azcodr.js lib/index.js lib/scaffold.js tests/cli.test.js tests/scaffold.test.js scripts/test_coverage.js",
     "validate": "bash .agents/skills/agentic-architect/scripts/validate_agentic_configs.sh",
-    "prepublishOnly": "npm test && npm run validate"
+    "prepublishOnly": "npm run test:coverage && npm run validate"
   }
 }