azcodr 2.0.0 → 2.2.0

package/src/cli.ts

@@ -0,0 +1,240 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { scaffold, getTemplateDir } from './scaffold.js';
+import type { ScaffoldOptions, ScaffoldResult } from './scaffold.js';
+import { parseArgs } from './cli-parse.js';
+import type { CliParsedOptions } from './cli-parse.js';
+import { askQuestion, resolveTargetDir, ensureWritableTarget } from './cli-target.js';
+
+interface PackageJsonShape {
+  version: string;
+}
+
+const pkg: PackageJsonShape = JSON.parse(
+  fs.readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'),
+    'utf-8'
+  )
+);
+
+export function printHelp(out: (msg: string) => void = console.log): void {
+  out(`
+azcodr v${pkg.version}
+Enterprise Multi-Tenant Architecture & Agentic Engineering Starter Template
+
+Usage:
+  npx azcodr [directory] [options]
+
+Commands:
+  [directory]     Scaffold azcodr template into directory (default: current directory)
+
+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
+
+Examples:
+  npx azcodr my-project
+  npx azcodr . --dry-run
+  npx azcodr . --force
+`);
+}
+
+export function printVersion(out: (msg: string) => void = console.log): void {
+  out(pkg.version);
+}
+
+export interface CliIo {
+  out?: (msg: string) => void;
+  err?: (msg: string) => void;
+  exit?: (code: number) => void | number;
+  stdin?: NodeJS.ReadableStream & { isTTY?: boolean };
+  stdout?: NodeJS.WritableStream;
+  cwd?: string;
+  templateDir?: string;
+  scaffold?: (options?: ScaffoldOptions) => ScaffoldResult;
+}
+
+export interface NormalizedCliIo {
+  out: (msg: string) => void;
+  err: (msg: string) => void;
+  exit: (code: number) => void | number;
+  stdin: NodeJS.ReadableStream & { isTTY?: boolean };
+  stdout: NodeJS.WritableStream;
+  cwd: string;
+  templateDir: string;
+  scaffoldFn: (options?: ScaffoldOptions) => ScaffoldResult;
+}
+
+function normalizeIo(io: CliIo = {}): NormalizedCliIo {
+  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;
+  return { out, err, exit, stdin, stdout, cwd, templateDir, scaffoldFn };
+}
+
+function outBanner(fullIo: NormalizedCliIo): void {
+  fullIo.out('\n🚀 azcodr - Enterprise Multi-Tenant Architecture & Agentic Engineering\n');
+}
+
+function handleTerminal(parsed: CliParsedOptions, io: NormalizedCliIo): void | number {
+  const { out, err, exit } = io;
+  if (parsed.terminal === 'help') {
+    printHelp(out);
+    return exit(0);
+  }
+  if (parsed.terminal === 'version') {
+    printVersion(out);
+    return exit(0);
+  }
+  err(`❌ Error: ${parsed.message}`);
+  return exit(1);
+}
+
+function reportDryRun(result: ScaffoldResult, out: (msg: string) => void): void {
+  for (const action of result.actions) {
+    out(`  [preview] ${action}`);
+  }
+  out('\n🎉 Dry run completed. 0 files modified on disk.\n');
+}
+
+function reportSuccess(result: ScaffoldResult, targetDir: string | null, out: (msg: string) => void): void {
+  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('  ✅ Editor formatting standards initialized (.editorconfig)');
+  out('  ✅ Agent directives and harness symlinks established (AGENTS.md, CLAUDE.md, agents.md, GEMINI.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md)');
+  out('  ✅ Project configuration initialized (package.json)');
+  if (result.gitInitialized) {
+    out('  ✅ Git repository initialized');
+  }
+  out('\n🎉 azcodr initialized successfully!\n');
+  out('Next steps:');
+  let step = 1;
+  if (targetDir !== '.' && targetDir !== './') {
+    out(`  ${step++}. cd ${targetDir}`);
+  }
+  out(`  ${step++}. Open the project in your AI coding assistant (Antigravity, Claude Code, Cursor, OpenHands)`);
+  out(`  ${step++}. Run /lets-build to start the architectural interview and scaffold your application stack!\n`);
+}
+
+function runScaffold(resolvedTarget: string, parsed: CliParsedOptions, io: NormalizedCliIo): void | number {
+  const { out, err, exit, templateDir, scaffoldFn } = io;
+  const banner = parsed.dryRun
+    ? `🔍 DRY RUN: Simulating azcodr scaffolding into: ${resolvedTarget}\n`
+    : `📦 Scaffolding azcodr into: ${resolvedTarget}`;
+  if (!parsed.silent) out(banner);
+  try {
+    const result = scaffoldFn({
+      targetDir: resolvedTarget,
+      force: parsed.force,
+      noGit: parsed.noGit,
+      templateDir,
+      dryRun: parsed.dryRun,
+      silent: parsed.silent
+    });
+    if (!parsed.silent) {
+      if (parsed.dryRun) reportDryRun(result, out);
+      else reportSuccess(result, parsed.targetDir, out);
+    }
+    return exit(0);
+  } catch (error) {
+    err(`\n❌ Scaffolding failed: ${(error as Error).message}\n`);
+    return exit(1);
+  }
+}
+
+interface ResolvePhaseResult {
+  resolvedTarget?: string;
+  chosen?: string;
+  exitCode?: number;
+}
+
+async function resolvePhase(parsed: CliParsedOptions, fullIo: NormalizedCliIo): Promise<ResolvePhaseResult> {
+  const { resolvedTarget, chosen, error } = await resolveTargetDir(parsed.targetDir, fullIo);
+  if (error !== null) {
+    fullIo.err(`❌ Error: ${error}`);
+    return { exitCode: 1 };
+  }
+  return { resolvedTarget, chosen };
+}
+
+interface WritablePhaseResult {
+  force?: boolean;
+  exitCode?: number;
+}
+
+async function writablePhase(
+  target: { chosen: string; resolvedTarget: string },
+  force: boolean,
+  fullIo: NormalizedCliIo
+): Promise<WritablePhaseResult> {
+  const writable = await ensureWritableTarget({
+    chosen: target.chosen,
+    resolvedTarget: target.resolvedTarget,
+    force,
+    io: fullIo
+  });
+  if (writable.exitCode === undefined) return { force: writable.force };
+  if (writable.message) {
+    fullIo.err(`❌ Error: ${writable.message}`);
+  }
+  return { exitCode: writable.exitCode };
+}
+
+export async function runCli(
+  rawArgs: string[] = process.argv.slice(2),
+  io: CliIo = {}
+): Promise<void | number> {
+  const fullIo = normalizeIo(io);
+
+  const parsed = parseArgs(rawArgs);
+  if (parsed.terminal !== null) return handleTerminal(parsed, fullIo);
+
+  if (!parsed.silent) {
+    outBanner(fullIo);
+  }
+
+  const target = await resolvePhase(parsed, fullIo);
+  if (target.exitCode !== undefined) return fullIo.exit(target.exitCode);
+
+  const ready = await writablePhase(
+    target as { chosen: string; resolvedTarget: string },
+    parsed.force,
+    fullIo
+  );
+  if (ready.exitCode !== undefined) return fullIo.exit(ready.exitCode);
+
+  return runScaffold(target.resolvedTarget!, { ...parsed, force: ready.force! }, fullIo);
+}
+
+export async function main(): Promise<void> {
+  try {
+    await runCli(process.argv.slice(2));
+  } catch (err) {
+    console.error('Unexpected error:', err);
+    process.exit(1);
+  }
+}
+
+export { askQuestion };
+
+export default {
+  runCli,
+  main,
+  printHelp,
+  printVersion,
+  askQuestion
+};

