azcodr 1.5.2 → 2.1.0

package/src/links.ts

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface EnsureSymlinkOptions {
+  targetDir: string;
+  linkName: string;
+  targetFileName: string;
+  dryRun?: boolean;
+}
+
+interface BothEntriesExistOptions {
+  targetDir: string;
+  linkName: string;
+  targetFileName: string;
+  entries: readonly string[];
+}
+
+function namesDifferOnlyByCase(linkName: string, targetFileName: string): boolean {
+  if (linkName.toLowerCase() !== targetFileName.toLowerCase()) return false;
+  return linkName !== targetFileName;
+}
+
+function readDirEntries(targetDir: string): string[] | null {
+  try {
+    return fs.readdirSync(targetDir);
+  } catch {
+    return null;
+  }
+}
+
+function bothEntriesExist(options: BothEntriesExistOptions): boolean {
+  const { targetDir, linkName, targetFileName, entries } = options;
+  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: string, linkPath: string): boolean {
+  if (!fs.existsSync(targetPath) || !fs.existsSync(linkPath)) return false;
+  try {
+    fs.lstatSync(targetPath);
+    fs.lstatSync(linkPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function removeIfExists(linkPath: string): void {
+  try {
+    fs.lstatSync(linkPath);
+    fs.rmSync(linkPath, { force: true });
+  } catch {
+    // Path does not exist, proceed
+  }
+}
+
+function copyFallback(targetDir: string, linkName: string, targetFileName: string): void {
+  const sourceFile = path.resolve(targetDir, targetFileName);
+  if (fs.existsSync(sourceFile)) {
+    fs.copyFileSync(sourceFile, path.join(targetDir, linkName));
+  }
+}
+
+/**
+ * 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).
+ */
+export function isSameCaseInsensitiveFile(
+  targetDir: string,
+  linkName: string,
+  targetFileName: string
+): boolean {
+  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);
+}
+
+/**
+ * Safely creates or updates a symbolic link, falling back to a file copy if symlinks are unsupported.
+ */
+export function ensureSymlink(options: EnsureSymlinkOptions): boolean {
+  const { targetDir, linkName, targetFileName, dryRun = false } = options;
+  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).
+ */
+export function ensureSymlinkOrPointer(options: EnsureSymlinkOptions): boolean {
+  const { targetDir, linkName, targetFileName, dryRun = false } = options;
+  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;
+  }
+}
+
+export default {
+  isSameCaseInsensitiveFile,
+  ensureSymlink,
+  ensureSymlinkOrPointer
+};

package/src/permissions.ts

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function chmodShFile(filePath: string, dryRun: boolean): void {
+  if (dryRun) return;
+  try {
+    fs.chmodSync(filePath, 0o755);
+  } catch {
+    // Non-critical if filesystem does not support POSIX permissions
+  }
+}
+
+function chmodShFilesIn(scriptsDir: string, dryRun: boolean): string[] {
+  const modified: string[] = [];
+  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).
+ */
+export function makeScriptsExecutable(targetDir: string, dryRun = false): string[] {
+  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;
+}
+
+export default { makeScriptsExecutable };

package/src/repo.ts

@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runGit } from './git.js';
+
+const INITIAL_COMMIT_MESSAGE = 'chore: initial scaffold from azcodr template';
+
+export interface InitGitOptions {
+  noGit?: boolean;
+  dryRun?: boolean;
+}
+
+/**
+ * Detects whether targetDir is already inside an existing Git worktree.
+ * Socket note: shell access is limited to `git rev-parse` via runGit (no shell).
+ */
+export function isInsideGitWorkTree(targetDir: string): boolean {
+  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: string): void {
+  try {
+    runGit(['branch', '-m', 'main'], { cwd: targetDir, stdio: 'ignore' });
+  } catch {
+    // Non-critical if branch rename fails
+  }
+}
+
+function initRepository(targetDir: string): void {
+  try {
+    runGit(['init', '-b', 'main', '-q'], { cwd: targetDir, stdio: 'ignore' });
+  } catch {
+    runGit(['init', '-q'], { cwd: targetDir, stdio: 'ignore' });
+    renameBranchMain(targetDir);
+  }
+}
+
+function commitWithFallbackIdentity(targetDir: string): void {
+  const options = { cwd: targetDir, stdio: 'ignore' as const };
+  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: string): void {
+  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.
+ */
+export function initGit(targetDir: string, options: InitGitOptions = {}): boolean {
+  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;
+  }
+}
+
+export default { isInsideGitWorkTree, initGit };

