sdd-full 4.6.2 → 4.8.0

package/skills/flutter-skills/tool/generator/lib/src/commands/update_readme_command.dart

@@ -0,0 +1,150 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:logging/logging.dart';
+import 'package:path/path.dart' as p;
+
+import '../models/skill_params.dart';
+import 'base_yaml_command.dart';
+
+/// Command to update the README.md file with a table of available skills.
+class UpdateReadmeCommand extends BaseYamlCommand {
+  /// Creates a new [UpdateReadmeCommand].
+  UpdateReadmeCommand({super.outputDir})
+    : super(logger: Logger('UpdateReadmeCommand')) {
+    argParser.addOption(
+      'readme',
+      help: 'Path to the README.md file to update.',
+    );
+  }
+
+  @override
+  String get name => 'update-readme';
+
+  @override
+  String get description =>
+      'Updates the README.md with a table of available skills from the configuration.';
+
+  @override
+  Future<void> runWithSkills(
+    List<SkillParams> skills,
+    Directory outputDir, {
+    Directory? configDir,
+  }) async {
+    String readmePath;
+    if (argResults?['readme'] != null) {
+      readmePath = argResults!['readme'] as String;
+    } else if (argResults!.rest.length > 1) {
+      readmePath = argResults!.rest[1];
+    } else {
+      final dirReadme = File(p.join(outputDir.path, 'README.md'));
+      final parentReadme = File(p.join(outputDir.parent.path, 'README.md'));
+
+      if (dirReadme.existsSync()) {
+        readmePath = dirReadme.path;
+      } else if (parentReadme.existsSync()) {
+        readmePath = parentReadme.path;
+      } else {
+        readmePath = 'README.md';
+      }
+    }
+
+    final readmeFile = File(readmePath);
+
+    if (!readmeFile.existsSync()) {
+      logger.severe('README file not found at $readmePath');
+      return;
+    }
+
+    logger.info('Updating README at ${readmeFile.path}...');
+
+    final content = readmeFile.readAsStringSync();
+
+    // Parse existing example prompts from the README if they exist
+    final existingPrompts = <String, String>{};
+    final tableLineRegex = RegExp(
+      r'^\| \[([^\]]+)\]\([^)]+\) \| [^|]+ \| ([^|]+) \|',
+      multiLine: true,
+    );
+    for (final match in tableLineRegex.allMatches(content)) {
+      final skillName = match.group(1)!;
+      final prompt = match.group(2)!.trim();
+      if (prompt.isNotEmpty) {
+        existingPrompts[skillName] = prompt;
+      }
+    }
+
+    // Generate the table
+    final buffer = StringBuffer()
+      ..writeln('| Skill | Description | Example prompt |')
+      ..writeln('|---|---|---|');
+
+    // Sort skills by name for consistency
+    final sortedSkills = List<SkillParams>.from(skills)
+      ..sort((a, b) => a.name.compareTo(b.name));
+
+    for (final skill in sortedSkills) {
+      // Calculate relative link from README to the SKILL.md file
+      final skillFile = File(p.join(outputDir.path, skill.name, 'SKILL.md'));
+      var relativeLink = p.relative(
+        skillFile.path,
+        from: readmeFile.parent.path,
+      );
+
+      // Ensure the link contains the skills/ directory in the URL.
+      if (!relativeLink.contains('skills/')) {
+        relativeLink = p.join('skills', relativeLink);
+      }
+
+      // Ensure we use forward slashes for the markdown link.
+      relativeLink = relativeLink.replaceAll('\\', '/');
+
+      final prompt = skill.examplePrompt ?? existingPrompts[skill.name] ?? '';
+
+      buffer.writeln(
+        '| [${skill.name}]($relativeLink) | ${skill.description} | $prompt |',
+      );
+    }
+
+    final newTable = buffer.toString();
+
+    // Find where to insert the table
+    final sectionRegex = RegExp(
+      '^## (Available Skills|List of Skills|Skills List|Skill Index)',
+      caseSensitive: false,
+      multiLine: true,
+    );
+    final match = sectionRegex.firstMatch(content);
+
+    String updatedContent;
+    if (match != null) {
+      // Find the end of the line with the header
+      final headerEnd = content.indexOf('\n', match.start);
+      // Find the next section header or end of file
+      final nextSectionIndex = content.indexOf(
+        RegExp(r'\n##\s', multiLine: true),
+        headerEnd + 1,
+      );
+
+      final prefix = content.substring(
+        0,
+        headerEnd == -1 ? content.length : headerEnd + 1,
+      );
+      final suffix = nextSectionIndex != -1
+          ? content.substring(nextSectionIndex)
+          : '';
+
+      updatedContent = '${prefix.trimRight()}\n\n$newTable${suffix.trimLeft()}';
+    } else {
+      // Add a new section at the end
+      updatedContent =
+          '${content.trimRight()}\n\n## Available Skills\n\n$newTable';
+    }
+
+    readmeFile.writeAsStringSync('${updatedContent.trimRight()}\n');
+    logger.info('Successfully updated $readmePath');
+  }
+}

