agentsmd-hierarchy 1.0.0

package/agentsmd-hierarchy/scripts/cli-prompts.mjs

@@ -0,0 +1,105 @@
+import { input, select } from '@inquirer/prompts';
+
+function canPrompt() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+export async function resolveOptionalScope({
+  allSelected,
+  allSelectionLabel,
+  normalizePath,
+  optionPath,
+  positionalPath,
+  promptMessage,
+  singleSelectionLabel,
+}) {
+  const explicitValues = [
+    allSelected ? '__ALL__' : null,
+    optionPath,
+    positionalPath,
+  ].filter(Boolean);
+
+  if (explicitValues.length > 1) {
+    throw new Error('Pass only one of a positional path, --path, or --all.');
+  }
+
+  if (allSelected) {
+    return normalizePath('.');
+  }
+
+  if (optionPath) {
+    return normalizePath(optionPath);
+  }
+
+  if (positionalPath) {
+    return normalizePath(positionalPath);
+  }
+
+  if (!canPrompt()) {
+    return normalizePath('.');
+  }
+
+  const selectionMode = await select({
+    choices: [
+      {
+        name: allSelectionLabel,
+        value: 'all',
+      },
+      {
+        name: singleSelectionLabel,
+        value: 'single',
+      },
+    ],
+    message: promptMessage,
+  });
+
+  if (selectionMode === 'all') {
+    return normalizePath('.');
+  }
+
+  const selectedPath = await input({
+    message:
+      'Enter a repo-relative directory or AGENTS.md file path (for example: packages/front or packages/front/AGENTS.md):',
+    validate(value) {
+      return value.trim() ? true : 'Enter a repo-relative path.';
+    },
+  });
+
+  return normalizePath(selectedPath.trim());
+}
+
+export async function resolveRequiredDirectory({
+  normalizeDirectory,
+  optionDirectory,
+  positionalDirectory,
+}) {
+  const explicitValues = [optionDirectory, positionalDirectory].filter(Boolean);
+
+  if (explicitValues.length > 1) {
+    throw new Error('Pass either a positional directory or --path, not both.');
+  }
+
+  if (optionDirectory) {
+    return normalizeDirectory(optionDirectory);
+  }
+
+  if (positionalDirectory) {
+    return normalizeDirectory(positionalDirectory);
+  }
+
+  if (!canPrompt()) {
+    throw new Error(
+      'Usage: node .codex/skills/agentsmd-hierarchy/scripts/scaffold-agents.mjs <repo-relative-directory>',
+    );
+  }
+
+  const selectedDirectory = await input({
+    message:
+      'Enter the repo-relative directory to scaffold (for example: packages/front/src):',
+    validate(value) {
+      return value.trim() ? true : 'Enter a repo-relative directory.';
+    },
+  });
+
+  return normalizeDirectory(selectedDirectory.trim());
+}

package/agentsmd-hierarchy/scripts/lib/AGENTS.md

@@ -0,0 +1,21 @@
+# agentsmd-hierarchy/scripts/lib
+
+Shared implementation modules for the bundled CLI, including structured logging, install planning, command registration, and AGENTS validation.
+
+## Directories
+
+- None.
+
+## Files
+
+- `cli-logger.mjs`: Color-aware structured logger used by commands and tests.
+- `errors.mjs`: Shared command error types and guards for consistent CLI failure handling.
+- `install-core.mjs`: Install planning and execution logic for Codex, Claude, Cursor, and Codex plugin bundle exports.
+- `program.mjs`: Commander program definition that wires subcommands, shared flags, and error handling together.
+- `validate-agents-core.mjs`: Core inventory, sync, and validation engine for hierarchical `AGENTS.md` files.
+
+## Writing Rules
+
+- Keep modules reusable from both CLI entrypoints and tests by accepting injected runtime state where practical.
+- Preserve stable option handling, debug log structure, and user-facing error messages because tests assert them.
+- Prefer adding shared behavior here rather than expanding the published bin wrappers.

package/agentsmd-hierarchy/scripts/lib/cli-logger.mjs