package/src/scaffold.ts

@@ -0,0 +1,273 @@
+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 { 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 const TEMPLATE_ITEMS: readonly string[] = [
+  'AGENTS.md',
+  'memory.md',
+  'README.md',
+  'docs',
+  '.agents',
+  '.github',
+  'scripts',
+  '.gitignore',
+  '.editorconfig',
+  'LICENSE'
+];
+
+export interface ScaffoldOptions {
+  targetDir?: string;
+  force?: boolean;
+  noGit?: boolean;
+  templateDir?: string;
+  dryRun?: boolean;
+  silent?: boolean;
+}
+
+export interface ScaffoldResult {
+  success: boolean;
+  targetDir: string;
+  gitInitialized: boolean;
+  dryRun: boolean;
+  actions: string[];
+}
+
+export interface ValidateTargetOptions {
+  templateDir?: string;
+  force?: boolean;
+  dryRun?: boolean;
+  allowProtected?: boolean;
+}
+
+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;
+  throw new ScaffoldError(
+    'E_TARGET_IS_TEMPLATE',
+    `${ERROR_CODES.E_TARGET_IS_TEMPLATE}: ${resolvedTarget}`
+  );
+}
+
+function rejectProtectedTarget(
+  resolvedTarget: string,
+  templateDir: string,
+  allowProtected: boolean
+): void {
+  if (allowProtected) return;
+  if (!isProtectedTarget(resolvedTarget, { templateDir })) return;
+  throw new ScaffoldError(
+    'E_TARGET_IS_PROTECTED',
+    `${ERROR_CODES.E_TARGET_IS_PROTECTED}: ${resolvedTarget}. ` +
+    'Scaffolding there would overwrite personal or system files. Choose a project subdirectory instead.'
+  );
+}
+
+function rejectNonEmptyTarget(resolvedTarget: string, force: boolean): void {
+  const entries = fs.readdirSync(resolvedTarget);
+  if (entries.length === 0 || force) return;
+  throw new ScaffoldError(
+    'E_TARGET_NOT_EMPTY',
+    `${ERROR_CODES.E_TARGET_NOT_EMPTY} (${entries.length} items found: ${resolvedTarget}). ` +
+    'Use --force to overwrite existing files.'
+  );
+}
+
+/**
+ * Validates the target directory to ensure it is suitable for scaffolding.
+ */
+export function validateTarget(targetDir: string, options: ValidateTargetOptions = {}): void {
+  const { templateDir = getTemplateDir(), force = false, dryRun = false, allowProtected = false } = options;
+  const resolvedTarget = path.resolve(targetDir);
+  const resolvedTemplate = path.resolve(templateDir);
+  rejectTemplateSelf(resolvedTarget, resolvedTemplate);
+  rejectProtectedTarget(resolvedTarget, templateDir, allowProtected);
+  if (!fs.existsSync(resolvedTarget)) {
+    if (!dryRun) fs.mkdirSync(resolvedTarget, { recursive: true });
+    return;
+  }
+  rejectNonEmptyTarget(resolvedTarget, force);
+}
+
+function resolveTemplateItem(resolvedTemplate: string, item: string): string {
+  let srcPath = path.join(resolvedTemplate, item);
+  if (item === '.gitignore' && !fs.existsSync(srcPath)) {
+    const npmIgnorePath = path.join(resolvedTemplate, '.npmignore');
+    if (fs.existsSync(npmIgnorePath)) srcPath = npmIgnorePath;
+  }
+  return srcPath;
+}
+
+function copyTemplateItems(resolvedTarget: string, resolvedTemplate: string, dryRun: boolean): string[] {
+  const actions: string[] = [];
+  for (const item of TEMPLATE_ITEMS) {
+    const srcPath = resolveTemplateItem(resolvedTemplate, item);
+    if (!fs.existsSync(srcPath)) continue;
+    const destPath = path.join(resolvedTarget, item);
+    assertInside(resolvedTemplate, srcPath);
+    assertInside(resolvedTarget, destPath);
+    actions.push(`copy: ${item} -> ${destPath}`);
+    if (!dryRun) fs.cpSync(srcPath, destPath, { recursive: true, force: true, dereference: false });
+  }
+  return actions;
+}
+
+function ensureHarnessParity(resolvedTarget: string, dryRun: boolean): string[] {
+  const links: readonly [string, string][] = [
+    ['CLAUDE.md', 'AGENTS.md'],
+    ['agents.md', 'AGENTS.md'],
+    ['GEMINI.md', 'AGENTS.md'],
+    ['.cursorrules', 'AGENTS.md'],
+    ['.windsurfrules', 'AGENTS.md']
+  ];
+  const actions: string[] = [];
+  for (const [linkName, targetFileName] of links) {
+    actions.push(`symlink: ${linkName} -> ${targetFileName}`);
+    ensureSymlink({ targetDir: resolvedTarget, linkName, targetFileName, dryRun });
+  }
+  return actions;
+}
+
+function ensureCopilotParity(resolvedTarget: string, dryRun: boolean): string[] {
+  const githubDir = path.join(resolvedTarget, '.github');
+  if (!dryRun && !fs.existsSync(githubDir)) fs.mkdirSync(githubDir, { recursive: true });
+  ensureSymlinkOrPointer({
+    targetDir: githubDir,
+    linkName: 'copilot-instructions.md',
+    targetFileName: '../AGENTS.md',
+    dryRun
+  });
+  return ['symlink: .github/copilot-instructions.md -> ../AGENTS.md'];
+}
+
+function starterPackageJson(resolvedTarget: string): Record<string, unknown> {
+  const projectName = path.basename(resolvedTarget) || 'my-project';
+  return {
+    name: projectName,
+    version: '0.1.0',
+    type: 'module',
+    private: true,
+    description: 'Scaffolded with azcodr enterprise architecture template',
+    scripts: {
+      test: 'node --test',
+      'test:coverage': 'node scripts/test_coverage.js',
+      lint: 'echo "No linter configured yet. Run /lets-build to configure toolchain."',
+      validate: 'node scripts/validate-cli.js'
+    }
+  };
+}
+
+function ensureStarterPackageJson(resolvedTarget: string, dryRun: boolean): string[] {
+  const pkgJsonPath = path.join(resolvedTarget, 'package.json');
+  if (fs.existsSync(pkgJsonPath)) return [];
+  if (dryRun) return ['create: package.json'];
+  const starterPkg = starterPackageJson(resolvedTarget);
+  fs.writeFileSync(pkgJsonPath, JSON.stringify(starterPkg, null, 2) + '\n', 'utf-8');
+  return ['create: package.json'];
+}
+
+function chmodTemplateScripts(inspectDir: string, dryRun: boolean): string[] {
+  const actions: string[] = [];
+  const scripts = makeScriptsExecutable(inspectDir, dryRun);
+  for (const script of scripts) {
+    actions.push(`chmod: +x ${path.relative(inspectDir, script)}`);
+  }
+  return actions;
+}
+
+/**
+ * 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).
+ */
+export function copyTemplate(
+  targetDir: string,
+  templateDir: string = getTemplateDir(),
+  options: CopyTemplateOptions = {}
+): string[] {
+  const { dryRun = false } = options;
+  const resolvedTarget = path.resolve(targetDir);
+  const resolvedTemplate = path.resolve(templateDir);
+  if (!dryRun && !fs.existsSync(resolvedTarget)) {
+    fs.mkdirSync(resolvedTarget, { recursive: true });
+  }
+  const actions = copyTemplateItems(resolvedTarget, resolvedTemplate, dryRun);
+  actions.push(...ensureHarnessParity(resolvedTarget, dryRun));
+  actions.push(...ensureCopilotParity(resolvedTarget, dryRun));
+  actions.push(...ensureStarterPackageJson(resolvedTarget, dryRun));
+  const inspectDir = dryRun ? resolvedTemplate : resolvedTarget;
+  actions.push(...chmodTemplateScripts(inspectDir, dryRun));
+  return actions;
+}
+
+/**
+ * High-level orchestration function to scaffold the azcodr workspace into targetDir.
+ */
+export function scaffold(options: ScaffoldOptions = {}): ScaffoldResult {
+  const {
+    targetDir = process.cwd(),
+    force = false,
+    noGit = false,
+    templateDir = getTemplateDir(),
+    dryRun = false
+  } = options;
+  const resolvedTarget = path.resolve(targetDir);
+  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, dryRun, actions };
+}
+
+export {
+  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
+};

package/.github/copilot-instructions.md

@@ -1 +0,0 @@
-../AGENTS.md