agent-flutter 0.1.6 → 0.1.8

package/README.md

@@ -70,8 +70,9 @@ npm run release:major
 
 ## Installed files
 
+- Workspace utilities: `spec/`, `tool/`, `tools/`, `.vscode/tasks.json`
 - Trae: `.trae/` (skills/rules/scripts)
-- Codex: `.codex/` + `AGENTS.md`
+- Codex: `.codex/` (skills/rules/scripts) + `AGENTS.md`
 - Cursor: `.cursor/skills/`, `.cursor/rules/shared/`, `.cursor/scripts/`, `.cursor/rules/agent-flutter.mdc`
 - Windsurf: `.windsurf/skills/`, `.windsurf/rules/shared/`, `.windsurf/scripts/`, `.windsurf/rules/agent-flutter.md`
 - Cline: `.clinerules/skills/`, `.clinerules/rules/`, `.clinerules/scripts/`, `.clinerules/agent-flutter.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-flutter",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Portable Flutter skill/rule pack initializer for multiple AI IDEs.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -142,6 +142,7 @@ async function applyPack({
   mode,
 }) {
   const verb = mode === 'sync' ? 'Synced' : 'Installed';
+  const sharedUtilityDirs = ['spec', 'tool', 'tools'];
   const syncDirectory = async ({ sourceDir, destinationDir, label }) => {
     if ((await exists(destinationDir)) && !force) {
       console.log(`Skipped ${label} (exists): ${destinationDir}`);
@@ -155,13 +156,77 @@ async function applyPack({
     });
     console.log(`${verb} ${label}: ${destinationDir}`);
   };
+  const syncTemplateFile = async ({ sourcePath, destinationPath, label }) => {
+    if ((await exists(destinationPath)) && !force) {
+      console.log(`Skipped ${label} (exists): ${destinationPath}`);
+      return;
+    }
+    await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+    if (isTextFile(path.basename(sourcePath))) {
+      const raw = await fs.readFile(sourcePath, 'utf8');
+      const transformed = replaceProjectPlaceholders(raw, projectRoot);
+      await fs.writeFile(destinationPath, transformed, 'utf8');
+    } else {
+      await fs.copyFile(sourcePath, destinationPath);
+    }
+    await copyFileMode(sourcePath, destinationPath);
+    console.log(`${verb} ${label}: ${destinationPath}`);
+  };
+  const syncWorkspaceUtilities = async () => {
+    for (const dirName of sharedUtilityDirs) {
+      await syncDirectory({
+        sourceDir: path.join(templateRoot, dirName),
+        destinationDir: path.join(projectRoot, dirName),
+        label: `Workspace ${dirName}`,
+      });
+    }
+  };
+  const syncWorkspaceVscodeTasks = async () => {
+    const sourcePath = path.join(templateRoot, 'vscode', 'tasks.json');
+    if (!(await exists(sourcePath))) return;
+    const raw = await fs.readFile(sourcePath, 'utf8');
+    const transformed = replaceProjectPlaceholders(raw, projectRoot);
+    const targetPath = path.join(projectRoot, '.vscode', 'tasks.json');
+    const written = await writeTextFile(
+      targetPath,
+      transformed,
+      { force },
+    );
+    console.log(
+      written
+        ? `${verb} Workspace VS Code tasks: ${targetPath}`
+        : `Skipped Workspace VS Code tasks (exists): ${targetPath}`,
+    );
+  };
+  await syncWorkspaceUtilities();
+  await syncWorkspaceVscodeTasks();
 
   if (ideTargets.has('trae')) {
     const traeTarget = path.join(projectRoot, '.trae');
     await syncDirectory({
-      sourceDir: templateRoot,
-      destinationDir: traeTarget,
-      label: 'Trae adapter',
+      sourceDir: path.join(templateRoot, 'skills'),
+      destinationDir: path.join(traeTarget, 'skills'),
+      label: 'Trae skills',
+    });
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'scripts'),
+      destinationDir: path.join(traeTarget, 'scripts'),
+      label: 'Trae scripts',
+    });
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'rules'),
+      destinationDir: path.join(traeTarget, 'rules'),
+      label: 'Trae rules',
+    });
+    await syncTemplateFile({
+      sourcePath: path.join(templateRoot, '.ignore'),
+      destinationPath: path.join(traeTarget, '.ignore'),
+      label: 'Trae ignore',
+    });
+    await syncTemplateFile({
+      sourcePath: path.join(templateRoot, 'TEMPLATES.md'),
+      destinationPath: path.join(traeTarget, 'TEMPLATES.md'),
+      label: 'Trae templates',
     });
   }
 
@@ -334,7 +399,6 @@ async function applyPack({
       });
       console.log(`${verb} GitHub rules: ${githubRulesPath}`);
     }
-
     const githubPath = path.join(projectRoot, '.github', 'copilot-instructions.md');
     const written = await writeTextFile(
       githubPath,

package/templates/shared/tool/generate_model_registry.dart

@@ -0,0 +1,111 @@
+import 'dart:io';
+
+void main() {
+  final projectRoot = Directory.current.path;
+  final modelRoot =
+      Directory('$projectRoot/lib/src/core/model'); // absolute at runtime
+
+  final uiDomainFiles = <File>[];
+  final requestFiles = <File>[];
+  final responseFiles = <File>[];
+
+  if (!modelRoot.existsSync()) {
+    stderr.writeln('Model root not found: ${modelRoot.path}');
+    exit(1);
+  }
+
+  // Collect files
+  for (final entity in modelRoot.listSync(recursive: true)) {
+    if (entity is File && entity.path.endsWith('.dart')) {
+      final p = entity.path;
+      if (p.contains('/request/')) {
+        requestFiles.add(entity);
+      } else if (p.contains('/response/')) {
+        responseFiles.add(entity);
+      } else {
+        uiDomainFiles.add(entity);
+      }
+    }
+  }
+
+  String relPath(File f) =>
+      f.path.replaceFirst(projectRoot, '').replaceFirst(RegExp(r'^/'), '');
+
+  List<_Decl> parseDecls(File file) {
+    final lines = file.readAsLinesSync();
+    final decls = <_Decl>[];
+    for (var i = 0; i < lines.length; i++) {
+      final line = lines[i].trim();
+      final classMatch = RegExp(r'^class\s+([A-Za-z0-9_]+)').firstMatch(line);
+      final enumMatch = RegExp(r'^enum\s+([A-Za-z0-9_]+)').firstMatch(line);
+      if (classMatch != null || enumMatch != null) {
+        final kind = classMatch != null ? 'class' : 'enum';
+        final name = (classMatch ?? enumMatch)!.group(1)!;
+        // Collect preceding doc comments (/// ...)
+        final docLines = <String>[];
+        var j = i - 1;
+        while (j >= 0) {
+          final prev = lines[j].trim();
+          if (prev.startsWith('///')) {
+            docLines.insert(0, prev.replaceFirst('///', '').trim());
+            j--;
+            continue;
+          }
+          break;
+        }
+        final description = docLines.isEmpty ? null : docLines.join(' ');
+        decls.add(_Decl(kind, name, description));
+      }
+    }
+    return decls;
+  }
+
+  String section(String title, List<File> files) {
+    final b = StringBuffer('## $title\n\n');
+    if (files.isEmpty) {
+      b.writeln('- (none)\n');
+      return b.toString();
+    }
+    for (final f in files) {
+      final decls = parseDecls(f);
+      final path = relPath(f);
+      if (decls.isEmpty) {
+        b.writeln('- $path');
+      } else {
+        for (final d in decls) {
+          b.writeln('- ${d.kind} ${d.name} — $path');
+          if (d.description != null && d.description!.isNotEmpty) {
+            b.writeln('  - ${d.description}');
+          }
+        }
+      }
+    }
+    b.writeln();
+    return b.toString();
+  }
+
+  final out = StringBuffer()
+    ..writeln('# Model Registry (AUTO-GENERATED)\n')
+    ..writeln(
+        '> Do not edit manually. Run: dart run tool/generate_model_registry.dart\n')
+    ..writeln(section('UI/Domain Models', uiDomainFiles))
+    ..writeln(section('Request Models', requestFiles))
+    ..writeln(section('Response Models', responseFiles));
+
+  // Ensure spec directory exists
+  final specDir = Directory('$projectRoot/spec');
+  if (!specDir.existsSync()) {
+    specDir.createSync(recursive: true);
+  }
+  final outputFile =
+      File('${specDir.path}/model-registry.md'); // overwrite existing
+  outputFile.writeAsStringSync(out.toString());
+  stdout.writeln('Generated ${outputFile.path}');
+}
+
+class _Decl {
+  final String kind;
+  final String name;
+  final String? description;
+  _Decl(this.kind, this.name, this.description);
+}

package/templates/shared/tool/generate_ui_workflow_spec.dart

@@ -0,0 +1,173 @@
+import 'dart:io';
+
+void main() {
+  final projectRoot = Directory.current.path;
+  final uiRoot = Directory('$projectRoot/lib/src/ui');
+  if (!uiRoot.existsSync()) {
+    stderr.writeln('UI root not found: ${uiRoot.path}');
+    exit(1);
+  }
+
+  final specDir = Directory('$projectRoot/spec');
+  if (!specDir.existsSync()) {
+    specDir.createSync(recursive: true);
+  }
+  final outputFile = File('${specDir.path}/ui-workflow.md');
+
+  final sections = <String>[];
+  for (final featureDir in uiRoot.listSync()) {
+    if (featureDir is! Directory) continue;
+    final name = featureDir.uri.pathSegments.lastWhere(
+      (s) => s.isNotEmpty,
+      orElse: () => featureDir.path.split('/').last,
+    );
+
+    final pages = <_FileDoc>[];
+    final components = <_FileDoc>[];
+    final hasBinding = Directory('${featureDir.path}/binding').existsSync();
+    final hasInteractor =
+        Directory('${featureDir.path}/interactor').existsSync();
+    final interactorFiles =
+        Directory('${featureDir.path}/interactor').existsSync()
+            ? Directory('${featureDir.path}/interactor')
+                .listSync()
+                .whereType<File>()
+                .where((f) => f.path.endsWith('.dart'))
+                .toList()
+            : <File>[];
+
+    // Collect page and component files
+    for (final entity in featureDir.listSync(recursive: true)) {
+      if (entity is File && entity.path.endsWith('.dart')) {
+        final rel = entity.path
+            .replaceFirst(projectRoot, '')
+            .replaceFirst(RegExp(r'^/'), '');
+        if (entity.path.endsWith('_page.dart')) {
+          pages.add(_readDoc(entity, rel));
+        } else if (rel.contains('/components/')) {
+          components.add(_readDoc(entity, rel));
+        }
+      }
+    }
+
+    // Derive feature goal from the first page doc (if any)
+    final featureGoal =
+        pages.isNotEmpty && pages.first.description != null
+            ? pages.first.description!
+            : '';
+
+    final b =
+        StringBuffer()
+          ..writeln('## $name')
+          ..writeln('**Path**: lib/src/ui/$name\n')
+          ..writeln('### 1. Description')
+          ..writeln('Goal: ${featureGoal.isEmpty ? "" : featureGoal}')
+          ..writeln('Features:')
+          ..writeln('- ')
+          ..writeln('\n### 2. UI Structure')
+          ..writeln('- Screens:')
+          ..writeAll(
+            pages.map(
+              (p) =>
+                  '  - ${p.symbolName} — ${p.relPath}\n${p.description != null && p.description!.isNotEmpty ? '    - ${p.description!}\n' : ''}',
+            ),
+          )
+          ..writeln('- Components:')
+          ..writeAll(
+            components.map(
+              (c) =>
+                  '  - ${c.symbolName} — ${c.relPath}\n${c.description != null && c.description!.isNotEmpty ? '    - ${c.description!}\n' : ''}',
+            ),
+          )
+          ..writeln('\n### 3. User Flow & Logic')
+          ..writeln('1) ')
+          ..writeln('2) ')
+          ..writeln('\n### 4. Key Dependencies')
+          ..writeln(hasInteractor ? '- interactor/*' : '- (none)')
+          ..writeAll(
+            interactorFiles.map(
+              (f) =>
+                  '  - ${f.path.replaceFirst(projectRoot, '').replaceFirst(RegExp(r'^/'), '')}\n',
+            ),
+          )
+          ..writeln(hasBinding ? '- binding/*' : '- (none)')
+          ..writeln('\n### 5. Notes & Known Issues')
+          ..writeln('- ')
+          ..writeln('');
+
+    sections.add(b.toString());
+  }
+
+  final out =
+      StringBuffer()
+        ..writeln('# UI Workflow (AUTO-GENERATED)\n')
+        ..writeln(
+          '> Do not edit manually. Run: dart run tool/generate_ui_workflow_spec.dart\n',
+        )
+        ..writeAll(sections);
+
+  outputFile.writeAsStringSync(out.toString());
+  stdout.writeln('Generated ${outputFile.path}');
+}
+
+class _FileDoc {
+  final String relPath;
+  final String symbolName;
+  final String? description;
+  _FileDoc(this.relPath, this.symbolName, this.description);
+}
+
+_FileDoc _readDoc(File file, String relPath) {
+  final lines = file.readAsLinesSync();
+  String? symbolName;
+  String? description;
+
+  // Find first class or widget name
+  for (var i = 0; i < lines.length; i++) {
+    final line = lines[i].trim();
+    final classMatch = RegExp(r'^class\s+([A-Za-z0-9_]+)').firstMatch(line);
+    if (classMatch != null) {
+      symbolName = classMatch.group(1)!;
+      // Collect leading doc comments (/// ...) before class
+      final docLines = <String>[];
+      var j = i - 1;
+      while (j >= 0) {
+        final prev = lines[j].trim();
+        if (prev.startsWith('///')) {
+          docLines.insert(0, prev.replaceFirst('///', '').trim());
+          j--;
+          continue;
+        }
+        // Stop at non-doc line
+        break;
+      }
+      if (docLines.isNotEmpty) {
+        description = docLines.join(' ');
+      }
+      break;
+    }
+  }
+
+  // Fallback: top-of-file doc block
+  if (description == null) {
+    final docLines = <String>[];
+    for (final l in lines) {
+      final t = l.trim();
+      if (t.startsWith('///')) {
+        docLines.add(t.replaceFirst('///', '').trim());
+      } else if (t.isEmpty || t.startsWith('//')) {
+        // continue scanning
+        continue;
+      } else {
+        break;
+      }
+    }
+    if (docLines.isNotEmpty) {
+      description = docLines.join(' ');
+    }
+  }
+
+  // Fallback symbol name to file basename
+  symbolName ??= relPath.split('/').last.replaceAll('.dart', '');
+  return _FileDoc(relPath, symbolName, description);
+}

package/templates/shared/tool/update_specs.dart

@@ -0,0 +1,40 @@
+import 'dart:io';
+
+void main() {
+  final code1 = _runWithFallback('tool/generate_model_registry.dart');
+  if (code1 != 0) exit(code1);
+  final code2 = _runWithFallback('tool/generate_ui_workflow_spec.dart');
+  if (code2 != 0) exit(code2);
+}
+
+int _runWithFallback(String scriptPath) {
+  const runners = <List<String>>[
+    <String>['dart', 'run'],
+    <String>['fvm', 'dart', 'run'],
+    <String>['flutter', 'pub', 'run'],
+  ];
+
+  ProcessResult? lastResult;
+  for (final runner in runners) {
+    final command = runner.first;
+    final args = <String>[...runner.sublist(1), scriptPath];
+    final result = Process.runSync(command, args, runInShell: true);
+    stdout.write(result.stdout);
+    stderr.write(result.stderr);
+    if (result.exitCode == 0) {
+      return 0;
+    }
+    if (!_isCommandNotFound(result)) {
+      return result.exitCode;
+    }
+    lastResult = result;
+  }
+
+  return lastResult?.exitCode ?? 1;
+}
+
+bool _isCommandNotFound(ProcessResult result) {
+  if (result.exitCode == 127) return true;
+  final stderrText = '${result.stderr}'.toLowerCase();
+  return stderrText.contains('command not found') || stderrText.contains('is not recognized');
+}