package/skills/flutter-skills/tool/generator/lib/src/commands/update_skill_command.dart

@@ -0,0 +1,97 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:logging/logging.dart';
+import 'package:path/path.dart' as p;
+
+import '../models/skill_params.dart';
+import '../services/gemini_service.dart';
+import '../services/resource_fetcher_service.dart';
+import 'base_skill_command.dart';
+
+/// Command to update skills from a configuration file, preserving existing content.
+class UpdateSkillCommand extends BaseSkillCommand {
+  /// Creates a new [UpdateSkillCommand].
+  UpdateSkillCommand({
+    required super.httpClient,
+    super.outputDir,
+    super.environment,
+  }) : super(logger: Logger('UpdateSkillCommand'));
+
+  @override
+  String get name => 'update-skill';
+
+  @override
+  String get description =>
+      'Updates an existing skill by combining its current content with fetched resources and new instructions.';
+
+  @override
+  Future<void> runSkill(
+    SkillParams skill,
+    GeminiService gemini,
+    Directory outputDir,
+    int thinkingBudget, {
+    Directory? configDir,
+  }) async {
+    logger.info('Updating skill: ${skill.name}...');
+
+    final skillFile = File(p.join(outputDir.path, skill.name, 'SKILL.md'));
+    if (!skillFile.existsSync()) {
+      logger.severe(
+        '  Skill file not found at ${skillFile.path}. Cannot update an non-existent skill.',
+      );
+      return;
+    }
+
+    try {
+      final existingContent = skillFile.readAsStringSync();
+
+      final fetcher = ResourceFetcherService(
+        httpClient: httpClient,
+        logger: logger,
+      );
+      final combinedMarkdown = await fetcher.fetchAndConvertContent(
+        skill.resources,
+        configDir: configDir,
+      );
+
+      if (combinedMarkdown.isEmpty) {
+        logger.warning('  No content fetched for ${skill.name}. Skipping.');
+        return;
+      }
+
+      final dryRun = argResults?['dry-run'] as bool? ?? false;
+      if (dryRun) {
+        logger
+          ..info('  [DRY RUN] Would update skill: ${skill.name}')
+          ..info(
+            '  [DRY RUN] Original file size: ${existingContent.split(' ').length} tokens -> Raw content size: ${combinedMarkdown.split(' ').length} tokens.',
+          );
+        return;
+      }
+
+      final generatedContent = await gemini.updateSkillContent(
+        existingContent,
+        combinedMarkdown,
+        skill.name,
+        skill.description,
+        instructions: skill.instructions,
+        thinkingBudget: thinkingBudget,
+      );
+
+      if (generatedContent != null && generatedContent.isNotEmpty) {
+        skillFile.writeAsStringSync(generatedContent);
+        logger.info(
+          '  Updated ${p.join(outputDir.path, skill.name, 'SKILL.md')}',
+        );
+      } else {
+        logger.severe('  Failed to update content for ${skill.name}');
+      }
+    } on Exception catch (e) {
+      logger.severe('  Error processing ${skill.name}: $e');
+    }
+  }
+}

package/skills/flutter-skills/tool/generator/lib/src/commands/validate_skill_command.dart

