@dewtech/dare-cli 3.10.0 → 3.12.0

package/skills/dare-ax/generator.ts

@@ -0,0 +1,325 @@
+/**
+ * dare-ax — DareAxGenerator
+ * Generates llms.txt at project root using the Jinja2-style template.
+ * License: MIT
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { ProjectConfig } from './types.js';
+import { containsSecrets } from './secret-detector.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_TEMPLATE_PATH = path.join(__dirname, 'templates', 'llms.txt.jinja2');
+
+/**
+ * Renders a Jinja2-style template with simple variable substitution.
+ * Supports: {{ variable }}, {% for x in list %}...{% endfor %},
+ * {% if condition %}...{% endif %}, {% if cond %}...{% else %}...{% endif %}
+ *
+ * Uses a token-based approach to avoid regex nesting issues.
+ */
+function renderTemplate(templateContent: string, context: Record<string, unknown>): string {
+  return renderWithContext(templateContent, context);
+}
+
+/**
+ * Tokenizes the template into literal strings and tag tokens, then evaluates them.
+ * This avoids the regex-ordering / nesting problems of sequential replacements.
+ */
+function renderWithContext(template: string, context: Record<string, unknown>): string {
+  const tokens = tokenize(template);
+  const result = evaluate(tokens, context, 0);
+  return result.output;
+}
+
+type Token =
+  | { type: 'text'; value: string }
+  | { type: 'var'; name: string }
+  | { type: 'for'; varName: string; listName: string }
+  | { type: 'endfor' }
+  | { type: 'if'; condName: string }
+  | { type: 'else' }
+  | { type: 'endif' };
+
+/** Splits the template into text and tag tokens */
+function tokenize(template: string): Token[] {
+  const tokens: Token[] = [];
+  let pos = 0;
+
+  while (pos < template.length) {
+    // Find next tag {{ or {%
+    const varStart = template.indexOf('{{', pos);
+    const tagStart = template.indexOf('{%', pos);
+
+    let next: number;
+    let isVar: boolean;
+
+    if (varStart === -1 && tagStart === -1) {
+      // No more tags — rest is text
+      tokens.push({ type: 'text', value: template.slice(pos) });
+      break;
+    } else if (varStart === -1) {
+      next = tagStart;
+      isVar = false;
+    } else if (tagStart === -1) {
+      next = varStart;
+      isVar = true;
+    } else {
+      next = Math.min(varStart, tagStart);
+      isVar = varStart < tagStart;
+    }
+
+    // Emit text before the tag
+    if (next > pos) {
+      tokens.push({ type: 'text', value: template.slice(pos, next) });
+    }
+
+    if (isVar) {
+      // {{ varname }}
+      const end = template.indexOf('}}', next + 2);
+      if (end === -1) {
+        tokens.push({ type: 'text', value: template.slice(next) });
+        break;
+      }
+      const name = template.slice(next + 2, end).trim();
+      tokens.push({ type: 'var', name });
+      pos = end + 2;
+    } else {
+      // {% tag ... %}
+      const end = template.indexOf('%}', next + 2);
+      if (end === -1) {
+        tokens.push({ type: 'text', value: template.slice(next) });
+        break;
+      }
+      const inner = template.slice(next + 2, end).trim();
+      pos = end + 2;
+
+      if (inner.startsWith('for ')) {
+        const m = /^for\s+(\w+)\s+in\s+([\w.]+)$/.exec(inner);
+        if (m) {
+          tokens.push({ type: 'for', varName: m[1], listName: m[2] });
+        }
+      } else if (inner === 'endfor') {
+        tokens.push({ type: 'endfor' });
+      } else if (inner.startsWith('if ')) {
+        const condName = inner.slice(3).trim();
+        tokens.push({ type: 'if', condName });
+      } else if (inner === 'else') {
+        tokens.push({ type: 'else' });
+      } else if (inner === 'endif') {
+        tokens.push({ type: 'endif' });
+      }
+      // Unknown tags are ignored
+    }
+  }
+
+  return tokens;
+}
+
+/** Evaluates a token list starting at `startIdx`. Returns the rendered output and next index. */
+function evaluate(
+  tokens: Token[],
+  context: Record<string, unknown>,
+  startIdx: number
+): { output: string; nextIdx: number } {
+  let output = '';
+  let i = startIdx;
+
+  while (i < tokens.length) {
+    const token = tokens[i];
+
+    if (token.type === 'text') {
+      output += token.value;
+      i++;
+    } else if (token.type === 'var') {
+      // {{ varname }} — resolve from context
+      const direct = context[token.name];
+      if (direct !== undefined && direct !== null) {
+        output += String(direct);
+      } else {
+        const val = getNestedValue(context, token.name);
+        if (val !== undefined && val !== null) output += String(val);
+      }
+      i++;
+    } else if (token.type === 'for') {
+      // Collect the for-body tokens until matching endfor
+      const bodyStart = i + 1;
+      let depth = 1;
+      let j = bodyStart;
+      while (j < tokens.length && depth > 0) {
+        if (tokens[j].type === 'for') depth++;
+        if (tokens[j].type === 'endfor') depth--;
+        if (depth > 0) j++;
+        else break;
+      }
+      const bodyTokens = tokens.slice(bodyStart, j);
+
+      const list = getNestedValue(context, token.listName);
+      if (Array.isArray(list)) {
+        for (const item of list) {
+          const itemContext: Record<string, unknown> = { ...context };
+          if (typeof item === 'object' && item !== null) {
+            itemContext[token.varName] = item;
+            for (const [k, v] of Object.entries(item as Record<string, unknown>)) {
+              itemContext[`${token.varName}.${k}`] = v;
+            }
+          } else {
+            itemContext[token.varName] = item;
+          }
+          output += evaluate(bodyTokens, itemContext, 0).output;
+        }
+      }
+      i = j + 1; // skip endfor
+    } else if (token.type === 'if') {
+      // Collect then-body and optional else-body until matching endif
+      const condName = token.condName;
+      const bodyStart = i + 1;
+      let depth = 1;
+      let j = bodyStart;
+      let elseIdx = -1;
+
+      while (j < tokens.length && depth > 0) {
+        if (tokens[j].type === 'if') depth++;
+        if (tokens[j].type === 'endif') depth--;
+        if (depth === 1 && tokens[j].type === 'else') elseIdx = j;
+        if (depth > 0) j++;
+        else break;
+      }
+      const endifIdx = j;
+
+      const thenTokens =
+        elseIdx >= 0
+          ? tokens.slice(bodyStart, elseIdx)
+          : tokens.slice(bodyStart, endifIdx);
+      const elseTokens =
+        elseIdx >= 0 ? tokens.slice(elseIdx + 1, endifIdx) : [];
+
+      const condValue = getNestedValue(context, condName);
+      if (isTruthy(condValue)) {
+        output += evaluate(thenTokens, context, 0).output;
+      } else {
+        output += evaluate(elseTokens, context, 0).output;
+      }
+      i = endifIdx + 1; // skip endif
+    } else if (token.type === 'else' || token.type === 'endif' || token.type === 'endfor') {
+      // These are consumed by the parent for/if handler above; if we hit them here, stop.
+      break;
+    } else {
+      i++;
+    }
+  }
+
+  return { output, nextIdx: i };
+}
+
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  return path.split('.').reduce((current: unknown, key: string) => {
+    if (current !== null && typeof current === 'object') {
+      return (current as Record<string, unknown>)[key];
+    }
+    return undefined;
+  }, obj as unknown);
+}
+
+function isTruthy(value: unknown): boolean {
+  if (Array.isArray(value)) return value.length > 0;
+  if (value === null || value === undefined) return false;
+  if (typeof value === 'string') return value.length > 0;
+  return Boolean(value);
+}
+
+/**
+ * Converts a ProjectConfig into the template context object.
+ */
+function buildContext(config: ProjectConfig): Record<string, unknown> {
+  return {
+    project_overview: config.projectOverview,
+    language: config.language,
+    framework: config.framework,
+    database: config.database,
+    key_dependencies: config.keyDependencies,
+    architecture_description: config.architectureDescription,
+    directory_structure: config.directoryStructure ?? defaultDirectoryStructure(config),
+    endpoints: config.endpoints ?? [],
+    config_file: config.configFile ?? 'config.json',
+    has_docker: config.hasDocker ?? false,
+    has_makefile: config.hasMakefile ?? false,
+    has_taskfile: config.hasTaskfile ?? false,
+    getting_started_command: config.gettingStartedCommand ?? 'make dev',
+    rate_limits: config.rateLimits ?? [
+      { scope: 'Public endpoints', limit: 100 },
+      { scope: 'Auth endpoints', limit: 10 },
+    ],
+    extra_security_notes: config.extraSecurityNotes ?? [],
+    cli_binary: config.cliBinary ?? config.name,
+    agent_notes: config.agentNotes ?? [],
+  };
+}
+
+function defaultDirectoryStructure(config: ProjectConfig): string {
+  const src = config.language === 'Ruby' ? 'app' : 'src';
+  return `${src}/
+├── handlers/      # HTTP handlers / controllers
+├── services/      # Business logic
+├── models/        # Data structures
+├── repositories/  # Database access
+└── utils/         # Utilities`;
+}
+
+export class DareAxGenerator {
+  private readonly templatePath: string;
+
+  constructor(templatePath?: string) {
+    this.templatePath = templatePath ?? DEFAULT_TEMPLATE_PATH;
+  }
+
+  /**
+   * Generates llms.txt in the project root.
+   * Throws if generated content would contain secrets.
+   *
+   * @param projectPath - Absolute path to the project root.
+   * @param config - Project configuration.
+   * @returns Absolute path to the generated file.
+   */
+  generateLlmsTxt(projectPath: string, config: ProjectConfig): string {
+    if (config.axNotApplicable) {
+      throw new Error(
+        'ax: not-applicable is set for this project. Skipping llms.txt generation.'
+      );
+    }
+
+    const templateContent = fs.readFileSync(this.templatePath, 'utf-8');
+    const context = buildContext(config);
+    const rendered = renderTemplate(templateContent, context);
+
+    // Security check: no secrets in rendered content
+    const secretCheck = containsSecrets(rendered);
+    if (secretCheck.found) {
+      throw new Error(
+        `dare-ax: Secret detected in llms.txt content (${secretCheck.pattern}). ` +
+          `Remove secrets before generating. llms.txt is a public file.`
+      );
+    }
+
+    const outputPath = path.join(projectPath, 'llms.txt');
+    fs.writeFileSync(outputPath, rendered, 'utf-8');
+
+    return outputPath;
+  }
+
+  /**
+   * Returns the rendered llms.txt content WITHOUT writing to disk.
+   * Useful for previewing or testing.
+   */
+  renderLlmsTxt(config: ProjectConfig): string {
+    if (config.axNotApplicable) {
+      throw new Error('ax: not-applicable is set; rendering skipped.');
+    }
+
+    const templateContent = fs.readFileSync(this.templatePath, 'utf-8');
+    const context = buildContext(config);
+    return renderTemplate(templateContent, context);
+  }
+}