package/src/errors.ts

@@ -0,0 +1,50 @@
+/**
+ * Machine-readable failure codes.
+ *
+ * Consumers branch on `err.code`, never on message text: a wording change must
+ * never be a breaking change (learned from typed-settings, where `docs/errors.md`
+ * explicitly tells users not to regex the message). Pinned by
+ * tests/error-codes.test.js.
+ */
+export const ERROR_CODES = {
+  E_TARGET_IS_TEMPLATE: 'Cannot scaffold into the azcodr template directory itself',
+  E_TARGET_NOT_EMPTY: 'Target directory is not empty',
+  E_TARGET_IS_PROTECTED: 'Refusing to scaffold into a protected system directory',
+  E_GIT_ARGS_INVALID: 'runGit requires a non-empty argv array',
+  E_GIT_BLOCKED: 'Blocked git subcommand',
+  E_PATH_ESCAPE: 'Path escapes allowed root'
+} as const;
+
+/**
+ * Union of valid machine-readable error codes for scaffolding failures.
+ */
+export type ScaffoldErrorCode = keyof typeof ERROR_CODES;
+
+/**
+ * Structural interface contract for errors thrown by the scaffolder.
+ */
+export interface ScaffoldErrorShape extends Error {
+  name: 'ScaffoldError';
+  code: ScaffoldErrorCode;
+}
+
+/**
+ * Custom error class thrown by scaffolding operations, carrying a machine-readable code.
+ */
+export class ScaffoldError extends Error implements ScaffoldErrorShape {
+  override readonly name: 'ScaffoldError' = 'ScaffoldError';
+  readonly code: ScaffoldErrorCode;
+
+  /**
+   * Constructs a new ScaffoldError instance.
+   *
+   * @param code - Machine-readable error code.
+   * @param message - Human-readable explanation of the error.
+   */
+  constructor(code: ScaffoldErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export default { ERROR_CODES, ScaffoldError };

package/src/git.ts

@@ -0,0 +1,42 @@
+import cp from 'node:child_process';
+import { ScaffoldError, ERROR_CODES } from './errors.js';
+
+/**
+ * Socket-hardened process boundary (Supply Chain: shell access).
+ * Scaffolder must spawn `git`, but never via a shell string.
+ * Uses execFileSync with argv (shell:false) and an explicit subcommand allowlist.
+ * No network, no env exfiltration; cwd is constrained to targetDir callers.
+ */
+export const GIT_ALLOWED_SUBCOMMANDS = new Set([
+  'rev-parse',
+  'init',
+  'branch',
+  'add',
+  'commit'
+]);
+
+/**
+ * Safely executes an allowlisted git subcommand using execFileSync with an argument array and shell disabled.
+ *
+ * @param args - Subcommand and arguments array to pass to git.
+ * @param options - Child process execution options.
+ * @returns Standard output from git as a string.
+ * @throws {ScaffoldError} When args is empty or the subcommand is not in GIT_ALLOWED_SUBCOMMANDS.
+ */
+export function runGit(args: string[], options: cp.ExecFileSyncOptions = {}): string {
+  if (!Array.isArray(args) || args.length === 0) {
+    throw new ScaffoldError('E_GIT_ARGS_INVALID', ERROR_CODES.E_GIT_ARGS_INVALID);
+  }
+  const subcommand = args[0];
+  if (!subcommand || !GIT_ALLOWED_SUBCOMMANDS.has(subcommand)) {
+    throw new ScaffoldError('E_GIT_BLOCKED', `${ERROR_CODES.E_GIT_BLOCKED}: ${String(subcommand)}`);
+  }
+  return cp.execFileSync('git', args, {
+    encoding: 'utf-8',
+    stdio: 'pipe',
+    shell: false,
+    ...options
+  }) as string;
+}
+
+export default { GIT_ALLOWED_SUBCOMMANDS, runGit };

package/src/guards.ts

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import process from 'node:process';
+import { ScaffoldError, ERROR_CODES } from './errors.js';
+import { getTemplateDir } from './scaffold.js';
+
+/**
+ * Options for configuring protected target verification.
+ */
+export interface ProtectedTargetOptions {
+  templateDir?: string;
+  force?: boolean;
+  dryRun?: boolean;
+  allowProtected?: boolean;
+}
+
+/**
+ * Filesystem scope guard (Supply Chain: filesystem access).
+ * Constrains all reads/writes to targetDir / templateDir, throwing if candidate escapes root.
+ *
+ * @param root - Absolute base directory.
+ * @param candidate - Candidate file or directory path to check.
+ * @param message - Optional custom error message.
+ * @throws {ScaffoldError} When candidate path escapes root directory.
+ */
+export function assertInside(root: string, candidate: string, message?: string): void {
+  const resolvedRoot = path.resolve(root);
+  const resolvedCandidate = path.resolve(root, candidate);
+  const relative = path.relative(resolvedRoot, resolvedCandidate);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new ScaffoldError('E_PATH_ESCAPE', message || `${ERROR_CODES.E_PATH_ESCAPE}: ${candidate}`);
+  }
+}
+
+/**
+ * Normalizes a path for protected-target comparison. On Windows the filesystem
+ * is case-insensitive, so `C:\Users\Name` and `c:\users\name` are the same
+ * directory and must compare equal.
+ *
+ * @param p - File or directory path to normalize.
+ * @returns Normalized path string.
+ */
+export function normalizeForComparison(p: string): string {
+  const resolved = path.resolve(p);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function readHomeDir(): string {
+  try {
+    return os.homedir();
+  } catch {
+    return '';
+  }
+}
+
+function isFilesystemRoot(resolvedTarget: string): boolean {
+  return resolvedTarget === path.parse(resolvedTarget).root;
+}
+
+function isHomeOrParent(normalizedTarget: string, home: string): boolean {
+  if (!home) return false;
+  if (normalizedTarget === normalizeForComparison(home)) return true;
+  const parent = path.dirname(path.resolve(home));
+  return normalizedTarget === normalizeForComparison(parent);
+}
+
+function isTemplateAncestor(resolvedTarget: string, templateDir: string): boolean {
+  const resolvedTemplate = path.resolve(templateDir);
+  const relative = path.relative(resolvedTarget, resolvedTemplate);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+function resolvesToProtectedLocation(resolvedTarget: string, home: string): boolean {
+  // Symlink alias: a symlink to / or ~ must not bypass the lexical checks.
+  let real = '';
+  try {
+    if (!fs.existsSync(resolvedTarget)) return false;
+    real = fs.realpathSync(resolvedTarget);
+  } catch {
+    return false;
+  }
+  if (real === path.parse(real).root) return true;
+  return Boolean(home) && normalizeForComparison(real) === normalizeForComparison(home);
+}
+
+/**
+ * Returns true when `targetDir` is a location the scaffolder must never write
+ * into: the filesystem root, the user's home directory, the home directory's
+ * parent (e.g. /home, C:\Users -- scaffolding there affects every user), or an
+ * ancestor of the template itself (scaffolding into D:\projects would merge
+ * the template into its own parent).
+ *
+ * Lexical comparison is not enough: a symlink pointing at home must also be
+ * caught, so an existing target is resolved with realpath before comparing.
+ *
+ * @param targetDir - The target directory path to evaluate.
+ * @param options - Optional configuration for protected target evaluation.
+ * @returns True if target is a protected location, false otherwise.
+ */
+export function isProtectedTarget(targetDir: string, options: ProtectedTargetOptions = {}): boolean {
+  const resolvedTarget = path.resolve(targetDir);
+  const normalizedTarget = normalizeForComparison(resolvedTarget);
+  if (isFilesystemRoot(resolvedTarget)) return true;
+  const home = readHomeDir();
+  if (isHomeOrParent(normalizedTarget, home)) return true;
+  const { templateDir = getTemplateDir() } = options;
+  if (isTemplateAncestor(resolvedTarget, templateDir)) return true;
+  return resolvesToProtectedLocation(resolvedTarget, home);
+}
+
+export default {
+  assertInside,
+  normalizeForComparison,
+  isProtectedTarget
+};

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * @module @azcodr/azcodr
+ * Enterprise Architecture & Agentic Engineering Starter Template.
+ *
+ * Provides problem-first, topology-aligned project scaffolding with strict systemic atomicity,
+ * filesystem scope guards, git worktree initialization, and multi-agent harness parity.
+ */
+
+/**
+ * Union type of all valid machine-readable error codes.
+ */
+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';
+
+/**
+ * Core scaffolding functions, guards, utilities, error classes, and constants.
+ */
+export {
+  scaffold,
+  validateTarget,
+  copyTemplate,
+  ensureSymlink,
+  ensureSymlinkOrPointer,
+  isSameCaseInsensitiveFile,
+  makeScriptsExecutable,
+  initGit,
+  isInsideGitWorkTree,
+  runGit,
+  assertInside,
+  isProtectedTarget,
+  getTemplateDir,
+  TEMPLATE_ITEMS,
+  ScaffoldError,
+  ERROR_CODES
+} from './scaffold.js';
+
+/**
+ * Type definitions and option interfaces for scaffolding operations.
+ */
+export type {
+  ScaffoldOptions,
+  ScaffoldResult,
+  ValidateTargetOptions,
+  CopyTemplateOptions,
+  EnsureSymlinkOptions,
+  InitGitOptions,
+  ScaffoldErrorShape
+} from './scaffold.js';
+
+import scaffoldModule from './scaffold.js';
+
+/**
+ * Default export providing the unified azcodr scaffolding module.
+ */
+export default scaffoldModule;

package/src/links.ts

@@ -0,0 +1,153 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Configuration options for symlink and pointer creation.
+ */
+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).
+ *
+ * @param targetDir - Directory containing the file entries.
+ * @param linkName - Name of the proposed symlink or alias entry.
+ * @param targetFileName - Target file name to match against.
+ * @returns True if both names resolve to the same disk file on a case-insensitive filesystem.
+ */
+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.
+ *
+ * @param options - Options specifying target directory, link name, target file name, and dry-run mode.
+ * @returns True if the symlink or copy fallback was successfully established.
+ */
+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).
+ *
+ * @param options - Options specifying target directory, link name, target file name, and dry-run mode.
+ * @returns True if the symlink or pointer fallback was successfully established.
+ */
+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
+};