sdd-full 4.6.2 → 4.8.0

package/skills/flutter-skills/tool/generator/lib/src/services/gemini_service.dart

@@ -0,0 +1,310 @@
+// 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' as io;
+
+import 'package:google_cloud_ai_generativelanguage_v1beta/generativelanguage.dart';
+import 'package:http/http.dart' as http;
+import 'package:logging/logging.dart';
+import 'package:meta/meta.dart';
+import 'package:retry/retry.dart';
+
+import 'prompts.dart';
+import 'skill_instructions.dart';
+
+/// Service for interacting with the Gemini API to generate and validate skills.
+class GeminiService {
+  /// Creates a new [GeminiService].
+  GeminiService({
+    required String apiKey,
+    http.Client? httpClient,
+    String? model,
+  }) : _model = model ?? defaultModel,
+       _client = _ApiKeyClient(httpClient ?? http.Client(), apiKey);
+
+  /// 0.2 is a good temperature for technical material.
+  static const double defaultTemperature = 0.2;
+
+  /// The default model to use for generation.
+  static const String defaultModel = 'models/gemini-3.1-pro-preview';
+
+  /// The default token budget for thinking.
+  static const int defaultThinkingBudget = 4096;
+
+  /// The default max output tokens for generation.
+  static const int defaultMaxOutputTokens = 8192;
+
+  /// The default safety settings to use for generation.
+  static final List<SafetySetting> defaultSafetySettings = [
+    SafetySetting(
+      category: HarmCategory.harmCategoryDangerousContent,
+      threshold: SafetySetting_HarmBlockThreshold.blockOnlyHigh,
+    ),
+    SafetySetting(
+      category: HarmCategory.harmCategoryHateSpeech,
+      threshold: SafetySetting_HarmBlockThreshold.blockOnlyHigh,
+    ),
+    SafetySetting(
+      category: HarmCategory.harmCategoryHarassment,
+      threshold: SafetySetting_HarmBlockThreshold.blockOnlyHigh,
+    ),
+    SafetySetting(
+      category: HarmCategory.harmCategorySexuallyExplicit,
+      threshold: SafetySetting_HarmBlockThreshold.blockOnlyHigh,
+    ),
+  ];
+
+  final String _model;
+  final http.Client _client;
+  final Logger _logger = Logger('GeminiService');
+
+  /// Generates the content for a skill based on raw markdown input.
+  Future<String?> generateSkillContent(
+    String rawMarkdown,
+    String skillName,
+    String description, {
+    String? instructions,
+    int thinkingBudget = defaultThinkingBudget,
+  }) async {
+    final service = GenerativeService(client: _client);
+    final lastModified = io.HttpDate.format(DateTime.now());
+    final prompt = Prompts.createSkillPrompt(rawMarkdown, instructions);
+
+    final request = _createRequest(
+      prompt,
+      systemInstruction: skillInstructions,
+      thinkingBudget: thinkingBudget,
+    );
+
+    _logger.info(
+      '  Model: $_model, Max Output Tokens: $defaultMaxOutputTokens, Thinking Budget: $thinkingBudget',
+    );
+
+    try {
+      const r = RetryOptions(maxAttempts: 3);
+      final response = await r.retry(() async {
+        final res = await service.generateContent(request);
+        final text = res.candidates.first.content?.parts
+            .where((part) => !part.thought)
+            .map((part) => part.text)
+            .where((text) => text != null)
+            .join('\n');
+
+        if (text == null || text.isEmpty) {
+          throw const FormatException('Empty response from Gemini');
+        }
+
+        return text;
+      }, onRetry: (e) => _logger.warning('Retrying Gemini generation: $e'));
+
+      final content = response;
+
+      final frontmatter =
+          '''---
+name: $skillName
+description: $description
+metadata:
+  model: $_model
+  last_modified: $lastModified
+---
+''';
+
+      return frontmatter + (cleanContent(content) ?? '');
+    } on Object catch (e) {
+      _logger.severe('Gemini generation failed: $e');
+      return null;
+    }
+  }
+
+  /// Updates the content for a skill based on raw markdown input and existing content.
+  Future<String?> updateSkillContent(
+    String existingContent,
+    String rawMarkdown,
+    String skillName,
+    String description, {
+    String? instructions,
+    int thinkingBudget = defaultThinkingBudget,
+  }) async {
+    final service = GenerativeService(client: _client);
+    final lastModified = io.HttpDate.format(DateTime.now());
+    final prompt = Prompts.updateSkillPrompt(
+      existingContent,
+      rawMarkdown,
+      instructions,
+    );
+
+    final request = _createRequest(
+      prompt,
+      systemInstruction: skillInstructions,
+      thinkingBudget: thinkingBudget,
+    );
+
+    _logger.info(
+      '  Model: $_model, Max Output Tokens: $defaultMaxOutputTokens, Thinking Budget: $thinkingBudget',
+    );
+
+    try {
+      const r = RetryOptions(maxAttempts: 3);
+      final response = await r.retry(() async {
+        final res = await service.generateContent(request);
+        final text = res.candidates.first.content?.parts
+            .where((part) => !part.thought)
+            .map((part) => part.text)
+            .where((text) => text != null)
+            .join('\n');
+
+        if (text == null || text.isEmpty) {
+          throw const FormatException('Empty response from Gemini');
+        }
+
+        return text;
+      }, onRetry: (e) => _logger.warning('Retrying Gemini generation: $e'));
+
+      final content = response;
+
+      final frontmatter =
+          '''---
+name: $skillName
+description: $description
+metadata:
+  model: $_model
+  last_modified: $lastModified
+---
+''';
+
+      return frontmatter + (cleanContent(content) ?? '');
+    } on Object catch (e) {
+      _logger.severe('Gemini update failed: $e');
+      return null;
+    }
+  }
+
+  /// Validates an existing skill
+  Future<String?> validateExistingSkillContent(
+    String markdown,
+    String skillName,
+    String instructions,
+    String generationDate,
+    String modelName,
+    String currentSkillContent, {
+    int thinkingBudget = defaultThinkingBudget,
+  }) async {
+    final service = GenerativeService(client: _client);
+    final validationPrompt = Prompts.validateExistingSkillContentPrompt(
+      markdown,
+      instructions,
+      generationDate,
+      modelName,
+      currentSkillContent,
+    );
+
+    final request = _createRequest(
+      validationPrompt,
+      systemInstruction: skillInstructions,
+      thinkingBudget: thinkingBudget,
+    );
+
+    _logger.info(
+      '  Model: $_model, Max Output Tokens: $defaultMaxOutputTokens, Thinking Budget: $thinkingBudget',
+    );
+
+    try {
+      const r = RetryOptions(maxAttempts: 3);
+      final response = await r.retry(() async {
+        final res = await service.generateContent(request);
+        final text = res.candidates.first.content?.parts
+            .where((part) => !part.thought)
+            .map((part) => part.text)
+            .where((text) => text != null)
+            .join('\n');
+
+        if (text == null || text.isEmpty) {
+          throw const FormatException('Empty response from Gemini');
+        }
+
+        return text;
+      }, onRetry: (e) => _logger.warning('Retrying Gemini validation: $e'));
+
+      return response;
+    } on Object catch (e) {
+      _logger.severe('Gemini validation failed: $e');
+      return null;
+    }
+  }
+
+  /// Cleans the generated content by removing markdown code blocks and frontmatter.
+  @visibleForTesting
+  String? cleanContent(String? content) {
+    if (content == null) return null;
+    var cleaned = content;
+    final startMatch = RegExp(
+      r'^\s*```[a-zA-Z]*\s*\n',
+      caseSensitive: false,
+    ).firstMatch(cleaned);
+    if (startMatch != null) {
+      cleaned = cleaned.substring(startMatch.end);
+      // Remove the last triple backticks if they exist
+      cleaned = cleaned.replaceAll(RegExp(r'\n```\s*$'), '');
+    }
+
+    final yamlStartIndex = cleaned.indexOf('---');
+    if (yamlStartIndex == 0) {
+      // Possible frontmatter, skip it
+      final end = cleaned.indexOf('---', 3);
+      if (end != -1) {
+        cleaned = cleaned.substring(end + 3).trim();
+      }
+    } else if (yamlStartIndex > 0) {
+      // Maybe noise before frontmatter, try to strip it if it looks like frontmatter
+      final end = cleaned.indexOf('---', yamlStartIndex + 3);
+      if (end != -1) {
+        cleaned = cleaned.substring(end + 3).trim();
+      }
+    }
+
+    // Ensure one trailing newline
+    return '${cleaned.trim()}\n';
+  }
+
+  GenerateContentRequest _createRequest(
+    String prompt, {
+    String? systemInstruction,
+    int thinkingBudget = defaultThinkingBudget,
+  }) {
+    return GenerateContentRequest(
+      model: _model,
+      systemInstruction: systemInstruction != null
+          ? Content(parts: [Part(text: systemInstruction)])
+          : null,
+      contents: [
+        Content(parts: [Part(text: prompt)]),
+      ],
+      // See [GenerationConfig] in package:google_cloud_ai_generativelanguage_v1beta
+      generationConfig: GenerationConfig(
+        temperature: defaultTemperature,
+        maxOutputTokens: defaultMaxOutputTokens,
+        thinkingConfig: thinkingBudget > 0
+            ? ThinkingConfig(
+                includeThoughts: true,
+                thinkingBudget: thinkingBudget,
+              )
+            : null,
+      ),
+      safetySettings: defaultSafetySettings,
+    );
+  }
+}
+
+class _ApiKeyClient extends http.BaseClient {
+  _ApiKeyClient(this._inner, this._apiKey);
+
+  final http.Client _inner;
+  final String _apiKey;
+
+  @override
+  Future<http.StreamedResponse> send(http.BaseRequest request) {
+    request.headers['x-goog-api-key'] = _apiKey;
+    return _inner.send(request);
+  }
+}

