azcodr 1.5.2 → 2.1.0

package/src/cli-target.ts

@@ -0,0 +1,167 @@
+import path from 'node:path';
+import readline from 'node:readline';
+import fs from 'node:fs';
+import process from 'node:process';
+import { isProtectedTarget } from './guards.js';
+
+export interface AskQuestionOptions {
+  input?: NodeJS.ReadableStream;
+  output?: NodeJS.WritableStream;
+}
+
+export function askQuestion(
+  query: string,
+  { input = process.stdin, output = process.stdout }: AskQuestionOptions = {}
+): Promise<string> {
+  const rl = readline.createInterface({ input, output });
+
+  return new Promise((resolve) => {
+    let resolved = false;
+    rl.question(query, (answer: string) => {
+      if (!resolved) {
+        resolved = true;
+        rl.close();
+        resolve(answer.trim());
+      }
+    });
+    rl.on('close', () => {
+      if (!resolved) {
+        resolved = true;
+        resolve('');
+      }
+    });
+  });
+}
+
+export interface PromptIo {
+  stdin: NodeJS.ReadStream | (NodeJS.ReadableStream & { isTTY?: boolean });
+  stdout: NodeJS.WriteStream | NodeJS.WritableStream;
+}
+
+export async function promptForTargetDir(io: PromptIo): Promise<string> {
+  const { stdin, stdout } = io;
+  if (!stdin.isTTY) return '.';
+  const answer = await askQuestion('? Where would you like to initialize your project? (./) ', {
+    input: stdin,
+    output: stdout
+  });
+  return answer || '.';
+}
+
+export function rejectBadTarget(resolvedTarget: string, templateDir: string): string | null {
+  if (resolvedTarget === templateDir) {
+    return `Cannot scaffold into the template directory itself: ${resolvedTarget}`;
+  }
+  if (isProtectedTarget(resolvedTarget, { templateDir })) {
+    return `Refusing to scaffold into protected directory: ${resolvedTarget}. Choose a project subdirectory instead.`;
+  }
+  return null;
+}
+
+export interface ResolveTargetIo extends PromptIo {
+  cwd: string;
+  templateDir: string;
+}
+
+export interface ResolveTargetResult {
+  resolvedTarget: string;
+  chosen: string;
+  error: string | null;
+}
+
+export async function resolveTargetDir(
+  targetDir: string | null,
+  io: ResolveTargetIo
+): Promise<ResolveTargetResult> {
+  const { cwd, templateDir } = io;
+  const chosen = targetDir || (await promptForTargetDir(io));
+  const resolvedTarget = path.resolve(cwd, chosen);
+  const rejection = rejectBadTarget(resolvedTarget, templateDir);
+  if (rejection !== null) return { resolvedTarget, chosen, error: rejection };
+  return { resolvedTarget, chosen, error: null };
+}
+
+export type TargetDirectoryStatus = 'missing' | 'not-a-directory' | 'empty' | 'non-empty';
+
+export interface TargetStatusResult {
+  status: TargetDirectoryStatus;
+  count: number;
+}
+
+export function targetStatus(resolvedTarget: string): TargetStatusResult {
+  if (!fs.existsSync(resolvedTarget)) return { status: 'missing', count: 0 };
+  if (!fs.statSync(resolvedTarget).isDirectory()) return { status: 'not-a-directory', count: 0 };
+  const count = fs.readdirSync(resolvedTarget).length;
+  return { status: count === 0 ? 'empty' : 'non-empty', count };
+}
+
+export interface ConfirmOverwriteIo extends PromptIo {
+  out: (msg: string) => void;
+}
+
+export interface ConfirmOverwriteResult {
+  confirmed: boolean;
+  aborted: boolean;
+}
+
+export async function confirmOverwrite(
+  targetDir: string,
+  count: number,
+  io: ConfirmOverwriteIo
+): Promise<ConfirmOverwriteResult> {
+  const { stdin, stdout, out } = io;
+  if (!stdin.isTTY) return { confirmed: false, aborted: false };
+  const confirm = await askQuestion(
+    `⚠️  Target directory '${targetDir}' is not empty (${count} items). Continue? (y/N) `,
+    { input: stdin, output: stdout }
+  );
+  if (confirm.toLowerCase() !== 'y' && confirm.toLowerCase() !== 'yes') {
+    out('Scaffolding aborted.');
+    return { confirmed: false, aborted: true };
+  }
+  return { confirmed: true, aborted: false };
+}
+
+export interface EnsureWritableOptions {
+  chosen: string;
+  resolvedTarget: string;
+  force: boolean;
+  io: ConfirmOverwriteIo & { err: (msg: string) => void };
+}
+
+export interface EnsureWritableResult {
+  force?: boolean;
+  exitCode?: number;
+  message?: string | null;
+}
+
+/**
+ * Ensures the target may be written. Returns { force } on success or
+ * { exitCode, message? } when the CLI must stop before scaffolding.
+ */
+export async function ensureWritableTarget(
+  options: EnsureWritableOptions
+): Promise<EnsureWritableResult> {
+  const { chosen, resolvedTarget, force, io } = options;
+  const { err } = io;
+  const { status, count } = targetStatus(resolvedTarget);
+  if (status === 'missing' || status === 'empty' || force) return { force };
+  if (status === 'not-a-directory') {
+    return { exitCode: 1, message: `Target '${resolvedTarget}' already exists and is not a directory.` };
+  }
+  const { confirmed, aborted } = await confirmOverwrite(chosen, count, io);
+  if (aborted) return { exitCode: 0, message: null };
+  if (confirmed) return { force: true };
+  err(`Target directory '${resolvedTarget}' is not empty. Use --force to proceed.`);
+  return { exitCode: 1, message: null };
+}
+
+export default {
+  askQuestion,
+  promptForTargetDir,
+  rejectBadTarget,
+  resolveTargetDir,
+  targetStatus,
+  confirmOverwrite,
+  ensureWritableTarget
+};

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,35 @@
+/**
+ * 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;
+
+export type ScaffoldErrorCode = keyof typeof ERROR_CODES;
+
+export interface ScaffoldErrorShape extends Error {
+  name: 'ScaffoldError';
+  code: ScaffoldErrorCode;
+}
+
+export class ScaffoldError extends Error implements ScaffoldErrorShape {
+  override readonly name: 'ScaffoldError' = 'ScaffoldError';
+  readonly code: ScaffoldErrorCode;
+
+  constructor(code: ScaffoldErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export default { ERROR_CODES, ScaffoldError };

package/src/git.ts

@@ -0,0 +1,34 @@
+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'
+]);
+
+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,101 @@
+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';
+
+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.
+ */
+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.
+ */
+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.
+ */
+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,39 @@
+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';
+
+export {
+  scaffold,
+  validateTarget,
+  copyTemplate,
+  ensureSymlink,
+  ensureSymlinkOrPointer,
+  isSameCaseInsensitiveFile,
+  makeScriptsExecutable,
+  initGit,
+  isInsideGitWorkTree,
+  runGit,
+  assertInside,
+  isProtectedTarget,
+  getTemplateDir,
+  TEMPLATE_ITEMS,
+  ScaffoldError,
+  ERROR_CODES
+} from './scaffold.js';
+
+export type {
+  ScaffoldOptions,
+  ScaffoldResult,
+  ValidateTargetOptions,
+  CopyTemplateOptions,
+  EnsureSymlinkOptions,
+  InitGitOptions,
+  ScaffoldErrorShape
+} from './scaffold.js';
+
+import scaffoldModule from './scaffold.js';
+export default scaffoldModule;