azcodr 1.5.2 → 2.0.0

package/lib/cli-target.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const path = require('node:path');
+const readline = require('node:readline');
+const fs = require('node:fs');
+const { isProtectedTarget } = require('./guards.js');
+
+function askQuestion(query, { input = process.stdin, output = process.stdout } = {}) {
+  const rl = readline.createInterface({ input, output });
+
+  return new Promise((resolve) => {
+    let resolved = false;
+    rl.question(query, (answer) => {
+      if (!resolved) {
+        resolved = true;
+        rl.close();
+        resolve(answer.trim());
+      }
+    });
+    rl.on('close', () => {
+      if (!resolved) {
+        resolved = true;
+        resolve('');
+      }
+    });
+  });
+}
+
+async function promptForTargetDir(io) {
+  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 || '.';
+}
+
+function rejectBadTarget(resolvedTarget, templateDir) {
+  if (resolvedTarget === templateDir) {
+    return `Cannot scaffold into the template directory itself: ${resolvedTarget}`;
+  }
+  // Fail fast on protected locations BEFORE the non-empty prompt. The prompt
+  // asks "Continue? (y/N)" for ordinary project directories; answering "y"
+  // for ~ or / must not be possible. The library enforces this again in
+  // validateTarget, so this is defence in depth, not the sole check.
+  if (isProtectedTarget(resolvedTarget, { templateDir })) {
+    return `Refusing to scaffold into protected directory: ${resolvedTarget}. Choose a project subdirectory instead.`;
+  }
+  return null;
+}
+
+async function resolveTargetDir(targetDir, io) {
+  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 };
+}
+
+function targetStatus(resolvedTarget) {
+  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 };
+}
+
+async function confirmOverwrite(targetDir, count, io) {
+  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 };
+}
+
+/**
+ * Ensures the target may be written. Returns { force } on success or
+ * { exitCode, message? } when the CLI must stop before scaffolding.
+ */
+async function ensureWritableTarget({ chosen, resolvedTarget, force, io }) {
+  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 };
+}
+
+module.exports = {
+  askQuestion,
+  promptForTargetDir,
+  rejectBadTarget,
+  resolveTargetDir,
+  targetStatus,
+  confirmOverwrite,
+  ensureWritableTarget
+};

package/lib/cli.js

@@ -0,0 +1,180 @@
+'use strict';
+
+const { scaffold, getTemplateDir } = require('./scaffold.js');
+const { parseArgs } = require('./cli-parse.js');
+const { askQuestion, resolveTargetDir, ensureWritableTarget } = require('./cli-target.js');
+const pkg = require('../package.json');
+
+function printHelp(out = console.log) {
+  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
+`);
+}
+
+function printVersion(out = console.log) {
+  out(pkg.version);
+}
+
+function normalizeIo(io = {}) {
+  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) {
+  fullIo.out('\n🚀 azcodr - Enterprise Multi-Tenant Architecture & Agentic Engineering\n');
+}
+
+function handleTerminal(parsed, io) {
+  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, out) {
+  for (const action of result.actions) {
+    out(`  [preview] ${action}`);
+  }
+  out('\n🎉 Dry run completed. 0 files modified on disk.\n');
+}
+
+function reportSuccess(result, targetDir, out) {
+  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, parsed, io) {
+  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.message}\n`);
+    return exit(1);
+  }
+}
+
+async function resolvePhase(parsed, fullIo) {
+  const { resolvedTarget, chosen, error } = await resolveTargetDir(parsed.targetDir, fullIo);
+  if (error !== null) {
+    fullIo.err(`❌ Error: ${error}`);
+    return { exitCode: 1 };
+  }
+  return { resolvedTarget, chosen };
+}
+
+async function writablePhase(target, force, fullIo) {
+  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 };
+}
+
+async function runCli(rawArgs = process.argv.slice(2), io = {}) {
+  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, parsed.force, fullIo);
+  if (ready.exitCode !== undefined) return fullIo.exit(ready.exitCode);
+
+  return runScaffold(target.resolvedTarget, { ...parsed, force: ready.force }, fullIo);
+}
+
+async function main() {
+  try {
+    await runCli(process.argv.slice(2));
+  } catch (err) {
+    console.error('Unexpected error:', err);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  runCli,
+  main,
+  printHelp,
+  printVersion,
+  askQuestion
+};

package/lib/errors.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * 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.
+ */
+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'
+};
+
+class ScaffoldError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ScaffoldError';
+    this.code = code;
+  }
+}
+
+module.exports = { ERROR_CODES, ScaffoldError };

