azcodr 1.0.1 → 1.2.0

package/docs/rules/workflow_state_machines.md

@@ -98,21 +98,3 @@ Every state change across any entity or workflow MUST be immutably recorded in a
 | `reason` | String? | Optional justification or audit comment. |
 | `metadata` | JSON? | Snapshot of transition context or rule evaluation. |
 | `createdAt` | DateTime | Immutable timestamp of transition. |
-
----
-
-## 4. Invariants (DO's & DONT's)
-
-### DO
-- **DO** enforce core business invariants inside Aggregate Roots using strongly-typed state transitions.
-- **DO** decouple core domain state from operational display stages or tenant-specific sub-statuses.
-- **DO** use non-Turing complete expression languages (CEL) to evaluate dynamic transition guards.
-- **DO** maintain an immutable transition history table for all status alterations.
-- **DO** validate state transition graphs at creation time to prevent dead-end or unreachable states.
-
-### DONT
-- **DONT** make financial or legal integrity states (e.g., `SETTLED`, `CANCELLED`, `REFUNDED`) freely rewritable by tenant configuration.
-- **DONT** expose generic status setters (`entity.setStatus(newStatus)`) on domain models.
-- **DONT** execute untrusted scripts or dynamic strings in the host runtime for workflow evaluations.
-- **DONT** allow a workflow orchestrator to bypass aggregate invariants by directly updating database columns.
-- **DONT** delete historical state transitions; status audit logs must be append-only.

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,