diff --git a/docs/skills.mdx b/docs/skills.mdx index 5fec95c7d..6c2b90a11 100644 --- a/docs/skills.mdx +++ b/docs/skills.mdx @@ -7,7 +7,13 @@ Think of Stac Skills as expert assistants that know Stac inside and out. They he ## Installation -Install all Stac skills with one command: +Install all Stac skills natively with the Stac CLI: + +```bash +stac skills add +``` + +Alternatively, you can install them using `npx`: ```bash npx skills add https://github.com/StacDev/stac diff --git a/examples/counter_example/pubspec.lock b/examples/counter_example/pubspec.lock index 7d0a109a8..cebde638e 100644 --- a/examples/counter_example/pubspec.lock +++ b/examples/counter_example/pubspec.lock @@ -141,10 +141,10 @@ packages: dependency: transitive description: name: characters - sha256: faf38497bda5ead2a8c7615f4f7939df04333478bf32e4173fcb06d428b5716b + sha256: f71061c654a3380576a52b451dd5532377954cf9dbd272a78fc8479606670803 url: "https://pub.dev" source: hosted - version: "1.4.1" + version: "1.4.0" checked_yaml: dependency: transitive description: @@ -460,26 +460,26 @@ packages: dependency: transitive description: name: matcher - sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861 + sha256: dc58c723c3c24bf8d3e2d3ad3f2f9d7bd9cf43ec6feaa64181775e60190153f2 url: "https://pub.dev" source: hosted - version: "0.12.19" + version: "0.12.17" material_color_utilities: dependency: transitive description: name: material_color_utilities - sha256: "9c337007e82b1889149c82ed242ed1cb24a66044e30979c44912381e9be4c48b" + sha256: f7142bb1154231d7ea5f96bc7bde4bda2a0945d2806bb11670e30b850d56bdec url: "https://pub.dev" source: hosted - version: "0.13.0" + version: "0.11.1" meta: dependency: transitive description: name: meta - sha256: "1741988757a65eb6b36abe716829688cf01910bbf91c34354ff7ec1c3de2b349" + sha256: "23f08335362185a5ea2ad3a4e597f1375e78bce8a040df5c600c8d3552ef2394" url: "https://pub.dev" source: hosted - version: "1.18.0" + version: "1.17.0" mime: dependency: transitive description: @@ -869,10 +869,10 @@ packages: dependency: transitive description: name: test_api - sha256: "949a932224383300f01be9221c39180316445ecb8e7547f70a41a35bf421fb9e" + sha256: ab2726c1a94d3176a45960b6234466ec367179b87dd74f1611adb1f3b5fb9d55 url: "https://pub.dev" source: hosted - version: "0.7.11" + version: "0.7.7" timing: dependency: transitive description: @@ -994,5 +994,5 @@ packages: source: hosted version: "3.1.3" sdks: - dart: ">=3.10.0-0 <4.0.0" + dart: ">=3.9.0 <4.0.0" flutter: ">=3.35.0" diff --git a/examples/movie_app/pubspec.lock b/examples/movie_app/pubspec.lock index 0244df713..951bc1cc0 100644 --- a/examples/movie_app/pubspec.lock +++ b/examples/movie_app/pubspec.lock @@ -117,10 +117,10 @@ packages: dependency: transitive description: name: characters - sha256: faf38497bda5ead2a8c7615f4f7939df04333478bf32e4173fcb06d428b5716b + sha256: f71061c654a3380576a52b451dd5532377954cf9dbd272a78fc8479606670803 url: "https://pub.dev" source: hosted - version: "1.4.1" + version: "1.4.0" checked_yaml: dependency: transitive description: @@ -396,26 +396,26 @@ packages: dependency: transitive description: name: matcher - sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861 + sha256: dc58c723c3c24bf8d3e2d3ad3f2f9d7bd9cf43ec6feaa64181775e60190153f2 url: "https://pub.dev" source: hosted - version: "0.12.19" + version: "0.12.17" material_color_utilities: dependency: transitive description: name: material_color_utilities - sha256: "9c337007e82b1889149c82ed242ed1cb24a66044e30979c44912381e9be4c48b" + sha256: f7142bb1154231d7ea5f96bc7bde4bda2a0945d2806bb11670e30b850d56bdec url: "https://pub.dev" source: hosted - version: "0.13.0" + version: "0.11.1" meta: dependency: transitive description: name: meta - sha256: "1741988757a65eb6b36abe716829688cf01910bbf91c34354ff7ec1c3de2b349" + sha256: "23f08335362185a5ea2ad3a4e597f1375e78bce8a040df5c600c8d3552ef2394" url: "https://pub.dev" source: hosted - version: "1.18.0" + version: "1.17.0" mime: dependency: transitive description: @@ -797,10 +797,10 @@ packages: dependency: transitive description: name: test_api - sha256: "949a932224383300f01be9221c39180316445ecb8e7547f70a41a35bf421fb9e" + sha256: ab2726c1a94d3176a45960b6234466ec367179b87dd74f1611adb1f3b5fb9d55 url: "https://pub.dev" source: hosted - version: "0.7.11" + version: "0.7.7" typed_data: dependency: transitive description: @@ -914,5 +914,5 @@ packages: source: hosted version: "3.1.3" sdks: - dart: ">=3.10.0-0 <4.0.0" + dart: ">=3.9.0 <4.0.0" flutter: ">=3.35.0" diff --git a/examples/stac_gallery/pubspec.lock b/examples/stac_gallery/pubspec.lock index 5770e7929..d7df31d7b 100644 --- a/examples/stac_gallery/pubspec.lock +++ b/examples/stac_gallery/pubspec.lock @@ -125,10 +125,10 @@ packages: dependency: transitive description: name: characters - sha256: faf38497bda5ead2a8c7615f4f7939df04333478bf32e4173fcb06d428b5716b + sha256: f71061c654a3380576a52b451dd5532377954cf9dbd272a78fc8479606670803 url: "https://pub.dev" source: hosted - version: "1.4.1" + version: "1.4.0" checked_yaml: dependency: transitive description: @@ -436,26 +436,26 @@ packages: dependency: transitive description: name: matcher - sha256: dc0b7dc7651697ea4ff3e69ef44b0407ea32c487a39fff6a4004fa585e901861 + sha256: dc58c723c3c24bf8d3e2d3ad3f2f9d7bd9cf43ec6feaa64181775e60190153f2 url: "https://pub.dev" source: hosted - version: "0.12.19" + version: "0.12.17" material_color_utilities: dependency: transitive description: name: material_color_utilities - sha256: "9c337007e82b1889149c82ed242ed1cb24a66044e30979c44912381e9be4c48b" + sha256: f7142bb1154231d7ea5f96bc7bde4bda2a0945d2806bb11670e30b850d56bdec url: "https://pub.dev" source: hosted - version: "0.13.0" + version: "0.11.1" meta: dependency: transitive description: name: meta - sha256: "1741988757a65eb6b36abe716829688cf01910bbf91c34354ff7ec1c3de2b349" + sha256: "23f08335362185a5ea2ad3a4e597f1375e78bce8a040df5c600c8d3552ef2394" url: "https://pub.dev" source: hosted - version: "1.18.0" + version: "1.17.0" mime: dependency: transitive description: @@ -868,10 +868,10 @@ packages: dependency: transitive description: name: test_api - sha256: "949a932224383300f01be9221c39180316445ecb8e7547f70a41a35bf421fb9e" + sha256: ab2726c1a94d3176a45960b6234466ec367179b87dd74f1611adb1f3b5fb9d55 url: "https://pub.dev" source: hosted - version: "0.7.11" + version: "0.7.7" typed_data: dependency: transitive description: @@ -1025,5 +1025,5 @@ packages: source: hosted version: "3.1.3" sdks: - dart: ">=3.10.0-0 <4.0.0" + dart: ">=3.9.0 <4.0.0" flutter: ">=3.35.0" diff --git a/packages/stac_cli/bin/stac_cli.dart b/packages/stac_cli/bin/stac_cli.dart index aabbf704c..ea89ae57a 100644 --- a/packages/stac_cli/bin/stac_cli.dart +++ b/packages/stac_cli/bin/stac_cli.dart @@ -9,6 +9,7 @@ import 'package:stac_cli/src/commands/build_command.dart'; import 'package:stac_cli/src/commands/deploy_command.dart'; import 'package:stac_cli/src/commands/init_command.dart'; import 'package:stac_cli/src/commands/project_command.dart'; +import 'package:stac_cli/src/commands/skills_command.dart'; import 'package:stac_cli/src/commands/upgrade_command.dart'; import 'package:stac_cli/src/config/env.dart'; import 'package:stac_cli/src/exceptions/stac_exception.dart'; @@ -67,6 +68,7 @@ void main(List arguments) async { ..addCommand(ProjectCommand()) ..addCommand(BuildCommand()) ..addCommand(DeployCommand()) + ..addCommand(SkillsCommand()) ..addCommand(UpgradeCommand()); // Add global flags diff --git a/packages/stac_cli/lib/src/commands/init_command.dart b/packages/stac_cli/lib/src/commands/init_command.dart index 3b40a19e6..ab13daed6 100644 --- a/packages/stac_cli/lib/src/commands/init_command.dart +++ b/packages/stac_cli/lib/src/commands/init_command.dart @@ -8,6 +8,7 @@ import '../services/project_service.dart'; import '../utils/console_logger.dart'; import '../utils/file_utils.dart'; import 'base_command.dart'; +import 'skills/add_command.dart'; /// Command for initializing a Stac project from cloud projects class InitCommand extends BaseCommand { @@ -84,6 +85,25 @@ class InitCommand extends BaseCommand { // Create default_stac_options.dart configuration file await _createStacConfigFile(targetDir, project); + // Ask to install skills + final shouldInstallSkills = Confirm( + prompt: + 'Install Stac agent skills? (Recommended for AI-assisted development)', + defaultValue: true, + ).interact(); + if (shouldInstallSkills) { + ConsoleLogger.info('Installing skills...'); + final skillsExitCode = await AddCommand( + targetDirectory: targetDir, + ).execute(); + if (skillsExitCode != 0) { + ConsoleLogger.warning( + 'Skills installation encountered an issue. ' + 'You can retry later with: stac skills add', + ); + } + } + ConsoleLogger.success('✓ Project initialized successfully!'); ConsoleLogger.info('Next steps:'); ConsoleLogger.info(' 1. Add your Stac widgets definitions to /stac'); diff --git a/packages/stac_cli/lib/src/commands/skills/add_command.dart b/packages/stac_cli/lib/src/commands/skills/add_command.dart new file mode 100644 index 000000000..069440cdf --- /dev/null +++ b/packages/stac_cli/lib/src/commands/skills/add_command.dart @@ -0,0 +1,259 @@ +import 'dart:convert'; +import 'dart:io'; + +import 'package:archive/archive_io.dart'; +import 'package:dio/dio.dart'; +import 'package:path/path.dart' as path; + +import '../../utils/console_logger.dart'; +import '../base_command.dart'; + +/// Command to add Stac AI agent skills +class AddCommand extends BaseCommand { + @override + String get name => 'add'; + + @override + String get description => 'Add Stac AI agent skills to your project'; + + @override + bool get requiresAuth => false; + + /// Optional target directory; defaults to [Directory.current]. + final String? targetDirectory; + + AddCommand({this.targetDirectory}); + + @override + Future execute() async { + String repoUrl = 'https://github.com/StacDev/stac'; + + if (argResults?.rest.isNotEmpty == true) { + repoUrl = argResults!.rest.first; + } + + if (!repoUrl.contains('github.com')) { + ConsoleLogger.error('Currently only github.com URLs are supported.'); + return 1; + } + + // Extract owner/repo + final uri = Uri.parse(repoUrl); + final segments = uri.pathSegments; + if (segments.length < 2) { + ConsoleLogger.error('Invalid GitHub URL format.'); + return 1; + } + + final owner = segments[0]; + final repo = segments[1].replaceAll('.git', ''); + + final zipUrl = 'https://github.com/$owner/$repo/archive/HEAD.zip'; + + ConsoleLogger.info('Fetching skills from $repoUrl...'); + + final tempDir = await Directory.systemTemp.createTemp('stac_skills_'); + try { + final dio = Dio(); + final zipFile = File(path.join(tempDir.path, 'repo.zip')); + + await dio.download(zipUrl, zipFile.path); + + // Extract ZIP + final archive = ZipDecoder().decodeBytes(zipFile.readAsBytesSync()); + final extractDir = Directory(path.join(tempDir.path, 'extracted')); + extractArchiveToDisk(archive, extractDir.path); + + // Find skills/catalog.json + // The extracted folder usually has a root folder named - + final rootDirs = extractDir.listSync().whereType().toList(); + if (rootDirs.isEmpty) { + ConsoleLogger.error('Empty repository archive.'); + return 1; + } + + final repoRoot = rootDirs.first; + ConsoleLogger.info('Extracted root: ${repoRoot.path}'); + + final catalogFile = File( + path.join(repoRoot.path, 'skills', 'catalog.json'), + ); + ConsoleLogger.info('Looking for catalog at: ${catalogFile.path}'); + + if (!await catalogFile.exists()) { + ConsoleLogger.error('skills/catalog.json not found in repository.'); + + ConsoleLogger.info('Contents of extracted:'); + for (var e in extractDir.listSync(recursive: true)) { + ConsoleLogger.info(e.path); + } + + return 1; + } + + // Parse catalog.json + final catalogContent = await catalogFile.readAsString(); + final List catalog = jsonDecode(catalogContent); + + final installDir = targetDirectory ?? Directory.current.path; + final targetAgentsDir = Directory( + path.join(installDir, '.agents', 'skills'), + ); + if (!await targetAgentsDir.exists()) { + await targetAgentsDir.create(recursive: true); + } + + // Canonical boundary paths for security checks + final repoRootCanonical = path.canonicalize(repoRoot.path); + final targetCanonical = path.canonicalize(targetAgentsDir.path); + + int installedCount = 0; + for (final skill in catalog) { + if (skill is! Map) { + ConsoleLogger.warning( + 'Skipping invalid catalog entry (not a map): $skill', + ); + continue; + } + final skillName = skill['name']; + final skillPath = skill['path']; + + if (skillName is! String || skillPath is! String) { + ConsoleLogger.warning('Skipping invalid catalog entry: $skill'); + continue; + } + + // Guard against path-traversal in catalog entries + if (containsPathTraversal(skillName) || + containsPathTraversal(skillPath)) { + ConsoleLogger.warning( + 'Skipping skill with suspicious name/path: $skillName / $skillPath', + ); + continue; + } + + final sourceSkillDir = Directory(path.join(repoRoot.path, skillPath)); + + // Ensure the resolved source is still inside the repo root + final sourceCanonical = path.canonicalize(sourceSkillDir.path); + if (!path.equals(repoRootCanonical, sourceCanonical) && + !path.isWithin(repoRootCanonical, sourceCanonical)) { + ConsoleLogger.warning( + 'Skill path $skillPath escapes repo root. Skipping.', + ); + continue; + } + + if (!await sourceSkillDir.exists()) { + ConsoleLogger.warning( + 'Skill directory $skillPath not found, skipping.', + ); + continue; + } + + final targetSkillDir = Directory( + path.join(targetAgentsDir.path, skillName), + ); + + // Ensure the resolved target is still inside .agents/skills + final targetSkillCanonical = path.canonicalize(targetSkillDir.path); + if (!path.equals(targetCanonical, targetSkillCanonical) && + !path.isWithin(targetCanonical, targetSkillCanonical)) { + ConsoleLogger.warning( + 'Skill name $skillName escapes target directory. Skipping.', + ); + continue; + } + + if (await targetSkillDir.exists()) { + await targetSkillDir.delete(recursive: true); + } + await targetSkillDir.create(recursive: true); + + // Copy directory contents + await _copyDirectory( + sourceSkillDir, + targetSkillDir, + sourceCanonical, + targetSkillCanonical, + ); + ConsoleLogger.success('✓ $skillName (copied)'); + installedCount++; + } + + ConsoleLogger.success( + 'Installed $installedCount skills to .agents/skills', + ); + return 0; + } catch (e) { + ConsoleLogger.error('Failed to install skills: $e'); + return 1; + } finally { + // Always clean up temp files regardless of success or failure + if (await tempDir.exists()) { + await tempDir.delete(recursive: true); + } + } + } + + /// Returns true if a name or path segment contains traversal patterns. + bool containsPathTraversal(String value) { + return value.contains('..') || + path.isAbsolute(value) || + value.contains(r'\'); + } + + Future _copyDirectory( + Directory source, + Directory destination, + String sourceRootCanonical, + String destinationRootCanonical, + ) async { + await for (var entity in source.list( + recursive: false, + followLinks: false, + )) { + if (entity is Link) { + ConsoleLogger.warning('Skipping symlink: ${entity.path}'); + continue; + } + + final entityCanonical = path.canonicalize(entity.path); + // Ensure the source entity is within the allowed source root + if (!path.equals(sourceRootCanonical, entityCanonical) && + !path.isWithin(sourceRootCanonical, entityCanonical)) { + ConsoleLogger.warning( + 'Skipping out-of-bounds source entity: ${entity.path}', + ); + continue; + } + + final targetPath = path.join( + destination.path, + path.basename(entity.path), + ); + final targetCanonical = path.canonicalize(targetPath); + // Ensure the destination path is within the allowed target root + if (!path.equals(destinationRootCanonical, targetCanonical) && + !path.isWithin(destinationRootCanonical, targetCanonical)) { + ConsoleLogger.warning( + 'Skipping out-of-bounds destination path: $targetPath', + ); + continue; + } + + if (entity is Directory) { + final newDirectory = Directory(targetPath); + await newDirectory.create(recursive: true); + await _copyDirectory( + entity, + newDirectory, + sourceRootCanonical, + destinationRootCanonical, + ); + } else if (entity is File) { + await entity.copy(targetPath); + } + } + } +} diff --git a/packages/stac_cli/lib/src/commands/skills_command.dart b/packages/stac_cli/lib/src/commands/skills_command.dart new file mode 100644 index 000000000..caabefbfa --- /dev/null +++ b/packages/stac_cli/lib/src/commands/skills_command.dart @@ -0,0 +1,15 @@ +import 'package:args/command_runner.dart'; +import 'skills/add_command.dart'; + +/// Command for managing Stac AI agent skills +class SkillsCommand extends Command { + @override + String get name => 'skills'; + + @override + String get description => 'Manage Stac AI agent skills'; + + SkillsCommand() { + addSubcommand(AddCommand()); + } +} diff --git a/packages/stac_cli/pubspec.lock b/packages/stac_cli/pubspec.lock index 4fe9fd6bf..6b0c6ebd2 100644 --- a/packages/stac_cli/pubspec.lock +++ b/packages/stac_cli/pubspec.lock @@ -17,6 +17,14 @@ packages: url: "https://pub.dev" source: hosted version: "10.0.1" + archive: + dependency: "direct main" + description: + name: archive + sha256: a96e8b390886ee8abb49b7bd3ac8df6f451c621619f52a26e815fdcf568959ff + url: "https://pub.dev" + source: hosted + version: "4.0.9" args: dependency: "direct main" description: @@ -401,6 +409,14 @@ packages: url: "https://pub.dev" source: hosted version: "1.5.2" + posix: + dependency: transitive + description: + name: posix + sha256: "185ef7606574f789b40f289c233efa52e96dead518aed988e040a10737febb07" + url: "https://pub.dev" + source: hosted + version: "6.5.0" pub_semver: dependency: transitive description: diff --git a/packages/stac_cli/pubspec.yaml b/packages/stac_cli/pubspec.yaml index 89c523dde..1e17fb04a 100644 --- a/packages/stac_cli/pubspec.yaml +++ b/packages/stac_cli/pubspec.yaml @@ -18,6 +18,7 @@ dependencies: json_annotation: ^4.11.0 dotenv: ^4.2.0 cryptography: ^2.9.0 + archive: ^4.0.9 # Executables that can be run globally executables: