azcodr 2.0.0 → 2.1.0

package/scripts/validate/parity.js

@@ -1,6 +1,4 @@
-'use strict';
-
-const fs = require('node:fs');
+import fs from 'node:fs';
 
 /**
  * Harness-parity verdicts, kept free of filesystem I/O.
@@ -15,7 +13,7 @@ const fs = require('node:fs');
  * The three target spellings a harness-parity file may legitimately use.
  * Pure so it can be unit-tested without touching the filesystem.
  */
-function isValidAgentsTarget(target, agentsFile) {
+export function isValidAgentsTarget(target, agentsFile) {
   const normalized = target.replace(/\\/g, '/');
   const rootNormalized = agentsFile.replace(/\\/g, '/');
   return normalized === 'AGENTS.md' || normalized === './AGENTS.md' || normalized === rootNormalized;
@@ -82,7 +80,7 @@ function fileVerdict(ctx) {
 /**
  * Decides whether a harness-parity entry is healthy, drifted, or outright wrong.
  */
-function evaluateParityTarget(ctx) {
+export function evaluateParityTarget(ctx) {
   if (ctx.isSymlink) return symlinkVerdict(ctx);
   if (ctx.isFile) return fileVerdict(ctx);
   // Anything lstat saw that is neither a symlink nor a regular file (a
@@ -97,7 +95,7 @@ function evaluateParityTarget(ctx) {
  *
  * @returns {{created: boolean, strategy: 'symlink'|'pointer'|null, reason: string|null}}
  */
-function createLowercaseParityLink(lowerPath, fsImpl = fs) {
+export function createLowercaseParityLink(lowerPath, fsImpl = fs) {
   try {
     fsImpl.symlinkSync('AGENTS.md', lowerPath);
     return { created: true, strategy: 'symlink', reason: null };
@@ -117,7 +115,7 @@ function createLowercaseParityLink(lowerPath, fsImpl = fs) {
   }
 }
 
-module.exports = {
+export default {
   isValidAgentsTarget,
   evaluateParityTarget,
   createLowercaseParityLink

package/scripts/validate/root.js

@@ -1,9 +1,7 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { readTextOrFail } = require('./io.js');
-const { evaluateParityTarget, createLowercaseParityLink } = require('./parity.js');
+import fs from 'node:fs';
+import path from 'node:path';
+import { readTextOrFail } from './io.js';
+import { evaluateParityTarget, createLowercaseParityLink } from './parity.js';
 
 function reportAgentsLineBudget(agentsText, ctx) {
   const lines = agentsText.split('\n').length;
@@ -181,4 +179,5 @@ function phaseRootConfig(ctx) {
   checkGitignore(ctx);
 }
 
-module.exports = { phaseRootConfig, checkParity, checkAgentsFile };
+export { phaseRootConfig, checkParity, checkAgentsFile };
+export default { phaseRootConfig, checkParity, checkAgentsFile };

package/scripts/validate/rules.js

@@ -1,11 +1,9 @@
-'use strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { readTextOrFail, walkMarkdown } from './io.js';
+import { stripFencedCode } from './text.js';
 
-const fs = require('node:fs');
-const path = require('node:path');
-const { readTextOrFail, walkMarkdown } = require('./io.js');
-const { stripFencedCode } = require('./text.js');
-
-function checkOneRule(fp, name, ctx) {
+export function checkOneRule(fp, name, ctx) {
   const content = readTextOrFail(fp, `Rule ${name}`, ctx.fail);
   if (content === null) return;
   const stat = fs.statSync(fp);
@@ -17,7 +15,7 @@ function checkOneRule(fp, name, ctx) {
   if (stat.size > 24000) ctx.warn(`Rule ${name} exceeds 24KB token-economy cap (${stat.size} bytes)`);
 }
 
-function phaseRules(ctx) {
+export function phaseRules(ctx) {
   ctx.log('');
   ctx.heading('2. Checking Progressive Disclosure Rules...');
   const rulesDir = path.join(ctx.workspaceRoot, 'docs', 'rules');
@@ -41,4 +39,4 @@ function phaseRules(ctx) {
   return count;
 }
 
-module.exports = { phaseRules, checkOneRule };
+export default { phaseRules, checkOneRule };

package/scripts/validate/skills.js

@@ -1,10 +1,8 @@
-'use strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { readTextOrFail, readSkillFolders } from './io.js';
 
-const fs = require('node:fs');
-const path = require('node:path');
-const { readTextOrFail, readSkillFolders } = require('./io.js');
-
-function frontMatterBlock(content, skill, fail) {
+export function frontMatterBlock(content, skill, fail) {
   const lines = content.split('\n');
   if (lines[0].trim() !== '---') {
     fail(`Skill '${skill}' missing opening front matter delimiter (---)`);
@@ -26,7 +24,7 @@ function frontMatterBlock(content, skill, fail) {
   return frontMatter;
 }
 
-function extractSkillDescription(frontMatter) {
+export function extractSkillDescription(frontMatter) {
   const descMatch = frontMatter.match(/^description:\s*(.+)$/m);
   const desc = descMatch ? descMatch[1].trim() : '';
   if (!/^[>|][-+]?$/.test(desc)) return desc;
@@ -60,7 +58,7 @@ function checkSkillBody(checked, ctx) {
   }
 }
 
-function checkOneSkill(skill, skillsDir, ctx) {
+export function checkOneSkill(skill, skillsDir, ctx) {
   const skillFile = path.join(skillsDir, skill, 'SKILL.md');
   if (!fs.existsSync(skillFile)) {
     ctx.fail(`Skill '${skill}' missing SKILL.md`);
@@ -75,7 +73,7 @@ function checkOneSkill(skill, skillsDir, ctx) {
   checkSkillBody({ content, desc, skill }, ctx);
 }
 
-function phaseSkills(ctx) {
+export function phaseSkills(ctx) {
   ctx.log('');
   ctx.heading('3. Checking Specialized Skills (.agents/skills)...');
   const skillsDir = path.join(ctx.workspaceRoot, '.agents', 'skills');
@@ -93,4 +91,4 @@ function phaseSkills(ctx) {
   return count;
 }
 
-module.exports = { phaseSkills, checkOneSkill, extractSkillDescription, frontMatterBlock };
+export default { phaseSkills, checkOneSkill, extractSkillDescription, frontMatterBlock };

package/scripts/validate/text.js

@@ -1,5 +1,3 @@
-'use strict';
-
 /**
  * Text helpers shared by the validator phases.
  *
@@ -8,7 +6,7 @@
  * would mistake documentation ABOUT the contract for the contract itself.
  */
 
-function stripHtmlComments(text) {
+export function stripHtmlComments(text) {
   // Remove HTML comments, tolerating unclosed ones. A stray `<!--` from an
   // editor's "comment selection" must not silently hide every ADR after it.
   return text
@@ -22,8 +20,8 @@ function stripHtmlComments(text) {
  * "Core Mandate" lines sit inside a ```md fence satisfies both checks, and a
  * `#### ADR-001` shown as an example is counted as a real decision.
  */
-function stripFencedCode(text) {
+export function stripFencedCode(text) {
   return text.replace(/^([ \t]*)(```|~~~)[\s\S]*?^\1\2[ \t]*$/gm, '');
 }
 
-module.exports = { stripHtmlComments, stripFencedCode };
+export default { stripHtmlComments, stripFencedCode };

package/scripts/validate-cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-'use strict';
 
 /**
  * CLI entry for the agentic-architecture validator.
@@ -8,6 +7,6 @@
  * `require.main` guard means requiring it never validates or exits, and it
  * avoids a permanently-unreachable branch that blocks the 100% coverage gate.
  */
-const { main } = require('./validate.js');
+import { main } from './validate.js';
 
 main();

package/scripts/validate.js

@@ -1,17 +1,16 @@
 #!/usr/bin/env node
-'use strict';
 
-const fs = require('node:fs');
-const path = require('node:path');
-const { createReporter, readTextOrFail } = require('./validate/io.js');
-const textHelpers = require('./validate/text.js');
-const parityHelpers = require('./validate/parity.js');
-const ioHelpers = require('./validate/io.js');
-const { parseAdrLedger, checkAdrIndexConsistency, checkGlossaryPopulated } = require('./validate/adr.js');
-const { phaseRootConfig } = require('./validate/root.js');
-const { phaseRules } = require('./validate/rules.js');
-const { phaseSkills } = require('./validate/skills.js');
-const { phaseLinks } = require('./validate/links.js');
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { createReporter, readTextOrFail, walkMarkdown } from './validate/io.js';
+import * as textHelpers from './validate/text.js';
+import * as parityHelpers from './validate/parity.js';
+import { parseAdrLedger, checkAdrIndexConsistency, checkGlossaryPopulated } from './validate/adr.js';
+import { phaseRootConfig } from './validate/root.js';
+import { phaseRules } from './validate/rules.js';
+import { phaseSkills } from './validate/skills.js';
+import { phaseLinks } from './validate/links.js';
 
 /**
  * NOTE: this module is a library. It never self-executes, so importing it from
@@ -123,7 +122,26 @@ function main(argv = process.argv.slice(2), exit = process.exit) {
   return exit(result.errors === 0 ? 0 : 1);
 }
 
-module.exports = {
+const { evaluateParityTarget, isValidAgentsTarget, createLowercaseParityLink } = parityHelpers;
+const { stripHtmlComments, stripFencedCode } = textHelpers;
+
+export {
+  runValidation,
+  parseArgs,
+  createReporter,
+  main,
+  parseAdrLedger,
+  checkAdrIndexConsistency,
+  checkGlossaryPopulated,
+  evaluateParityTarget,
+  isValidAgentsTarget,
+  createLowercaseParityLink,
+  stripHtmlComments,
+  stripFencedCode,
+  walkMarkdown
+};
+
+export default {
   runValidation,
   parseArgs,
   createReporter,
@@ -131,10 +149,10 @@ module.exports = {
   parseAdrLedger,
   checkAdrIndexConsistency,
   checkGlossaryPopulated,
-  evaluateParityTarget: parityHelpers.evaluateParityTarget,
-  isValidAgentsTarget: parityHelpers.isValidAgentsTarget,
-  createLowercaseParityLink: parityHelpers.createLowercaseParityLink,
-  stripHtmlComments: textHelpers.stripHtmlComments,
-  stripFencedCode: textHelpers.stripFencedCode,
-  walkMarkdown: ioHelpers.walkMarkdown
+  evaluateParityTarget,
+  isValidAgentsTarget,
+  createLowercaseParityLink,
+  stripHtmlComments,
+  stripFencedCode,
+  walkMarkdown
 };

package/src/cli-parse.ts

@@ -0,0 +1,77 @@
+/**
+ * Argument parsing for the azcodr CLI.
+ *
+ * Table-driven: every boolean flag is one Map entry, so adding a flag cannot
+ * raise the complexity of the parser itself.
+ */
+
+export interface CliParsedOptions {
+  targetDir: string | null;
+  force: boolean;
+  noGit: boolean;
+  dryRun: boolean;
+  silent: boolean;
+  terminal: 'help' | 'version' | 'unknown-flag' | 'extra-arg' | null;
+  message?: string;
+}
+
+export type BooleanFlagKey = 'force' | 'noGit' | 'dryRun' | 'silent';
+
+export function emptyOptions(): Omit<CliParsedOptions, 'terminal' | 'message'> {
+  return { targetDir: null, force: false, noGit: false, dryRun: false, silent: false };
+}
+
+export const BOOLEAN_FLAGS = new Map<string, BooleanFlagKey>([
+  ['-f', 'force'],
+  ['--force', 'force'],
+  ['--no-git', 'noGit'],
+  ['-d', 'dryRun'],
+  ['--dry-run', 'dryRun'],
+  ['-s', 'silent'],
+  ['--silent', 'silent']
+]);
+
+export interface ArgOutcome {
+  terminal: 'help' | 'version' | 'unknown-flag' | 'extra-arg' | null;
+  message?: string;
+}
+
+export function applyArg(
+  state: Omit<CliParsedOptions, 'terminal' | 'message'>,
+  arg: string
+): ArgOutcome {
+  if (arg === '-h' || arg === '--help') return { terminal: 'help' };
+  if (arg === '-v' || arg === '--version') return { terminal: 'version' };
+  const flag = BOOLEAN_FLAGS.get(arg);
+  if (flag !== undefined) {
+    state[flag] = true;
+    return { terminal: null };
+  }
+  if (arg.startsWith('-')) {
+    return {
+      terminal: 'unknown-flag',
+      message: `Unknown argument '${arg}'. Run 'npx azcodr --help' for available options.`
+    };
+  }
+  if (!state.targetDir) {
+    state.targetDir = arg;
+    return { terminal: null };
+  }
+  return {
+    terminal: 'extra-arg',
+    message: `Unexpected argument '${arg}'. Run 'npx azcodr --help' for available options.`
+  };
+}
+
+export function parseArgs(rawArgs: readonly string[]): CliParsedOptions {
+  const state = emptyOptions();
+  for (const arg of rawArgs) {
+    const outcome = applyArg(state, arg);
+    if (outcome.terminal !== null) {
+      return { ...state, terminal: outcome.terminal, message: outcome.message };
+    }
+  }
+  return { ...state, terminal: null, message: undefined };
+}
+
+export default { emptyOptions, BOOLEAN_FLAGS, applyArg, parseArgs };

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
+};