package/skills/flutter-skills/tool/generator/lib/src/services/markdown_converter.dart

@@ -0,0 +1,226 @@
+// 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 'package:html/dom.dart';
+import 'package:html/parser.dart';
+
+/// Converts HTML content to Markdown.
+class MarkdownConverter {
+  /// Converts HTML content to Markdown.
+  String convert(String htmlContent) {
+    final document = parse(htmlContent);
+    final body = document.body;
+    if (body == null) return '';
+    return _convertElement(body).trim();
+  }
+
+  String _convertElement(Element element) {
+    final buffer = StringBuffer();
+
+    for (final node in element.nodes) {
+      if (node is Text) {
+        buffer.write(node.text);
+      } else if (node is Element) {
+        buffer.write(_processTag(node));
+      }
+    }
+
+    return buffer.toString();
+  }
+
+  String _processTag(Element element) {
+    final content = _convertElement(element);
+
+    switch (element.localName) {
+      case 'h1':
+        return '\n# $content\n\n';
+      case 'h2':
+        return '\n## $content\n\n';
+      case 'h3':
+        return '\n### $content\n\n';
+      case 'h4':
+        return '\n#### $content\n\n';
+      case 'h5':
+        return '\n##### $content\n\n';
+      case 'h6':
+        return '\n###### $content\n\n';
+      case 'p':
+        return '$content\n\n';
+      case 'a':
+        final href = element.attributes['href'];
+        return '[$content]($href)';
+      case 'strong':
+      case 'b':
+        return '**$content**';
+      case 'em':
+      case 'i':
+        return '*$content*';
+      case 'del':
+      case 's':
+      case 'strike':
+        return '~~$content~~';
+      case 'code':
+        return '`$content`';
+      case 'pre':
+        return '\n```\n${element.text}\n```\n\n';
+      case 'blockquote':
+        return '\n> $content\n\n';
+      case 'hr':
+        return '\n---\n\n';
+      case 'ul':
+        return '\n$content\n';
+      case 'ol':
+        return '\n$content\n';
+      case 'li':
+        return '- $content\n';
+      case 'img':
+        final src = element.attributes['src'] ?? '';
+        final alt = element.attributes['alt'] ?? '';
+        return '![$alt]($src)';
+      case 'video':
+        final src = element.attributes['src'] ?? '';
+        final poster = element.attributes['poster'] ?? '';
+        final title = element.attributes['title'] ?? 'Video';
+
+        String? videoUrl;
+        if (src.isNotEmpty) {
+          videoUrl = src;
+        } else {
+          // Fallback for source elements
+          videoUrl = element.children
+              .where((e) => e.localName == 'source')
+              .map((e) => e.attributes['src'])
+              .firstWhere((s) => s != null, orElse: () => null);
+        }
+
+        if (videoUrl != null) {
+          if (poster.isNotEmpty) {
+            return '[![$title]($poster)]($videoUrl)';
+          }
+          return '[$title]($videoUrl)';
+        }
+        return '';
+      case 'iframe':
+        final src = element.attributes['src'] ?? '';
+        final title = element.attributes['title'] ?? 'Iframe';
+        if (src.isNotEmpty) {
+          return '[$title]($src)';
+        }
+        return '';
+      case 'table':
+        return _processTable(element);
+      case 'dl':
+        return _processDefinitionList(element);
+      case 'dt':
+        return '\n**$content**\n';
+      case 'dd':
+        return ': $content\n';
+      case 'details':
+        // Preserve details as HTML, but convert children to markdown?
+        // Or just preserve the tag structure and convert internal content.
+        // Let's try to preserve the tag but convert content.
+        return '\n<details>\n$content\n</details>\n';
+      case 'summary':
+        return '<summary>$content</summary>';
+      case 'br':
+        return '\n';
+      case 'div':
+      case 'section':
+      case 'main':
+      case 'article':
+        return '$content\n';
+      default:
+        return content;
+    }
+  }
+
+  String _processTable(Element table) {
+    // Simple table converter
+    // 1. Find headers (th)
+    // 2. Find rows (tr)
+    // 3. Construct markdown table
+
+    final buffer = StringBuffer('\n');
+    var headerCells = <Element>[];
+    final bodyRows = <Element>[];
+
+    final theads = table.children.where((e) => e.localName == 'thead').toList();
+    if (theads.isNotEmpty) {
+      final headerRows = theads.first.children
+          .where((e) => e.localName == 'tr')
+          .toList();
+      if (headerRows.isNotEmpty) {
+        final headerRow = headerRows.first;
+        headerCells = headerRow.children
+            .where((e) => e.localName == 'th')
+            .toList();
+        if (headerCells.isEmpty) {
+          headerCells = headerRow.children
+              .where((e) => e.localName == 'td')
+              .toList();
+        }
+      }
+    }
+
+    for (final child in table.children) {
+      if (child.localName == 'tbody' || child.localName == 'tfoot') {
+        bodyRows.addAll(child.children.where((e) => e.localName == 'tr'));
+      } else if (child.localName == 'tr') {
+        bodyRows.add(child);
+      }
+    }
+
+    // Promote first row to header if needed
+    if (headerCells.isEmpty && bodyRows.isNotEmpty) {
+      final firstRow = bodyRows.first;
+      headerCells = firstRow.children
+          .where((e) => e.localName == 'th')
+          .toList();
+      if (headerCells.isEmpty) {
+        headerCells = firstRow.children
+            .where((e) => e.localName == 'td')
+            .toList();
+      }
+      bodyRows.removeAt(0);
+    }
+
+    if (headerCells.isEmpty && bodyRows.isEmpty) return '';
+
+    // Write Header
+    buffer.write('|');
+    for (final cell in headerCells) {
+      buffer.write(' ${_convertElement(cell).trim()} |');
+    }
+    buffer.write('\n|');
+    for (var i = 0; i < headerCells.length; i++) {
+      buffer.write('---|');
+    }
+    buffer.write('\n');
+
+    // Write Body
+    for (final row in bodyRows) {
+      final cells = row.children
+          .where((e) => e.localName == 'td' || e.localName == 'th')
+          .toList();
+      if (cells.isEmpty) continue;
+      buffer.write('|');
+      for (final cell in cells) {
+        buffer.write(' ${_convertElement(cell).trim()} |');
+      }
+      buffer.write('\n');
+    }
+    buffer.write('\n');
+
+    return buffer.toString();
+  }
+
+  String _processDefinitionList(Element dl) {
+    final buffer = StringBuffer('\n');
+    for (final child in dl.children) {
+      buffer.write(_processTag(child));
+    }
+    buffer.write('\n\n');
+    return buffer.toString();
+  }
+}