@@ -0,0 +1,284 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:logging/logging.dart';
+import 'package:path/path.dart' as p;
+import 'package:yaml/yaml.dart';
+
+import '../models/skill_params.dart';
+import '../services/gemini_service.dart';
+import '../services/resource_fetcher_service.dart';
+import 'base_skill_command.dart';
+
+/// Command to validate skills by re-generating and comparing with existing skills.
+class ValidateSkillCommand extends BaseSkillCommand {
+  /// Creates a new [ValidateSkillCommand].
+  ValidateSkillCommand({
+    required super.httpClient,
+    super.outputDir,
+    super.environment,
+    this.validationDir,
+  }) : super(logger: Logger('ValidateSkillCommand'));
+
+  /// The directory to output validation reports.
+  final Directory? validationDir;
+
+  @override
+  String get name => 'validate-skill';
+
+  @override
+  String get description =>
+      'Validates skills using existing skill files and yaml configuration.';
+
+  @override
+  Future<void> run() async {
+    final inputFile = argResults!.rest.isNotEmpty
+        ? argResults!.rest.first
+        : 'resources/flutter_skills.yaml';
+
+    final file = File(inputFile);
+    if (!file.existsSync()) {
+      logger.severe('Configuration file not found: $inputFile');
+      return;
+    }
+
+    final yamlContent = file.readAsStringSync();
+    YamlList yamlList;
+    try {
+      final decoded = loadYaml(yamlContent);
+      if (decoded is! YamlList) {
+        logger.severe('Invalid configuration: Root must be a YAML list.');
+        return;
+      }
+      yamlList = decoded;
+    } on Object catch (e) {
+      logger.severe('Invalid YAML syntax in $inputFile: $e');
+      return;
+    }
+
+    final isValid = _validateYamlStructure(yamlList, p.basename(file.path));
+    if (!isValid) {
+      logger.severe('Configuration validation failed.');
+      return;
+    }
+
+    await super.run();
+  }
+
+  bool _validateYamlStructure(YamlList yamlList, String fileName) {
+    if (yamlList.isEmpty) {
+      logger.severe('Configuration list must not be empty.');
+      return false;
+    }
+
+    var isValid = true;
+    final kabobCase = RegExp(r'^[a-z0-9]+(-[a-z0-9]+)*$');
+
+    for (var i = 0; i < yamlList.length; i++) {
+      final item = yamlList[i];
+      if (item is! Map) {
+        logger.severe('Item $i is not a Map.');
+        isValid = false;
+        continue;
+      }
+
+      final rawName = item['name'];
+      final name = rawName is String ? rawName : 'Item $i';
+      if (rawName == null) {
+        logger.severe('Item $i is missing required field "name".');
+        isValid = false;
+      } else if (rawName is! String) {
+        logger.severe('Item $i field "name" must be a string.');
+        isValid = false;
+      }
+
+      final rawDescription = item['description'];
+      if (rawDescription == null) {
+        logger.severe('Skill "$name" is missing required field "description".');
+        isValid = false;
+      } else if (rawDescription is! String) {
+        logger.severe('Skill "$name" field "description" must be a string.');
+        isValid = false;
+      }
+
+      if (item['resources'] == null) {
+        logger.severe('Skill "$name" is missing required field "resources".');
+        isValid = false;
+      }
+
+      if (item['instructions'] != null && item['instructions'] is! String) {
+        logger.severe('Skill "$name" field "instructions" must be a string.');
+        isValid = false;
+      }
+
+      if (rawName is String) {
+        if (!kabobCase.hasMatch(name)) {
+          logger.severe(
+            'Skill name "$name" must be kabob-case (e.g. abc-def).',
+          );
+          isValid = false;
+        }
+
+        if (fileName == 'flutter_skills.yaml') {
+          if (!name.startsWith('flutter-')) {
+            logger.severe(
+              'Skill name "$name" in flutter_skills.yaml must start with "flutter-".',
+            );
+            isValid = false;
+          }
+        } else if (fileName == 'dart_skills.yaml') {
+          if (!name.startsWith('dart-')) {
+            logger.severe(
+              'Skill name "$name" in dart_skills.yaml must start with "dart-".',
+            );
+            isValid = false;
+          }
+        }
+      }
+
+      final resources = item['resources'];
+      if (resources != null) {
+        if (resources is! List) {
+          logger.severe('Skill "$name" field "resources" must be a list.');
+          isValid = false;
+        } else if (resources.isEmpty) {
+          logger.severe('Skill "$name" field "resources" must not be empty.');
+          isValid = false;
+        } else {
+          for (final resource in resources) {
+            if (resource is! String) {
+              logger.severe('Skill "$name" resource must be a string.');
+              isValid = false;
+            } else {
+              if (resource.contains('://') &&
+                  !resource.startsWith('https://')) {
+                logger.severe(
+                  'Skill "$name" resource URL "$resource" must use secure HTTPS.',
+                );
+                isValid = false;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    return isValid;
+  }
+
+  @override
+  Future<void> runSkill(
+    SkillParams skill,
+    GeminiService gemini,
+    Directory outputDir,
+    int thinkingBudget, {
+    Directory? configDir,
+  }) async {
+    logger.info('Validating skill: ${skill.name}...');
+
+    try {
+      // Re-generate markdown content
+      final fetcher = ResourceFetcherService(
+        httpClient: httpClient,
+        logger: logger,
+      );
+      final markdown = await fetcher.fetchAndConvertContent(
+        skill.resources,
+        configDir: configDir,
+      );
+
+      if (markdown.isEmpty) {
+        logger.warning(
+          '  No content fetched for ${skill.name}. Skipping validation.',
+        );
+        return;
+      }
+
+      // Read existing content
+      final existingSkillFile = File(
+        p.join(outputDir.path, skill.name, 'SKILL.md'),
+      );
+      if (!existingSkillFile.existsSync()) {
+        logger.warning(
+          '  Existing skill file not found at ${existingSkillFile.path}',
+        );
+        return;
+      }
+
+      final existingSkillFileContent = existingSkillFile.readAsStringSync();
+
+      // Check for verbatim name
+      final namePattern = RegExp(
+        'name:\\s*["\']?${RegExp.escape(skill.name)}["\']?',
+      );
+      if (!namePattern.hasMatch(existingSkillFileContent)) {
+        logger.severe(
+          '  Validation Failed: Skill name mismatch in ${existingSkillFile.path}. '
+          'Expected "name: ${skill.name}" (quotes allowed)',
+        );
+      }
+
+      // Extract metadata from existing content
+      final generationDate =
+          RegExp(
+            'last_modified: (.*)',
+          ).firstMatch(existingSkillFileContent)?.group(1) ??
+          'Unknown';
+      final modelName =
+          RegExp(
+            'model: (.*)',
+          ).firstMatch(existingSkillFileContent)?.group(1) ??
+          'Unknown';
+
+      // Compare
+      final dryRun = argResults?['dry-run'] as bool? ?? false;
+      if (dryRun) {
+        logger
+          ..info('  [DRY RUN] Would validate skill: ${skill.name}')
+          ..info(
+            '  [DRY RUN] existing file size: ${existingSkillFileContent.split(' ').length} tokens -> new fetched content size: ${markdown.split(' ').length} tokens.',
+          );
+        return;
+      }
+
+      logger.info('  Comparing versions...');
+      final result = await gemini.validateExistingSkillContent(
+        markdown,
+        skill.name,
+        skill.instructions ?? 'No instructions provided',
+        generationDate,
+        modelName,
+        existingSkillFileContent,
+        thinkingBudget: thinkingBudget,
+      );
+
+      if (result != null) {
+        final valDirBase = validationDir ?? Directory('validation');
+        final valDir = Directory(p.join(valDirBase.path, skill.name));
+        if (!valDir.existsSync()) {
+          valDir.createSync(recursive: true);
+        }
+
+        File(p.join(valDir.path, 'validation.md')).writeAsStringSync(result);
+
+        // Extract and log the grade
+        final gradeMatch = RegExp(r'Grade:\s*(\d+)').firstMatch(result);
+        final grade = gradeMatch?.group(1);
+
+        logger.info(
+          '  Validation report written to ${p.join(valDir.path, 'validation.md')} '
+          '${grade != null ? '(Grade: $grade)' : ''}',
+        );
+      } else {
+        logger.severe(
+          '  Failed to generate validation report for ${skill.name}',
+        );
+      }
+    } on Exception catch (e) {
+      logger.severe('  Error validating ${skill.name}: $e');
+    }
+  }
+}

package/skills/flutter-skills/tool/generator/lib/src/models/skill_params.dart

@@ -0,0 +1,41 @@
+// Copyright (c) 2026, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// Parameters for generating a skill from resources.
+class SkillParams {
+  /// Creates a new [SkillParams] instance.
+  SkillParams({
+    required this.name,
+    required this.description,
+    required this.resources,
+    this.instructions,
+    this.examplePrompt,
+  });
+
+  /// Creates a [SkillParams] instance from a JSON map.
+  factory SkillParams.fromJson(Map<String, dynamic> json) {
+    return SkillParams(
+      name: json['name'] as String,
+      description: json['description'] as String,
+      resources: (json['resources'] as List).cast<String>(),
+      instructions: json['instructions'] as String?,
+      examplePrompt: json['examplePrompt'] as String?,
+    );
+  }
+
+  /// The name of the skill.
+  final String name;
+
+  /// The description of the skill.
+  final String description;
+
+  /// The example prompt for the skill.
+  final String? examplePrompt;
+
+  /// Optional instructions for generating the skill.
+  final String? instructions;
+
+  /// The resources to fetch content from.
+  final List<String> resources;
+}