azcodr 1.5.1 → 2.0.0

package/lib/index.d.ts

@@ -1,134 +1,199 @@
-/**
- * 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 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;
-
-/**
- * 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;
-
-/**
- * Creates a symlink, falling back to a text pointer (not a full copy).
- */
-export function ensureSymlinkOrPointer(
-  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;
-  validateTarget: typeof validateTarget;
-  copyTemplate: typeof copyTemplate;
-  ensureSymlink: typeof ensureSymlink;
-  ensureSymlinkOrPointer: typeof ensureSymlinkOrPointer;
-  isSameCaseInsensitiveFile: typeof isSameCaseInsensitiveFile;
-  makeScriptsExecutable: typeof makeScriptsExecutable;
-  initGit: typeof initGit;
-  getTemplateDir: typeof getTemplateDir;
-  TEMPLATE_ITEMS: typeof TEMPLATE_ITEMS;
-};
-
-export default defaultExport;
+/**
+ * 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 ValidateTargetOptions {
+  /** Custom template root directory */
+  templateDir?: string;
+  /** Force allow non-empty directory */
+  force?: boolean;
+  /**
+   * Bypass the protected-target guard (filesystem root, home, home's parent,
+   * template ancestors). The CLI never passes this. Programmatic use only.
+   */
+  allowProtected?: 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;
+}
+
+/**
+ * Machine-readable failure codes thrown by this library.
+ *
+ * Branch on `error.code`, never on `error.message`: message wording may change
+ * between releases, codes are part of the public contract.
+ */
+export type ScaffoldErrorCode =
+  | 'E_TARGET_IS_TEMPLATE'
+  | 'E_TARGET_NOT_EMPTY'
+  | 'E_TARGET_IS_PROTECTED'
+  | 'E_GIT_ARGS_INVALID'
+  | 'E_GIT_BLOCKED'
+  | 'E_PATH_ESCAPE';
+
+/** Error type thrown by every azcodr API. Always carries a `code`. */
+export interface ScaffoldErrorShape extends Error {
+  name: 'ScaffoldError';
+  code: ScaffoldErrorCode;
+}
+
+export declare class ScaffoldError extends Error implements ScaffoldErrorShape {
+  constructor(code: ScaffoldErrorCode, message: string);
+  name: 'ScaffoldError';
+  code: ScaffoldErrorCode;
+}
+
+/** Human-readable prefix for each code, as thrown. */
+export declare const ERROR_CODES: Readonly<Record<ScaffoldErrorCode, string>>;
+
+/**
+ * High-level orchestration function to scaffold the azcodr workspace into targetDir.
+ */
+export function scaffold(options?: ScaffoldOptions): ScaffoldResult;
+
+/**
+ * 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(options: {
+  targetDir: string;
+  linkName: string;
+  targetFileName: string;
+  dryRun?: boolean;
+}): boolean;
+
+/**
+ * Creates a symlink, falling back to a text pointer (not a full copy).
+ */
+export function ensureSymlinkOrPointer(options: {
+  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;
+
+/**
+ * Detects whether targetDir is already inside an existing Git worktree.
+ * Shell access is limited to `git rev-parse` via a shell-free allowlisted spawn.
+ */
+export function isInsideGitWorkTree(targetDir: string): boolean;
+
+/**
+ * Spawns `git` with argv (never a shell string) through an explicit
+ * subcommand allowlist. @throws ScaffoldError with E_GIT_ARGS_INVALID or E_GIT_BLOCKED.
+ */
+export function runGit(args: string[], options?: Record<string, unknown>): string;
+
+/**
+ * Scope guard: throws if `candidate` resolves outside `root`.
+ * @throws ScaffoldError with E_PATH_ESCAPE.
+ */
+export function assertInside(root: string, candidate: string, message?: string): void;
+
+/**
+ * Returns true when `targetDir` is a protected system location the scaffolder
+ * must never write into (filesystem root, home, home's parent, template
+ * ancestors, symlink aliases). @throws never; pure predicate.
+ */
+export function isProtectedTarget(targetDir: string, options?: ValidateTargetOptions): 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;
+  validateTarget: typeof validateTarget;
+  copyTemplate: typeof copyTemplate;
+  ensureSymlink: typeof ensureSymlink;
+  ensureSymlinkOrPointer: typeof ensureSymlinkOrPointer;
+  isSameCaseInsensitiveFile: typeof isSameCaseInsensitiveFile;
+  makeScriptsExecutable: typeof makeScriptsExecutable;
+  initGit: typeof initGit;
+  isInsideGitWorkTree: typeof isInsideGitWorkTree;
+  runGit: typeof runGit;
+  assertInside: typeof assertInside;
+  isProtectedTarget: typeof isProtectedTarget;
+  getTemplateDir: typeof getTemplateDir;
+  TEMPLATE_ITEMS: typeof TEMPLATE_ITEMS;
+  ScaffoldError: typeof ScaffoldError;
+  ERROR_CODES: typeof ERROR_CODES;
+};
+
+export default defaultExport;

package/lib/index.js

@@ -1,5 +1,5 @@
-'use strict';
-
-const scaffold = require('./scaffold.js');
-
-module.exports = scaffold;
+'use strict';
+
+const scaffold = require('./scaffold.js');
+
+module.exports = scaffold;

package/lib/links.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * 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).
+ */
+function namesDifferOnlyByCase(linkName, targetFileName) {
+  if (linkName.toLowerCase() !== targetFileName.toLowerCase()) return false;
+  return linkName !== targetFileName;
+}
+
+function readDirEntries(targetDir) {
+  try {
+    return fs.readdirSync(targetDir);
+  } catch {
+    return null;
+  }
+}
+
+function bothEntriesExist({ targetDir, linkName, targetFileName, entries }) {
+  if (!entries.includes(targetFileName) || !entries.includes(linkName)) return false;
+  try {
+    fs.lstatSync(path.join(targetDir, targetFileName));
+    fs.lstatSync(path.join(targetDir, linkName));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function accessiblePair(targetPath, linkPath) {
+  // Case-insensitive collision: the listing holds one spelling while both
+  // paths resolve. Verify the entries are accessible (throws on disk error).
+  if (!fs.existsSync(targetPath) || !fs.existsSync(linkPath)) return false;
+  try {
+    fs.lstatSync(targetPath);
+    fs.lstatSync(linkPath);
+  } catch {
+    return false;
+  }
+  return true;
+}
+
+function isSameCaseInsensitiveFile(targetDir, linkName, targetFileName) {
+  if (linkName === targetFileName) return true;
+  if (!namesDifferOnlyByCase(linkName, targetFileName)) return false;
+  const entries = readDirEntries(targetDir);
+  if (entries === null) return false;
+  if (bothEntriesExist({ targetDir, linkName, targetFileName, entries })) {
+    return !fs.lstatSync(path.join(targetDir, linkName)).isSymbolicLink();
+  }
+  const targetPath = path.join(targetDir, targetFileName);
+  const linkPath = path.join(targetDir, linkName);
+  return accessiblePair(targetPath, linkPath);
+}
+
+function removeIfExists(linkPath) {
+  try {
+    fs.lstatSync(linkPath);
+    fs.rmSync(linkPath, { force: true });
+  } catch {
+    // Path does not exist, proceed
+  }
+}
+
+function copyFallback(targetDir, linkName, targetFileName) {
+  // Fallback if environment (e.g., certain Windows configs) prevents symlink creation
+  const sourceFile = path.resolve(targetDir, targetFileName);
+  if (fs.existsSync(sourceFile)) {
+    fs.copyFileSync(sourceFile, path.join(targetDir, linkName));
+  }
+}
+
+/**
+ * Safely creates or updates a symbolic link, falling back to a file copy if symlinks are unsupported.
+ */
+function ensureSymlink({ targetDir, linkName, targetFileName, dryRun = false }) {
+  if (dryRun) return true;
+  if (isSameCaseInsensitiveFile(targetDir, linkName, targetFileName)) return true;
+  const linkPath = path.join(targetDir, linkName);
+  removeIfExists(linkPath);
+  try {
+    fs.symlinkSync(targetFileName, linkPath, 'file');
+    return true;
+  } catch {
+    copyFallback(targetDir, linkName, targetFileName);
+    return true;
+  }
+}
+
+/**
+ * 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).
+ */
+function ensureSymlinkOrPointer({ targetDir, linkName, targetFileName, dryRun = false }) {
+  if (dryRun) return true;
+  const linkPath = path.join(targetDir, linkName);
+  try {
+    try {
+      fs.lstatSync(linkPath);
+      const existing = fs.existsSync(linkPath) ? fs.readFileSync(linkPath, 'utf-8') : '';
+      if (existing.trim() === targetFileName) return true;
+      fs.rmSync(linkPath, { force: true });
+    } catch {
+      // Path does not exist, proceed
+    }
+    fs.symlinkSync(targetFileName, linkPath, 'file');
+    return true;
+  } catch {
+    fs.writeFileSync(linkPath, `${targetFileName}\n`, 'utf-8');
+    return true;
+  }
+}
+
+module.exports = {
+  isSameCaseInsensitiveFile,
+  ensureSymlink,
+  ensureSymlinkOrPointer
+};

package/lib/permissions.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function chmodShFile(filePath, dryRun) {
+  if (dryRun) return;
+  try {
+    fs.chmodSync(filePath, 0o755);
+  } catch {
+    // Non-critical if filesystem does not support POSIX permissions
+  }
+}
+
+function chmodShFilesIn(scriptsDir, dryRun) {
+  const modified = [];
+  if (!fs.existsSync(scriptsDir) || !fs.statSync(scriptsDir).isDirectory()) return modified;
+  const files = fs.readdirSync(scriptsDir);
+  for (const file of files) {
+    if (!file.endsWith('.sh')) continue;
+    const filePath = path.join(scriptsDir, file);
+    modified.push(filePath);
+    chmodShFile(filePath, dryRun);
+  }
+  return modified;
+}
+
+/**
+ * Ensures all bash scripts in agent and skill directories have executable permissions (0o755).
+ */
+function makeScriptsExecutable(targetDir, dryRun = false) {
+  const agentScriptsDir = path.join(targetDir, '.agents', 'scripts');
+  const modified = chmodShFilesIn(agentScriptsDir, dryRun);
+  const skillsDir = path.join(targetDir, '.agents', 'skills');
+  if (!fs.existsSync(skillsDir)) return modified;
+  const skills = fs.readdirSync(skillsDir);
+  for (const skill of skills) {
+    const scriptsDir = path.join(skillsDir, skill, 'scripts');
+    modified.push(...chmodShFilesIn(scriptsDir, dryRun));
+  }
+  return modified;
+}
+
+module.exports = { makeScriptsExecutable };

package/lib/repo.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { runGit } = require('./git.js');
+
+const INITIAL_COMMIT_MESSAGE = 'chore: initial scaffold from azcodr template';
+
+/**
+ * Detects whether targetDir is already inside an existing Git worktree.
+ * Socket note: shell access is limited to `git rev-parse` via runGit (no shell).
+ */
+function isInsideGitWorkTree(targetDir) {
+  try {
+    const checkDir = fs.existsSync(targetDir) ? targetDir : path.dirname(targetDir);
+    const out = runGit(['rev-parse', '--is-inside-work-tree'], {
+      cwd: checkDir,
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    return String(out).trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+
+function renameBranchMain(targetDir) {
+  try {
+    runGit(['branch', '-m', 'main'], { cwd: targetDir, stdio: 'ignore' });
+  } catch {
+    // Non-critical if branch rename fails
+  }
+}
+
+function initRepository(targetDir) {
+  try {
+    runGit(['init', '-b', 'main', '-q'], { cwd: targetDir, stdio: 'ignore' });
+  } catch {
+    runGit(['init', '-q'], { cwd: targetDir, stdio: 'ignore' });
+    renameBranchMain(targetDir);
+  }
+}
+
+function commitWithFallbackIdentity(targetDir) {
+  const options = { cwd: targetDir, stdio: 'ignore' };
+  try {
+    runGit(['commit', '-q', '-m', INITIAL_COMMIT_MESSAGE], options);
+  } catch {
+    runGit(['commit', '-q', '-m', INITIAL_COMMIT_MESSAGE], {
+      ...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'
+      }
+    });
+  }
+}
+
+function initialCommit(targetDir) {
+  try {
+    runGit(['add', '-A'], { cwd: targetDir, stdio: 'ignore' });
+    commitWithFallbackIdentity(targetDir);
+  } catch {
+    // Non-critical if initial commit fails
+  }
+}
+
+/**
+ * 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.
+ */
+function initGit(targetDir, options = {}) {
+  const { noGit = false, dryRun = false } = options;
+  if (noGit) return false;
+  const gitDir = path.join(targetDir, '.git');
+  if (fs.existsSync(gitDir)) return false;
+  if (isInsideGitWorkTree(targetDir)) return false;
+  if (dryRun) return true;
+  try {
+    initRepository(targetDir);
+    initialCommit(targetDir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { isInsideGitWorkTree, initGit };