froggy-docs 1.1.0 → 1.1.3

package/.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(head -80 /home/kmt/.pub-cache/hosted/pub.dev/jaspr-0.23.1/lib/src/dom/html/html.dart)",
+      "Read(//home/kmt/.pub-cache/hosted/pub.dev/jaspr-0.23.1/lib/src/dom/html/**)",
+      "Bash(cat /home/kmt/.pub-cache/hosted/pub.dev/jaspr-0.23.1/lib/src/dom/events.dart | head -100)",
+      "Read(//home/kmt/.pub-cache/hosted/pub.dev/jaspr-0.23.1/lib/src/dom/**)",
+      "Read(//home/kmt/.pub-cache/hosted/pub.dev/jaspr-0.23.1/**)",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); [print\\(p['name'],p.get\\('rootUri',''\\)\\) for p in d['packages'] if 'web' in p['name'].lower\\(\\) or 'universal' in p['name'].lower\\(\\)]\")",
+      "Bash(head -20 /home/kmt/.pub-cache/hosted/pub.dev/universal_web-1.1.1+1/lib/web.dart 2>/dev/null)",
+      "Read(//home/kmt/.pub-cache/hosted/pub.dev/universal_web-1.1.1+1/lib/**)",
+      "Bash(dart test *)",
+      "Bash(find /home/kmt/.pub-cache/hosted/pub.dev/jaspr-0.23.1 -name \"*.dart\" | xargs grep -l \"sort_children_last\\\\|div\\(classes\" 2>/dev/null | head -5 && echo \"---\" && find /home/kmt/.pub-cache/hosted/pub.dev/jaspr_lints* -name \"*.dart\" 2>/dev/null | head -5)",
+      "Read(//home/kmt/.pub-cache/hosted/pub.dev/**)",
+      "Bash(dart analyze *)",
+      "Bash(echo \"Exit code: $?\")",
+      "Bash(npm --version)",
+      "Bash(node -e \"const p = require.resolve\\('npm/package.json'\\); console.log\\(require\\('path'\\).dirname\\(p\\)\\)\")"
+    ]
+  }
+}

package/.github/workflows/froggy-docs.yml

@@ -0,0 +1,59 @@
+name: FroggyDocs CI/CD
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Dart SDK
+        uses: dart-lang/setup-dart@v1
+        with:
+          sdk: stable
+
+      - name: Install dependencies
+        run: dart pub get
+
+      - name: Run analyzer
+        run: dart analyze
+
+      - name: Run tests
+        run: dart test
+
+      - name: Build FroggyDocs
+        run: dart run bin/froggy_docs.dart build --output docs/froggy_docs.json
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: frontend/web/
+
+  deploy:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/ABOUT.md

