azcodr 2.0.0 → 2.2.0

package/src/permissions.ts

@@ -0,0 +1,46 @@
+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).
+ *
+ * @param targetDir - Root directory containing .agents and skills.
+ * @param dryRun - When true, simulates permission changes without modifying disk.
+ * @returns Array of file paths that were modified or would be modified.
+ */
+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,104 @@
+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';
+
+/**
+ * Options controlling git repository initialization.
+ */
+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).
+ *
+ * @param targetDir - Directory path to inspect.
+ * @returns True if target directory is within a git worktree, false otherwise.
+ */
+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.
+ *
+ * @param targetDir - Directory where git repository should be initialized.
+ * @param options - Configuration options for git initialization.
+ * @returns True if repository was initialized and committed, false otherwise.
+ */
+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,282 @@
+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';
+
+/**
+ * Canonical list of template files and directories copied into a new workspace.
+ */
+export const TEMPLATE_ITEMS: readonly string[] = [
+  'AGENTS.md',
+  'memory.md',
+  'README.md',
+  'docs',
+  '.agents',
+  '.github',
+  'scripts',
+  '.gitignore',
+  '.editorconfig',
+  'LICENSE'
+];
+
+/**
+ * Configuration options for the primary scaffold orchestration function.
+ */
+export interface ScaffoldOptions {
+  targetDir?: string;
+  force?: boolean;
+  noGit?: boolean;
+  templateDir?: string;
+  dryRun?: boolean;
+  silent?: boolean;
+}
+
+/**
+ * Result object returned upon completion of a scaffold operation.
+ */
+export interface ScaffoldResult {
+  success: boolean;
+  targetDir: string;
+  gitInitialized: boolean;
+  dryRun: boolean;
+  actions: string[];
+}
+
+/**
+ * Options controlling pre-scaffold target directory validation.
+ */
+export interface ValidateTargetOptions {
+  templateDir?: string;
+  force?: boolean;
+  dryRun?: boolean;
+  allowProtected?: boolean;
+}
+
+/**
+ * Options controlling template file copying and file generation.
+ */
+export interface CopyTemplateOptions {
+  dryRun?: boolean;
+}
+
+/**
+ * Resolves the root filesystem directory of the azcodr template files.
+ *
+ * @returns Absolute filesystem path to the template root directory.
+ */
+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.
+ *
+ * @param targetDir - Target directory path to validate.
+ * @param options - Validation options including force, dry-run, and protected overrides.
+ * @throws {ScaffoldError} When target is invalid, protected, or non-empty without force.
+ */
+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': 'jest --coverage',
+      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).
+ *
+ * @param targetDir - Destination directory path.
+ * @param templateDir - Source template directory path.
+ * @param options - Copy options including dry-run flag.
+ * @returns Array of recorded scaffolding action descriptions.
+ */
+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.
+ *
+ * @param options - Scaffolding options.
+ * @returns Result object containing success flag, target directory, and action log.
+ */
+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/scripts/test_coverage.js

@@ -1,66 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-const { spawnSync } = require('node:child_process');
-
-// Native threshold flags and include filtering were added in Node v22.8.0.
-// Fail closed on older runtimes instead of silently passing without a gate.
-const [major, minor] = process.versions.node.split('.').map(Number);
-const supportsThresholds = major > 22 || (major === 22 && minor >= 8);
-if (!supportsThresholds) {
-  console.error(
-    `test:coverage requires Node >=22.8.0 for threshold enforcement (current: ${process.versions.node}). ` +
-    `Upgrade Node, or invoke the runner directly: node --test --experimental-test-coverage.`
-  );
-  process.exit(1);
-}
-
-const args = [
-  '--test',
-  '--experimental-test-coverage',
-  '--test-coverage-include=bin/**',
-  '--test-coverage-include=lib/**',
-  // Explicit file, not scripts/**: validate-cli.js is a two-line process entry
-  // that only runs when invoked directly, so it cannot be covered in-process.
-  // Every other script IS gated.
-  '--test-coverage-include=scripts/validate.js',
-  '--test-coverage-include=scripts/validate/io.js',
-  '--test-coverage-include=scripts/validate/text.js',
-  '--test-coverage-include=scripts/validate/parity.js',
-  '--test-coverage-include=scripts/validate/adr.js',
-  '--test-coverage-include=scripts/validate/root.js',
-  '--test-coverage-include=scripts/validate/rules.js',
-  '--test-coverage-include=scripts/validate/skills.js',
-  '--test-coverage-include=scripts/validate/links.js',
-  '--test-coverage-include=scripts/test_coverage.js',
-  // bin/, lib/ and test_coverage.js hold no environment-dependent defensive
-  // branches and are held at 100%. validate.js is a filesystem auditor: it
-  // contains fault handlers for conditions this host cannot produce (creating
-  // symlinks requires Developer Mode; a RangeError needs a tree thousands of
-  // levels deep). Those are exercised by tests/validate-faults.test.js where
-  // the fault can be injected, so the gate here is deliberately lower rather
-  // than silently passing.
-  '--test-coverage-branches=98',
-  '--test-coverage-functions=97',
-  '--test-coverage-lines=100'
-];
-
-const result = spawnSync(process.execPath, args, {
-  stdio: 'inherit',
-  env: process.env
-});
-
-if (result.error) {
-  console.error(result.error);
-  process.exit(1);
-}
-
-// A null status means the child was killed by a signal (OOM, SIGKILL from a
-// runner timeout). `status ?? 0` reported success for a crashed runner, which
-// is how a green build can carry zero coverage data.
-if (result.signal) {
-  console.error(`test runner terminated by signal ${result.signal}; coverage gate could not be evaluated.`);
-  process.exit(1);
-}
-
-process.exit(result.status ?? 1);