@odavl/guardian 2.0.0 → 2.0.1

package/src/guardian/first-run.js

@@ -1,67 +1,65 @@
-/**
- * Guardian First-Run Detection & Initialization
- * Deterministically detects first run and coordinates welcome behavior.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const STATE_FILE = '.odavl-guardian/.first-run-state.json';
-
-function hasRunBefore(stateDir = '.odavl-guardian') {
-  try {
-    const filePath = path.join(stateDir, '.first-run-state.json');
-    return fs.existsSync(filePath);
-  } catch {
-    return false;
-  }
-}
-
-function markAsRun(stateDir = '.odavl-guardian') {
-  try {
-    fs.mkdirSync(stateDir, { recursive: true });
-    const filePath = path.join(stateDir, '.first-run-state.json');
-    fs.writeFileSync(filePath, JSON.stringify({ firstRunAt: new Date().toISOString() }, null, 2));
-  } catch (e) {
-    // Silently ignore state write failures (e.g., permission issues)
-  }
-}
-
-function isFirstRun(stateDir = '.odavl-guardian') {
-  return !hasRunBefore(stateDir);
-}
-
-function printWelcome(label = 'ODAVL Guardian') {
-  const lines = [
-    '',
-    `Welcome to ${label}!`,
-    'Running first-time setup…',
-    ''
-  ];
-  console.log(lines.join('\n'));
-}
-
-function printFirstRunHint() {
-  console.log("\nTip: Try 'guardian smoke <url>' for a fast CI-ready check.\n");
-}
-
-function printFirstRunIntroIfNeeded(config, argv) {
-  // Detect quiet mode from config or CLI args
-  const isQuiet = (config && config.output && config.output.quiet) || argv.includes('--quiet');
-  const isCI = process.env.CI === 'true';
-  
-  // Only print welcome on first run and not in CI/quiet mode
-  if (isFirstRun() && !isQuiet && !isCI) {
-    printWelcome();
-    printFirstRunHint();
-  }
-}
-
-module.exports = {
-  isFirstRun,
-  hasRunBefore,
-  markAsRun,
-  printWelcome,
-  printFirstRunHint,
-  printFirstRunIntroIfNeeded
-};
+/**
+ * Guardian First-Run Detection & Initialization
+ * Deterministically detects first run and coordinates welcome behavior.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function hasRunBefore(stateDir = '.odavl-guardian') {
+  try {
+    const filePath = path.join(stateDir, '.first-run-state.json');
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+function markAsRun(stateDir = '.odavl-guardian') {
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    const filePath = path.join(stateDir, '.first-run-state.json');
+    fs.writeFileSync(filePath, JSON.stringify({ firstRunAt: new Date().toISOString() }, null, 2));
+  } catch (e) {
+    // Silently ignore state write failures (e.g., permission issues)
+  }
+}
+
+function isFirstRun(stateDir = '.odavl-guardian') {
+  return !hasRunBefore(stateDir);
+}
+
+function printWelcome(label = 'ODAVL Guardian') {
+  const lines = [
+    '',
+    `Welcome to ${label}!`,
+    'Running first-time setup…',
+    ''
+  ];
+  console.log(lines.join('\n'));
+}
+
+function printFirstRunHint() {
+  console.log("\nTip: Try 'guardian smoke <url>' for a fast CI-ready check.\n");
+}
+
+function printFirstRunIntroIfNeeded(config, argv) {
+  // Detect quiet mode from config or CLI args
+  const isQuiet = (config && config.output && config.output.quiet) || argv.includes('--quiet');
+  const isCI = process.env.CI === 'true';
+  
+  // Only print welcome on first run and not in CI/quiet mode
+  if (isFirstRun() && !isQuiet && !isCI) {
+    printWelcome();
+    printFirstRunHint();
+  }
+}
+
+module.exports = {
+  isFirstRun,
+  hasRunBefore,
+  markAsRun,
+  printWelcome,
+  printFirstRunHint,
+  printFirstRunIntroIfNeeded
+};

package/src/guardian/flag-validator.js

@@ -1,111 +1,111 @@
-/**
- * Guardian Flag Validation
- * Early validation of flags and options to catch errors before module load.
- */
-
-const VALID_SUBCOMMANDS = [
-  'init', 'protect', 'reality', 'attempt', 'baseline',
-  'presets', 'template', 'list', 'cleanup', 'evaluate', 'version', 'flow', 'scan', 'smoke', 'check',
-  'journey-scan', 'journey', 'live', 'plan', 'upgrade', 'ci', 'feedback',
-  'sites', 'users', 'audit', 'export', 'recipe'
-];
-
-const VALID_GLOBAL_FLAGS = [
-  '--help', '-h', '--version', '-v', '--debug'
-];
-
-const VALID_SUBCOMMAND_FLAGS = {
-  'scan': ['--url', '--preset', '--artifacts', '--policy', '--headful', '--no-trace', '--no-screenshots', '--watch', '-w', '--fast', '--fail-fast', '--timeout-profile', '--attempts', '--parallel', '--help', '-h'],
-  'journey-scan': ['--url', '--preset', '--out', '--artifacts', '--timeout', '--headful', '--help', '-h'],
-  'journey': ['--url', '--preset', '--out', '--artifacts', '--timeout', '--headful', '--help', '-h'],
-  'live': ['--url', '--preset', '--out', '--artifacts', '--timeout', '--interval', '--cooldown', '--headful', '--help', '-h'],
-  'protect': ['--url', '--policy', '--webhook', '--watch', '-w', '--fast', '--fail-fast', '--timeout-profile', '--attempts', '--parallel', '--help', '-h'],
-  'reality': ['--url', '--attempts', '--artifacts', '--policy', '--preset', '--discover', '--universal', '--webhook', '--headful', '--watch', '-w', '--no-trace', '--no-screenshots', '--fast', '--fail-fast', '--timeout-profile', '--parallel', '--help', '-h', '--max-pages', '--max-depth', '--timeout'],
-  'attempt': ['--url', '--attempt', '--artifacts', '--headful', '--no-trace', '--no-screenshots', '--help', '-h'],
-  'smoke': ['--url', '--headful', '--budget-ms', '--help', '-h'],
-  'check': ['--url', '--headful', '--budget-ms', '--help', '-h'],
-  'baseline': [],
-  'init': ['--preset', '--help', '-h'],
-  'list': ['--artifacts', '--failed', '--site', '--limit', '--help', '-h'],
-  'cleanup': ['--artifacts', '--older-than', '--keep-latest', '--failed-only', '--help', '-h'],
-  'presets': ['--help', '-h'],
-  'template': ['--output', '--help', '-h'],
-  'sites': ['--project', '--help', '-h'],
-  'users': ['--help', '-h'],
-  'audit': ['--limit', '--action', '--user', '--help', '-h'],
-  'export': ['--format', '--output', '--help', '-h'],
-  'recipe': ['--url', '--file', '--out', '--force', '--help', '-h']
-};
-
-function validateFlags(argv) {
-  const args = argv.slice(2);
-  if (args.length === 0) return { valid: true };
-
-  const subcommand = args[0];
-
-  // Check if it's a global flag or help
-  if (VALID_GLOBAL_FLAGS.includes(subcommand)) {
-    return { valid: true };
-  }
-
-  // Check if subcommand is valid
-  if (subcommand && !subcommand.startsWith('-') && !VALID_SUBCOMMANDS.includes(subcommand)) {
-    return {
-      valid: false,
-      error: `Unknown command '${subcommand}'`,
-      hint: `Valid commands: ${VALID_SUBCOMMANDS.slice(0, 5).join(', ')}, …`
-    };
-  }
-
-  // If we have a valid subcommand, validate its flags
-  if (VALID_SUBCOMMANDS.includes(subcommand)) {
-    const validFlags = VALID_SUBCOMMAND_FLAGS[subcommand] || [];
-    const subArgs = args.slice(1);
-
-    for (let i = 0; i < subArgs.length; i++) {
-      const arg = subArgs[i];
-      if (arg.startsWith('--') || arg.startsWith('-')) {
-        const flagName = arg.split('=')[0]; // Handle --flag=value
-        if (!validFlags.includes(flagName)) {
-          return {
-            valid: false,
-            error: `Unknown flag '${flagName}' for command '${subcommand}'`,
-            hint: `Run 'guardian ${subcommand} --help' for valid options.`
-          };
-        }
-        // Check if flag expects a value
-        if ((flagName.includes('--') && !arg.includes('=')) || (flagName === '-w')) {
-          const expectsValue = ![
-            '--headful', '--watch', '-w', '--discover', '--universal',
-            '--no-trace', '--no-screenshots', '--help', '-h', '--fast', '--fail-fast'
-          ].includes(flagName);
-
-          if (expectsValue && i + 1 < subArgs.length && subArgs[i + 1].startsWith('-')) {
-            return {
-              valid: false,
-              error: `Flag '${flagName}' requires a value`,
-              hint: `Usage: guardian ${subcommand} ${flagName} <value>`
-            };
-          }
-        }
-      }
-    }
-  }
-
-  return { valid: true };
-}
-
-function reportFlagError(validation) {
-  if (!validation.valid) {
-    console.error(`Error: ${validation.error}`);
-    if (validation.hint) {
-      console.error(`Hint:  ${validation.hint}`);
-    }
-  }
-}
-
-module.exports = {
-  validateFlags,
-  reportFlagError,
-  VALID_SUBCOMMANDS
-};
+/**
+ * Guardian Flag Validation
+ * Early validation of flags and options to catch errors before module load.
+ */
+
+const VALID_SUBCOMMANDS = [
+  'init', 'protect', 'reality', 'attempt', 'baseline',
+  'presets', 'template', 'list', 'cleanup', 'evaluate', 'version', 'flow', 'scan', 'smoke', 'check',
+  'journey-scan', 'journey', 'live', 'plan', 'upgrade', 'ci', 'feedback',
+  'sites', 'users', 'audit', 'export', 'recipe'
+];
+
+const VALID_GLOBAL_FLAGS = [
+  '--help', '-h', '--version', '-v', '--debug'
+];
+
+const VALID_SUBCOMMAND_FLAGS = {
+  'scan': ['--url', '--preset', '--artifacts', '--policy', '--headful', '--no-trace', '--no-screenshots', '--watch', '-w', '--fast', '--fail-fast', '--timeout-profile', '--attempts', '--parallel', '--help', '-h'],
+  'journey-scan': ['--url', '--preset', '--out', '--artifacts', '--timeout', '--headful', '--help', '-h'],
+  'journey': ['--url', '--preset', '--out', '--artifacts', '--timeout', '--headful', '--help', '-h'],
+  'live': ['--url', '--preset', '--out', '--artifacts', '--timeout', '--interval', '--cooldown', '--headful', '--help', '-h'],
+  'protect': ['--url', '--policy', '--webhook', '--watch', '-w', '--fast', '--fail-fast', '--timeout-profile', '--attempts', '--parallel', '--help', '-h'],
+  'reality': ['--url', '--attempts', '--artifacts', '--policy', '--preset', '--discover', '--universal', '--webhook', '--headful', '--watch', '-w', '--no-trace', '--no-screenshots', '--fast', '--fail-fast', '--timeout-profile', '--parallel', '--help', '-h', '--max-pages', '--max-depth', '--timeout'],
+  'attempt': ['--url', '--attempt', '--artifacts', '--headful', '--no-trace', '--no-screenshots', '--help', '-h'],
+  'smoke': ['--url', '--headful', '--budget-ms', '--help', '-h'],
+  'check': ['--url', '--headful', '--budget-ms', '--help', '-h'],
+  'baseline': [],
+  'init': ['--preset', '--help', '-h'],
+  'list': ['--artifacts', '--failed', '--site', '--limit', '--help', '-h'],
+  'cleanup': ['--artifacts', '--older-than', '--keep-latest', '--failed-only', '--help', '-h'],
+  'presets': ['--help', '-h'],
+  'template': ['--output', '--help', '-h'],
+  'sites': ['--project', '--help', '-h'],
+  'users': ['--help', '-h'],
+  'audit': ['--limit', '--action', '--user', '--help', '-h'],
+  'export': ['--format', '--output', '--help', '-h'],
+  'recipe': ['--url', '--file', '--out', '--force', '--help', '-h']
+};
+
+function validateFlags(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0) return { valid: true };
+
+  const subcommand = args[0];
+
+  // Check if it's a global flag or help
+  if (VALID_GLOBAL_FLAGS.includes(subcommand)) {
+    return { valid: true };
+  }
+
+  // Check if subcommand is valid
+  if (subcommand && !subcommand.startsWith('-') && !VALID_SUBCOMMANDS.includes(subcommand)) {
+    return {
+      valid: false,
+      error: `Unknown command '${subcommand}'`,
+      hint: `Valid commands: ${VALID_SUBCOMMANDS.slice(0, 5).join(', ')}, …`
+    };
+  }
+
+  // If we have a valid subcommand, validate its flags
+  if (VALID_SUBCOMMANDS.includes(subcommand)) {
+    const validFlags = VALID_SUBCOMMAND_FLAGS[subcommand] || [];
+    const subArgs = args.slice(1);
+
+    for (let i = 0; i < subArgs.length; i++) {
+      const arg = subArgs[i];
+      if (arg.startsWith('--') || arg.startsWith('-')) {
+        const flagName = arg.split('=')[0]; // Handle --flag=value
+        if (!validFlags.includes(flagName)) {
+          return {
+            valid: false,
+            error: `Unknown flag '${flagName}' for command '${subcommand}'`,
+            hint: `Run 'guardian ${subcommand} --help' for valid options.`
+          };
+        }
+        // Check if flag expects a value
+        if ((flagName.includes('--') && !arg.includes('=')) || (flagName === '-w')) {
+          const expectsValue = ![
+            '--headful', '--watch', '-w', '--discover', '--universal',
+            '--no-trace', '--no-screenshots', '--help', '-h', '--fast', '--fail-fast'
+          ].includes(flagName);
+
+          if (expectsValue && i + 1 < subArgs.length && subArgs[i + 1].startsWith('-')) {
+            return {
+              valid: false,
+              error: `Flag '${flagName}' requires a value`,
+              hint: `Usage: guardian ${subcommand} ${flagName} <value>`
+            };
+          }
+        }
+      }
+    }
+  }
+
+  return { valid: true };
+}
+
+function reportFlagError(validation) {
+  if (!validation.valid) {
+    console.error(`Error: ${validation.error}`);
+    if (validation.hint) {
+      console.error(`Hint:  ${validation.hint}`);
+    }
+  }
+}
+
+module.exports = {
+  validateFlags,
+  reportFlagError,
+  VALID_SUBCOMMANDS
+};