@@ -0,0 +1,99 @@
+# 🐸 FroggyDocs Project Guide
+
+## Overview
+
+FroggyDocs is a cross-platform tool designed to auto-generate interactive API documentation from code annotations. It supports multiple programming languages (JavaScript, Python, Go, Ruby, etc.) and provides a modern web interface for viewing and testing API endpoints.
+
+### Core Technologies
+- **Language:** Dart (SDK ^3.11.5)
+- **Frontend Framework:** [Jaspr](https://pub.dev/packages/jaspr) (Dart web framework)
+- **HTTP Server:** [Shelf](https://pub.dev/packages/shelf)
+- **CLI Utilities:** `package:args`, `package:watcher`
+- **Specification:** OpenAPI 3.0.0
+
+### Architecture
+- **CLI (`bin/froggy_docs.dart`):** The entry point for commands like `serve` and `watch`.
+- **Parser Engine (`lib/src/parser_engine.dart`):** Scans source files for comments starting with `@api` and other tags to build the OpenAPI specification.
+- **Web Server (`lib/src/web_server.dart`):** Serves the generated documentation and handles API proxying for the "Try It Out" feature.
+- **Frontend (`frontend/`):** A client-side Jaspr application that consumes the generated `froggy_docs.json` and renders the UI.
+
+---
+
+## Getting Started
+
+### Prerequisites
+- Dart SDK installed and configured.
+- (Optional) Node.js/npm for global installation.
+- (Optional) Docker for containerized deployment.
+
+### Development Setup
+1.  **Install dependencies:**
+    ```bash
+    dart pub get
+    cd frontend && dart pub get
+    ```
+
+2.  **Run the CLI locally:**
+    ```bash
+    dart bin/froggy_docs.dart serve
+    ```
+
+3.  **Build the frontend:**
+    ```bash
+    cd frontend
+    dart run build_runner build
+    ```
+
+### Testing
+Run tests using the standard Dart test runner:
+```bash
+dart test
+```
+
+---
+
+## Development Conventions
+
+### Annotation Syntax
+The parser scans for specific tags in comments. Supported languages use their standard comment prefixes (e.g., `//` for JS/Dart, `#` for Python).
+
+| Tag | Description | Example |
+|-----|-------------|---------|
+| `@api` | Defines the method and path | `@api POST /api/users` |
+| `@desc` | Brief description of the endpoint | `@desc Create a new user` |
+| `@tag` | Groups endpoints in the UI | `@tag Users` |
+| `@body` | Defines a request body field | `@body name string User's full name` |
+| `@body-json` | Inline JSON schema for the body | `@body-json {"id": 1}` |
+| `@auth` | Marks the endpoint as requiring authentication | `@auth` |
+
+### Coding Standards
+- Follow the [Dart Style Guide](https://dart.dev/guides/language/effective-dart/style).
+- Use `package:lints/recommended.yaml` for static analysis.
+- Ensure all new logic is added to `lib/src/` and properly exported if necessary.
+- Frontend components should be modular Jaspr components located in `frontend/lib/`.
+
+---
+
+## Deployment and Distribution
+
+### npm
+The project includes a `package.json` for distribution via npm. The main executable is linked to `bin/froggy-docs` (which may be a wrapper script or compiled binary in the distributed package).
+
+### Docker
+A `Dockerfile` is provided for containerization.
+```bash
+docker build -t froggy-docs .
+docker run -p 8080:8080 froggy-docs
+```
+
+### Pub
+Distributed as a Dart package on [pub.dev](https://pub.dev/packages/froggy_docs).
+
+---
+
+## Key Files
+- `bin/froggy_docs.dart`: CLI entry point and command handling.
+- `lib/src/parser_engine.dart`: Core logic for parsing annotations and generating OpenAPI JSON.
+- `lib/src/web_server.dart`: Shelf-based server with proxy support.
+- `frontend/lib/app.dart`: Main frontend logic and UI rendering.
+- `frontend/web/froggy_docs.json`: The generated OpenAPI specification used by the frontend.

package/MILESTONE.md

@@ -1,6 +1,6 @@
 # 🐸 FroggyDocs Milestone
 
-## Date: April 28, 2026
+## Date: May 1, 2026
 
 ---
 
@@ -39,6 +39,7 @@
 - [x] Serves froggy_docs.json at `/froggy_docs.json`
 - [x] Static file serving (CSS, JS)
 - [x] Mock API endpoints for Try It Out testing
+- [x] **NEW** Proxy support for forwarding API requests to backend server (`--proxy` option)
 
 ### Frontend UI
 - [x] Sidebar with tag groups (collapsible)
@@ -49,6 +50,7 @@
 - [x] "Try It Out" button with live API calls
 - [x] Response display on page
 - [x] Method badges (color-coded GET/POST/PUT/DELETE)
+- [x] **CHANGED** Replaced Jaspr (Dart) with vanilla JavaScript for better compatibility
 
 ### Deployment
 - [x] Standalone executable (dart compile exe)
@@ -57,7 +59,7 @@
 - [x] Dockerfile
 - [x] .froggyrc.example config
 - [x] GitHub Actions CI workflow
-- [x] Published to npm
+- [x] Published to npm as `froggy-docs`
 
 ---
 
@@ -66,22 +68,28 @@
 ```
 froggy_docs/
 ├── bin/froggy_docs.dart          # CLI entrypoint
+├── bin/froggy-docs               # Compiled executable
 ├── lib/
 │   └── src/
 │       ├── parser_engine.dart    # Annotation parser
-│       ├── watcher_engine.dart  # File watcher
-│       └── web_server.dart     # HTTP server + mock API
+│       ├── watcher_engine.dart   # File watcher
+│       └── web_server.dart       # HTTP server + proxy
 ├── frontend/
-│   ├── lib/app.dart            # Jaspr UI
-│   └── web/styles.css         # Styling
+│   ├── web/
+│   │   ├── index.html           # Main UI
+│   │   ├── app.js               # JavaScript frontend
+│   │   ├── styles.css           # Styling
+│   │   └── froggy_docs.json     # Generated docs
+│   └── pubspec.yaml
 ├── docs/
-│   └── annotations.md         # Full annotation guide
-├── package.json               # npm package config
-├── package.js                # npm wrapper
-├── install.sh                # Shell installer
-├── Dockerfile                 # Docker image
-├── .froggyrc.example          # Config example
-└── README.md                 # Documentation
+│   └── annotations.md           # Full annotation guide
+├── package.json                 # npm package config
+├── package.js                   # npm wrapper
+├── install.sh                   # Shell installer
+├── Dockerfile                   # Docker image
+├── .froggyrc.example            # Config example
+├── pubspec.yaml                 # Dart dependencies
+└── README.md                    # Documentation
 ```
 
 ---
@@ -93,11 +101,14 @@ froggy_docs/
 npm install -g froggy-docs
 froggy-docs serve
 
+# With proxy to backend API (e.g., Express on port 3000)
+froggy-docs serve --proxy http://localhost:3000
+
 # Via Docker
 docker run -p 8080:8080 froggy-docs
 
 # Via binary
-./froggy-docs serve -p 8080
+./froggy-docs serve -p 8080 --proxy http://localhost:3000
 ```
 
 ---
@@ -134,12 +145,13 @@ app.post('/api/users', handler);
 Built with:
 - [Shelf](https://pub.dev/packages/shelf) - HTTP server
 - [Watcher](https://pub.dev/packages/watcher) - File watching
-- [Jaspr](https://pub.dev/packages/jaspr) - Web framework
 
 ---
 
-**Status: ✅ Ready for Production Use**
+## 📦 Latest Version
+
+**Version: 1.1.1**
 
 npm: `npm install -g froggy-docs`
 Docker: `docker run -p 8080:8080 froggy-docs`
-GitHub: [Releases](https://github.com/yourusername/froggy-docs/releases)
+GitHub: [Releases](https://github.com/Kaung-Myat/froggydocs/releases)

package/bin/froggy_docs.dart

@@ -1,48 +1,6 @@
-import 'dart:io';
-import 'dart:async';
-import 'package:args/args.dart';
-import 'package:froggy_docs/src/watcher_engine.dart';
-import 'package:froggy_docs/src/web_server.dart';
+import 'package:froggy_docs/src/cli_runner.dart';
 
 void main(List<String> arguments) async {
-  final parser = ArgParser();
-  parser.addCommand('watch');
-  parser.addCommand('serve');
-  parser.addOption(
-    'port',
-    abbr: 'p',
-    help: 'Port for server',
-    defaultsTo: '8080',
-  );
-  parser.addOption(
-    'proxy',
-    abbr: 'x',
-    help: 'Proxy API requests to this URL (e.g., http://localhost:3000)',
-    defaultsTo: '',
-  );
-
-  try {
-    final results = parser.parse(arguments);
-
-    if (results.command?.name == 'watch') {
-      print('🐸 FroggyDocs is watching your API project...');
-      final watcher = WatcherEngine();
-      watcher.startWatching(Directory.current.path);
-    } else if (results.command?.name == 'serve') {
-      final port = int.parse(results['port'] as String);
-      final proxyUrl = results['proxy'] as String;
-      print('🐸 Starting FroggyDocs server with live reload...');
-      if (proxyUrl.isNotEmpty) {
-        print('🔄 Proxy enabled: API requests will be forwarded to $proxyUrl');
-      }
-
-      // Start server and watcher
-      await startServer(port: port, proxyUrl: proxyUrl);
-      final watcher = WatcherEngine();
-      watcher.startWatching(Directory.current.path);
-    }
-  } catch (e) {
-    print('Error: ${e.toString()}');
-    exit(1);
-  }
+  final runner = CliRunner();
+  runner.run(arguments);
 }