@@ -0,0 +1,149 @@
+const ANSI = {
+  blue: '\x1b[34m',
+  bold: '\x1b[1m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  reset: '\x1b[0m',
+  yellow: '\x1b[33m',
+};
+
+function shouldUseColor(stdout, stderr) {
+  if ('NO_COLOR' in process.env) {
+    return false;
+  }
+
+  if (process.env.FORCE_COLOR === '0') {
+    return false;
+  }
+
+  if (
+    process.env.FORCE_COLOR &&
+    process.env.FORCE_COLOR !== '0' &&
+    process.env.FORCE_COLOR !== ''
+  ) {
+    return true;
+  }
+
+  return Boolean(stdout.isTTY || stderr.isTTY);
+}
+
+function applyAnsi(text, stdout, stderr, ...codes) {
+  if (!shouldUseColor(stdout, stderr) || codes.length === 0) {
+    return text;
+  }
+
+  return `${codes.join('')}${text}${ANSI.reset}`;
+}
+
+function getLevelStyle(level) {
+  switch (level) {
+    case 'DEBUG':
+      return [ANSI.dim];
+    case 'INFO':
+      return [ANSI.blue, ANSI.bold];
+    case 'STEP':
+      return [ANSI.cyan, ANSI.bold];
+    case 'DONE':
+      return [ANSI.green, ANSI.bold];
+    case 'WARN':
+      return [ANSI.yellow, ANSI.bold];
+    case 'FAIL':
+      return [ANSI.red, ANSI.bold];
+    case 'NOTE':
+      return [ANSI.dim];
+    default:
+      return [];
+  }
+}
+
+function sortDebugDetails(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortDebugDetails);
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.keys(value)
+      .sort()
+      .reduce((result, key) => {
+        result[key] = sortDebugDetails(value[key]);
+        return result;
+      }, {});
+  }
+
+  return value;
+}
+
+function formatDebugMessage(eventOrMessage, details) {
+  if (details === undefined) {
+    return String(eventOrMessage);
+  }
+
+  return `${eventOrMessage} ${JSON.stringify(sortDebugDetails(details))}`;
+}
+
+export function createLogger(name, options = {}) {
+  const {
+    debugEnabled = false,
+    stderr = process.stderr,
+    stdout = process.stdout,
+  } = options;
+  const prefix = applyAnsi(`[${name}]`, stdout, stderr, ANSI.cyan, ANSI.bold);
+
+  function write(stream, level, message) {
+    const styledLevel = applyAnsi(
+      level,
+      stdout,
+      stderr,
+      ...getLevelStyle(level),
+    );
+    stream.write(`${prefix} ${styledLevel} ${message}\n`);
+  }
+
+  return {
+    style(text, tone) {
+      switch (tone) {
+        case 'path':
+          return applyAnsi(text, stdout, stderr, ANSI.cyan);
+        case 'success':
+          return applyAnsi(text, stdout, stderr, ANSI.green);
+        case 'warning':
+          return applyAnsi(text, stdout, stderr, ANSI.yellow);
+        case 'error':
+          return applyAnsi(text, stdout, stderr, ANSI.red);
+        case 'muted':
+          return applyAnsi(text, stdout, stderr, ANSI.dim);
+        case 'strong':
+          return applyAnsi(text, stdout, stderr, ANSI.bold);
+        default:
+          return text;
+      }
+    },
+    info(message) {
+      write(stdout, 'INFO', message);
+    },
+    debug(eventOrMessage, details) {
+      if (!debugEnabled) {
+        return;
+      }
+
+      write(stdout, 'DEBUG', formatDebugMessage(eventOrMessage, details));
+    },
+    step(message) {
+      write(stdout, 'STEP', message);
+    },
+    success(message) {
+      write(stdout, 'DONE', message);
+    },
+    warn(message) {
+      write(stderr, 'WARN', message);
+    },
+    error(message) {
+      write(stderr, 'FAIL', message);
+    },
+    note(message) {
+      write(stdout, 'NOTE', message);
+    },
+  };
+}

package/agentsmd-hierarchy/scripts/lib/errors.mjs

@@ -0,0 +1,12 @@
+export class CommandError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'CommandError';
+    this.exitCode = options.exitCode ?? 1;
+    this.exposeHelp = options.exposeHelp ?? false;
+  }
+}
+
+export function isCommandError(error) {
+  return error instanceof CommandError;
+}