package/lib/git.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const cp = require('node:child_process');
+const { ScaffoldError, ERROR_CODES } = require('./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.
+ */
+const GIT_ALLOWED_SUBCOMMANDS = new Set(['rev-parse', 'init', 'branch', 'add', 'commit']);
+
+function runGit(args, options = {}) {
+  if (!Array.isArray(args) || args.length === 0) {
+    throw new ScaffoldError('E_GIT_ARGS_INVALID', ERROR_CODES.E_GIT_ARGS_INVALID);
+  }
+  if (!GIT_ALLOWED_SUBCOMMANDS.has(args[0])) {
+    throw new ScaffoldError('E_GIT_BLOCKED', `${ERROR_CODES.E_GIT_BLOCKED}: ${String(args[0])}`);
+  }
+  return cp.execFileSync('git', args, {
+    encoding: 'utf-8',
+    stdio: 'pipe',
+    shell: false,
+    ...options
+  });
+}
+
+module.exports = { GIT_ALLOWED_SUBCOMMANDS, runGit };

package/lib/guards.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { ScaffoldError, ERROR_CODES } = require('./errors.js');
+
+/**
+ * Filesystem scope guard (Supply Chain: filesystem access).
+ * Constrains all reads/writes to targetDir / templateDir.
+ */
+function assertInside(root, candidate, message) {
+  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.
+ */
+function normalizeForComparison(p) {
+  const resolved = path.resolve(p);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function readHomeDir() {
+  try {
+    return os.homedir();
+  } catch {
+    return '';
+  }
+}
+
+function isFilesystemRoot(resolvedTarget) {
+  return resolvedTarget === path.parse(resolvedTarget).root;
+}
+
+function isHomeOrParent(normalizedTarget, home) {
+  if (!home) return false;
+  if (normalizedTarget === normalizeForComparison(home)) return true;
+  const parent = path.dirname(path.resolve(home));
+  return normalizedTarget === normalizeForComparison(parent);
+}
+
+function isTemplateAncestor(resolvedTarget, templateDir) {
+  const resolvedTemplate = path.resolve(templateDir);
+  const relative = path.relative(resolvedTarget, resolvedTemplate);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+
+function resolvesToProtectedLocation(resolvedTarget, home) {
+  // Symlink alias: a symlink to / or ~ must not bypass the lexical checks.
+  let real = null;
+  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.
+ */
+function isProtectedTarget(targetDir, options = {}) {
+  const resolvedTarget = path.resolve(targetDir);
+  const normalizedTarget = normalizeForComparison(resolvedTarget);
+  if (isFilesystemRoot(resolvedTarget)) return true;
+  const home = readHomeDir();
+  if (isHomeOrParent(normalizedTarget, home)) return true;
+  // Deferred require: scaffold.js requires this module, so a top-level
+  // require would be circular. Resolved at call time, after both modules load.
+  const { templateDir = require('./scaffold.js').getTemplateDir() } = options;
+  if (isTemplateAncestor(resolvedTarget, templateDir)) return true;
+  return resolvesToProtectedLocation(resolvedTarget, home);
+}
+
+module.exports = {
+  assertInside,
+  normalizeForComparison,
+  isProtectedTarget
+};