package/skills/dare-ax/index.ts

@@ -0,0 +1,19 @@
+/**
+ * dare-ax — Agent Experience (AX) skill
+ * Codifies best practices for AI-assisted development.
+ * License: MIT
+ */
+
+export { DareAxGenerator } from './generator.js';
+export { DareAxValidator } from './validator.js';
+export { DareAxMetrics } from './metrics.js';
+export { containsSecrets, findAllSecrets } from './secret-detector.js';
+export type {
+  ProjectConfig,
+  ValidationResult,
+  ValidationError,
+  ValidationWarning,
+  MetricResult,
+  RateLimit,
+  Endpoint,
+} from './types.js';

package/skills/dare-ax/metrics.ts

@@ -0,0 +1,352 @@
+/**
+ * dare-ax — DareAxMetrics
+ * Collects M-01 to M-04 metrics for a project.
+ * License: MIT
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { MetricResult } from './types.js';
+import { DareAxValidator } from './validator.js';
+
+/**
+ * Known rate-limit library identifiers, checked in:
+ * - package.json / Gemfile / Cargo.toml / go.mod / requirements.txt / composer.json
+ * - Source files (middleware setup patterns)
+ */
+const RATE_LIMIT_LIBRARIES: Array<{ name: string; pattern: RegExp }> = [
+  // Ruby / Rails
+  { name: 'rack-attack', pattern: /rack-attack/i },
+  // Node.js
+  { name: 'express-rate-limit', pattern: /express-rate-limit/i },
+  { name: '@nestjs/throttler', pattern: /@nestjs\/throttler/i },
+  { name: 'rate-limiter-flexible', pattern: /rate-limiter-flexible/i },
+  { name: 'limiter', pattern: /["']limiter["']/ },
+  // Rust
+  { name: 'tower-governor', pattern: /tower-governor/i },
+  { name: 'axum-ratelimit', pattern: /axum-ratelimit/i },
+  // Python
+  { name: 'slowapi', pattern: /slowapi/i },
+  { name: 'limits', pattern: /["']limits["']/ },
+  { name: 'django-ratelimit', pattern: /django-ratelimit/i },
+  // Go
+  { name: 'golang.org/x/time/rate', pattern: /golang\.org\/x\/time\/rate/i },
+  { name: 'ulule/limiter', pattern: /ulule\/limiter/i },
+  // PHP
+  { name: 'laravel-rate-limiting', pattern: /throttle:/i },
+  // Generic middleware patterns in source
+  { name: 'RateLimit middleware', pattern: /rate[_-]?limit/i },
+];
+
+/** Known CLI JSON flag patterns to look for in source code */
+const JSON_FLAG_PATTERNS: RegExp[] = [
+  /--json/,
+  /['"]json['"]\s*,.*flag/i,
+  /\.option\(['"]-?-?json/i,
+  /jsonOutput/i,
+  /output.*json/i,
+  /format.*json/i,
+];
+
+export class DareAxMetrics {
+  private readonly validator: DareAxValidator;
+
+  constructor() {
+    this.validator = new DareAxValidator();
+  }
+
+  /**
+   * Collects all four metrics for the given project path.
+   *
+   * @param projectPath - Absolute path to the project root.
+   * @returns Array of MetricResult for M-01 to M-04.
+   */
+  collect(projectPath: string): MetricResult[] {
+    return [
+      this.collectM01(projectPath),
+      this.collectM02(projectPath),
+      this.collectM03(projectPath),
+      this.collectM04(projectPath),
+    ];
+  }
+
+  /**
+   * M-01: llms.txt exists and is valid (no secrets, required sections present).
+   */
+  collectM01(projectPath: string): MetricResult {
+    const llmsTxtPath = path.join(projectPath, 'llms.txt');
+
+    if (!fs.existsSync(llmsTxtPath)) {
+      return {
+        id: 'M-01',
+        pass: false,
+        description: 'llms.txt exists and is valid',
+        detail: `llms.txt not found at ${llmsTxtPath}`,
+      };
+    }
+
+    const result = this.validator.validate(llmsTxtPath);
+
+    if (!result.valid) {
+      const errorSummary = result.errors.map((e) => e.message).join('; ');
+      return {
+        id: 'M-01',
+        pass: false,
+        description: 'llms.txt exists and is valid',
+        detail: `Validation failed: ${errorSummary}`,
+      };
+    }
+
+    const warningSummary =
+      result.warnings.length > 0
+        ? ` (${result.warnings.length} warnings: ${result.warnings.map((w) => w.code).join(', ')})`
+        : '';
+
+    return {
+      id: 'M-01',
+      pass: true,
+      description: 'llms.txt exists and is valid',
+      detail: `Valid${warningSummary}`,
+    };
+  }
+
+  /**
+   * M-02: openapi.json exists (checks public/openapi.json and openapi.json).
+   */
+  collectM02(projectPath: string): MetricResult {
+    const candidates = [
+      path.join(projectPath, 'public', 'openapi.json'),
+      path.join(projectPath, 'openapi.json'),
+      path.join(projectPath, 'static', 'openapi.json'),
+      path.join(projectPath, 'docs', 'openapi.json'),
+      path.join(projectPath, 'api', 'openapi.json'),
+      // Also support YAML variants
+      path.join(projectPath, 'openapi.yaml'),
+      path.join(projectPath, 'openapi.yml'),
+      path.join(projectPath, 'public', 'openapi.yaml'),
+    ];
+
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        return {
+          id: 'M-02',
+          pass: true,
+          description: 'OpenAPI specification exists',
+          detail: `Found at ${path.relative(projectPath, candidate)}`,
+        };
+      }
+    }
+
+    return {
+      id: 'M-02',
+      pass: false,
+      description: 'OpenAPI specification exists',
+      detail:
+        'No openapi.json or openapi.yaml found in project root, public/, static/, docs/, or api/ directories.',
+    };
+  }
+
+  /**
+   * M-03: CLI supports --json flag.
+   * Searches source code for --json flag definitions.
+   */
+  collectM03(projectPath: string): MetricResult {
+    const sourceExtensions = ['.ts', '.js', '.mjs', '.rb', '.rs', '.py', '.go', '.php'];
+    const searchDirs = [
+      path.join(projectPath, 'src'),
+      path.join(projectPath, 'lib'),
+      path.join(projectPath, 'app'),
+      path.join(projectPath, 'cmd'),
+      path.join(projectPath, 'bin'),
+      path.join(projectPath, 'cli'),
+    ];
+
+    // Search for --json pattern in CLI-related source files
+    for (const dir of searchDirs) {
+      if (!fs.existsSync(dir)) continue;
+
+      const found = searchDirectoryForPattern(dir, JSON_FLAG_PATTERNS, sourceExtensions, 3);
+      if (found) {
+        return {
+          id: 'M-03',
+          pass: true,
+          description: 'CLI supports --json flag',
+          detail: `Found --json flag pattern in ${path.relative(projectPath, found)}`,
+        };
+      }
+    }
+
+    // Also check root-level bin files
+    const rootBinCandidates = findFilesWithPattern(projectPath, /^(cli|main|index|app)\.(ts|js|rb|rs|py|go)$/, 1);
+    for (const file of rootBinCandidates) {
+      if (fileMatchesAnyPattern(file, JSON_FLAG_PATTERNS)) {
+        return {
+          id: 'M-03',
+          pass: true,
+          description: 'CLI supports --json flag',
+          detail: `Found --json flag pattern in ${path.relative(projectPath, file)}`,
+        };
+      }
+    }
+
+    return {
+      id: 'M-03',
+      pass: false,
+      description: 'CLI supports --json flag',
+      detail:
+        'No --json flag detected in CLI source files. Add --json output flag to CLI commands (see dare-ax ADR-04).',
+    };
+  }
+
+  /**
+   * M-04: Rate limit configuration detected.
+   * Checks package manifests and source code.
+   */
+  collectM04(projectPath: string): MetricResult {
+    // Check package manifests
+    const manifests = [
+      { file: path.join(projectPath, 'package.json'), key: 'dependencies' },
+      { file: path.join(projectPath, 'package.json'), key: 'devDependencies' },
+      { file: path.join(projectPath, 'Gemfile'), key: null },
+      { file: path.join(projectPath, 'Cargo.toml'), key: null },
+      { file: path.join(projectPath, 'go.mod'), key: null },
+      { file: path.join(projectPath, 'requirements.txt'), key: null },
+      { file: path.join(projectPath, 'composer.json'), key: null },
+      { file: path.join(projectPath, 'pyproject.toml'), key: null },
+    ];
+
+    for (const { file } of manifests) {
+      if (!fs.existsSync(file)) continue;
+
+      try {
+        const content = fs.readFileSync(file, 'utf-8');
+        for (const { name, pattern } of RATE_LIMIT_LIBRARIES) {
+          if (pattern.test(content)) {
+            return {
+              id: 'M-04',
+              pass: true,
+              description: 'Rate limit configuration detected',
+              detail: `Found rate limit library "${name}" in ${path.relative(projectPath, file)}`,
+            };
+          }
+        }
+      } catch {
+        // Skip unreadable files
+      }
+    }
+
+    // Search source directories for rate limit patterns
+    const sourceDirs = [
+      path.join(projectPath, 'src'),
+      path.join(projectPath, 'lib'),
+      path.join(projectPath, 'app'),
+      path.join(projectPath, 'config'),
+    ];
+
+    const rateLimitPatterns = RATE_LIMIT_LIBRARIES.map((l) => l.pattern);
+
+    for (const dir of sourceDirs) {
+      if (!fs.existsSync(dir)) continue;
+
+      const found = searchDirectoryForPattern(
+        dir,
+        rateLimitPatterns,
+        ['.ts', '.js', '.rb', '.rs', '.py', '.go', '.php'],
+        4
+      );
+
+      if (found) {
+        return {
+          id: 'M-04',
+          pass: true,
+          description: 'Rate limit configuration detected',
+          detail: `Found rate limit pattern in ${path.relative(projectPath, found)}`,
+        };
+      }
+    }
+
+    return {
+      id: 'M-04',
+      pass: false,
+      description: 'Rate limit configuration detected',
+      detail:
+        'No rate limit library or middleware detected. ' +
+        'Add rate limiting (rack-attack, express-rate-limit, tower-governor, etc.) to protect public endpoints.',
+    };
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Recursively searches a directory for files matching given patterns.
+ * Returns the first matching file path, or null.
+ */
+function searchDirectoryForPattern(
+  dir: string,
+  patterns: RegExp[],
+  extensions: string[],
+  maxDepth: number,
+  currentDepth = 0
+): string | null {
+  if (currentDepth > maxDepth) return null;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'target' || entry.name === 'dist') {
+      continue;
+    }
+
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      const found = searchDirectoryForPattern(fullPath, patterns, extensions, maxDepth, currentDepth + 1);
+      if (found) return found;
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name);
+      if (!extensions.includes(ext)) continue;
+
+      if (fileMatchesAnyPattern(fullPath, patterns)) {
+        return fullPath;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Reads a file and returns true if any of the patterns match its content.
+ */
+function fileMatchesAnyPattern(filePath: string, patterns: RegExp[]): boolean {
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return false;
+  }
+
+  return patterns.some((p) => p.test(content));
+}
+
+/**
+ * Returns files in a directory (non-recursive) whose names match the given pattern.
+ */
+function findFilesWithPattern(dir: string, namePattern: RegExp, _maxDepth: number): string[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter((e) => e.isFile() && namePattern.test(e.name))
+    .map((e) => path.join(dir, e.name));
+}