package/skills/flutter-skills/tool/generator/lib/src/services/prompts.dart

@@ -0,0 +1,72 @@
+// 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.
+
+// ignore_for_file: avoid_classes_with_only_static_members
+
+/// Manages prompts used by the GeminiService.
+class Prompts {
+  /// Creates the prompt for generating a new skill.
+  static String createSkillPrompt(String markdown, String? instructions) {
+    return '''
+Rewrite the following technical documentation into a high-quality "SKILL.md" file.
+
+${instructions != null && instructions.isNotEmpty ? 'Special Instructions: $instructions' : ''}
+
+Raw Content:
+$markdown
+''';
+  }
+
+  /// Creates the prompt for updating an existing skill.
+  static String updateSkillPrompt(
+    String existingContent,
+    String markdown,
+    String? instructions,
+  ) {
+    return '''
+Update the following existing "SKILL.md" file using the provided new technical documentation.
+Carefully integrate the new information without losing valuable existing instructions or context.
+
+${instructions != null && instructions.isNotEmpty ? 'Special Instructions: $instructions' : ''}
+
+Existing SKILL.md Content:
+$existingContent
+
+New Technical Documentation (Raw Content):
+$markdown
+''';
+  }
+
+  /// Creates the prompt for validating an existing skill.
+  static String validateExistingSkillContentPrompt(
+    String markdown,
+    String instructions,
+    String generationDate,
+    String modelName,
+    String currentSkillContent,
+  ) {
+    return '''
+Validate the following skill document against the provided source material and verify if it is valid.
+Focus on accuracy, structure, and completeness based on the Source Material and the system instructions.
+
+Context:
+- The skill was originally generated on: $generationDate
+- The current evaluation is using model: $modelName
+- The instructions used to generate the skill were:
+$instructions
+
+Source Material:
+$markdown
+
+Current Skill Content:
+  "$currentSkillContent"
+---
+
+Grade the current output based on the instructions and the comparison to current website content and instructions today.
+Establish a conclusion on whether the new skill is valid or not.
+Reasons for a good or bad quality grade should be provided including concepts such as missing content, different model used, more than a few months old, etc.
+On the very last line, output "Grade: [0-100]" representing overall quality of the skill compared to the assumed value if it were generated again today.
+''';
+  }
+}

package/skills/flutter-skills/tool/generator/lib/src/services/resource_fetcher_service.dart

@@ -0,0 +1,84 @@
+// 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' as io;
+
+import 'package:http/http.dart' as http;
+import 'package:logging/logging.dart';
+import 'package:path/path.dart' as p;
+
+import 'markdown_converter.dart';
+
+/// Fetches and converts content from diverse resources.
+class ResourceFetcherService {
+  /// Creates a new [ResourceFetcherService].
+  ResourceFetcherService({
+    required http.Client httpClient,
+    required Logger logger,
+  }) : _httpClient = httpClient,
+       _logger = logger;
+
+  final http.Client _httpClient;
+  final Logger _logger;
+
+  /// Fetches and converts content from a list of resources.
+  ///
+  /// Throws an [Exception] if fetching any resource fails. This strict behavior
+  /// prevents wasting tokens on generating low-quality skills when
+  /// source material is missing.
+  Future<String> fetchAndConvertContent(
+    List<String> resources, {
+    io.Directory? configDir,
+  }) async {
+    final converter = MarkdownConverter();
+    final sb = StringBuffer();
+    for (final resource in resources) {
+      _logger.info('  Fetching $resource...');
+
+      if (resource.startsWith('http://')) {
+        throw Exception(
+          'Insecure HTTP URL found: $resource. '
+          'Only HTTPS URLs or relative file paths are allowed.',
+        );
+      }
+
+      if (resource.startsWith('https://')) {
+        final response = await _httpClient.get(Uri.parse(resource));
+        if (response.statusCode == 200) {
+          sb
+            ..writeln('--- Raw content from $resource ---')
+            ..writeln(converter.convert(response.body));
+        } else {
+          throw Exception(
+            'Failed to fetch $resource: HTTP ${response.statusCode}. '
+            'Failing fast to save Gemini tokens.',
+          );
+        }
+      } else {
+        if (configDir == null) {
+          throw Exception(
+            'Relative resource "$resource" found, but no configuration '
+            'directory was provided to resolve it.',
+          );
+        }
+        final file = io.File(p.join(configDir.path, resource));
+        if (!file.existsSync()) {
+          throw Exception('Local resource file not found: ${file.path}');
+        }
+
+        final String content;
+        try {
+          content = file.readAsStringSync();
+        } on io.FileSystemException {
+          throw Exception('Local resource file is not readable: ${file.path}');
+        }
+
+        sb
+          ..writeln('--- Raw content from $resource ---')
+          ..writeln(content);
+      }
+    }
+    return sb.toString();
+  }
+}